@flowdot.ai/guardian-agent 0.1.0

package/dist/runtime/multi-rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/runtime/multi-rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC;IACxD;;;OAGG;IACH,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,yCAAyC;IACzC,KAAK,EAAE,eAAe,CAAC;IACvB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,aAAa,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAU1E,CAAC;AA2CF;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;gBAE7C,OAAO,EAAE,uBAAuB;IAY5C;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,aAAa;IAe9D,6DAA6D;IAC7D,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAQnC"}

package/dist/runtime/multi-rate-limiter.js

@@ -0,0 +1,133 @@
+/**
+ * Per-capability token-bucket rate limiter. SPEC §5 extension (v0.3.0+).
+ *
+ * v0.7 of the surface glues used a single global bucket. v0.8 splits the
+ * bucket per {@link CapabilityClass}: read-heavy work doesn't get blocked
+ * by a writes burst, and an exfil pattern (lots of credential reads +
+ * network-egress writes) hits the narrow buckets long before the global
+ * rate.
+ *
+ * A normal-workload session sees zero impact at the conservative defaults
+ * documented below. The buckets only bite on bursts that match the exfil
+ * shape.
+ *
+ * Pure mechanism: N token buckets, one per class. Same arithmetic, more
+ * dimensions.
+ */
+/**
+ * Library-recommended defaults. Tuned to never trip normal CLI workloads
+ * (read/write at human-edit speed, occasional outbound calls) while
+ * catching exfil-shaped bursts in the seconds-window.
+ */
+export const DEFAULT_BUCKETS = {
+    read: { maxCallsPerSecond: 50 },
+    write: { maxCallsPerSecond: 10 },
+    delete: { maxCallsPerSecond: 1 },
+    execute: { maxCallsPerSecond: 5 },
+    'network-egress': { maxCallsPerSecond: 5 },
+    'network-ingress': { maxCallsPerSecond: 50 },
+    credential: { maxCallsPerSecond: 2 },
+    'system-path': { maxCallsPerSecond: 1 },
+    bulk: { maxCallsPerSecond: 2 },
+};
+class Bucket {
+    refillPerMs;
+    capacity;
+    now;
+    tokens;
+    lastRefill;
+    constructor(config, now) {
+        this.refillPerMs = config.maxCallsPerSecond / 1000;
+        this.capacity = config.bucketCapacity ?? config.maxCallsPerSecond;
+        this.now = now;
+        this.tokens = this.capacity;
+        this.lastRefill = this.now();
+    }
+    tryConsume() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return { allowed: true };
+        }
+        const needed = 1 - this.tokens;
+        const retryAfterMs = Math.ceil(needed / this.refillPerMs);
+        return { allowed: false, retryAfterMs };
+    }
+    /** Visible for tests. */
+    currentTokens() {
+        this.refill();
+        return this.tokens;
+    }
+    refill() {
+        const t = this.now();
+        const elapsed = t - this.lastRefill;
+        if (elapsed <= 0)
+            return;
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillPerMs);
+        this.lastRefill = t;
+    }
+}
+/**
+ * Per-capability rate limiter. One {@link Bucket} per class; multi-class
+ * tools consume from every relevant bucket atomically (first denial wins;
+ * earlier-class buckets already consumed are NOT refunded).
+ *
+ * "First denial wins, no refund" matches the safety-conservative
+ * interpretation: a multi-class tool that's blocked on its rarest
+ * capability is fully blocked. The slightly-tighter accounting on
+ * already-consumed buckets is acceptable because it errs on the side of
+ * slowing the caller (not letting more through).
+ */
+export class MultiRateLimiter {
+    buckets = new Map();
+    defaultBucket;
+    now;
+    configMap;
+    defaultConfig;
+    constructor(options) {
+        this.now = options.now ?? Date.now;
+        this.configMap = new Map(Object.entries(options.buckets));
+        this.defaultConfig = options.defaultBucket;
+        if (this.defaultConfig !== undefined) {
+            this.defaultBucket = new Bucket(this.defaultConfig, this.now);
+        }
+        for (const [cls, cfg] of this.configMap.entries()) {
+            this.buckets.set(cls, new Bucket(cfg, this.now));
+        }
+    }
+    /**
+     * Attempt to consume one token from every relevant bucket. If ANY bucket
+     * is empty, return the FIRST class to deny (in iteration order of
+     * `classes`). Tokens already consumed from earlier classes in this call
+     * are not refunded — see class JSDoc.
+     *
+     * `unknown` (or any class not in `buckets` and no `defaultBucket`)
+     * passes through allowed.
+     */
+    tryConsume(classes) {
+        for (const cls of classes) {
+            let bucket = this.buckets.get(cls);
+            if (!bucket && this.defaultBucket) {
+                bucket = this.defaultBucket;
+            }
+            if (!bucket)
+                continue; // no policy for this class → allowed
+            const r = bucket.tryConsume();
+            if (!r.allowed) {
+                return { allowed: false, class: cls, retryAfterMs: r.retryAfterMs };
+            }
+        }
+        return { allowed: true };
+    }
+    /** Current token count per class (tests + introspection). */
+    snapshot() {
+        const out = {};
+        for (const [cls, bucket] of this.buckets.entries()) {
+            out[cls] = bucket.currentTokens();
+        }
+        if (this.defaultBucket)
+            out['_default'] = this.defaultBucket.currentTokens();
+        return out;
+    }
+}
+//# sourceMappingURL=multi-rate-limiter.js.map

package/dist/runtime/multi-rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-rate-limiter.js","sourceRoot":"","sources":["../../src/runtime/multi-rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,94 @@
+/**
+ * GuardianRuntime — the orchestrator. SPEC §4 / §5.
+ *
+ * v0.1.0 scope: tool wrapping + audit emission + EStopLocal coordination.
+ * Policy and gate are introduced in v0.2/v0.3; v0.1 emits a pre-approved
+ * policy_check + tool_result for every tool call so the wire shape is correct
+ * even before policy enforcement is wired.
+ */
+import type { AuditLogWriter } from '../audit/writer.js';
+import type { ModelAttribution } from '../types.js';
+import type { EStopLocal } from '../estop/local.js';
+import type { EStopPressOptions } from '../estop/types.js';
+import { type HoneytokenSet } from './honeytokens.js';
+import { CapabilityWindow, type CapabilityClass, type CapabilityRule } from './capability.js';
+import { type OperatorConfirmationGate } from '../gate/two-key.js';
+export interface GuardianRuntimeOptions {
+    agentId: string;
+    sessionId?: string;
+    audit: AuditLogWriter;
+    estop?: EStopLocal;
+    defaultModel?: ModelAttribution;
+    /**
+     * Honeytoken set scanned against every tool call. A hit fires
+     * `x_honeytoken_triggered` + presses the EStop (if configured) + throws
+     * `GuardianHaltedError`. SPEC §11. v0.3.0+.
+     */
+    honeytokens?: HoneytokenSet;
+    /**
+     * Capability rules evaluated after every dispatched tool call. v0.8 ships
+     * Yellow-line only (audit-row, no behavior change). SPEC §4. v0.3.0+.
+     */
+    capabilityRules?: CapabilityRule[];
+    /**
+     * Two-key operator gate. When set, tools marked
+     * `requiresOperatorConfirmation: true` will suspend pending operator
+     * approval. SPEC §4.5. v0.4.0+.
+     */
+    operatorGate?: OperatorConfirmationGate;
+    /** Default timeout for operator confirmations. Default 5 minutes. */
+    operatorTimeoutMs?: number;
+}
+export interface ToolOptions {
+    name?: string;
+    model?: ModelAttribution;
+    /**
+     * Capability classes this tool exercises. The runtime feeds these into
+     * the {@link CapabilityWindow} after each dispatch so rule combinations
+     * can fire `x_capability_yellow` (v0.8) / `x_capability_redline` (v0.10).
+     *
+     * Untagged tools are recorded with `['unknown']` so they participate in
+     * window accounting but never match consumer-defined combinations
+     * (unless a rule deliberately names `'unknown'`).
+     */
+    capabilities?: CapabilityClass[];
+    /**
+     * When true, the runtime suspends the call before dispatch and calls
+     * the configured `operatorGate`. The gate's `denied` response (including
+     * timeout-as-denied) throws `GuardianHaltedError`. SPEC §4.5. v0.4.0+.
+     *
+     * Setting this true with no operator gate configured throws — that's
+     * a configuration error, not a runtime fail-closed.
+     */
+    requiresOperatorConfirmation?: boolean;
+    /** Free-text reason recorded on the pending audit row. */
+    operatorConfirmationReason?: string;
+    /** Per-call timeout override (ms). Default = runtime's operatorTimeoutMs. */
+    operatorConfirmationTimeoutMs?: number;
+}
+export declare class GuardianRuntime {
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly audit: AuditLogWriter;
+    readonly estop: EStopLocal | undefined;
+    readonly defaultModel: ModelAttribution | undefined;
+    readonly honeytokens: HoneytokenSet | undefined;
+    readonly capabilityWindow: CapabilityWindow | undefined;
+    readonly operatorGate: OperatorConfirmationGate | undefined;
+    readonly operatorTimeoutMs: number;
+    private sessionOpened;
+    private closed;
+    constructor(options: GuardianRuntimeOptions);
+    /** Open the session. Idempotent. Emits session_open. */
+    openSession(): Promise<void>;
+    /**
+     * Wrap a tool function. Returned function intercepts every call.
+     * SPEC §2.4 — emits the documented event sequence.
+     */
+    tool<Args extends unknown[], Result>(fn: (...args: Args) => Promise<Result> | Result, opts?: ToolOptions): (...args: Args) => Promise<Result>;
+    /** Trip the local emergency-stop. No-op if no EStopLocal was provided. */
+    pressEStop(options: EStopPressOptions): Promise<void>;
+    /** Close the runtime: emit session_close, drain audit queue. Idempotent. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACxC,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC;;;;;;;OAOG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,0DAA0D;IAC1D,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,6EAA6E;IAC7E,6BAA6B,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,WAAW,EAAE,aAAa,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,YAAY,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,sBAAsB;IAe3C,wDAAwD;IAClD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAUlC;;;OAGG;IACH,IAAI,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACjC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EAC/C,IAAI,CAAC,EAAE,WAAW,GACjB,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC;IA8MrC,0EAA0E;IACpE,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3D,4EAA4E;IACtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAY7B"}

package/dist/runtime/runtime.js

@@ -0,0 +1,276 @@
+/**
+ * GuardianRuntime — the orchestrator. SPEC §4 / §5.
+ *
+ * v0.1.0 scope: tool wrapping + audit emission + EStopLocal coordination.
+ * Policy and gate are introduced in v0.2/v0.3; v0.1 emits a pre-approved
+ * policy_check + tool_result for every tool call so the wire shape is correct
+ * even before policy enforcement is wired.
+ */
+import { ulid } from 'ulidx';
+import { GuardianHaltedError } from '../errors.js';
+import { checkHoneytoken } from './honeytokens.js';
+import { CapabilityWindow } from './capability.js';
+import { awaitWithTimeout, newGateId, } from '../gate/two-key.js';
+export class GuardianRuntime {
+    agentId;
+    sessionId;
+    audit;
+    estop;
+    defaultModel;
+    honeytokens;
+    capabilityWindow;
+    operatorGate;
+    operatorTimeoutMs;
+    sessionOpened = false;
+    closed = false;
+    constructor(options) {
+        this.agentId = options.agentId;
+        this.sessionId = options.sessionId ?? 'sess_' + ulid();
+        this.audit = options.audit;
+        this.estop = options.estop;
+        this.defaultModel = options.defaultModel;
+        this.honeytokens = options.honeytokens;
+        this.capabilityWindow =
+            options.capabilityRules && options.capabilityRules.length > 0
+                ? new CapabilityWindow({ rules: options.capabilityRules })
+                : undefined;
+        this.operatorGate = options.operatorGate;
+        this.operatorTimeoutMs = options.operatorTimeoutMs ?? 5 * 60 * 1000;
+    }
+    /** Open the session. Idempotent. Emits session_open. */
+    async openSession() {
+        if (this.sessionOpened)
+            return;
+        this.sessionOpened = true;
+        await this.audit.append({
+            kind: 'session_open',
+            status: 'approved',
+            initiator: 'system',
+        });
+    }
+    /**
+     * Wrap a tool function. Returned function intercepts every call.
+     * SPEC §2.4 — emits the documented event sequence.
+     */
+    tool(fn, opts) {
+        const toolName = opts?.name ?? fn.name;
+        if (toolName === '' || toolName === undefined) {
+            throw new Error('tool() requires a name (either fn.name or opts.name)');
+        }
+        if (toolName.startsWith('guardian.') ||
+            toolName.startsWith('runtime.') ||
+            toolName.startsWith('internal.')) {
+            throw new Error(`tool name "${toolName}" uses a reserved prefix`);
+        }
+        return async (...args) => {
+            if (!this.sessionOpened) {
+                await this.openSession();
+            }
+            // Honeytoken check fires BEFORE the halt check + audit. A honeytoken
+            // hit is itself a halt trigger: we record x_honeytoken_triggered,
+            // press the estop (if configured), and throw. Subsequent calls then
+            // see the pressed estop and refuse on the normal path.
+            if (this.honeytokens) {
+                const hit = checkHoneytoken(this.honeytokens, toolName, argsToObject(args));
+                if (hit !== null) {
+                    await this.audit.append({
+                        kind: 'x_honeytoken_triggered',
+                        status: 'halted',
+                        initiator: 'system',
+                        tool: { name: toolName, args: argsToObject(args) },
+                        detail: {
+                            set_id: this.honeytokens.id,
+                            hit_kind: hit.kind,
+                            ...(hit.kind === 'value_in_args' ? { token_id: hit.tokenId } : {}),
+                            ...(hit.kind === 'phantom_tool' ? { tool_name: hit.toolName } : {}),
+                        },
+                    });
+                    if (this.estop) {
+                        const reason = hit.kind === 'value_in_args'
+                            ? `honeytoken:${hit.tokenId}`
+                            : `honeytoken:phantom_tool:${hit.toolName}`;
+                        await this.estop.press({ reason, initiator: 'system' });
+                    }
+                    throw new GuardianHaltedError(`tool call rejected: honeytoken triggered (${hit.kind})`, 'honeytoken');
+                }
+            }
+            // Halt check first: if pressed, refuse the call before any audit churn.
+            if (this.estop?.isPressed()) {
+                await this.audit.append({
+                    kind: 'policy_check',
+                    status: 'halted',
+                    initiator: 'system',
+                    tool: { name: toolName, args: argsToObject(args) },
+                    detail: { reason: 'estop' },
+                });
+                throw new GuardianHaltedError(`tool call rejected: emergency stop active`, this.estop.getState().pressedReason);
+            }
+            // Two-key operator authorization. SPEC §4.5. Fires BEFORE tool_call
+            // (pending_operator means we haven't decided to dispatch yet).
+            // Sequence: pending_operator → gate awaits → approved or denied,
+            // all three rows share the same gate_id for correlation.
+            if (opts?.requiresOperatorConfirmation) {
+                if (!this.operatorGate) {
+                    throw new Error(`tool ${JSON.stringify(toolName)} requires operator confirmation but no operatorGate is configured on the runtime`);
+                }
+                const gateId = newGateId();
+                const timeoutMs = opts.operatorConfirmationTimeoutMs ?? this.operatorTimeoutMs;
+                const reason = opts.operatorConfirmationReason ?? 'unspecified';
+                await this.audit.append({
+                    kind: 'policy_check',
+                    status: 'pending_operator',
+                    initiator: 'system',
+                    tool: { name: toolName, args: argsToObject(args) },
+                    detail: { gate_id: gateId, timeout_ms: timeoutMs, reason },
+                });
+                const response = await awaitWithTimeout(this.operatorGate, {
+                    gate_id: gateId,
+                    tool_name: toolName,
+                    tool_args: argsToObject(args),
+                    reason,
+                    timeout_ms: timeoutMs,
+                    agent_id: this.agentId,
+                    session_id: this.sessionId,
+                });
+                const resolutionDetail = { gate_id: gateId };
+                if (response.operator_id !== undefined) {
+                    resolutionDetail.operator_id = response.operator_id;
+                }
+                if (response.reason !== undefined) {
+                    resolutionDetail.reason = response.reason;
+                }
+                await this.audit.append({
+                    kind: 'policy_check',
+                    status: response.decision,
+                    initiator: 'operator',
+                    tool: { name: toolName, args: argsToObject(args) },
+                    detail: resolutionDetail,
+                });
+                if (response.decision === 'denied') {
+                    throw new GuardianHaltedError(`tool call rejected: operator ${response.reason === 'timeout' ? 'confirmation timed out' : 'denied'}`, `operator:${response.reason ?? 'denied'}`);
+                }
+            }
+            const model = opts?.model ?? this.defaultModel;
+            const capabilities = opts?.capabilities ?? ['unknown'];
+            // Build the shared tool sub-object once so capabilities are present
+            // on every record this dispatch produces (tool_call, policy_check,
+            // tool_result). audit consumers can read the capability tags without
+            // consulting an external tagging table.
+            const toolBase = {
+                name: toolName,
+                args: argsToObject(args),
+                capabilities,
+            };
+            // 1. tool_call (pending)
+            const callRecord = await this.audit.append({
+                kind: 'tool_call',
+                status: 'pending',
+                initiator: 'agent',
+                tool: toolBase,
+                ...(model === undefined ? {} : { model: modelToWire(model) }),
+            });
+            // Capability-window accounting + Yellow-line evaluation. Records
+            // every dispatched call; fires per-rule matches. v0.8: audit-only —
+            // matches do NOT change dispatch behavior. The matches are captured
+            // here so the post-dispatch hook can write `x_capability_yellow`
+            // adjacent to the tool_call event for forensic clarity.
+            const capabilityMatches = this.capabilityWindow
+                ? this.capabilityWindow.record(capabilities, callRecord.event_id)
+                : [];
+            for (const match of capabilityMatches) {
+                await this.audit.append({
+                    kind: (match.level === 'yellow'
+                        ? 'x_capability_yellow'
+                        : 'x_capability_redline'),
+                    status: 'approved',
+                    initiator: 'system',
+                    tool: toolBase,
+                    detail: {
+                        rule_id: match.ruleId,
+                        combination: match.combination,
+                        window_ms: match.window_ms,
+                        contributing_event_ids: match.contributingEventIds,
+                        tool_capabilities: capabilities,
+                    },
+                });
+                // v0.8: Yellow does not change behavior. Red-line auto-stop ships
+                // in v0.10 — explicitly NOT wired here. When v0.10 lands, the
+                // estop.press() call goes inside this `if`.
+            }
+            // 2. policy_check (approved) — v0.1 is fail-open; v0.2 wires real policy.
+            await this.audit.append({
+                kind: 'policy_check',
+                status: 'approved',
+                initiator: 'system',
+                tool: toolBase,
+                detail: { matched_at: 'default' },
+            });
+            // 3. execute
+            const startMs = Date.now();
+            let result;
+            try {
+                result = await fn(...args);
+            }
+            catch (err) {
+                const durationMs = Date.now() - startMs;
+                await this.audit.append({
+                    kind: 'tool_result',
+                    status: 'errored',
+                    initiator: 'system',
+                    tool: { ...toolBase, duration_ms: durationMs },
+                    detail: { error: err instanceof Error ? err.message : String(err) },
+                });
+                throw err;
+            }
+            const durationMs = Date.now() - startMs;
+            await this.audit.append({
+                kind: 'tool_result',
+                status: 'executed',
+                initiator: 'system',
+                tool: { ...toolBase, result, duration_ms: durationMs },
+            });
+            return result;
+        };
+    }
+    /** Trip the local emergency-stop. No-op if no EStopLocal was provided. */
+    async pressEStop(options) {
+        if (!this.estop) {
+            throw new Error('GuardianRuntime constructed without an EStopLocal');
+        }
+        await this.estop.press(options);
+    }
+    /** Close the runtime: emit session_close, drain audit queue. Idempotent. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.sessionOpened) {
+            await this.audit.append({
+                kind: 'session_close',
+                status: 'approved',
+                initiator: 'system',
+            });
+        }
+        await this.audit.close();
+    }
+}
+function argsToObject(args) {
+    // Wire shape requires args to be an object. We wrap positional args as
+    // { "0": ..., "1": ..., ... } for stable serialization.
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        out[String(i)] = args[i];
+    }
+    return out;
+}
+function modelToWire(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        ...(model.surface === undefined ? {} : { surface: model.surface }),
+        ...(model.aggregator === undefined ? {} : { aggregator: model.aggregator }),
+        ...(model.inputTokens === undefined ? {} : { input_tokens: model.inputTokens }),
+        ...(model.outputTokens === undefined ? {} : { output_tokens: model.outputTokens }),
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime/runtime.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared types matching SPEC §2. The wire format the audit log uses on disk.
+ */
+export declare const SPEC_VERSION: "0.2.0";
+export type AuditRecordKind = 'session_open' | 'tool_call' | 'gate_request' | 'gate_response' | 'policy_check' | 'tool_result' | 'estop_press' | 'estop_clear' | 'session_close';
+export type AuditRecordStatus = 'pending' | 'approved' | 'denied' | 'executed' | 'errored' | 'halted'
+/**
+ * Tool dispatch is suspended awaiting operator confirmation. SPEC §4.5
+ * (v0.4.0+). The matching resolution row writes `approved` or `denied`
+ * with the same `detail.gate_id`.
+ */
+ | 'pending_operator';
+export type AuditRecordInitiator = 'operator' | 'agent' | 'system';
+/**
+ * Identifies which model issued a tool call. SPEC §2.3.
+ *
+ * The optional `surface` and `aggregator` fields (v0.7+) extend the basic
+ * `provider/id` pair with the chain that delivered the call:
+ *
+ *   surface       — which FlowDot surface (or third-party harness) is hosting
+ *                   the agent (e.g., 'FlowDot', 'FlowDotMobile', 'cursor').
+ *   aggregator    — the optional intermediary that routed the request
+ *                   (e.g., 'RedPill', 'OpenRouter'). `'direct'` is the
+ *                   convention when no aggregator is in the path.
+ *   provider      — the model vendor (e.g., 'Anthropic', 'OpenAI').
+ *   id            — the specific model id (e.g., 'claude-opus-4.5').
+ *
+ * Rendered as `surface/aggregator/provider/id` (see
+ * `policy/attribution.ts:renderAttributionPath`) for glob-based policy rules.
+ *
+ * Missing segments render as `'*'`. Old call sites that only supply
+ * `{provider, id}` continue to work and render as `*\/*\/<provider>/<id>`.
+ */
+export interface ModelAttribution {
+    provider: string;
+    id: string;
+    surface?: string;
+    aggregator?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * Tool sub-object on relevant event kinds. SPEC §2.3.
+ */
+export interface AuditRecordTool {
+    name: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    durationMs?: number;
+}
+/**
+ * The audit record itself. Every line in the JSONL log is one of these.
+ * Field names match the wire spec (snake_case) for cross-language interop.
+ */
+export interface AuditRecord {
+    v: string;
+    event_id: string;
+    ts: string;
+    agent_id: string;
+    session_id: string;
+    kind: AuditRecordKind;
+    tool?: {
+        name: string;
+        args: Record<string, unknown>;
+        result?: unknown;
+        duration_ms?: number;
+        /**
+         * Capability classes for the dispatched tool. Recorded on `tool_call`
+         * (and forwarded on `tool_result`) so audit consumers can correlate
+         * a call with its declared capabilities without consulting an external
+         * tagging table. SPEC §13.1. v0.3.0+.
+         */
+        capabilities?: string[];
+    };
+    model?: {
+        provider: string;
+        id: string;
+        surface?: string;
+        aggregator?: string;
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+    status: AuditRecordStatus;
+    initiator: AuditRecordInitiator;
+    prev_hash: string;
+    signature?: string | null;
+    /** Optional free-form structured details (e.g., gate decision, estop reason). */
+    detail?: Record<string, unknown>;
+}
+/**
+ * The fields a caller supplies. The writer fills in the rest.
+ */
+export type AuditRecordInput = Omit<AuditRecord, 'v' | 'event_id' | 'ts' | 'agent_id' | 'session_id' | 'prev_hash' | 'signature'> & {
+    agentId?: string;
+    sessionId?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,EAAG,OAAgB,CAAC;AAE7C,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,WAAW,GACX,cAAc,GACd,eAAe,GACf,cAAc,GACd,aAAa,GACb,aAAa,GACb,aAAa,GACb,eAAe,CAAC;AAEpB,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,UAAU,GACV,QAAQ,GACR,UAAU,GACV,SAAS,GACT,QAAQ;AACV;;;;GAIG;GACD,kBAAkB,CAAC;AAEvB,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB;;;;;WAKG;QACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;IACF,KAAK,CAAC,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,oBAAoB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,WAAW,EACX,GAAG,GAAG,UAAU,GAAG,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,CAChF,GAAG;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types matching SPEC §2. The wire format the audit log uses on disk.
+ */
+export const SPEC_VERSION = '0.2.0';
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAgB,CAAC"}