@clgplatform/sdk

TypeScript/JavaScript SDK for CLG Platform (Causal Liability Gateway).

Installation

npm install @clgplatform/sdk

Quick start (5-line wrapAgent)

import { wrapAgent } from '@clgplatform/sdk';

const trackedAgent = wrapAgent(myAgentFunction, {
  apiUrl: process.env.CLG_URL || 'https://clgplatform.com',
  apiKey: process.env.CLG_API_KEY!,
  agentId: 'my-agent',
  workflowId: 'wf-001'
});

const result = await trackedAgent({ prompt: 'Hello' });

Quick start (CLGSidecar directly)

import { CLGSidecar } from '@clgplatform/sdk';

const clg = new CLGSidecar({
  apiUrl: process.env.CLG_URL || 'https://clgplatform.com',
  apiKey: process.env.CLG_API_KEY!,
  mode: 'gateway'
});

await clg.createReceipt({
  workflow_id: 'wf-001',
  task_id: 'task-001',
  agent_id: 'my-agent',
  task_input: { prompt: 'Hello' },
  output: { answer: 'Hi!' }
});

Deployment modes

• gateway: sends cleartext payload to POST /v1/receipts for server-side signing.
• sidecar: signs locally, then sends signed payload to POST /v1/receipts/signed.
• hybrid: same transport as sidecar; useful when you locally sign but still centrally ingest.

Evaluate decision (new in 1.1.0)

evaluateDecision calls CLG mandate evaluation endpoint and returns an approve/deny decision plus a signed receipt.

import { CLGSidecar } from '@clgplatform/sdk';

const clg = new CLGSidecar({
  apiUrl: process.env.CLG_URL || 'https://clgplatform.com',
  apiKey: process.env.CLG_API_KEY!,
  mode: 'gateway'
});

const result = await clg.evaluateDecision({
  workflow_id: 'wf-001',
  task_id: 'task-001',
  agent_id: 'agent-001',
  mandate_ref: 'default',
  decision_type: 'tool-call',
  decision_value: 'invoice:create',
  task_input: { customerId: 'c-1' }
});

if (result.decision === 'deny') {
  console.log('Denied:', result.reason);
}

Sidecar and hybrid behavior for evaluateDecision

Even when running in sidecar or hybrid, evaluateDecision is sent to the CLG gateway endpoint because mandate resolution and tenant policy state are server-side concerns.

Chain positioning in sidecar/hybrid

createReceipt supports:

• chain_position and optional workflow_depth (explicit control), or
• previous_receipt_hashes (auto-resolve previous receipt from API and set chain_position = previous + 1).

Example (explicit):

await clg.createReceipt({
  workflow_id: 'wf-001',
  task_id: 'task-002',
  agent_id: 'my-agent',
  task_input: { step: 2 },
  output: { ok: true },
  chain_position: 2,
  workflow_depth: 2,
  previous_receipt_hashes: ['<receipt-hash-step-1>']
});

Environment variables example

CLG_URL=https://clgplatform.com
CLG_API_KEY=clg_live_xxxxx
CLG_MODE=gateway
CLG_LOCAL_SIGNING_KEY="-----BEGIN PRIVATE KEY-----..."

import { wrapAgent } from '@clgplatform/sdk';

const tracked = wrapAgent(agentFn, {
  apiUrl: process.env.CLG_URL!,
  apiKey: process.env.CLG_API_KEY!,
  mode: (process.env.CLG_MODE as 'gateway' | 'sidecar' | 'hybrid') || 'gateway',
  localSigningKey: process.env.CLG_LOCAL_SIGNING_KEY,
  agentId: 'agent-prod',
  workflowId: 'wf-prod-42'
});