@sernixa/sdk

TypeScript SDK for Sernixa — governed tool and agent execution with MCP call-gate support.

What This Does

The SDK gates local JavaScript/TypeScript function execution through Sernixa's approval oracle. Your code runs only after Sernixa returns an approved-style decision (approved, auto_approved, or executed).

This is not a native MCP JSON-RPC server or transport. Sernixa exposes a governed HTTP call gate for host/router-controlled MCP dispatch. Native MCP transport is not shipped yet.

Install

From the repository root:

npm install
npm -w packages/sdk run build

After npm publication (when available):

npm install @sernixa/sdk

Quick Start

import { Client } from "@sernixa/sdk";

const client = new Client({
  baseUrl: "http://localhost:8000",
  apiKey: process.env.SERNIXA_API_KEY,
});

const readFile = client.intercept(
  async (path: string) => `contents for ${path}`,
  {
    intentId: "mcp-read-file",
    riskLevel: "LOW",
    operationClass: "read",
    dataSensitivity: "internal",
    systemsTouched: ["workspace"],
  }
);

const result = await readFile("/workspace/report.md");

The client also exposes typed control-plane methods for whoami(), governanceTest(), and organization API-key create/list/get/revoke operations.

MCP Call Gate

Use mcpCallGate() to request approval for an MCP-style tool call through Sernixa's governed HTTP call gate:

const response = await client.mcpCallGate({
  mcpToolsetId: "workspace-mcp",
  toolName: "read_file",
  intentId: "read-workspace-file",
  arguments: { path: "/workspace/report.md" },
  riskLevel: "LOW",
  operationClass: "read",
  dataSensitivity: "internal",
});

if (response.status === "accepted" || response.status === "auto_approved") {
  // Dispatch the actual MCP tool call from the caller-owned host
}

Important: dispatch_mode is always caller_owned_after_allowed. Sernixa does not execute upstream MCP servers — it governs whether the call should proceed.

Gateway Wrapper

import { SernixaGateway } from "@sernixa/sdk";

const gateway = new SernixaGateway({
  apiKey: process.env.SERNIXA_API_KEY,
  mcpProfile: "prod-tools",
  enforceEbpf: true,
});

const result = await gateway.run(
  () => agent.run({ input: "Summarize customer risk" }),
  {
    intentId: "agent-risk-summary",
    riskLevel: "MEDIUM",
    operationClass: "agent_run",
    dataSensitivity: "internal",
  }
);

enforceEbpf=true does not start an eBPF collector. It checks /ready and requires Flight Recorder runtime support outside local_demo.

Delegation

import { Client } from "@sernixa/sdk";

const client = new Client();

const token = await client.createDelegationToken({
  delegatorAgentId: "orchestrator",
  delegateeAgentId: "worker",
  scope: {
    max_risk_level: "low",
    allowed_operation_classes: ["read"],
  },
});

const governed = client.interceptWithDelegation(
  async () => "worker result",
  {
    intentId: "delegated-read",
    riskLevel: "LOW",
    operationClass: "read",
    dataSensitivity: "internal",
    systemsTouched: ["workspace"],
  },
  {
    agentId: "worker",
    delegationTokenId: token.token_id as string,
    signingSecret: process.env.SERNIXA_REQUEST_SIGNING_SECRET!,
  }
);

const result = await governed();

Error Handling

import {
  SernixaBlockedError,
  SernixaRejectedError,
  SernixaTimeoutError,
  SernixaSignatureError,
  SernixaDelegationScopeError,
} from "@sernixa/sdk";

try {
  await governed();
} catch (error) {
  if (error instanceof SernixaBlockedError) {
    console.error("Policy blocked:", error.reason);
  } else if (error instanceof SernixaRejectedError) {
    console.error("Reviewer rejected:", error.reason);
  } else if (error instanceof SernixaDelegationScopeError) {
    console.error("Delegation scope error:", error.reason);
  } else if (error instanceof SernixaSignatureError) {
    console.error("Signature error:", error.reason);
  } else if (error instanceof SernixaTimeoutError) {
    console.error("Approval pending:", error.approvalId);
  }
}

Environment Variables

| Variable | Default | Description | | ---------------------------------- | -------------------- | -------------------------------------- | | SERNIXA_BASE_URL | http://localhost:8000 | Sernixa API base URL | | SERNIXA_API_KEY | (empty) | Bearer token | | SERNIXA_POLL_INTERVAL_SECONDS | 2 | Seconds between approval polls | | SERNIXA_POLL_TIMEOUT_SECONDS | 600 | Max seconds to wait for approval | | SERNIXA_TIMEOUT_MS | 10000 | Per-request HTTP timeout | | SERNIXA_MAX_RETRIES | 2 | Retries for 429/5xx/network errors | | SERNIXA_CAPTURE_ARGUMENTS | false | Submit function argument values | | SERNIXA_REQUEST_SIGNING_KEY_ID | local-request-key-v1 | Key ID for delegation signing |

License

MIT