halo-record 0.1.0

package/dist/integrations/common.d.ts

@@ -0,0 +1,53 @@
+import { type HaloRecord, type Source } from "../record.ts";
+export type ActionClass = "connector" | "exec" | "data_write" | "data_read" | "network" | "other";
+export declare const ACTION_TYPE_BY_CLASS: Record<ActionClass, string>;
+export declare const CATEGORY_BY_CLASS: Record<ActionClass, string>;
+export declare function classifyTool(toolName: string | null | undefined): ActionClass;
+export declare function deriveScope(cls: ActionClass, toolName: string): string;
+export declare function deriveOutcome(response: unknown, error?: unknown): Record<string, unknown>;
+export interface RecorderLike {
+    append(record: HaloRecord): HaloRecord;
+}
+export interface ToolCallOptions {
+    response?: unknown;
+    error?: unknown;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    cls?: ActionClass;
+    actionType?: string;
+    category?: string;
+    scope?: string;
+    sessionId?: string;
+    decision?: string;
+    approver?: string;
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    source?: string | Partial<Source> | null;
+    summaries?: boolean;
+}
+export interface ModelCallOptions {
+    provider: string;
+    model: string;
+    zdr?: boolean;
+    purpose?: string;
+    messages?: number;
+    response?: unknown;
+    error?: unknown;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    sessionId?: string;
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    source?: string | Partial<Source> | null;
+    summaries?: boolean;
+}
+export declare function recordModelCall(recorder: RecorderLike, opts: ModelCallOptions): HaloRecord;
+export declare function recordToolCall(recorder: RecorderLike, toolName: string, toolInput?: unknown, opts?: ToolCallOptions): HaloRecord;

package/dist/integrations/common.js

@@ -0,0 +1,134 @@
+/* Shared, framework-independent core for the adapters — port of the Python
+   integrations/_common.py funnel. Every adapter ultimately does the same
+   thing: take a tool name, its input, and an outcome (return value or error),
+   and append one Halo Runtime Record. No framework imports here. */
+import { inputHash } from "../canon.js";
+import { redactText } from "../redact.js";
+import { build } from "../record.js";
+export const ACTION_TYPE_BY_CLASS = {
+    connector: "tool_call",
+    exec: "tool_call",
+    data_write: "write",
+    data_read: "read",
+    network: "network",
+    other: "tool_call",
+};
+export const CATEGORY_BY_CLASS = {
+    connector: "security",
+    exec: "security",
+    data_write: "safety",
+    data_read: "privacy",
+    network: "security",
+    other: "security",
+};
+/* Map an arbitrary tool name to a Halo action class. Never returns null
+   (adapters decide what to skip) — an unrecognized tool is a generic
+   "connector" call, the safe default for a trust-boundary action whose nature
+   we can't infer from the name alone. */
+export function classifyTool(toolName) {
+    if (!toolName)
+        return "connector";
+    if (toolName.startsWith("mcp__") || toolName.startsWith("mcp:"))
+        return "connector";
+    const lowered = toolName.toLowerCase();
+    if (["bash", "shell", "exec", "python", "code_interpreter"].includes(lowered))
+        return "exec";
+    if (["write", "edit", "write_file", "create_file", "put"].includes(lowered))
+        return "data_write";
+    if (["read", "glob", "grep", "ls", "read_file", "list", "get"].includes(lowered))
+        return "data_read";
+    if (["webfetch", "websearch", "fetch", "search", "http", "browse"].includes(lowered))
+        return "network";
+    return "connector";
+}
+export function deriveScope(cls, toolName) {
+    if (cls === "connector") {
+        const parts = toolName.split("__");
+        const server = parts.length > 1 ? parts[1] : "mcp";
+        return "mcp:" + server;
+    }
+    return { data_read: "fs.read", data_write: "fs.write", exec: "exec", network: "network" }[cls] ?? "tool";
+}
+function extractText(obj, depth = 0) {
+    if (depth > 6)
+        return "";
+    if (typeof obj === "string")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map((i) => extractText(i, depth + 1)).join(" ");
+    if (obj !== null && typeof obj === "object") {
+        return Object.values(obj).map((v) => extractText(v, depth + 1)).join(" ");
+    }
+    return String(obj);
+}
+/* Deterministic outcome block: what the call actually did. status is "error"
+   only on a thrown error or an explicit error marker in the response — never
+   inferred (ledger, not classifier). The full response is hashed into the
+   chain; only a redacted summary is stored, never the raw content. */
+export function deriveOutcome(response, error) {
+    if (error !== undefined && error !== null) {
+        return {
+            status: "error",
+            summary: redactText(String(error)).slice(0, 200),
+            hash: inputHash({ error: String(error) }),
+        };
+    }
+    let status = "ok";
+    if (response !== null && typeof response === "object" && !Array.isArray(response)) {
+        const r = response;
+        if (r["is_error"] || r["error"] || r["status"] === "error")
+            status = "error";
+    }
+    const out = { status, hash: inputHash(response ?? null) };
+    const summary = redactText(extractText(response ?? "")).slice(0, 200);
+    if (summary)
+        out["summary"] = summary;
+    return out;
+}
+/* Record one LLM generation as a first-class action. The buyer's first
+   question about a bought agent is "which model saw my data, and was it
+   allowed to keep it?" — so model calls get their own loud entry:
+   tool=model.generate, scope=model:<provider>, category privacy, with
+   provider / model / zero-data-retention / purpose in the (hashed +
+   summarized) input. Raw prompts and completions never enter the record. */
+export function recordModelCall(recorder, opts) {
+    const toolInput = { provider: opts.provider, model: opts.model };
+    if (opts.zdr !== undefined)
+        toolInput["zdr"] = Boolean(opts.zdr);
+    if (opts.purpose)
+        toolInput["purpose"] = opts.purpose;
+    if (opts.messages !== undefined)
+        toolInput["messages"] = opts.messages;
+    return recordToolCall(recorder, "model.generate", toolInput, {
+        response: opts.response,
+        error: opts.error,
+        agent: opts.agent,
+        actionType: "tool_call",
+        category: "privacy",
+        scope: "model:" + opts.provider,
+        sessionId: opts.sessionId ?? "local",
+        subject: opts.subject,
+        source: opts.source,
+        summaries: opts.summaries ?? true,
+    });
+}
+/* Build and append one record for a completed tool call — the single funnel
+   every adapter goes through, so classification, scope derivation, redaction,
+   and hashing behave identically regardless of ecosystem. */
+export function recordToolCall(recorder, toolName, toolInput, opts = {}) {
+    const cls = opts.cls ?? classifyTool(toolName);
+    const record = build(opts.actionType ?? ACTION_TYPE_BY_CLASS[cls] ?? "tool_call", opts.category ?? CATEGORY_BY_CLASS[cls] ?? "security", {
+        tool: toolName,
+        toolInput,
+        sessionId: opts.sessionId ?? "local",
+        agent: opts.agent,
+        scope: opts.scope ?? deriveScope(cls, toolName),
+        decision: opts.decision ?? "allowed",
+        approver: opts.approver,
+        outcome: deriveOutcome(opts.response, opts.error),
+        subject: opts.subject,
+        source: opts.source,
+        summaries: opts.summaries ?? true,
+    });
+    return recorder.append(record);
+}

package/dist/integrations/langchain.d.ts

@@ -0,0 +1,26 @@
+import { type RecorderLike } from "./common.ts";
+import type { Source } from "../record.ts";
+export interface LangChainHandlerOptions {
+    category?: string;
+    scope?: string;
+    sessionId?: string;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    source?: string | Partial<Source>;
+    summaries?: boolean;
+}
+export declare function createLangChainHandler(recorder: RecorderLike, opts?: LangChainHandlerOptions): {
+    name: string;
+    handleToolStart(tool: {
+        name?: string;
+        id?: string[];
+    } | undefined, input: string, runId: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(err: unknown, runId: string): void;
+};

package/dist/integrations/langchain.js

@@ -0,0 +1,49 @@
+/* LangChain.js / LangGraph.js adapter.
+
+   Returns a plain callback-handler object (LangChain.js accepts handler
+   objects in the `callbacks` array — no subclassing, no dependency on the
+   langchain package):
+
+       import { Recorder } from "halo-record";
+       import { createLangChainHandler } from "halo-record";
+
+       const rec = new Recorder("audit.jsonl");
+       await agent.invoke(inputs, { callbacks: [createLangChainHandler(rec)] });
+
+   Mirrors the Python HaloCallbackHandler: tool calls keyed by runId, one
+   record emitted on end or error. */
+import { recordToolCall } from "./common.js";
+const AGENT = { id: "langchain", name: "langchain" };
+export function createLangChainHandler(recorder, opts = {}) {
+    const pending = new Map();
+    const emit = (runId, output, error) => {
+        const p = pending.get(runId);
+        if (!p)
+            return;
+        pending.delete(runId);
+        recordToolCall(recorder, p.tool, p.input, {
+            response: output,
+            error,
+            agent: opts.agent ?? AGENT,
+            category: opts.category,
+            scope: opts.scope,
+            sessionId: opts.sessionId ?? "local",
+            subject: opts.subject,
+            source: opts.source ?? "langchain",
+            summaries: opts.summaries ?? true,
+        });
+    };
+    return {
+        name: "halo-record",
+        handleToolStart(tool, input, runId) {
+            const name = tool?.name ?? (Array.isArray(tool?.id) ? tool.id[tool.id.length - 1] : undefined) ?? "tool";
+            pending.set(runId, { tool: name, input });
+        },
+        handleToolEnd(output, runId) {
+            emit(runId, output);
+        },
+        handleToolError(err, runId) {
+            emit(runId, undefined, err);
+        },
+    };
+}

package/dist/integrations/mcp.d.ts

@@ -0,0 +1,31 @@
+import { type RecorderLike } from "./common.ts";
+export interface McpOptions {
+    server?: string;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    sessionId?: string;
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    summaries?: boolean;
+}
+export declare function recordMcpCall(recorder: RecorderLike, name: string, args: unknown, opts?: McpOptions & {
+    response?: unknown;
+    error?: unknown;
+}): import("../record.ts").HaloRecord;
+interface CallToolParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+interface McpClientLike {
+    callTool(params: CallToolParams, ...rest: unknown[]): Promise<unknown>;
+}
+export declare function instrumentMcpClient<T extends McpClientLike>(client: T, recorder: RecorderLike, opts?: McpOptions): T;
+type ToolHandler = (request: {
+    params: CallToolParams;
+}, ...rest: unknown[]) => Promise<unknown>;
+export declare function wrapMcpToolHandler(handler: ToolHandler, recorder: RecorderLike, opts?: McpOptions): ToolHandler;
+export {};

package/dist/integrations/mcp.js

@@ -0,0 +1,92 @@
+/* MCP (Model Context Protocol) adapter — TypeScript SDK.
+
+   Client side: instrument an MCP client so every callTool is recorded:
+
+       import { Recorder, instrumentMcpClient } from "halo-record";
+       const rec = new Recorder("audit.jsonl");
+       instrumentMcpClient(client, rec, { server: "gmail" });
+
+   Server side: wrap a tool handler so calls are recorded where they execute:
+
+       server.setRequestHandler(CallToolRequestSchema,
+         wrapMcpToolHandler(handler, rec, { server: "gmail" }));
+
+   Tool names are normalized to mcp__<server>__<name> so they classify as
+   connectors with scope mcp:<server> — the same shape the Python adapter and
+   the Claude Code hook produce, so reports look identical across on-ramps. */
+import { recordToolCall } from "./common.js";
+const AGENT = { id: "mcp", name: "mcp" };
+/* Flatten an MCP tool result (content blocks + isError) into the payload
+   shape deriveOutcome understands — mirrors the Python _result_payload. */
+function resultPayload(response) {
+    if (response === null || response === undefined)
+        return { is_error: false };
+    const r = response;
+    const isError = Boolean(r["isError"] ?? r["is_error"]);
+    const textParts = [];
+    const content = r["content"];
+    if (Array.isArray(content)) {
+        for (const item of content) {
+            const t = item?.["text"];
+            if (typeof t === "string")
+                textParts.push(t);
+        }
+    }
+    const payload = { is_error: isError };
+    if (textParts.length)
+        payload["summary"] = textParts.join(" ");
+    return payload;
+}
+function normalizeName(name, server) {
+    return name.startsWith("mcp__") ? name : `mcp__${server}__${name}`;
+}
+/* Record one MCP tool call (use directly when you own the call site). */
+export function recordMcpCall(recorder, name, args, opts = {}) {
+    return recordToolCall(recorder, normalizeName(name, opts.server ?? "mcp"), args, {
+        response: opts.error === undefined ? resultPayload(opts.response) : undefined,
+        error: opts.error,
+        agent: opts.agent ?? AGENT,
+        cls: "connector",
+        sessionId: opts.sessionId ?? "local",
+        subject: opts.subject,
+        source: "mcp",
+        summaries: opts.summaries ?? true,
+    });
+}
+/* Wrap client.callTool so every tool call is recorded. Returns the client
+   (now instrumented). Idempotent: a client is only wrapped once. */
+export function instrumentMcpClient(client, recorder, opts = {}) {
+    const original = client.callTool?.bind(client);
+    if (!original || client.callTool._haloWrapped)
+        return client;
+    const wrapped = async (params, ...rest) => {
+        try {
+            const result = await original(params, ...rest);
+            recordMcpCall(recorder, params.name, params.arguments, { ...opts, response: result });
+            return result;
+        }
+        catch (err) {
+            recordMcpCall(recorder, params.name, params.arguments, { ...opts, error: err });
+            throw err;
+        }
+    };
+    wrapped._haloWrapped = true;
+    client.callTool = wrapped;
+    return client;
+}
+/* Wrap an MCP server CallToolRequest handler so every executed tool call is
+   recorded at the server boundary. */
+export function wrapMcpToolHandler(handler, recorder, opts = {}) {
+    return async (request, ...rest) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await handler(request, ...rest);
+            recordMcpCall(recorder, name, args, { ...opts, response: result });
+            return result;
+        }
+        catch (err) {
+            recordMcpCall(recorder, name, args, { ...opts, error: err });
+            throw err;
+        }
+    };
+}

package/dist/integrations/openaiAgents.d.ts

@@ -0,0 +1,26 @@
+import { type RecorderLike } from "./common.ts";
+import type { Source } from "../record.ts";
+export interface AgentsHooksOptions {
+    category?: string;
+    scope?: string;
+    sessionId?: string;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    source?: string | Partial<Source>;
+    summaries?: boolean;
+}
+interface ToolLike {
+    name?: string;
+    toolName?: string;
+}
+export declare function createAgentsHooks(recorder: RecorderLike, opts?: AgentsHooksOptions): {
+    onToolStart(_context: unknown, _agent: unknown, tool: ToolLike | string): Promise<void>;
+    onToolEnd(_context: unknown, _agent: unknown, tool: ToolLike | string, result: unknown): Promise<void>;
+};
+export {};

package/dist/integrations/openaiAgents.js

@@ -0,0 +1,41 @@
+/* OpenAI Agents SDK (JavaScript) adapter.
+
+   Returns a hooks object whose onToolStart/onToolEnd methods record each tool
+   call — mirrors the Python HaloRunHooks. Pass it wherever the SDK accepts
+   run hooks. No dependency on @openai/agents; the shape is structural:
+
+       import { Recorder, createAgentsHooks } from "halo-record";
+       const rec = new Recorder("audit.jsonl");
+       const hooks = createAgentsHooks(rec);
+       // run(agent, input, { hooks })  — or attach per the SDK version in use
+*/
+import { recordToolCall } from "./common.js";
+const AGENT = { id: "openai_agents", name: "openai_agents" };
+function toolName(tool) {
+    if (typeof tool === "string")
+        return tool;
+    return tool?.name ?? tool?.toolName ?? "tool";
+}
+export function createAgentsHooks(recorder, opts = {}) {
+    const pending = new Map();
+    return {
+        async onToolStart(_context, _agent, tool) {
+            pending.set(typeof tool === "object" ? tool : String(tool), toolName(tool));
+        },
+        async onToolEnd(_context, _agent, tool, result) {
+            const key = typeof tool === "object" ? tool : String(tool);
+            const name = pending.get(key) ?? toolName(tool);
+            pending.delete(key);
+            recordToolCall(recorder, name, undefined, {
+                response: result,
+                agent: opts.agent ?? AGENT,
+                category: opts.category,
+                scope: opts.scope,
+                sessionId: opts.sessionId ?? "local",
+                subject: opts.subject,
+                source: opts.source ?? "openai_agents",
+                summaries: opts.summaries ?? true,
+            });
+        },
+    };
+}

package/dist/integrations/vercel.d.ts

@@ -0,0 +1,38 @@
+import { type RecorderLike } from "./common.ts";
+import type { Source } from "../record.ts";
+export interface VercelOptions {
+    category?: string;
+    scope?: string;
+    sessionId?: string;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    source?: string | Partial<Source>;
+    summaries?: boolean;
+}
+interface VercelToolLike {
+    execute?: (args: unknown, options?: unknown) => Promise<unknown> | unknown;
+    [k: string]: unknown;
+}
+export declare function wrapVercelTools<T extends Record<string, VercelToolLike>>(tools: T, recorder: RecorderLike, opts?: VercelOptions): T;
+interface StepLike {
+    toolCalls?: Array<{
+        toolCallId?: string;
+        toolName?: string;
+        args?: unknown;
+        input?: unknown;
+    }>;
+    toolResults?: Array<{
+        toolCallId?: string;
+        toolName?: string;
+        result?: unknown;
+        output?: unknown;
+    }>;
+}
+export declare function createStepRecorder(recorder: RecorderLike, opts?: VercelOptions): (step: StepLike) => void;
+export {};

package/dist/integrations/vercel.js

@@ -0,0 +1,85 @@
+/* Vercel AI SDK adapter.
+
+   Two on-ramps, both boundary-captured:
+
+   1. Wrap your tools object — every execute() is recorded, including errors:
+
+        import { Recorder, wrapVercelTools } from "halo-record";
+        const rec = new Recorder("audit.jsonl");
+        const result = await generateText({ model, tools: wrapVercelTools(tools, rec), ... });
+
+   2. Or record from onStepFinish (no tool wrapping; pairs toolCalls with
+      toolResults per step):
+
+        await generateText({ model, tools,
+          onStepFinish: createStepRecorder(rec) });
+
+   No dependency on the `ai` package; shapes are structural. */
+import { recordToolCall } from "./common.js";
+const AGENT = { id: "vercel_ai", name: "vercel_ai" };
+/* Wrap each tool's execute so the call is recorded where it runs. Tools
+   without an execute function (client-side tools) pass through untouched. */
+export function wrapVercelTools(tools, recorder, opts = {}) {
+    const out = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        if (typeof tool?.execute !== "function") {
+            out[name] = tool;
+            continue;
+        }
+        const original = tool.execute.bind(tool);
+        out[name] = {
+            ...tool,
+            execute: async (args, options) => {
+                try {
+                    const result = await original(args, options);
+                    recordToolCall(recorder, name, args, {
+                        response: result,
+                        agent: opts.agent ?? AGENT,
+                        category: opts.category,
+                        scope: opts.scope,
+                        sessionId: opts.sessionId ?? "local",
+                        subject: opts.subject,
+                        source: opts.source ?? "vercel_ai",
+                        summaries: opts.summaries ?? true,
+                    });
+                    return result;
+                }
+                catch (err) {
+                    recordToolCall(recorder, name, args, {
+                        error: err,
+                        agent: opts.agent ?? AGENT,
+                        category: opts.category,
+                        scope: opts.scope,
+                        sessionId: opts.sessionId ?? "local",
+                        subject: opts.subject,
+                        source: opts.source ?? "vercel_ai",
+                        summaries: opts.summaries ?? true,
+                    });
+                    throw err;
+                }
+            },
+        };
+    }
+    return out;
+}
+/* onStepFinish handler: records each toolCall paired with its toolResult.
+   Use when you can't (or don't want to) wrap tool execute functions. */
+export function createStepRecorder(recorder, opts = {}) {
+    return (step) => {
+        const calls = step.toolCalls ?? [];
+        const results = new Map((step.toolResults ?? []).map((r) => [r.toolCallId ?? r.toolName, r.result ?? r.output]));
+        for (const call of calls) {
+            const name = call.toolName ?? "tool";
+            recordToolCall(recorder, name, call.args ?? call.input, {
+                response: results.get(call.toolCallId ?? name),
+                agent: opts.agent ?? AGENT,
+                category: opts.category,
+                scope: opts.scope,
+                sessionId: opts.sessionId ?? "local",
+                subject: opts.subject,
+                source: opts.source ?? "vercel_ai",
+                summaries: opts.summaries ?? true,
+            });
+        }
+    };
+}

package/dist/record.d.ts

@@ -0,0 +1,55 @@
+import { type Finding } from "./redact.ts";
+export declare const SCHEMA_VERSION = "0.1";
+export declare const ACTION_TYPES: Set<string>;
+export declare const CATEGORIES: Set<string>;
+export interface Source {
+    adapter: string;
+    via: string;
+    capture: "captured" | "ingested";
+}
+export declare const SOURCES: Record<string, Source>;
+export declare function normalizeSource(source: string | Partial<Source> | null | undefined): Source | null;
+export interface BuildOptions {
+    tool?: string;
+    toolInput?: unknown;
+    sessionId?: string;
+    agent?: {
+        id: string;
+        name: string;
+    };
+    scope?: string;
+    decision?: string;
+    approver?: string;
+    findings?: Finding[] | null;
+    outcome?: Record<string, unknown> | null;
+    ts?: string;
+    subject?: string | {
+        id: string;
+        name?: string;
+    } | null;
+    source?: string | Partial<Source> | null;
+    summaries?: boolean;
+}
+export type HaloRecord = Record<string, unknown>;
+export declare function build(actionType: string, category: string, opts?: BuildOptions): HaloRecord;
+export declare class Recorder {
+    #private;
+    path: string;
+    constructor(path: string);
+    lastHash(): string;
+    append(record: HaloRecord): HaloRecord;
+    record(actionType: string, category: string, opts?: BuildOptions): HaloRecord;
+}
+export declare class TenantRecorder {
+    directory: string;
+    default: string;
+    private recorders;
+    constructor(directory: string, opts?: {
+        default?: string;
+    });
+    static safe(name: unknown): string;
+    subjectId(record: HaloRecord): string;
+    pathFor(subjectId: string): string;
+    recorderFor(subjectId: string): Recorder;
+    append(record: HaloRecord): HaloRecord;
+}