ambitry 0.1.0

package/dist/db.js

@@ -0,0 +1,137 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+const SCHEMA = `
+create table if not exists traces (
+  id            text primary key,
+  started_at    integer not null,
+  ended_at      integer,
+  provider      text not null,
+  path          text not null,
+  model         text,
+  status        integer,
+  streamed      integer not null default 0,
+  input_tokens  integer,
+  output_tokens integer,
+  cost_usd      real,
+  request_json  text not null,
+  response_json text,
+  error         text
+);
+create table if not exists tool_calls (
+  id         text primary key,
+  trace_id   text not null references traces(id),
+  seq        integer not null,
+  name       text not null,
+  input_json text not null,
+  decision   text not null,
+  reason     text
+);
+create table if not exists findings (
+  id        text primary key,
+  trace_id  text not null references traces(id),
+  kind      text not null,
+  severity  text not null,
+  preview   text not null,
+  count     integer not null
+);
+create index if not exists idx_traces_started on traces(started_at desc);
+create index if not exists idx_findings_trace on findings(trace_id);
+create index if not exists idx_tool_calls_trace on tool_calls(trace_id);
+create index if not exists idx_tool_calls_name on tool_calls(name);
+`;
+export class Store {
+    db;
+    constructor(path) {
+        this.db = new DatabaseSync(path);
+        // WAL keeps the dashboard readable while the proxy is mid-write.
+        this.db.exec('pragma journal_mode = WAL');
+        this.db.exec(SCHEMA);
+    }
+    beginTrace(input) {
+        const id = randomUUID();
+        this.db
+            .prepare(`insert into traces (id, started_at, provider, path, model, streamed, request_json)
+         values (?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, Date.now(), input.provider, input.path, input.model, input.streamed ? 1 : 0, JSON.stringify(input.request));
+        return id;
+    }
+    finishTrace(id, patch) {
+        this.db
+            .prepare(`update traces set
+           ended_at = ?, status = ?, input_tokens = ?, output_tokens = ?,
+           cost_usd = ?, response_json = ?, error = ?
+         where id = ?`)
+            .run(Date.now(), patch.status ?? null, patch.inputTokens ?? null, patch.outputTokens ?? null, patch.costUsd ?? null, patch.response === undefined ? null : JSON.stringify(patch.response), patch.error ?? null, id);
+    }
+    recordToolCall(t) {
+        this.db
+            .prepare(`insert into tool_calls (id, trace_id, seq, name, input_json, decision, reason)
+         values (?, ?, ?, ?, ?, ?, ?)`)
+            .run(randomUUID(), t.traceId, t.seq, t.name, JSON.stringify(t.input ?? null), t.decision, t.reason ?? null);
+    }
+    /**
+     * Persist what a scan found.
+     *
+     * Only the kind, severity, and masked preview are stored — never the secret
+     * itself. A tool that logs the credentials it catches has moved the leak,
+     * not closed it.
+     */
+    recordFindings(traceId, findings) {
+        const stmt = this.db.prepare(`insert into findings (id, trace_id, kind, severity, preview, count) values (?, ?, ?, ?, ?, ?)`);
+        for (const f of findings) {
+            stmt.run(randomUUID(), traceId, f.kind, f.severity, f.preview, f.count);
+        }
+    }
+    findingsFor(traceId) {
+        return this.db
+            .prepare(`select kind, severity, preview, count from findings where trace_id = ?`)
+            .all(traceId);
+    }
+    /** Aggregate across recent traffic, for the dashboard headline. */
+    findingsSummary(since) {
+        return this.db
+            .prepare(
+        // min(preview) is arbitrary but stable — one masked sample per kind is
+        // all the dashboard shows, and they are masked anyway.
+        `select f.kind, f.severity, min(f.preview) as preview,
+                sum(f.count) as occurrences, count(distinct f.trace_id) as traces
+         from findings f join traces t on t.id = f.trace_id
+         where t.started_at >= ?
+         group by f.kind, f.severity
+         order by case f.severity when 'critical' then 0 when 'high' then 1 else 2 end, occurrences desc`)
+            .all(since);
+    }
+    /** Total spend since a given epoch-ms timestamp. Used for spend caps. */
+    spendSince(since) {
+        const row = this.db
+            .prepare(`select coalesce(sum(cost_usd), 0) as total from traces where started_at >= ?`)
+            .get(since);
+        return row?.total ?? 0;
+    }
+    /** Tool calls in a window, for evaluating a policy against real history. */
+    toolCallsSince(since) {
+        return this.db
+            .prepare(`select c.name, c.decision, t.started_at
+         from tool_calls c join traces t on t.id = c.trace_id
+         where t.started_at >= ?
+         order by t.started_at asc`)
+            .all(since);
+    }
+    recentTraces(limit = 100) {
+        return this.db
+            .prepare(`select * from traces order by started_at desc limit ?`)
+            .all(limit);
+    }
+    trace(id) {
+        const trace = this.db.prepare(`select * from traces where id = ?`).get(id);
+        if (!trace)
+            return null;
+        const toolCalls = this.db
+            .prepare(`select * from tool_calls where trace_id = ? order by seq asc`)
+            .all(id);
+        return { trace, toolCalls };
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/demo.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Point the proxy at the stub and drive traffic through it.
+ *
+ * Returns a cleanup function. The caller owns the proxy; this only supplies
+ * the fake upstream and the requests.
+ */
+export declare function runDemo(proxyPort: number, write: (s: string) => void): Promise<() => void>;
+/** Policy used in demo mode, so there is something to see being enforced. */
+export declare const DEMO_POLICY: {
+    default: "allow";
+    tools: {
+        allow: never[];
+        deny: string[];
+    };
+    spend: {
+        perDayUsd: number;
+    };
+};

package/dist/demo.js

@@ -0,0 +1,113 @@
+import http from 'node:http';
+// Ordered to tell a story on the dashboard: normal work, a leaked
+// credential, then an action policy stops.
+const SCRIPT = [
+    {
+        label: 'reading the repo',
+        prompt: 'Summarise the open issues in this repository.',
+        tool: { name: 'read_file', input: { path: 'README.md' } },
+        inputTokens: 18_400,
+        outputTokens: 900,
+    },
+    {
+        label: 'searching',
+        prompt: 'Find every caller of the billing module.',
+        tool: { name: 'search_code', input: { query: 'billing.charge(' } },
+        inputTokens: 41_200,
+        outputTokens: 1_600,
+    },
+    {
+        label: 'leaking a credential',
+        prompt: 'Deploy the staging stack. Use AKIAIOSFODNN7EXAMPLE with secret ' +
+            'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY and notify ops@realcompany.com.',
+        tool: { name: 'run_command', input: { cmd: 'terraform apply -auto-approve' } },
+        inputTokens: 22_800,
+        outputTokens: 1_100,
+    },
+    {
+        label: 'attempting a destructive action',
+        prompt: 'Clean up the stale test accounts.',
+        tool: { name: 'delete_user', input: { id: 'u_8842', reason: 'stale' } },
+        inputTokens: 12_500,
+        outputTokens: 700,
+    },
+    {
+        label: 'sending mail',
+        prompt: 'Let the team know the cleanup finished.',
+        tool: { name: 'send_email', input: { to: 'team@realcompany.com', subject: 'Cleanup done' } },
+        inputTokens: 9_300,
+        outputTokens: 400,
+    },
+];
+/** Stub provider returning Anthropic-shaped responses. */
+function startStub() {
+    let turn = 0;
+    const server = http.createServer((req, res) => {
+        req.resume();
+        req.on('end', () => {
+            const t = SCRIPT[Math.min(turn++, SCRIPT.length - 1)];
+            const content = [{ type: 'text', text: 'Working on it.' }];
+            if (t.tool)
+                content.push({ type: 'tool_use', id: `toolu_${turn}`, name: t.tool.name, input: t.tool.input });
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                id: `msg_demo_${turn}`,
+                model: 'claude-opus-5',
+                stop_reason: t.tool ? 'tool_use' : 'end_turn',
+                content,
+                usage: { input_tokens: t.inputTokens, output_tokens: t.outputTokens },
+            }));
+        });
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => resolve({ port: server.address().port, close: () => server.close() }));
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Point the proxy at the stub and drive traffic through it.
+ *
+ * Returns a cleanup function. The caller owns the proxy; this only supplies
+ * the fake upstream and the requests.
+ */
+export async function runDemo(proxyPort, write) {
+    const stub = await startStub();
+    process.env.AMBITRY_ANTHROPIC_BASE = `http://127.0.0.1:${stub.port}`;
+    write(`\n  Running a scripted agent — no API key used, nothing leaves this machine.\n\n`);
+    for (const t of SCRIPT) {
+        // Paced so the dashboard visibly fills rather than appearing all at once.
+        await sleep(700);
+        try {
+            const res = await fetch(`http://127.0.0.1:${proxyPort}/anthropic/v1/messages`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-api-key': 'demo-not-a-real-key' },
+                body: JSON.stringify({
+                    model: 'claude-opus-5',
+                    max_tokens: 1024,
+                    messages: [{ role: 'user', content: t.prompt }],
+                }),
+            });
+            // A denied tool call comes back 200 with the call stripped out, so
+            // status alone would report a blocked action as having succeeded.
+            const text = await res.text();
+            const mark = res.status === 403 ? 'stopped' : text.includes('blocked by policy') ? 'blocked' : 'ok';
+            write(`  ${mark.padEnd(8)} ${t.label}\n`);
+        }
+        catch (err) {
+            write(`  failed   ${t.label} — ${err.message}\n`);
+        }
+    }
+    write(`\n  Open http://localhost:${proxyPort} — you should see a leaked AWS key,\n` +
+        `  a blocked delete_user call, and what the run cost.\n\n` +
+        `  Ctrl-C to stop.\n\n`);
+    return () => {
+        stub.close();
+        delete process.env.AMBITRY_ANTHROPIC_BASE;
+    };
+}
+/** Policy used in demo mode, so there is something to see being enforced. */
+export const DEMO_POLICY = {
+    default: 'allow',
+    tools: { allow: [], deny: ['delete_*', 'send_email'] },
+    spend: { perDayUsd: 5 },
+};

package/dist/dryrun.d.ts

@@ -0,0 +1,30 @@
+import type { Store } from './db.ts';
+import { type Policy } from './policy.ts';
+/**
+ * Evaluate a policy against traffic that already happened.
+ *
+ * Nobody switches on deny-by-default blind — the risk of silently breaking a
+ * working agent is too high, so the safest posture is the one least likely to
+ * be adopted. Answering "what would this have blocked last week" from real
+ * history removes the guesswork, and it is the reason to come back and tune.
+ */
+export interface ToolVerdict {
+    name: string;
+    calls: number;
+    wouldBlock: boolean;
+    reason: string | null;
+    /** True when the current policy already blocks it — no change. */
+    blockedToday: boolean;
+}
+export interface DryRunResult {
+    since: number;
+    totalCalls: number;
+    /** Calls that run today but the candidate policy would stop. */
+    newlyBlocked: number;
+    /** Calls blocked today that the candidate policy would let through. */
+    newlyAllowed: number;
+    tools: ToolVerdict[];
+}
+export declare function dryRun(store: Store, policy: Policy, days: number): DryRunResult;
+/** Render a dry run for the terminal. */
+export declare function formatDryRun(r: DryRunResult, days: number): string;

package/dist/dryrun.js

@@ -0,0 +1,64 @@
+import { Controls } from "./policy.js";
+export function dryRun(store, policy, days) {
+    const since = Date.now() - days * 86_400_000;
+    const calls = store.toolCallsSince(since);
+    const controls = new Controls(policy);
+    // Grouped by name because that is the unit a policy rule addresses; a
+    // per-call listing is unreadable at any real traffic volume.
+    const byName = new Map();
+    for (const c of calls) {
+        const entry = byName.get(c.name) ?? { calls: 0, blockedToday: 0 };
+        entry.calls++;
+        if (c.decision === 'deny')
+            entry.blockedToday++;
+        byName.set(c.name, entry);
+    }
+    let newlyBlocked = 0;
+    let newlyAllowed = 0;
+    const tools = [...byName.entries()]
+        .map(([name, { calls: n, blockedToday }]) => {
+        const decision = controls.checkTool(name);
+        const wouldBlock = !decision.allowed;
+        // Counted per call, not per tool: a rule that stops one call a week and
+        // one that stops four hundred are very different decisions.
+        if (wouldBlock)
+            newlyBlocked += n - blockedToday;
+        else
+            newlyAllowed += blockedToday;
+        return {
+            name,
+            calls: n,
+            wouldBlock,
+            reason: decision.reason,
+            blockedToday: blockedToday > 0,
+        };
+    })
+        .sort((a, b) => Number(b.wouldBlock) - Number(a.wouldBlock) || b.calls - a.calls);
+    return { since, totalCalls: calls.length, newlyBlocked, newlyAllowed, tools };
+}
+/** Render a dry run for the terminal. */
+export function formatDryRun(r, days) {
+    if (r.totalCalls === 0) {
+        return `\n  No tool calls in the last ${days} days — nothing to evaluate.\n\n`;
+    }
+    const lines = [
+        `\n  Policy dry run — ${r.totalCalls} tool call${r.totalCalls === 1 ? '' : 's'} over ${days} days\n`,
+    ];
+    const width = Math.max(...r.tools.map((t) => t.name.length), 4);
+    for (const t of r.tools) {
+        const mark = t.wouldBlock ? 'BLOCK' : 'allow';
+        const note = t.wouldBlock && t.reason ? `  ${t.reason}` : '';
+        lines.push(`  ${mark.padEnd(6)} ${t.name.padEnd(width)}  ${String(t.calls).padStart(4)}×${note}`);
+    }
+    lines.push('');
+    if (r.newlyBlocked > 0) {
+        lines.push(`  ${r.newlyBlocked} call${r.newlyBlocked === 1 ? '' : 's'} that ran would have been stopped.`);
+    }
+    if (r.newlyAllowed > 0) {
+        lines.push(`  ${r.newlyAllowed} call${r.newlyAllowed === 1 ? '' : 's'} blocked today would be let through.`);
+    }
+    if (r.newlyBlocked === 0 && r.newlyAllowed === 0) {
+        lines.push(`  No change against this history.`);
+    }
+    return lines.join('\n') + '\n\n';
+}

package/dist/enforce.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Removing denied tool calls from an upstream response.
+ *
+ * The agent never sees a blocked call, so it cannot execute it. That is the
+ * whole enforcement mechanism, and it is worth being precise about its limit:
+ * it governs tools invoked *through this proxy's LLM traffic*. It is not
+ * network egress control, and it is weaker than a `before_tool_call` hook
+ * inside the agent framework, which sees every call regardless of origin.
+ */
+export interface Denial {
+    index: number;
+    name: string;
+    reason: string;
+}
+/** Rewrite a complete JSON response body with denied calls removed. */
+export declare function filterBody(provider: string, body: string, denials: Denial[]): string;
+/**
+ * Rewrite a buffered SSE stream with denied calls removed.
+ *
+ * Replays the original event text verbatim when nothing is denied, so the
+ * common case is byte-identical to what the upstream sent and no SDK can
+ * tell the proxy was there.
+ */
+export declare function filterStream(provider: string, sse: string, denials: Denial[]): string;

package/dist/enforce.js

@@ -0,0 +1,120 @@
+/**
+ * Removing denied tool calls from an upstream response.
+ *
+ * The agent never sees a blocked call, so it cannot execute it. That is the
+ * whole enforcement mechanism, and it is worth being precise about its limit:
+ * it governs tools invoked *through this proxy's LLM traffic*. It is not
+ * network egress control, and it is weaker than a `before_tool_call` hook
+ * inside the agent framework, which sees every call regardless of origin.
+ */
+function noteFor(denials) {
+    const lines = denials.map((d) => `- ${d.name}: ${d.reason}`);
+    return `[ambitry] ${denials.length} tool call${denials.length === 1 ? '' : 's'} blocked by policy:\n${lines.join('\n')}`;
+}
+/** Rewrite a complete JSON response body with denied calls removed. */
+export function filterBody(provider, body, denials) {
+    if (denials.length === 0)
+        return body;
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        // Unparseable upstream body: fail closed rather than forward something we
+        // could not inspect. A malformed response is not worth passing through.
+        return JSON.stringify({ type: 'error', error: { type: 'ambitry_blocked', message: noteFor(denials) } });
+    }
+    const denied = new Set(denials.map((d) => d.index));
+    if (provider === 'anthropic') {
+        const content = Array.isArray(json.content) ? json.content : [];
+        json.content = content.filter((_, i) => !denied.has(i));
+        json.content.push({ type: 'text', text: noteFor(denials) });
+        // The turn no longer contains tool calls, so leaving stop_reason as
+        // "tool_use" would make the SDK wait for a tool result that never comes.
+        if (json.stop_reason === 'tool_use')
+            json.stop_reason = 'end_turn';
+        return JSON.stringify(json);
+    }
+    const choice = json.choices?.[0];
+    if (choice?.message) {
+        const calls = Array.isArray(choice.message.tool_calls) ? choice.message.tool_calls : [];
+        const kept = calls.filter((_, i) => !denied.has(i));
+        if (kept.length > 0)
+            choice.message.tool_calls = kept;
+        else
+            delete choice.message.tool_calls;
+        choice.message.content = [choice.message.content, noteFor(denials)].filter(Boolean).join('\n\n');
+        if (choice.finish_reason === 'tool_calls')
+            choice.finish_reason = 'stop';
+    }
+    return JSON.stringify(json);
+}
+/**
+ * Rewrite a buffered SSE stream with denied calls removed.
+ *
+ * Replays the original event text verbatim when nothing is denied, so the
+ * common case is byte-identical to what the upstream sent and no SDK can
+ * tell the proxy was there.
+ */
+export function filterStream(provider, sse, denials) {
+    if (denials.length === 0)
+        return sse;
+    const denied = new Set(denials.map((d) => d.index));
+    const out = [];
+    for (const block of sse.split('\n\n')) {
+        if (block.trim() === '')
+            continue;
+        const dataLine = block.split('\n').find((l) => l.trim().startsWith('data:'));
+        const payload = dataLine?.trim().slice(5).trim();
+        if (!payload || payload === '[DONE]') {
+            out.push(block);
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(payload);
+        }
+        catch {
+            out.push(block);
+            continue;
+        }
+        if (provider === 'anthropic') {
+            // Every event carrying a denied block index is dropped whole:
+            // content_block_start, its input_json_deltas, and content_block_stop.
+            if (typeof event.index === 'number' && denied.has(event.index))
+                continue;
+            if (event.type === 'message_delta' && event.delta?.stop_reason === 'tool_use') {
+                event.delta.stop_reason = 'end_turn';
+                out.push(`event: message_delta\ndata: ${JSON.stringify(event)}`);
+                continue;
+            }
+            out.push(block);
+            continue;
+        }
+        const calls = event.choices?.[0]?.delta?.tool_calls;
+        if (Array.isArray(calls)) {
+            const kept = calls.filter((c) => !denied.has(c.index ?? 0));
+            // Dropping the last fragment of a call would leave an empty delta, so
+            // skip the event entirely rather than emit a meaningless one.
+            if (kept.length === 0)
+                continue;
+            event.choices[0].delta.tool_calls = kept;
+            out.push(`data: ${JSON.stringify(event)}`);
+            continue;
+        }
+        out.push(block);
+    }
+    const note = provider === 'anthropic'
+        ? `event: content_block_start\ndata: ${JSON.stringify({ type: 'content_block_start', index: 99, content_block: { type: 'text', text: noteFor(denials) } })}\n\nevent: content_block_stop\ndata: ${JSON.stringify({ type: 'content_block_stop', index: 99 })}`
+        : `data: ${JSON.stringify({ choices: [{ delta: { content: `\n\n${noteFor(denials)}` }, index: 0 }] })}`;
+    // The notice is a content block, so it has to land before the events that
+    // close the message. Appending at the end puts it after `message_delta`
+    // (Anthropic) or `[DONE]` (OpenAI), and SDKs stop collecting content there
+    // — the block would be silently dropped by the very client it warns.
+    const terminal = out.findIndex((b) => b.includes('[DONE]') || b.includes('"message_delta"') || b.includes('"message_stop"'));
+    if (terminal === -1)
+        out.push(note);
+    else
+        out.splice(terminal, 0, note);
+    return out.join('\n\n') + '\n\n';
+}

package/dist/parse.d.ts

@@ -0,0 +1,60 @@
+export interface ToolCall {
+    name: string;
+    /** Parsed arguments, or the raw string when the model emitted invalid JSON. */
+    input: unknown;
+    /**
+     * Content-block index (Anthropic) or choice index (OpenAI).
+     *
+     * Carried so enforcement can drop exactly the events belonging to a denied
+     * call when replaying a buffered stream, rather than discarding the turn.
+     */
+    index: number;
+}
+export interface ParsedRequest {
+    model: string | null;
+    stream: boolean;
+    /** Tools the caller offered the model, not the ones it chose. */
+    toolNames: string[];
+}
+export interface ParsedResponse {
+    model: string | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    toolCalls: ToolCall[];
+}
+export declare function parseRequest(provider: string, body: Buffer): ParsedRequest;
+/**
+ * Accumulates a response — streaming or not — into a ParsedResponse.
+ *
+ * Two things make this fiddly, and both are silent-corruption bugs rather
+ * than crashes, so they are worth naming:
+ *
+ *  1. TCP chunks do not align with SSE event boundaries. A `data:` line can
+ *     be split across two `push()` calls, so we hold a line buffer and only
+ *     process complete lines.
+ *  2. Chunks can split a multi-byte UTF-8 character. `Buffer.toString()` per
+ *     chunk would replace the halves with U+FFFD and corrupt any non-ASCII
+ *     prompt. StringDecoder holds the partial bytes until the rest arrives.
+ */
+export declare class ResponseParser {
+    private decoder;
+    private lineBuffer;
+    /** Whole-body text, used only in the non-streaming path. */
+    private body;
+    private model;
+    private inputTokens;
+    private outputTokens;
+    /** Streaming tool calls, keyed by content-block / choice index. */
+    private partial;
+    private done;
+    private provider;
+    private streaming;
+    constructor(provider: string, streaming: boolean);
+    push(chunk: Buffer): void;
+    private handleLine;
+    private anthropicEvent;
+    private openaiEvent;
+    private flush;
+    finish(): ParsedResponse;
+    private parseWholeBody;
+}