@valence-ai/sdk

Valence AI SDK for integrating security issue ingestion, local scan uploads, and runtime security signals into the Valence AI control plane.

What it supports

• Local scan ingestion (runLocalSecurityScan)
• CI scan ingestion (client.reportFindings)
• Runtime decision reporting as security issues (createRuntimeFindingHooks, reportRuntimeDecisionFinding)
• Optional runtime guardrail controls (createToolExecutionGuard, withValenceGuard)

Install

npm install @valence-ai/sdk

Required configuration

Integration requires:

• Valence API base URL
• Project API key
• Project ID
• Environment (production | staging | sandbox)

Optional:

• Workspace ID
• Agent name (mainly for runtime guardrail flows)

Create a client

import { createValenceClient } from '@valence-ai/sdk';

const client = createValenceClient({
  baseUrl: process.env.VALENCE_API_BASE_URL!,
  apiKey: process.env.VALENCE_API_KEY!,
});

Local scan integration

import { runLocalSecurityScan } from '@valence-ai/sdk';

const result = await runLocalSecurityScan(
  {
    baseUrl: process.env.VALENCE_API_BASE_URL!,
    apiKey: process.env.VALENCE_API_KEY!,
  },
  {
    cwd: process.cwd(),
    projectId: process.env.VALENCE_PROJECT_ID!,
    workspaceId: process.env.VALENCE_WORKSPACE_ID,
    environment: process.env.VALENCE_ENVIRONMENT as 'production' | 'staging' | 'sandbox',
    metadata: { sourceLabel: 'Local developer scan' },
  }
);

console.log(`Uploaded ${result.findings.length} security issues`);

Current scan coverage is optimized for high-signal web-app findings, dependency risk from npm audit, and environment/secret misconfiguration patterns.

CI ingestion (bring your own scanner)

await client.reportFindings({
  projectId: process.env.VALENCE_PROJECT_ID!,
  workspaceId: process.env.VALENCE_WORKSPACE_ID,
  environment: process.env.VALENCE_ENVIRONMENT as 'production' | 'staging' | 'sandbox',
  source: 'CI_SCAN',
  findings: ciFindings,
  metadata: {
    branch: process.env.GITHUB_REF_NAME,
    commitSha: process.env.GITHUB_SHA,
  },
});

ciFindings must be mapped to the Valence finding shape before upload.

Runtime security issue reporting

Auto-map runtime decisions to security issues

import {
  createRuntimeFindingHooks,
  createToolExecutionGuard,
} from '@valence-ai/sdk';

const runtimeHooks = createRuntimeFindingHooks(client, {
  minimumRisk: 'HIGH',
});

const guard = createToolExecutionGuard(
  client,
  {
    workspaceId: process.env.VALENCE_WORKSPACE_ID!,
    projectId: process.env.VALENCE_PROJECT_ID!,
    environment: process.env.VALENCE_ENVIRONMENT as 'production' | 'staging' | 'sandbox',
    goal: 'serve customer dashboard',
  },
  runtimeHooks
);

Report a runtime decision directly

import { reportRuntimeDecisionFinding } from '@valence-ai/sdk';

await reportRuntimeDecisionFinding(
  client,
  {
    workspaceId: process.env.VALENCE_WORKSPACE_ID!,
    projectId: process.env.VALENCE_PROJECT_ID!,
    environment: 'production',
    goal: 'export invoices',
    tool: 'billing_export',
    action: 'export',
  },
  {
    decision: 'REQUIRES_APPROVAL',
    reason: 'Billing exports require review in production.',
    risk: 'HIGH',
    latencyMs: 14,
  }
);

Optional runtime guardrail controls

import { withValenceGuard } from '@valence-ai/sdk';

const guardedReadIncident = withValenceGuard(client, {
  workspaceId: process.env.VALENCE_WORKSPACE_ID!,
  projectId: process.env.VALENCE_PROJECT_ID!,
  agentName: process.env.VALENCE_AGENT_NAME!,
  tool: 'read_incident',
  action: 'read',
  environment: 'staging',
  goal: 'resolve_incident',
});

const incident = await guardedReadIncident(async () => readIncident('INC-1421'));

Use this mode only for workflows that need pre-execution allow/block/approval behavior.

Error handling

import {
  ValenceApprovalRequiredError,
  ValenceBlockError,
} from '@valence-ai/sdk';

try {
  await guard.runTool(
    { tool: 'restart_service', action: 'write' },
    async () => restartService('payments-api')
  );
} catch (error) {
  if (error instanceof ValenceApprovalRequiredError) {
    console.log('Approval required', error.approvalId);
  } else if (error instanceof ValenceBlockError) {
    console.log('Blocked', error.message);
  } else {
    throw error;
  }
}

Exports

createValenceClient
runLocalSecurityScan
createRuntimeFindingHooks
reportRuntimeDecisionFinding
buildRuntimeDecisionFinding
createToolExecutionGuard
guardToolExecution
withValenceGuard
ValenceDecisionError
ValenceBlockError
ValenceApprovalRequiredError
isValenceDecisionError