Governance SDK Quickstart (Node.js)

@kla-digital/governance is the KLA governance SDK for Node.js. It sends agent actions to the KLA Control Plane, receives one of the four policy outcomes (allow, warn, require_approval, block), waits on human approval at the Decision Desk, and returns the server-recorded execution result. KLA's registered connector owns the side effect. The server records the decision, approval, execution, and receipt references.

Support status: the package is unpublished until the Publish Governance SDKs workflow (environment sdk-publish) runs. Framework coverage is tracked by the agent compatibility matrix in agent-compatibility/v1/; the SDK's adapter helpers are structural and carry no framework dependency, and no framework is claimed as supported here.

Install

npm install @kla-digital/governance

Requires Node.js 20 or later. The package has zero runtime dependencies.

Authenticate

The SDK needs three things: a base URL, a client-credentials access token, and the agent binding (agent id, pinned release version, and an active mandate id). Obtain the token from your identity provider with the client-credentials grant for your workload client. Tenant identity comes from the verified token; the SDK never sends a tenant field in the request body. Setting tenantId adds an x-kla-tenant-id header as a routing hint.

import { KLAClient } from '@kla-digital/governance';

const client = new KLAClient({
  baseUrl: 'https://api.kla.digital',
  credential: () => getAccessToken(),
  agent: { agentId: process.env.KLA_AGENT_ID!, releaseVersion: '1.4.2' },
  mandateId: process.env.KLA_MANDATE_ID!,
});

const binding = await client.resolveBinding();
console.log(`Mandate revision ${binding.mandate.version} is active`);

Register the tool and its connector in the Tool Catalog before using the SDK. The active mandate must cover the agent, tool, operation, and destination shown in the action. resolveBinding is a read-only startup check of the current approved Release, mandate revision, status, validity window, and allowed actions.

Gate one action

import { DecisionDenied } from '@kla-digital/governance';

async function processPayment(accountId: string, amount: number) {
  try {
    return await client.executeAction(
      {
        tool: 'payments',
        operation: 'charge',
        destination: 'stripe:acct_main',
        parameters: { accountId, amount },
      },
      { proposalId: stableIdFor(accountId, amount), timeoutMs: 15 * 60 * 1000 }
    );
  } catch (error) {
    if (error instanceof DecisionDenied) {
      return { declined: true, reasonCodes: error.reasonCodes };
    }
    throw error;
  }
}

executeAction always settles to a server execution. allow and warn execute immediately. A require_approval action waits for a Decision Desk verdict and redeems that same proposal identity. The method returns execution.result. block, a denied approval, and an expired approval throw DecisionDenied. Branch on reasonCodes; the remediation text is for humans.

Approval handling

• Run gated calls on a worker or background task. A reviewer can take minutes or days.
• Pass timeoutMs to bound the wait. ApprovalTimeout means the Decision Request remains pending; call executeAction again with the same proposalId to continue.
• An AbortSignal stops the local wait. The server proposal stays open. Call cancelAction(proposalId, { reason }) to close a received or approval-pending proposal.
• ExecutionMissing is the final defensive guard when a settled decision lacks a server execution record. The SDK fails closed and does not invoke a local destination.
• ExecutionEvidencePending means the connector ran while evidence sealing is incomplete. The SDK withholds every result in this state. The error retains the decision and receipt references. Reconcile the same proposal identity.
• KLATransportError with code: "response_schema_invalid" means the response failed the exact schema, proposal/action binding, lifecycle matrix, result hash, or receipt checks. No output is released.

Retry rules

• Reuse the same proposalId for retries of the same logical action. A committed proposal replays its recorded outcome.
• 503 responses and network errors are retried automatically with backoff and jitter.
• 4xx responses are terminal for that proposal and surface as KLATransportError with retryable: false. Generate a new proposalId only for a genuinely new action.
• The typed Revoked, EvidenceUnavailable, ExecutorUnavailable, and Cancelled errors identify common terminal and service-failure branches.

Local tests

Use the exported LocalSandboxClient with static scenarios. It has no network or destination callback. Its call records redact parameter values. Results carry production: false and environment: 'local-sandbox', so test results remain distinguishable from live KLA execution.

Troubleshooting

• 404 on /v1/agent-actions: the ingress is behind KLA_AGENT_ACTION_INGRESS_ENABLED and is disabled in that environment.
• 401 unauthorized: the Bearer token is missing, expired, or issued for another audience.
• 409 release_mismatch: releaseVersion differs from the active approved rollout for the tenant and environment.
• 403 mandate_invalid, mandate_revoked, mandate_expired: the mandate does not cover the tool, operation, and destination, or is no longer active.
• 409 args_mismatch on resume: the action arguments changed between approval and redemption. Propose a new action.
• 410 approval_expired on resume: the approval passed its dueAt. Propose a new action.
• proposal_cancelled: the proposal closed before execution. Start a new proposal for a new action.