ambitry 0.1.0

package/dist/parse.js

@@ -0,0 +1,197 @@
+import { StringDecoder } from 'node:string_decoder';
+/** Best-effort JSON: a malformed body must degrade, never throw. */
+function tryJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function parseRequest(provider, body) {
+    const json = tryJson(body.toString('utf8'));
+    if (!json)
+        return { model: null, stream: false, toolNames: [] };
+    const toolNames = Array.isArray(json.tools)
+        ? json.tools
+            .map((t) => (provider === 'openai' ? t?.function?.name : t?.name))
+            .filter((n) => typeof n === 'string')
+        : [];
+    return {
+        model: typeof json.model === 'string' ? json.model : null,
+        stream: json.stream === true,
+        toolNames,
+    };
+}
+/**
+ * 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 class ResponseParser {
+    decoder = new StringDecoder('utf8');
+    lineBuffer = '';
+    /** Whole-body text, used only in the non-streaming path. */
+    body = '';
+    model = null;
+    inputTokens = null;
+    outputTokens = null;
+    /** Streaming tool calls, keyed by content-block / choice index. */
+    partial = new Map();
+    done = [];
+    // Written out longhand rather than as parameter properties: Node's
+    // strip-only TypeScript mode rejects those, and running straight from
+    // source with no build step is worth more than the shorthand.
+    provider;
+    streaming;
+    constructor(provider, streaming) {
+        this.provider = provider;
+        this.streaming = streaming;
+    }
+    push(chunk) {
+        const text = this.decoder.write(chunk);
+        if (!this.streaming) {
+            this.body += text;
+            return;
+        }
+        this.lineBuffer += text;
+        const lines = this.lineBuffer.split('\n');
+        // The trailing element is whatever came after the last newline — it may
+        // be an incomplete line, so it stays buffered for the next chunk.
+        this.lineBuffer = lines.pop() ?? '';
+        for (const line of lines)
+            this.handleLine(line);
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('data:'))
+            return;
+        const payload = trimmed.slice(5).trim();
+        if (payload === '' || payload === '[DONE]')
+            return;
+        const event = tryJson(payload);
+        if (!event)
+            return;
+        if (this.provider === 'anthropic')
+            this.anthropicEvent(event);
+        else
+            this.openaiEvent(event);
+    }
+    anthropicEvent(e) {
+        switch (e.type) {
+            case 'message_start':
+                this.model = e.message?.model ?? this.model;
+                this.inputTokens = e.message?.usage?.input_tokens ?? this.inputTokens;
+                // A resumed or cached turn can report output tokens here too.
+                this.outputTokens = e.message?.usage?.output_tokens ?? this.outputTokens;
+                break;
+            case 'content_block_start':
+                if (e.content_block?.type === 'tool_use') {
+                    this.partial.set(e.index, { name: e.content_block.name, json: '' });
+                }
+                break;
+            case 'content_block_delta':
+                if (e.delta?.type === 'input_json_delta') {
+                    const slot = this.partial.get(e.index);
+                    if (slot)
+                        slot.json += e.delta.partial_json ?? '';
+                }
+                break;
+            case 'content_block_stop':
+                this.flush(e.index);
+                break;
+            case 'message_delta':
+                // Cumulative for the message, so last write wins rather than summing.
+                if (typeof e.usage?.output_tokens === 'number')
+                    this.outputTokens = e.usage.output_tokens;
+                if (typeof e.usage?.input_tokens === 'number')
+                    this.inputTokens = e.usage.input_tokens;
+                break;
+        }
+    }
+    openaiEvent(e) {
+        this.model = e.model ?? this.model;
+        if (e.usage) {
+            this.inputTokens = e.usage.prompt_tokens ?? this.inputTokens;
+            this.outputTokens = e.usage.completion_tokens ?? this.outputTokens;
+        }
+        for (const call of e.choices?.[0]?.delta?.tool_calls ?? []) {
+            const index = call.index ?? 0;
+            const slot = this.partial.get(index) ?? { name: '', json: '' };
+            // The name arrives once, on the first fragment; arguments stream after.
+            if (call.function?.name)
+                slot.name = call.function.name;
+            slot.json += call.function?.arguments ?? '';
+            this.partial.set(index, slot);
+        }
+    }
+    flush(index) {
+        const slot = this.partial.get(index);
+        if (!slot)
+            return;
+        this.partial.delete(index);
+        this.done.push({
+            name: slot.name,
+            // Empty is a legitimate no-argument call; anything unparseable is kept
+            // verbatim so the audit log shows what the model actually emitted.
+            input: slot.json === '' ? {} : (tryJson(slot.json) ?? slot.json),
+            index,
+        });
+    }
+    finish() {
+        this.body += this.decoder.end();
+        if (this.streaming) {
+            if (this.lineBuffer)
+                this.handleLine(this.lineBuffer);
+            // OpenAI has no per-call terminator, so anything still open at the end
+            // of the stream is complete by definition.
+            for (const index of [...this.partial.keys()])
+                this.flush(index);
+        }
+        else {
+            this.parseWholeBody();
+        }
+        return {
+            model: this.model,
+            inputTokens: this.inputTokens,
+            outputTokens: this.outputTokens,
+            toolCalls: this.done,
+        };
+    }
+    parseWholeBody() {
+        const json = tryJson(this.body);
+        if (!json)
+            return;
+        this.model = json.model ?? null;
+        if (this.provider === 'anthropic') {
+            this.inputTokens = json.usage?.input_tokens ?? null;
+            this.outputTokens = json.usage?.output_tokens ?? null;
+            const content = json.content ?? [];
+            for (let i = 0; i < content.length; i++) {
+                if (content[i]?.type === 'tool_use') {
+                    this.done.push({ name: content[i].name, input: content[i].input ?? {}, index: i });
+                }
+            }
+            return;
+        }
+        this.inputTokens = json.usage?.prompt_tokens ?? null;
+        this.outputTokens = json.usage?.completion_tokens ?? null;
+        const calls = json.choices?.[0]?.message?.tool_calls ?? [];
+        for (let i = 0; i < calls.length; i++) {
+            const args = calls[i].function?.arguments;
+            this.done.push({
+                name: calls[i].function?.name ?? '',
+                input: typeof args === 'string' ? (args === '' ? {} : (tryJson(args) ?? args)) : (args ?? {}),
+                index: i,
+            });
+        }
+    }
+}

package/dist/policy.d.ts

@@ -0,0 +1,50 @@
+import type { Store } from './db.ts';
+export interface SpendLimits {
+    perHourUsd?: number;
+    perDayUsd?: number;
+}
+export interface Policy {
+    /** Applied when no allow/deny pattern matches. */
+    default: 'allow' | 'deny';
+    tools: {
+        allow: string[];
+        deny: string[];
+    };
+    spend: SpendLimits;
+}
+export declare const DEFAULT_POLICY: Policy;
+export interface Decision {
+    allowed: boolean;
+    /** Human-readable cause, shown in the trace and returned to the agent. */
+    reason: string | null;
+}
+export declare class Controls {
+    private policy;
+    private killed;
+    private killReason;
+    constructor(policy?: Policy);
+    /** True when any rule could reject a tool call. Drives stream buffering. */
+    get enforcing(): boolean;
+    get limits(): SpendLimits;
+    get isKilled(): boolean;
+    kill(reason: string): void;
+    revive(): void;
+    /** Checked before a request is forwarded, so a kill stops spend immediately. */
+    checkRequest(store: Store): Decision;
+    /**
+     * Decide a single tool call.
+     *
+     * Deny wins over allow. If a name matches both lists the safe reading is
+     * that someone intended to carve an exception out of a broad allow, and
+     * the cost of getting that backwards is an action that should not have run.
+     */
+    checkTool(name: string): Decision;
+}
+/**
+ * Read a policy file, filling in defaults for anything absent.
+ *
+ * An unreadable or malformed policy throws rather than falling back to the
+ * permissive default: silently ignoring a typo'd security config is how you
+ * end up believing you have controls that were never loaded.
+ */
+export declare function loadPolicy(path: string): Policy;

package/dist/policy.js

@@ -0,0 +1,141 @@
+import { readFileSync, existsSync } from 'node:fs';
+export const DEFAULT_POLICY = {
+    // Allow-by-default so `npx ambitry` in front of a running agent changes
+    // nothing on the first run. A tool that breaks your agent the moment you
+    // install it never gets a second run — deny-by-default is what the README
+    // recommends once you know which tools you actually use.
+    default: 'allow',
+    tools: { allow: [], deny: [] },
+    spend: {},
+};
+const ALLOWED = { allowed: true, reason: null };
+/**
+ * Glob match supporting `*` only.
+ *
+ * Deliberately not full regex: policy files are security configuration, and
+ * a rule that is easy to misread is a rule that gets written wrong. `*`
+ * covers `delete_*` and `*_admin`, which is the shape real rules take.
+ */
+function matches(pattern, name) {
+    if (pattern === '*')
+        return true;
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`).test(name);
+}
+function matchesAny(patterns, name) {
+    return patterns.find((p) => matches(p, name)) ?? null;
+}
+export class Controls {
+    policy;
+    killed = false;
+    killReason = null;
+    constructor(policy = DEFAULT_POLICY) {
+        this.policy = policy;
+    }
+    /** True when any rule could reject a tool call. Drives stream buffering. */
+    get enforcing() {
+        return this.policy.default === 'deny' || this.policy.tools.deny.length > 0;
+    }
+    get limits() {
+        return this.policy.spend;
+    }
+    get isKilled() {
+        return this.killed;
+    }
+    kill(reason) {
+        this.killed = true;
+        this.killReason = reason;
+    }
+    revive() {
+        this.killed = false;
+        this.killReason = null;
+    }
+    /** Checked before a request is forwarded, so a kill stops spend immediately. */
+    checkRequest(store) {
+        if (this.killed) {
+            return { allowed: false, reason: this.killReason ?? 'Stopped by kill switch' };
+        }
+        const { perHourUsd, perDayUsd } = this.policy.spend;
+        const now = Date.now();
+        if (perHourUsd !== undefined) {
+            const spent = store.spendSince(now - 3_600_000);
+            if (spent >= perHourUsd) {
+                return { allowed: false, reason: `Hourly spend cap reached: $${spent.toFixed(2)} of $${perHourUsd.toFixed(2)}` };
+            }
+        }
+        if (perDayUsd !== undefined) {
+            const spent = store.spendSince(now - 86_400_000);
+            if (spent >= perDayUsd) {
+                return { allowed: false, reason: `Daily spend cap reached: $${spent.toFixed(2)} of $${perDayUsd.toFixed(2)}` };
+            }
+        }
+        return ALLOWED;
+    }
+    /**
+     * Decide a single tool call.
+     *
+     * Deny wins over allow. If a name matches both lists the safe reading is
+     * that someone intended to carve an exception out of a broad allow, and
+     * the cost of getting that backwards is an action that should not have run.
+     */
+    checkTool(name) {
+        const denied = matchesAny(this.policy.tools.deny, name);
+        if (denied)
+            return { allowed: false, reason: `Blocked by deny rule "${denied}"` };
+        const allowed = matchesAny(this.policy.tools.allow, name);
+        if (allowed)
+            return ALLOWED;
+        if (this.policy.default === 'deny') {
+            return { allowed: false, reason: 'Blocked by deny-by-default policy' };
+        }
+        return ALLOWED;
+    }
+}
+/**
+ * Read a policy file, filling in defaults for anything absent.
+ *
+ * An unreadable or malformed policy throws rather than falling back to the
+ * permissive default: silently ignoring a typo'd security config is how you
+ * end up believing you have controls that were never loaded.
+ */
+export function loadPolicy(path) {
+    if (!existsSync(path))
+        return DEFAULT_POLICY;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err.message}`);
+    }
+    if (raw.default !== undefined && raw.default !== 'allow' && raw.default !== 'deny') {
+        throw new Error(`${path}: "default" must be "allow" or "deny", got ${JSON.stringify(raw.default)}`);
+    }
+    const list = (value, field) => {
+        if (value === undefined)
+            return [];
+        if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+            throw new Error(`${path}: "${field}" must be an array of strings`);
+        }
+        return value;
+    };
+    const positive = (value, field) => {
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== 'number' || !(value > 0)) {
+            throw new Error(`${path}: "${field}" must be a positive number`);
+        }
+        return value;
+    };
+    return {
+        default: raw.default ?? DEFAULT_POLICY.default,
+        tools: {
+            allow: list(raw.tools?.allow, 'tools.allow'),
+            deny: list(raw.tools?.deny, 'tools.deny'),
+        },
+        spend: {
+            perHourUsd: positive(raw.spend?.perHourUsd, 'spend.perHourUsd'),
+            perDayUsd: positive(raw.spend?.perDayUsd, 'spend.perDayUsd'),
+        },
+    };
+}

package/dist/pricing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-million-token rates, USD.
+ *
+ * Anthropic rates are first-party API list prices (verified 2026-08-01).
+ * OpenAI rates are NOT bundled: we will not ship guessed numbers for a tool
+ * whose entire value proposition is telling you what your agents actually
+ * cost. Supply them via `pricing.json` (see `loadPricingOverrides`), and
+ * unpriced models simply report `cost_usd: null` rather than a wrong number.
+ */
+export interface Rate {
+    /** USD per 1M input tokens. */
+    input: number;
+    /** USD per 1M output tokens. */
+    output: number;
+    /**
+     * Optional promotional rate that supersedes the above until `until`
+     * (exclusive, ISO date). Anthropic runs these; getting it wrong means
+     * silently misreporting spend on either side of the cutover.
+     */
+    promo?: {
+        input: number;
+        output: number;
+        until: string;
+    };
+}
+export declare function loadPricingOverrides(table: Record<string, Rate>): void;
+/**
+ * Resolve a model id to a rate.
+ *
+ * Providers prefix and suffix model ids freely — Bedrock prepends
+ * `anthropic.`, and callers pin dated snapshots like
+ * `claude-haiku-4-5-20251001`. Match on the longest key that the id
+ * contains so both forms resolve without a separate alias table.
+ */
+export declare function rateFor(model: string | null): Rate | null;
+/**
+ * Cost in USD for one request, or null when we have no rate for the model.
+ *
+ * `at` is the request timestamp, which decides whether a promotional rate
+ * still applies — backfilling old traces must price them as they were billed,
+ * not as they would be billed today.
+ */
+export declare function costUsd(model: string | null, inputTokens: number | null, outputTokens: number | null, at?: number): number | null;
+/** Model ids we can price, for the `ambitry models` CLI listing. */
+export declare function pricedModels(): string[];

package/dist/pricing.js

@@ -0,0 +1,70 @@
+/**
+ * Per-million-token rates, USD.
+ *
+ * Anthropic rates are first-party API list prices (verified 2026-08-01).
+ * OpenAI rates are NOT bundled: we will not ship guessed numbers for a tool
+ * whose entire value proposition is telling you what your agents actually
+ * cost. Supply them via `pricing.json` (see `loadPricingOverrides`), and
+ * unpriced models simply report `cost_usd: null` rather than a wrong number.
+ */
+const ANTHROPIC = {
+    'claude-fable-5': { input: 10, output: 50 },
+    'claude-mythos-5': { input: 10, output: 50 },
+    'claude-opus-5': { input: 5, output: 25 },
+    'claude-opus-4-8': { input: 5, output: 25 },
+    'claude-opus-4-7': { input: 5, output: 25 },
+    'claude-opus-4-6': { input: 5, output: 25 },
+    'claude-sonnet-5': {
+        input: 3,
+        output: 15,
+        promo: { input: 2, output: 10, until: '2026-09-01' },
+    },
+    'claude-sonnet-4-6': { input: 3, output: 15 },
+    'claude-haiku-4-5': { input: 1, output: 5 },
+};
+/** User-supplied rates, merged over the built-ins. */
+let overrides = {};
+export function loadPricingOverrides(table) {
+    overrides = table;
+}
+/**
+ * Resolve a model id to a rate.
+ *
+ * Providers prefix and suffix model ids freely — Bedrock prepends
+ * `anthropic.`, and callers pin dated snapshots like
+ * `claude-haiku-4-5-20251001`. Match on the longest key that the id
+ * contains so both forms resolve without a separate alias table.
+ */
+export function rateFor(model) {
+    if (!model)
+        return null;
+    const table = { ...ANTHROPIC, ...overrides };
+    if (table[model])
+        return table[model];
+    let best = null;
+    for (const key of Object.keys(table)) {
+        if (model.includes(key) && (best === null || key.length > best.length))
+            best = key;
+    }
+    return best ? table[best] : null;
+}
+/**
+ * Cost in USD for one request, or null when we have no rate for the model.
+ *
+ * `at` is the request timestamp, which decides whether a promotional rate
+ * still applies — backfilling old traces must price them as they were billed,
+ * not as they would be billed today.
+ */
+export function costUsd(model, inputTokens, outputTokens, at = Date.now()) {
+    const rate = rateFor(model);
+    if (!rate)
+        return null;
+    const active = rate.promo && at < Date.parse(rate.promo.until)
+        ? { input: rate.promo.input, output: rate.promo.output }
+        : { input: rate.input, output: rate.output };
+    return ((inputTokens ?? 0) * active.input + (outputTokens ?? 0) * active.output) / 1_000_000;
+}
+/** Model ids we can price, for the `ambitry models` CLI listing. */
+export function pricedModels() {
+    return Object.keys({ ...ANTHROPIC, ...overrides }).sort();
+}

package/dist/providers.d.ts

@@ -0,0 +1,32 @@
+export interface Provider {
+    id: string;
+    base: string;
+    /** Path the SDK appends after the base URL the developer configures. */
+    example: string;
+}
+/**
+ * Upstream bases, overridable per provider via `AMBITRY_<ID>_BASE`.
+ *
+ * Read at call time rather than module load so tests can point a provider at
+ * a local stub. Also covers Azure-hosted OpenAI, gateways, and local models
+ * serving a compatible API.
+ */
+export declare const PROVIDERS: Record<string, Provider>;
+export interface Route {
+    provider: Provider;
+    /** Absolute upstream URL, with the /<provider> prefix stripped. */
+    upstream: string;
+}
+/**
+ * Map an inbound request path to an upstream.
+ *
+ * `/anthropic/v1/messages` -> `https://api.anthropic.com/v1/messages`
+ *
+ * Routing by path prefix rather than by inspecting the body keeps this
+ * decision cheap and total: we never have to buffer a request to know where
+ * it goes, which matters because request bodies can be megabytes.
+ */
+export declare function routeFor(rawUrl: string): Route | null;
+/** Strip a header set down to what is safe to persist. */
+export declare function redactHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string>;
+export declare function forwardHeaders(headers: Record<string, string | string[] | undefined>): Headers;

package/dist/providers.js

@@ -0,0 +1,112 @@
+/**
+ * Upstream bases, overridable per provider via `AMBITRY_<ID>_BASE`.
+ *
+ * Read at call time rather than module load so tests can point a provider at
+ * a local stub. Also covers Azure-hosted OpenAI, gateways, and local models
+ * serving a compatible API.
+ */
+export const PROVIDERS = {
+    anthropic: {
+        id: 'anthropic',
+        base: 'https://api.anthropic.com',
+        example: 'base_url="http://localhost:8787/anthropic"',
+    },
+    openai: {
+        id: 'openai',
+        base: 'https://api.openai.com',
+        example: 'base_url="http://localhost:8787/openai/v1"',
+    },
+};
+function baseFor(provider) {
+    return process.env[`AMBITRY_${provider.id.toUpperCase()}_BASE`] ?? provider.base;
+}
+/**
+ * Map an inbound request path to an upstream.
+ *
+ * `/anthropic/v1/messages` -> `https://api.anthropic.com/v1/messages`
+ *
+ * Routing by path prefix rather than by inspecting the body keeps this
+ * decision cheap and total: we never have to buffer a request to know where
+ * it goes, which matters because request bodies can be megabytes.
+ */
+export function routeFor(rawUrl) {
+    const [pathname, query] = rawUrl.split('?');
+    const segments = pathname.split('/').filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    const provider = PROVIDERS[segments[0]];
+    if (!provider)
+        return null;
+    const rest = segments.slice(1).join('/');
+    return {
+        provider,
+        upstream: `${baseFor(provider)}/${rest}${query ? `?${query}` : ''}`,
+    };
+}
+/**
+ * Headers preserved in the trace store.
+ *
+ * This is an allowlist, not a blocklist, and deliberately so: a blocklist
+ * silently leaks the first credential header a provider invents that we
+ * did not think to name. Anything not listed here never reaches disk, so
+ * the failure mode of an unknown header is a missing debug field rather
+ * than a leaked API key.
+ */
+const LOGGABLE_HEADERS = new Set([
+    'content-type',
+    'accept',
+    'user-agent',
+    'anthropic-version',
+    'anthropic-beta',
+    'openai-organization',
+    'openai-beta',
+    'x-stainless-lang',
+    'x-stainless-package-version',
+    'x-stainless-runtime',
+    'x-stainless-runtime-version',
+]);
+/** Strip a header set down to what is safe to persist. */
+export function redactHeaders(headers) {
+    const safe = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const key = name.toLowerCase();
+        if (!LOGGABLE_HEADERS.has(key))
+            continue;
+        safe[key] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    return safe;
+}
+/**
+ * Headers forwarded upstream.
+ *
+ * Credentials pass through untouched — the proxy is transparent to auth and
+ * never mints, stores, or substitutes keys. `host` is dropped so undici sets
+ * it from the upstream URL, and hop-by-hop headers are dropped per RFC 9110;
+ * forwarding `connection` or `transfer-encoding` to a different connection
+ * corrupts the response framing.
+ */
+const HOP_BY_HOP = new Set([
+    'host',
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'content-length',
+]);
+export function forwardHeaders(headers) {
+    const out = new Headers();
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        if (HOP_BY_HOP.has(name.toLowerCase()))
+            continue;
+        out.set(name, Array.isArray(value) ? value.join(', ') : value);
+    }
+    return out;
+}

package/dist/secrets.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Detecting credentials and personal data in outgoing prompts.
+ *
+ * Everything here runs locally and only ever reports *that* something was
+ * found, plus a masked preview. The secret itself is never written to the
+ * trace store — a tool that logs the credentials it catches has moved the
+ * leak rather than closed it.
+ *
+ * The design bias throughout is against false positives. A detector that
+ * fires on ordinary text gets muted within a day, and a muted detector is
+ * worth less than none at all because it also buys false confidence.
+ */
+export type Severity = 'critical' | 'high' | 'medium';
+export interface Finding {
+    kind: string;
+    severity: Severity;
+    /** First and last few characters only; the middle is never retained. */
+    preview: string;
+    count: number;
+}
+export declare function scan(text: string): Finding[];
+/** Walk a parsed request body and scan every string it contains. */
+export declare function scanRequest(body: unknown): Finding[];