@mindburn/helm-ai-kernel 0.5.1

package/dist/adapters/agent-frameworks.test.js

@@ -0,0 +1,196 @@
+import { describe, expect, it, vi } from "vitest";
+import { agentFrameworkAdapters, buildGovernedToolRequest, createAgentFrameworkAdapter, fromAutoGenToolCall, fromCrewAITask, fromLangGraphToolCall, fromLangChainToolCall, fromLlamaIndexToolCall, fromLiteLLMToolCall, fromN8NNodeExecution, fromOpenAIAgentsToolCall, fromPydanticAIToolCall, fromRawMCPToolCall, fromSemanticKernelFunctionCall, fromZapierWebhookCall, toOpenAIFunctionTool, } from "./agent-frameworks.js";
+describe("agent framework adapters", () => {
+    it("catalogs the frameworks tracked against Microsoft AGT coverage", () => {
+        expect(agentFrameworkAdapters.map((adapter) => adapter.framework)).toEqual([
+            "langchain",
+            "langgraph",
+            "autogen",
+            "crewai",
+            "openai-agents",
+            "semantic-kernel",
+            "pydantic-ai",
+            "llamaindex",
+            "litellm",
+            "n8n",
+            "zapier-webhook",
+            "raw-mcp",
+        ]);
+    });
+    it("normalizes LangGraph tool calls", () => {
+        const action = fromLangGraphToolCall({
+            id: "call-lg",
+            name: "web.search",
+            args: { query: "agent governance toolkit" },
+            metadata: { graph: "due-diligence" },
+        });
+        expect(action).toMatchObject({
+            framework: "langgraph",
+            toolName: "web.search",
+            toolCallId: "call-lg",
+            arguments: { query: "agent governance toolkit" },
+            metadata: { graph: "due-diligence" },
+        });
+    });
+    it("normalizes CrewAI task calls", () => {
+        const action = fromCrewAITask({
+            id: "crew-call",
+            task: "research-task",
+            agent: "researcher",
+            tool: { name: "fetch_url", description: "Fetch a URL" },
+            input: { url: "https://example.test" },
+        });
+        expect(action).toMatchObject({
+            framework: "crewai",
+            toolName: "fetch_url",
+            taskId: "research-task",
+            agentId: "researcher",
+            description: "Fetch a URL",
+            arguments: { url: "https://example.test" },
+        });
+    });
+    it("normalizes OpenAI Agents SDK function arguments from JSON", () => {
+        const action = fromOpenAIAgentsToolCall({
+            id: "call-openai",
+            function: {
+                name: "file.write",
+                arguments: '{"path":"/tmp/out.txt","content":"ok"}',
+            },
+        });
+        expect(action).toMatchObject({
+            framework: "openai-agents",
+            toolName: "file.write",
+            toolCallId: "call-openai",
+            arguments: { path: "/tmp/out.txt", content: "ok" },
+        });
+    });
+    it("normalizes PydanticAI and LlamaIndex variants", () => {
+        expect(fromPydanticAIToolCall({
+            tool_call_id: "pd-call",
+            tool_name: "lookup_customer",
+            args: '{"customer_id":"cus_123"}',
+            agent: "support-agent",
+        })).toMatchObject({
+            framework: "pydantic-ai",
+            toolName: "lookup_customer",
+            toolCallId: "pd-call",
+            agentId: "support-agent",
+            arguments: { customer_id: "cus_123" },
+        });
+        expect(fromLlamaIndexToolCall({
+            id: "llama-call",
+            toolName: "retrieve_context",
+            kwargs: ["policy", "evidence"],
+        })).toMatchObject({
+            framework: "llamaindex",
+            toolName: "retrieve_context",
+            toolCallId: "llama-call",
+            arguments: { items: ["policy", "evidence"] },
+        });
+    });
+    it("normalizes the 2026 framework middleware set into pre-dispatch actions", () => {
+        expect(fromLangChainToolCall({
+            id: "lc-call",
+            name: "retriever.lookup",
+            args: { q: "boundary" },
+            runId: "run-lc",
+        })).toMatchObject({
+            framework: "langchain",
+            toolName: "retriever.lookup",
+            runId: "run-lc",
+        });
+        expect(fromAutoGenToolCall({
+            id: "ag-call",
+            tool: "shell.exec",
+            args: { command: "make test" },
+            agent: "coder",
+        })).toMatchObject({ framework: "autogen", toolName: "shell.exec", agentId: "coder" });
+        expect(fromSemanticKernelFunctionCall({
+            pluginName: "Files",
+            functionName: "Write",
+            arguments: { path: "/tmp/out" },
+        })).toMatchObject({ framework: "semantic-kernel", toolName: "Files.Write" });
+        expect(fromLiteLLMToolCall({
+            function: { name: "db.query", arguments: "{}" },
+            model: "gpt-4.1",
+        })).toMatchObject({ framework: "litellm", toolName: "db.query" });
+        expect(fromN8NNodeExecution({
+            id: "n8n-node",
+            node: "http.request",
+            parameters: { url: "https://example.test" },
+            workflowId: "wf-1",
+        })).toMatchObject({ framework: "n8n", toolName: "http.request", runId: "wf-1" });
+        expect(fromZapierWebhookCall({
+            id: "zap-call",
+            action: "crm.update",
+            payload: { id: "lead-1" },
+            zapId: "zap-1",
+        })).toMatchObject({ framework: "zapier-webhook", toolName: "crm.update", runId: "zap-1" });
+        expect(fromRawMCPToolCall({
+            id: "mcp-call",
+            serverId: "srv-1",
+            toolName: "files.read",
+            args: { path: "/tmp/a" },
+            scopes: ["tools.call"],
+        })).toMatchObject({ framework: "raw-mcp", toolName: "files.read", agentId: "srv-1" });
+    });
+    it("builds an OpenAI-compatible HELM request with the original action in the policy prompt", () => {
+        const action = fromOpenAIAgentsToolCall({
+            id: "call-openai",
+            function: {
+                name: "shell.exec",
+                arguments: { command: "npm test" },
+            },
+        });
+        const request = buildGovernedToolRequest(action, {
+            model: "helm-governance",
+        });
+        expect(request.model).toBe("helm-governance");
+        expect(request.temperature).toBe(0);
+        expect(request.tools?.[0]._function?.name).toBe("shell_exec");
+        expect(request.messages[1].content).toContain('"framework": "openai-agents"');
+        expect(request.messages[1].content).toContain('"tool_name": "shell.exec"');
+    });
+    it("submits through the receipt-bearing client path", async () => {
+        const client = {
+            chatCompletionsWithReceipt: vi.fn().mockResolvedValue({
+                response: { id: "chatcmpl-1" },
+                governance: {
+                    receiptId: "receipt-1",
+                    status: "APPROVED",
+                    outputHash: "hash",
+                    lamportClock: 1,
+                    reasonCode: "ALLOW",
+                    decisionId: "decision-1",
+                    proofGraphNode: "node-1",
+                    signature: "sig",
+                    toolCalls: 1,
+                },
+            }),
+        };
+        const adapter = createAgentFrameworkAdapter(client, {
+            model: "helm-governance",
+            metadata: { environment: "test" },
+        });
+        const result = await adapter.submit(fromLangGraphToolCall({
+            name: "search",
+            args: { q: "helm" },
+            metadata: { run: "r1" },
+        }));
+        expect(client.chatCompletionsWithReceipt).toHaveBeenCalledTimes(1);
+        expect(result.governance.receiptId).toBe("receipt-1");
+        expect(result.action.metadata).toEqual({ environment: "test", run: "r1" });
+    });
+    it("rejects framework events without a tool name", () => {
+        expect(() => fromLangGraphToolCall({ args: { query: "missing tool" } })).toThrow("langgraph adapter requires a tool name");
+    });
+    it("keeps original tool name in metadata while sanitizing OpenAI function names", () => {
+        const tool = toOpenAIFunctionTool(fromOpenAIAgentsToolCall({
+            function: {
+                name: "browser.open/url",
+                arguments: {},
+            },
+        }));
+        expect(tool._function?.name).toBe("browser_open_url");
+    });
+});

package/dist/client.d.ts

@@ -0,0 +1,244 @@
+import type { ChatCompletionRequest, ChatCompletionResponse, ApprovalRequest, Receipt, Session, VerificationResult, ConformanceRequest, ConformanceResult, VersionInfo, HelmError, ReasonCode, DecisionRequest } from './types.gen.js';
+export type { ReasonCode, HelmError };
+export interface EvidenceEnvelopeExportRequest {
+    manifest_id: string;
+    envelope: 'dsse' | 'jws' | 'in-toto' | 'slsa' | 'sigstore' | 'scitt' | 'cose';
+    native_evidence_hash: string;
+    subject?: string;
+    experimental?: boolean;
+}
+export interface EvidenceEnvelopeManifest {
+    manifest_id: string;
+    envelope: string;
+    native_evidence_hash: string;
+    native_authority: true;
+    subject?: string;
+    statement_hash?: string;
+    payload_type?: string;
+    payload_hash?: string;
+    experimental?: boolean;
+    created_at: string;
+    manifest_hash?: string;
+}
+export interface NegativeBoundaryVector {
+    id: string;
+    category: string;
+    trigger: string;
+    expected_verdict: 'ALLOW' | 'DENY' | 'ESCALATE';
+    expected_reason_code: string;
+    must_emit_receipt: boolean;
+    must_not_dispatch: boolean;
+    must_bind_evidence?: string[];
+}
+export interface McpRegistryDiscoverRequest {
+    server_id: string;
+    name?: string;
+    transport?: string;
+    endpoint?: string;
+    tool_names?: string[];
+    risk?: 'unknown' | 'low' | 'medium' | 'high' | 'critical';
+    reason?: string;
+}
+export interface McpRegistryApprovalRequest {
+    server_id: string;
+    approver_id: string;
+    approval_receipt_id: string;
+    reason?: string;
+}
+export interface McpQuarantineRecord {
+    server_id: string;
+    name?: string;
+    transport?: string;
+    endpoint?: string;
+    tool_names?: string[];
+    risk: 'unknown' | 'low' | 'medium' | 'high' | 'critical';
+    state: 'discovered' | 'quarantined' | 'approved' | 'revoked' | 'expired';
+    discovered_at: string;
+    approved_at?: string;
+    approved_by?: string;
+    approval_receipt_id?: string;
+    revoked_at?: string;
+    expires_at?: string;
+    reason?: string;
+}
+export interface SandboxBackendProfile {
+    name: string;
+    kind: 'wasi-wazero' | 'wasi-wasmtime' | 'native-nsjail' | 'native-gvisor' | 'native-firecracker' | 'hosted-adapter';
+    runtime: string;
+    hosted: boolean;
+    deny_network_by_default: boolean;
+    native_isolation: boolean;
+    experimental?: boolean;
+}
+export interface SandboxGrant {
+    grant_id: string;
+    runtime: string;
+    runtime_version?: string;
+    profile: string;
+    image_digest?: string;
+    template_digest?: string;
+    filesystem_preopens?: Array<{
+        path: string;
+        mode: 'ro' | 'rw';
+        content_hash?: string;
+    }>;
+    env: {
+        mode: 'deny-all' | 'allowlist' | 'redacted';
+        names?: string[];
+        names_hash?: string;
+        redacted?: boolean;
+    };
+    network: {
+        mode: 'deny-all' | 'allowlist';
+        destinations?: string[];
+        cidrs?: string[];
+    };
+    limits?: {
+        memory_bytes?: number;
+        cpu_time?: number;
+        output_bytes?: number;
+        open_files?: number;
+    };
+    declared_at: string;
+    policy_epoch?: string;
+    grant_hash?: string;
+}
+export type SurfaceRecord = Record<string, unknown>;
+export type BoundaryStatus = SurfaceRecord;
+export type BoundaryCapabilitySummary = SurfaceRecord;
+export type ExecutionBoundaryRecord = SurfaceRecord;
+export type BoundaryRecordVerification = SurfaceRecord;
+export type BoundaryCheckpoint = SurfaceRecord;
+export type MCPAuthorizationProfile = SurfaceRecord;
+export type MCPScanRequest = SurfaceRecord;
+export type MCPScanResult = SurfaceRecord;
+export type MCPAuthorizeCallRequest = SurfaceRecord;
+export type SandboxPreflightRequest = SurfaceRecord;
+export type SandboxPreflightResult = SurfaceRecord;
+export type DemoRunResult = SurfaceRecord;
+export type DemoReceiptVerification = SurfaceRecord;
+export type AuthzSnapshot = SurfaceRecord;
+export type ApprovalCeremony = SurfaceRecord;
+export type ApprovalWebAuthnChallenge = SurfaceRecord;
+export type ApprovalWebAuthnAssertion = SurfaceRecord;
+export type BudgetCeiling = SurfaceRecord;
+export type AgentIdentityProfile = SurfaceRecord;
+export type AuthzHealth = SurfaceRecord;
+export type EvidenceEnvelopeVerification = SurfaceRecord;
+export type EvidenceEnvelopePayload = SurfaceRecord;
+export type TelemetryOTelConfig = SurfaceRecord;
+export type TelemetryExportRequest = SurfaceRecord;
+export type TelemetryExportResult = SurfaceRecord;
+export type CoexistenceCapabilityManifest = SurfaceRecord;
+/** Governance metadata extracted from X-Helm-* response headers. */
+export interface GovernanceMetadata {
+    receiptId: string;
+    status: string;
+    outputHash: string;
+    lamportClock: number;
+    reasonCode: string;
+    decisionId: string;
+    proofGraphNode: string;
+    signature: string;
+    toolCalls: number;
+}
+/** Chat completion response with kernel-issued governance metadata. */
+export interface ChatCompletionWithReceipt {
+    response: ChatCompletionResponse;
+    governance: GovernanceMetadata;
+}
+/** Thrown when the HELM API returns a non-2xx response. */
+export declare class HelmApiError extends Error {
+    readonly status: number;
+    readonly reasonCode: ReasonCode;
+    readonly details?: Record<string, unknown>;
+    readonly body?: unknown;
+    constructor(status: number, body: HelmError | unknown);
+}
+export interface HelmClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    tenantId?: string;
+    timeout?: number;
+}
+export declare class HelmClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeout;
+    constructor(config: HelmClientConfig);
+    private request;
+    chatCompletions(req: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+    /**
+     * Send a chat completion request and extract kernel-issued governance metadata
+     * from X-Helm-* response headers. Use this instead of chatCompletions() when
+     * you need the kernel receipt.
+     */
+    chatCompletionsWithReceipt(req: ChatCompletionRequest): Promise<ChatCompletionWithReceipt>;
+    evaluateDecision(req: DecisionRequest | SurfaceRecord): Promise<SurfaceRecord>;
+    runPublicDemo(actionId: string, args?: SurfaceRecord): Promise<DemoRunResult>;
+    verifyPublicDemoReceipt(receipt: SurfaceRecord, expectedReceiptHash: string): Promise<DemoReceiptVerification>;
+    approveIntent(req: ApprovalRequest): Promise<Receipt>;
+    listSessions(limit?: number, offset?: number): Promise<Session[]>;
+    getReceipts(sessionId: string): Promise<Receipt[]>;
+    getReceipt(receiptHash: string): Promise<Receipt>;
+    exportEvidence(sessionId?: string): Promise<Blob>;
+    verifyEvidence(bundle: Blob): Promise<VerificationResult>;
+    replayVerify(bundle: Blob): Promise<VerificationResult>;
+    createEvidenceEnvelopeManifest(req: EvidenceEnvelopeExportRequest): Promise<EvidenceEnvelopeManifest>;
+    listEvidenceEnvelopeManifests(): Promise<EvidenceEnvelopeManifest[]>;
+    getEvidenceEnvelopeManifest(manifestId: string): Promise<EvidenceEnvelopeManifest>;
+    verifyEvidenceEnvelopeManifest(manifestId: string): Promise<EvidenceEnvelopeVerification>;
+    getEvidenceEnvelopePayload(manifestId: string): Promise<EvidenceEnvelopePayload>;
+    getBoundaryStatus(): Promise<BoundaryStatus>;
+    listBoundaryCapabilities(): Promise<BoundaryCapabilitySummary[]>;
+    listBoundaryRecords(query?: Record<string, string | number | undefined>): Promise<ExecutionBoundaryRecord[]>;
+    getBoundaryRecord(recordId: string): Promise<ExecutionBoundaryRecord>;
+    verifyBoundaryRecord(recordId: string): Promise<BoundaryRecordVerification>;
+    listBoundaryCheckpoints(): Promise<BoundaryCheckpoint[]>;
+    createBoundaryCheckpoint(): Promise<BoundaryCheckpoint>;
+    verifyBoundaryCheckpoint(checkpointId: string): Promise<SurfaceRecord>;
+    conformanceRun(req: ConformanceRequest): Promise<ConformanceResult>;
+    getConformanceReport(reportId: string): Promise<ConformanceResult>;
+    listConformanceReports(): Promise<ConformanceResult[]>;
+    listConformanceVectors(): Promise<NegativeBoundaryVector[]>;
+    listNegativeConformanceVectors(): Promise<NegativeBoundaryVector[]>;
+    listMcpRegistry(): Promise<McpQuarantineRecord[]>;
+    discoverMcpServer(req: McpRegistryDiscoverRequest): Promise<McpQuarantineRecord>;
+    approveMcpServer(req: McpRegistryApprovalRequest): Promise<McpQuarantineRecord>;
+    getMcpRegistryRecord(serverId: string): Promise<McpQuarantineRecord>;
+    approveMcpRegistryRecord(serverId: string, req: Partial<McpRegistryApprovalRequest>): Promise<McpQuarantineRecord>;
+    revokeMcpRegistryRecord(serverId: string, reason?: string): Promise<McpQuarantineRecord>;
+    scanMcpServer(req: MCPScanRequest): Promise<MCPScanResult>;
+    listMcpAuthProfiles(): Promise<MCPAuthorizationProfile[]>;
+    putMcpAuthProfile(profileId: string, profile: MCPAuthorizationProfile): Promise<MCPAuthorizationProfile>;
+    authorizeMcpCall(req: MCPAuthorizeCallRequest): Promise<ExecutionBoundaryRecord>;
+    inspectSandboxGrants(): Promise<SandboxBackendProfile[]>;
+    inspectSandboxGrants(runtime: string, profile?: string, policyEpoch?: string): Promise<SandboxGrant>;
+    listSandboxProfiles(): Promise<SandboxBackendProfile[]>;
+    listSandboxGrants(): Promise<SandboxGrant[]>;
+    createSandboxGrant(req: SurfaceRecord): Promise<SandboxGrant>;
+    getSandboxGrant(grantId: string): Promise<SandboxGrant>;
+    verifySandboxGrant(grantId: string): Promise<SandboxPreflightResult>;
+    preflightSandboxGrant(req: SandboxPreflightRequest): Promise<SandboxPreflightResult>;
+    listAgentIdentities(): Promise<AgentIdentityProfile[]>;
+    getAuthzHealth(): Promise<AuthzHealth>;
+    checkAuthz(req: SurfaceRecord): Promise<AuthzSnapshot>;
+    listAuthzSnapshots(): Promise<AuthzSnapshot[]>;
+    getAuthzSnapshot(snapshotId: string): Promise<AuthzSnapshot>;
+    listApprovalCeremonies(): Promise<ApprovalCeremony[]>;
+    createApprovalCeremony(req: ApprovalCeremony): Promise<ApprovalCeremony>;
+    transitionApprovalCeremony(approvalId: string, action: 'approve' | 'deny' | 'revoke', req?: SurfaceRecord): Promise<ApprovalCeremony>;
+    createApprovalWebAuthnChallenge(approvalId: string, req?: SurfaceRecord): Promise<ApprovalWebAuthnChallenge>;
+    assertApprovalWebAuthnChallenge(approvalId: string, req: ApprovalWebAuthnAssertion): Promise<ApprovalCeremony>;
+    listBudgetCeilings(): Promise<BudgetCeiling[]>;
+    putBudgetCeiling(budgetId: string, req: BudgetCeiling): Promise<BudgetCeiling>;
+    getCoexistenceCapabilities(): Promise<CoexistenceCapabilityManifest>;
+    getTelemetryOTelConfig(): Promise<TelemetryOTelConfig>;
+    exportTelemetry(req: TelemetryExportRequest): Promise<TelemetryExportResult>;
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    version(): Promise<VersionInfo>;
+}
+export default HelmClient;