@mindburn/helm-ai-kernel 0.5.1

package/README.md

@@ -0,0 +1,89 @@
+# HELM SDK - TypeScript
+
+Typed TypeScript client for the retained HELM kernel API.
+
+## Local Install
+
+```bash
+cd sdk/ts
+npm ci
+npm run build
+```
+
+Package metadata declares version `0.5.1` in `package.json`; this README does
+not claim that a registry package has been published.
+
+## Local Development
+
+```bash
+npm ci
+npm test -- --run
+npm run build
+```
+
+## Source Layout
+
+- `src/client.ts` is the hand-maintained HTTP wrapper.
+- `src/types.gen.ts` contains OpenAPI-derived model types.
+- `src/adapters/agent-frameworks.ts` contains the source-backed framework
+  adapter helpers.
+- Protobuf bindings under `src/generated/` are generated from
+  `protocols/proto/` with `ts-proto` when codegen has been run.
+
+## Usage
+
+```ts
+import { HelmClient } from "@mindburn/helm-ai-kernel";
+
+const client = new HelmClient({ baseUrl: "http://127.0.0.1:7715" });
+const decision = await client.evaluateDecision({
+  principal: "example-agent",
+  action: "read-ticket",
+  resource: "ticket:123",
+});
+console.log(decision.verdict); // ALLOW, DENY, or ESCALATE
+```
+
+Run the first-class local example with `make sdk-examples-smoke` or directly
+from `examples/ts_sdk/`.
+
+## Agent Framework Adapters
+
+The TypeScript SDK includes lightweight adapter helpers for LangGraph, CrewAI, OpenAI Agents SDK, PydanticAI, and LlamaIndex tool-call events. These helpers normalize each framework event into a HELM governance request and submit it through `chatCompletionsWithReceipt`, preserving the kernel receipt returned in `X-Helm-*` headers.
+
+```ts
+import { HelmClient, createAgentFrameworkAdapter, fromOpenAIAgentsToolCall } from "@mindburn/helm-ai-kernel";
+
+const helm = new HelmClient({ baseUrl: "http://127.0.0.1:7714" });
+const adapter = createAgentFrameworkAdapter(helm, { model: "helm-governance" });
+
+const result = await adapter.submit(
+  fromOpenAIAgentsToolCall({
+    id: "call_123",
+    function: {
+      name: "crm.update_customer",
+      arguments: '{"customer_id":"cus_123","tier":"enterprise"}',
+    },
+  }),
+);
+
+console.log(result.governance.receiptId);
+```
+
+The helpers do not add Microsoft Agent Governance Toolkit as a dependency and
+do not claim Microsoft certification. They cover the same framework families
+so HELM can sit behind AGT or another orchestrator as the receipt-bearing
+enforcement boundary.
+
+## Execution Boundary Methods
+
+The client also exposes methods for proof-bearing boundary operations:
+evidence envelope manifests, boundary records and checkpoints, conformance
+vectors, MCP quarantine and authorization profiles, sandbox profiles and
+grants, authz snapshots, approvals, budgets, telemetry export, and coexistence
+capabilities. These methods keep external envelopes, MCP quarantine decisions,
+and sandbox grants attached to HELM-native receipts and EvidencePacks.
+
+## Release Notes
+
+`0.5.1` is the release-hardening patch with the retained OpenAPI client surface and protobuf message bindings.

package/dist/adapters/agent-frameworks.d.ts

@@ -0,0 +1,160 @@
+import type { ChatCompletionWithReceipt } from "../client.js";
+import type { ChatCompletionRequest, ChatCompletionRequestToolsInner } from "../types.gen.js";
+export type AgentFramework = "langchain" | "langgraph" | "autogen" | "crewai" | "openai-agents" | "semantic-kernel" | "pydantic-ai" | "llamaindex" | "litellm" | "n8n" | "zapier-webhook" | "raw-mcp";
+export interface AgentFrameworkAdapterMetadata {
+    framework: AgentFramework;
+    displayName: string;
+    status: "compatible";
+    source: string;
+}
+export declare const agentFrameworkAdapters: AgentFrameworkAdapterMetadata[];
+export interface AgentFrameworkAction {
+    framework: AgentFramework;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    toolCallId?: string;
+    agentId?: string;
+    runId?: string;
+    taskId?: string;
+    actor?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface FrameworkAdapterOptions {
+    model: string;
+    policyPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface FrameworkAdapterDefaults extends FrameworkAdapterOptions {
+    metadata?: Record<string, unknown>;
+}
+export interface HelmGovernanceClient {
+    chatCompletionsWithReceipt(req: ChatCompletionRequest): Promise<ChatCompletionWithReceipt>;
+}
+export interface GovernedFrameworkResult extends ChatCompletionWithReceipt {
+    request: ChatCompletionRequest;
+    action: AgentFrameworkAction;
+}
+export interface LangGraphToolCall {
+    id?: string;
+    name?: string;
+    tool?: string;
+    args?: unknown;
+    arguments?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface LangChainToolCall extends LangGraphToolCall {
+    runId?: string;
+}
+export interface CrewAITaskCall {
+    id?: string;
+    task?: string;
+    taskId?: string;
+    tool?: string | {
+        name?: string;
+        description?: string;
+    };
+    input?: unknown;
+    args?: unknown;
+    agent?: string;
+    crew?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface OpenAIAgentsToolCall {
+    id?: string;
+    name?: string;
+    arguments?: unknown;
+    function?: {
+        name?: string;
+        arguments?: unknown;
+    };
+    metadata?: Record<string, unknown>;
+}
+export interface AutoGenToolCall {
+    id?: string;
+    name?: string;
+    tool?: string;
+    arguments?: unknown;
+    args?: unknown;
+    agent?: string;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SemanticKernelFunctionCall {
+    id?: string;
+    functionName?: string;
+    pluginName?: string;
+    arguments?: unknown;
+    args?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface PydanticAIToolCall {
+    id?: string;
+    tool_call_id?: string;
+    tool_name?: string;
+    name?: string;
+    args?: unknown;
+    arguments?: unknown;
+    agent?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LlamaIndexToolCall {
+    id?: string;
+    toolName?: string;
+    tool_name?: string;
+    name?: string;
+    kwargs?: unknown;
+    input?: unknown;
+    agent?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LiteLLMToolCall extends OpenAIAgentsToolCall {
+    model?: string;
+}
+export interface N8NNodeExecution {
+    id?: string;
+    node?: string;
+    name?: string;
+    parameters?: unknown;
+    input?: unknown;
+    workflowId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ZapierWebhookCall {
+    id?: string;
+    zapId?: string;
+    action?: string;
+    tool?: string;
+    payload?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface RawMCPToolCall {
+    id?: string;
+    serverId?: string;
+    name?: string;
+    toolName?: string;
+    arguments?: unknown;
+    args?: unknown;
+    scopes?: string[];
+    metadata?: Record<string, unknown>;
+}
+export declare function fromLangGraphToolCall(call: LangGraphToolCall): AgentFrameworkAction;
+export declare function fromLangChainToolCall(call: LangChainToolCall): AgentFrameworkAction;
+export declare function fromCrewAITask(call: CrewAITaskCall): AgentFrameworkAction;
+export declare function fromOpenAIAgentsToolCall(call: OpenAIAgentsToolCall): AgentFrameworkAction;
+export declare function fromAutoGenToolCall(call: AutoGenToolCall): AgentFrameworkAction;
+export declare function fromSemanticKernelFunctionCall(call: SemanticKernelFunctionCall): AgentFrameworkAction;
+export declare function fromPydanticAIToolCall(call: PydanticAIToolCall): AgentFrameworkAction;
+export declare function fromLlamaIndexToolCall(call: LlamaIndexToolCall): AgentFrameworkAction;
+export declare function fromLiteLLMToolCall(call: LiteLLMToolCall): AgentFrameworkAction;
+export declare function fromN8NNodeExecution(call: N8NNodeExecution): AgentFrameworkAction;
+export declare function fromZapierWebhookCall(call: ZapierWebhookCall): AgentFrameworkAction;
+export declare function fromRawMCPToolCall(call: RawMCPToolCall): AgentFrameworkAction;
+export declare function buildGovernedToolRequest(action: AgentFrameworkAction, options: FrameworkAdapterOptions): ChatCompletionRequest;
+export declare function toOpenAIFunctionTool(action: AgentFrameworkAction): ChatCompletionRequestToolsInner;
+export declare function submitGovernedToolIntent(client: HelmGovernanceClient, action: AgentFrameworkAction, options: FrameworkAdapterOptions): Promise<GovernedFrameworkResult>;
+export declare function createAgentFrameworkAdapter(client: HelmGovernanceClient, defaults: FrameworkAdapterDefaults): {
+    buildRequest(action: AgentFrameworkAction, options?: Partial<FrameworkAdapterOptions>): ChatCompletionRequest;
+    submit(action: AgentFrameworkAction, options?: Partial<FrameworkAdapterOptions>): Promise<GovernedFrameworkResult>;
+};

package/dist/adapters/agent-frameworks.js

@@ -0,0 +1,289 @@
+export const agentFrameworkAdapters = [
+    {
+        framework: "langchain",
+        displayName: "LangChain",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "langgraph",
+        displayName: "LangGraph",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "autogen",
+        displayName: "AutoGen",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "crewai",
+        displayName: "CrewAI",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "openai-agents",
+        displayName: "OpenAI Agents SDK",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "semantic-kernel",
+        displayName: "Semantic Kernel",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "pydantic-ai",
+        displayName: "PydanticAI",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "llamaindex",
+        displayName: "LlamaIndex",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "litellm",
+        displayName: "LiteLLM",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "n8n",
+        displayName: "n8n",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "zapier-webhook",
+        displayName: "Zapier-style webhook",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+    {
+        framework: "raw-mcp",
+        displayName: "Raw MCP client",
+        status: "compatible",
+        source: "TypeScript SDK",
+    },
+];
+const DEFAULT_POLICY_PROMPT = "Evaluate whether this agent framework tool call may execute through HELM policy. Return a normal chat completion and rely on HELM response headers for the governance receipt.";
+export function fromLangGraphToolCall(call) {
+    return frameworkAction("langgraph", call.name ?? call.tool, call.args ?? call.arguments, {
+        toolCallId: call.id,
+        metadata: call.metadata,
+    });
+}
+export function fromLangChainToolCall(call) {
+    return frameworkAction("langchain", call.name ?? call.tool, call.args ?? call.arguments, {
+        toolCallId: call.id,
+        runId: call.runId,
+        metadata: call.metadata,
+    });
+}
+export function fromCrewAITask(call) {
+    const tool = typeof call.tool === "string" ? call.tool : call.tool?.name;
+    return frameworkAction("crewai", tool, call.input ?? call.args, {
+        toolCallId: call.id,
+        taskId: call.taskId ?? call.task,
+        agentId: call.agent ?? call.crew,
+        description: typeof call.tool === "string" ? undefined : call.tool?.description,
+        metadata: call.metadata,
+    });
+}
+export function fromOpenAIAgentsToolCall(call) {
+    return frameworkAction("openai-agents", call.function?.name ?? call.name, call.function?.arguments ?? call.arguments, {
+        toolCallId: call.id,
+        metadata: call.metadata,
+    });
+}
+export function fromAutoGenToolCall(call) {
+    return frameworkAction("autogen", call.name ?? call.tool, call.arguments ?? call.args, {
+        toolCallId: call.id,
+        agentId: call.agent,
+        runId: call.conversationId,
+        metadata: call.metadata,
+    });
+}
+export function fromSemanticKernelFunctionCall(call) {
+    const toolName = call.pluginName && call.functionName
+        ? `${call.pluginName}.${call.functionName}`
+        : call.functionName;
+    return frameworkAction("semantic-kernel", toolName, call.arguments ?? call.args, {
+        toolCallId: call.id,
+        metadata: call.metadata,
+    });
+}
+export function fromPydanticAIToolCall(call) {
+    return frameworkAction("pydantic-ai", call.tool_name ?? call.name, call.args ?? call.arguments, {
+        toolCallId: call.tool_call_id ?? call.id,
+        agentId: call.agent,
+        metadata: call.metadata,
+    });
+}
+export function fromLlamaIndexToolCall(call) {
+    return frameworkAction("llamaindex", call.toolName ?? call.tool_name ?? call.name, call.kwargs ?? call.input, {
+        toolCallId: call.id,
+        agentId: call.agent,
+        metadata: call.metadata,
+    });
+}
+export function fromLiteLLMToolCall(call) {
+    const action = fromOpenAIAgentsToolCall(call);
+    return {
+        ...action,
+        framework: "litellm",
+        metadata: { model: call.model, ...action.metadata },
+    };
+}
+export function fromN8NNodeExecution(call) {
+    return frameworkAction("n8n", call.node ?? call.name, call.parameters ?? call.input, {
+        toolCallId: call.id,
+        runId: call.workflowId,
+        metadata: call.metadata,
+    });
+}
+export function fromZapierWebhookCall(call) {
+    return frameworkAction("zapier-webhook", call.action ?? call.tool, call.payload, {
+        toolCallId: call.id,
+        runId: call.zapId,
+        metadata: call.metadata,
+    });
+}
+export function fromRawMCPToolCall(call) {
+    return frameworkAction("raw-mcp", call.toolName ?? call.name, call.arguments ?? call.args, {
+        toolCallId: call.id,
+        agentId: call.serverId,
+        metadata: { scopes: call.scopes, ...call.metadata },
+    });
+}
+export function buildGovernedToolRequest(action, options) {
+    const tool = toOpenAIFunctionTool(action);
+    const payload = {
+        framework: action.framework,
+        tool_name: action.toolName,
+        tool_call_id: action.toolCallId,
+        agent_id: action.agentId,
+        run_id: action.runId,
+        task_id: action.taskId,
+        actor: action.actor,
+        arguments: action.arguments,
+        metadata: action.metadata,
+    };
+    return {
+        model: options.model,
+        temperature: options.temperature ?? 0,
+        max_tokens: options.maxTokens,
+        messages: [
+            {
+                role: "system",
+                content: options.policyPrompt ?? DEFAULT_POLICY_PROMPT,
+            },
+            {
+                role: "user",
+                content: `Authorize this ${displayName(action.framework)} tool call before execution.\n${JSON.stringify(payload, null, 2)}`,
+            },
+        ],
+        tools: [tool],
+    };
+}
+export function toOpenAIFunctionTool(action) {
+    return {
+        type: "function",
+        _function: {
+            name: normalizeToolName(action.toolName),
+            description: action.description ??
+                `${displayName(action.framework)} tool call: ${action.toolName}`,
+            parameters: {
+                type: "object",
+                additionalProperties: true,
+                properties: {},
+            },
+        },
+    };
+}
+export async function submitGovernedToolIntent(client, action, options) {
+    const request = buildGovernedToolRequest(action, options);
+    const result = await client.chatCompletionsWithReceipt(request);
+    return { ...result, request, action };
+}
+export function createAgentFrameworkAdapter(client, defaults) {
+    return {
+        buildRequest(action, options = {}) {
+            return buildGovernedToolRequest(mergeDefaults(action, defaults), mergeOptions(defaults, options));
+        },
+        submit(action, options = {}) {
+            const mergedAction = mergeDefaults(action, defaults);
+            return submitGovernedToolIntent(client, mergedAction, mergeOptions(defaults, options));
+        },
+    };
+}
+function frameworkAction(framework, toolName, args, optional) {
+    if (!toolName?.trim()) {
+        throw new TypeError(`${framework} adapter requires a tool name`);
+    }
+    return {
+        framework,
+        toolName,
+        arguments: normalizeArguments(args),
+        ...optional,
+    };
+}
+function normalizeArguments(args) {
+    if (args == null)
+        return {};
+    if (typeof args === "string") {
+        const trimmed = args.trim();
+        if (!trimmed)
+            return {};
+        try {
+            return normalizeArguments(JSON.parse(trimmed));
+        }
+        catch {
+            return { value: args };
+        }
+    }
+    if (Array.isArray(args)) {
+        return { items: args };
+    }
+    if (typeof args === "object") {
+        return args;
+    }
+    return { value: args };
+}
+function normalizeToolName(name) {
+    const normalized = name
+        .trim()
+        .replace(/[^A-Za-z0-9_-]/g, "_")
+        .slice(0, 64);
+    if (!normalized) {
+        throw new TypeError("tool name normalizes to an empty OpenAI function name");
+    }
+    return normalized;
+}
+function mergeDefaults(action, defaults) {
+    return {
+        ...action,
+        metadata: {
+            ...defaults.metadata,
+            ...action.metadata,
+        },
+    };
+}
+function mergeOptions(defaults, options) {
+    return {
+        model: options.model ?? defaults.model,
+        policyPrompt: options.policyPrompt ?? defaults.policyPrompt,
+        temperature: options.temperature ?? defaults.temperature,
+        maxTokens: options.maxTokens ?? defaults.maxTokens,
+    };
+}
+function displayName(framework) {
+    return (agentFrameworkAdapters.find((adapter) => adapter.framework === framework)
+        ?.displayName ?? framework);
+}

package/dist/adapters/agent-frameworks.test.d.ts

@@ -0,0 +1 @@
+export {};