@connexum/typescript-sdk

Welcome to the Citadel — My-CC fortress for building Agent Trust. The TypeScript SDK shim for My-CC.io AI Agent Trust Citadel.

Drop-in replacements for @anthropic-ai/sdk, openai, and @aws-sdk/client-bedrock-runtime that enforce governance policy at the SDK boundary -- unavoidably -- before every LLM call and tool dispatch.

Robotics + Embedded AI

My Compliance Cortex governs the AI brain — the agent runtime that emits tool-call decisions. Governance fires on those decisions before execution.

My-CC enforces policy on the AI agent's tool-call surface. It does NOT directly enforce policy on mechanical actuators, physical sensors, hardware safety interlocks, or real-time control loops. Actuator safety remains the integrating system's responsibility. My-CC provides audit-chain visibility into AI decisions that precede actuator commands; it does not veto those commands at the hardware layer.

Today, embedded TypeScript controllers (Node.js on Jetson, Raspberry Pi, etc.) can use any of the 7 LLM provider shims + LangChain TS framework adapter without additional build. See docs/ROBOTICS_INTEGRATION_PLAN.md for the full spec including the planned embedded deployment runtime, real-time latency mode, and multi-modal sensor classification interface.

Scope Disclaimer (v0.1)

Supported:

• GovernedAnthropic: non-streaming Anthropic messages.create() governance
• GovernedOpenAI: non-streaming OpenAI chat.completions.create() governance
• GovernedBedrock: non-streaming AWS Bedrock InvokeModelCommand governance with multi-model routing:
  • anthropic.claude-*: Anthropic Claude on Bedrock (native Anthropic body format)
  • meta.llama*: Meta Llama 2 (raw prompt) and Llama 3 (structured messages)
  • amazon.titan*: Amazon Titan text models (inputText format)
  • mistral.*: Mistral Instruct (raw prompt) and Mistral Large chat (structured messages)
  • cohere.*: Cohere Command / Command R (permissive parse with warning)
  • Unknown model families: permissive body parse with governance fidelity warning
• client.dispatchTool(): governed tool-call dispatch with per-tool policy enforcement
• GovernanceViolation / GovernancePendingApproval error types for clean error handling

NOT supported in v0.1 (documented v0.2+ targets):

• Streaming:
  • Anthropic: .stream(), .withStreamingResponse -- throws GovernanceViolation
  • OpenAI: stream: true in params -- throws GovernanceViolation
  • Bedrock: InvokeModelWithResponseStreamCommand -- throws GovernanceViolation
• LangChain / LangGraph adapter hardening
• Async Anthropic client (AsyncAnthropic)
• Azure OpenAI (GovernedAzureOpenAI planned v0.2)
• Google Gemini (GovernedGemini planned v0.2)

Bypass paths on all three adapters raise GovernanceViolation immediately (e.g. .beta, .withRawResponse, .middlewareStack).

Installation

This package is distributed via GitHub Packages. Requires a valid My-CC license key.

Step 1: Configure npm to use GitHub Packages for the @connexum scope.

Create or update .npmrc in your project root:

@connexum:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

GITHUB_TOKEN must be a GitHub personal access token with read:packages scope, provided by Connexum after purchase.

Step 2: Install the package.

npm install @connexum/typescript-sdk

@anthropic-ai/sdk is a peer dependency -- bring your own version (>=0.20.0).

Quick Start

import { createGovernedAnthropic, GovernanceViolation, GovernancePendingApproval } from '@connexum/typescript-sdk';

const client = createGovernedAnthropic(
  // Passed directly to new Anthropic() -- all Anthropic client options work
  { apiKey: process.env.ANTHROPIC_API_KEY },
  {
    governanceServerUrl: process.env.MYCC_GOVERNANCE_URL ?? 'http://localhost:3200',
    licenseKey: process.env.MYCC_LICENSE_KEY!,
    packIds: ['hipaa'],  // Compliance packs active for this client
    toolRegistry: {
      search_web: async (input) => {
        // Your tool implementation here
        return `Results for: ${input['query']}`;
      },
      read_file: async (input) => {
        // Your tool implementation here
        return `File contents of: ${input['path']}`;
      },
    },
  },
);

// Drop-in replacement for client.messages.create()
try {
  const response = await client.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 1024,
    tools: [
      {
        name: 'search_web',
        description: 'Search the web',
        input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
      },
    ],
    messages: [{ role: 'user', content: 'Find recent news about AI governance.' }],
  });

  // When the model wants to use a tool, use client.dispatchTool() -- NOT the function directly
  if (response.stop_reason === 'tool_use') {
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        const toolResult = await client.dispatchTool(block.name, block.input);
        // toolResult is the function's return value (string | object)
        // or a synthetic error string if the tool was denied by governance
      }
    }
  }
} catch (err) {
  if (err instanceof GovernanceViolation) {
    // The call was denied. Do NOT retry without resolving the policy issue.
    console.error('Governance denial:', err.decision.reason);
  } else if (err instanceof GovernancePendingApproval) {
    // A human must approve before this call can proceed.
    // Poll GET /api/v1/governance/approvals/:approvalId on the governance server.
    console.log('Waiting for approval:', err.approvalId);
  } else {
    throw err;
  }
}

How It Works

Customer code            GovernedAnthropic         Governance Server      Anthropic
    |                          |                          |                    |
    |-- messages.create() ---> |                          |                    |
    |                          |-- POST /check ---------->|                    |
    |                          |<-- ALLOW / DENY / PENDING|                    |
    |                          |                          |                    |
    |    [on DENY]             |-- throws GovernanceViolation                  |
    |    [on PENDING]          |-- throws GovernancePendingApproval            |
    |    [on ALLOW]            |-- messages.create() ----------------------------> |
    |<-- response -------------|<-------------------------------------------------|
    |                          |                          |                    |
    |-- dispatchTool() ------> |                          |                    |
    |                          |-- POST /check ---------->|                    |
    |                          |<-- ALLOW / DENY          |                    |
    |    [on DENY]             |-- returns synthetic error string              |
    |    [on ALLOW]            |-- calls tool fn                               |
    |<-- tool result ----------|                          |                    |

Key invariant: The customer cannot accidentally bypass governance by calling tool functions directly. The governance check fires or the Anthropic API call does not happen.

Error Handling Reference

| Error | When | Recovery | |-------|------|----------| | GovernanceViolation | messages.create() denied | Do not retry -- fix the policy or the request | | GovernancePendingApproval | messages.create() needs human approval | Poll /api/v1/governance/approvals/:approvalId | | GovernanceViolation (from dispatchTool) | Does NOT throw -- returns error string | Model receives error text and may self-correct | | GovernanceViolation (bypass access) | .beta, .stream, etc. accessed | Remove bypass access; use governed surface only |

Configuration Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | governanceServerUrl | string | required | Base URL of the My-CC governance server | | licenseKey | string | required | License key from my-cc.io | | packIds | string[] | [] | Active compliance pack IDs (e.g. ['hipaa', 'soc2']) | | toolRegistry | Record<string, ToolFunction> | {} | Tool implementations for governed dispatch | | onServerUnreachable | 'fail-open' \| 'fail-closed' | 'fail-open' | Policy when governance server is unreachable |

Connexum Network Inc.

• Docs: docs.my-cc.io
• License server: license.my-cc.io
• Support: [email protected]