@flowdot.ai/guardian-agent 0.1.0

package/dist/policy/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Policy types. SPEC §3.
+ */
+/** Persistence scope. */
+export type PolicyScope = 'once' | 'session' | 'forever' | 'banned';
+/** Effective decision. */
+export type PolicyDecision = 'allow' | 'deny' | 'prompt';
+/**
+ * Conditional clause: a rule only matches when these model attributes
+ * match the request. Strings are matched with the same shell-style globs
+ * (`*`, `?`, `[seq]`) used for tool names — except `attribution_path`, which
+ * uses flat-glob (where `*` also matches `/`).
+ *
+ * v0.6+. SPEC §3 open question (resolved).
+ *
+ * Multiple fields are conjunctive: the rule matches only when every
+ * provided clause matches.
+ */
+export interface PolicyWhen {
+    /** Match on `model.provider` (e.g., 'anthropic', 'openai', 'ollama'). */
+    'model.provider'?: string;
+    /** Match on `model.id` (e.g., 'claude-*-4.5*', 'gpt-5*', 'llama3*'). */
+    'model.id'?: string;
+    /**
+     * Match on the rendered attribution path
+     * `surface/aggregator/provider/id`. Flat-glob: `*` matches across `/`.
+     * Examples: `'*\/RedPill/*\/*'`, `'FlowDot/*\/Anthropic/claude-*-4.*'`,
+     * `'*claude-opus*'`. See `policy/attribution.ts`.
+     */
+    attribution_path?: string;
+}
+/** A single rule in the policy. */
+export interface PolicyRule {
+    /**
+     * Tool pattern. Supports shell-style globs ( * ? [seq] ). May also be
+     * `category:<name>` to target a category (SPEC §3.7).
+     */
+    tool: string;
+    /** Persistence scope of this rule. */
+    scope: PolicyScope;
+    /**
+     * Decision when the rule matches. Omit for `scope: banned` (implies `deny`).
+     * For `scope: once|session|forever`, defaults to `allow`.
+     */
+    decision?: Exclude<PolicyDecision, 'prompt'>;
+    /** Optional conditional clause. The rule only matches when all entries hold. */
+    when?: PolicyWhen;
+    /** Optional human note. Ignored by the evaluator. */
+    notes?: string;
+}
+/** Loaded policy: defaults + rules. */
+export interface Policy {
+    /** Spec version of the policy file (e.g., '0.2'). */
+    version: string;
+    /** Agent id this policy applies to. */
+    agent_id: string;
+    /** Default behavior when no rule matches. */
+    defaults: {
+        scope: 'prompt' | PolicyScope;
+        decision?: Exclude<PolicyDecision, 'prompt'>;
+    };
+    /** Rules in declaration order. */
+    rules: PolicyRule[];
+}
+/** Result of evaluating a tool name against a policy. */
+export interface PolicyEvaluation {
+    decision: PolicyDecision;
+    matchedRule: PolicyRule | undefined;
+    matchedAt: 'exact' | 'wildcard' | 'category' | 'default';
+    scope: PolicyScope | 'prompt';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/policy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,yBAAyB;AACzB,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpE,0BAA0B;AAC1B,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IAC7C,gFAAgF;IAChF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,MAAM;IACrB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE;QACR,KAAK,EAAE,QAAQ,GAAG,WAAW,CAAC;QAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;KAC9C,CAAC;IACF,kCAAkC;IAClC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,SAAS,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IACzD,KAAK,EAAE,WAAW,GAAG,QAAQ,CAAC;CAC/B"}

package/dist/policy/types.js

@@ -0,0 +1,5 @@
+/**
+ * Policy types. SPEC §3.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/policy/types.js.map

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

package/dist/runtime/capability.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Capability tags + sliding-window combination detection. SPEC §4 extension
+ * (v0.3.0+).
+ *
+ * Each tool is tagged with one or more capability classes (the canonical
+ * set is documented below but consumers can register additional strings).
+ * The supervisor maintains a per-session sliding window of recent tool
+ * calls + their capability sets. Rules describe "suspicious combinations"
+ * — a list of classes that, if all observed within `window_ms`, fire an
+ * event.
+ *
+ * v0.8 ships YELLOW-LINE ONLY. A combination match writes
+ * `x_capability_yellow` to the audit log; dispatch is NOT blocked. The
+ * point is to collect calibration data. Red-line auto-stop ships in v0.10
+ * after the v0.8 corpus shows zero false positives at proposed thresholds.
+ *
+ * Pure mechanism: tag lookup + set membership over a fixed-window event
+ * list. Constant memory per session (oldest events drop as window slides).
+ */
+/**
+ * Canonical capability classes. The string-union form lets consumers extend
+ * with their own strings (e.g., `'database-write'` for a SQL-tool surface)
+ * without forking the library.
+ *
+ * Class meanings (canonical):
+ * - `read`            — pure read of agent-accessible data
+ * - `write`           — local write of agent-accessible data
+ * - `delete`          — destruction of agent-accessible data
+ * - `execute`         — run a subprocess / arbitrary code
+ * - `network-egress`  — outbound network call
+ * - `network-ingress` — accept inbound network call
+ * - `credential`      — read or write credentials
+ * - `system-path`     — touch OS-level paths (`/etc`, `~/.ssh`, etc.)
+ * - `bulk`            — operation over many items (>N, configurable per-tool)
+ * - `unknown`         — fallback for untagged tools
+ */
+export type CapabilityClass = 'read' | 'write' | 'delete' | 'execute' | 'network-egress' | 'network-ingress' | 'credential' | 'system-path' | 'bulk' | 'unknown' | (string & {});
+/**
+ * One rule in the capability-rule set. A rule matches when every class in
+ * `combination` has been observed within the last `window_ms`.
+ *
+ * `level` is `'yellow'` in v0.8 (audit-only). `'red'` (auto-E-stop) lands
+ * in v0.10 once Yellow data justifies thresholds.
+ */
+export interface CapabilityRule {
+    /** Stable id used in audit records. ASCII, short. */
+    id: string;
+    /** Free-form human note. Ignored by the matcher. */
+    description?: string;
+    /** Classes that must all appear within the window. Order is irrelevant. */
+    combination: CapabilityClass[];
+    /** Time window in milliseconds. */
+    window_ms: number;
+    /** v0.8: always 'yellow'. v0.10 adds 'red'. */
+    level: 'yellow' | 'red';
+}
+/**
+ * Event recorded into the sliding window. The supervisor synthesizes these
+ * after every dispatched tool call; they hold only what the matcher needs.
+ */
+export interface CapabilityEvent {
+    /** Wall-clock ms (monotonic preferred when consumer supplies a `now`). */
+    ts: number;
+    /** Capability classes of THIS specific tool call. */
+    classes: CapabilityClass[];
+    /** Audit event_id, copied so a fired rule can cite the contributing events. */
+    eventId: string;
+}
+/**
+ * Result of recording one event. Lists every rule that fired on this event.
+ * Most events fire nothing; this array is typically empty.
+ */
+export interface CapabilityMatch {
+    ruleId: string;
+    level: 'yellow' | 'red';
+    combination: CapabilityClass[];
+    window_ms: number;
+    /** event_ids of the events that contributed to the match, in chronological order. */
+    contributingEventIds: string[];
+}
+export interface CapabilityWindowOptions {
+    rules: CapabilityRule[];
+    /** Override for time source (testing). Defaults to Date.now. */
+    now?: () => number;
+    /**
+     * Maximum events kept in the window irrespective of age. Defensive cap so
+     * a runaway agent can't grow the buffer without bound. Default 10000.
+     */
+    maxEvents?: number;
+}
+/**
+ * Per-session sliding-window state. One instance per supervisor.
+ *
+ * Memory: O(max window_ms × call rate) in the worst case, capped at
+ * `maxEvents`. Events older than the longest rule window are dropped on
+ * every `record` call.
+ */
+export declare class CapabilityWindow {
+    private readonly rules;
+    private readonly now;
+    private readonly maxEvents;
+    private readonly maxWindowMs;
+    private events;
+    constructor(options: CapabilityWindowOptions);
+    /**
+     * Record a tool dispatch + evaluate all rules against the current window.
+     *
+     * Returns the list of rules that fired (often empty). Caller is
+     * responsible for converting fires into audit rows + (in v0.10) E-stop
+     * presses.
+     */
+    record(classes: CapabilityClass[], eventId: string): CapabilityMatch[];
+    /** Snapshot of currently-buffered events (for tests + introspection). */
+    buffered(): readonly CapabilityEvent[];
+    /**
+     * Test whether `rule` is satisfied by the current window ending at `now`.
+     * Returns the contributing event ids on match, null otherwise.
+     *
+     * Algorithm: for each class in `combination`, find the most-recent event
+     * (within the window) that includes that class. If every class found a
+     * contributor, the rule matches.
+     */
+    private evaluateRule;
+}
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/runtime/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,OAAO,GACP,QAAQ,GACR,SAAS,GACT,gBAAgB,GAChB,iBAAiB,GACjB,YAAY,GACZ,aAAa,GACb,MAAM,GACN,SAAS,GACT,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC;IACxB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,MAAM,CAAyB;gBAE3B,OAAO,EAAE,uBAAuB;IAmB5C;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE;IA0BtE,yEAAyE;IACzE,QAAQ,IAAI,SAAS,eAAe,EAAE;IAItC;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;CA0BrB"}

package/dist/runtime/capability.js

@@ -0,0 +1,121 @@
+/**
+ * Capability tags + sliding-window combination detection. SPEC §4 extension
+ * (v0.3.0+).
+ *
+ * Each tool is tagged with one or more capability classes (the canonical
+ * set is documented below but consumers can register additional strings).
+ * The supervisor maintains a per-session sliding window of recent tool
+ * calls + their capability sets. Rules describe "suspicious combinations"
+ * — a list of classes that, if all observed within `window_ms`, fire an
+ * event.
+ *
+ * v0.8 ships YELLOW-LINE ONLY. A combination match writes
+ * `x_capability_yellow` to the audit log; dispatch is NOT blocked. The
+ * point is to collect calibration data. Red-line auto-stop ships in v0.10
+ * after the v0.8 corpus shows zero false positives at proposed thresholds.
+ *
+ * Pure mechanism: tag lookup + set membership over a fixed-window event
+ * list. Constant memory per session (oldest events drop as window slides).
+ */
+/**
+ * Per-session sliding-window state. One instance per supervisor.
+ *
+ * Memory: O(max window_ms × call rate) in the worst case, capped at
+ * `maxEvents`. Events older than the longest rule window are dropped on
+ * every `record` call.
+ */
+export class CapabilityWindow {
+    rules;
+    now;
+    maxEvents;
+    maxWindowMs;
+    events = [];
+    constructor(options) {
+        this.rules = options.rules;
+        this.now = options.now ?? Date.now;
+        this.maxEvents = options.maxEvents ?? 10_000;
+        this.maxWindowMs = this.rules.reduce((m, r) => Math.max(m, r.window_ms), 0);
+        // Validate rule shapes once.
+        for (const r of this.rules) {
+            if (r.combination.length === 0) {
+                throw new Error(`CapabilityRule ${JSON.stringify(r.id)} has empty combination`);
+            }
+            if (r.window_ms <= 0) {
+                throw new Error(`CapabilityRule ${JSON.stringify(r.id)} has non-positive window_ms`);
+            }
+        }
+    }
+    /**
+     * Record a tool dispatch + evaluate all rules against the current window.
+     *
+     * Returns the list of rules that fired (often empty). Caller is
+     * responsible for converting fires into audit rows + (in v0.10) E-stop
+     * presses.
+     */
+    record(classes, eventId) {
+        const ts = this.now();
+        const event = { ts, classes, eventId };
+        this.events.push(event);
+        // Age-based prune.
+        if (this.maxWindowMs > 0) {
+            const cutoff = ts - this.maxWindowMs;
+            while (this.events.length > 0 && this.events[0].ts < cutoff) {
+                this.events.shift();
+            }
+        }
+        // Hard cap.
+        while (this.events.length > this.maxEvents) {
+            this.events.shift();
+        }
+        // Evaluate each rule against the current window.
+        const matches = [];
+        for (const rule of this.rules) {
+            const m = this.evaluateRule(rule, ts);
+            if (m)
+                matches.push(m);
+        }
+        return matches;
+    }
+    /** Snapshot of currently-buffered events (for tests + introspection). */
+    buffered() {
+        return this.events;
+    }
+    /**
+     * Test whether `rule` is satisfied by the current window ending at `now`.
+     * Returns the contributing event ids on match, null otherwise.
+     *
+     * Algorithm: for each class in `combination`, find the most-recent event
+     * (within the window) that includes that class. If every class found a
+     * contributor, the rule matches.
+     */
+    evaluateRule(rule, now) {
+        const cutoff = now - rule.window_ms;
+        const required = new Set(rule.combination);
+        const contributors = new Map();
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            if (ev.ts < cutoff)
+                break;
+            for (const cls of ev.classes) {
+                if (required.has(cls) && !contributors.has(cls)) {
+                    contributors.set(cls, ev);
+                }
+            }
+            if (contributors.size === required.size)
+                break;
+        }
+        if (contributors.size < required.size)
+            return null;
+        // Order contributing events chronologically + dedupe (a single
+        // multi-class event may satisfy several required classes).
+        const ids = Array.from(new Set(Array.from(contributors.values()).sort((a, b) => a.ts - b.ts).map((e) => e.eventId)));
+        return {
+            ruleId: rule.id,
+            level: rule.level,
+            combination: rule.combination,
+            window_ms: rule.window_ms,
+            contributingEventIds: ids,
+        };
+    }
+}
+//# sourceMappingURL=capability.js.map

package/dist/runtime/capability.js.map

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

package/dist/runtime/honeytokens.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Honeytoken detection. SPEC §11 (v0.3.0+).
+ *
+ * The library exposes two zero-false-positive-by-construction defenses:
+ *
+ * 1. **Value match.** Consumer registers a set of decoy strings or regexes
+ *    that should NEVER legitimately appear in a tool call's arguments
+ *    (e.g., a fake `AKIA...` key stashed in a never-read env var, a
+ *    phantom file path `~/.flowdot/keys/recovery.pem` that exists but
+ *    contains only a marker). The matcher walks the canonical-JSON
+ *    representation of every tool call's args; any hit means an agent has
+ *    been probing.
+ *
+ * 2. **Phantom tool.** Consumer registers a tool name that is documented
+ *    internally as "do not call" — never advertised to legitimate agents.
+ *    Any dispatch to that tool name → immediate fire.
+ *
+ * Both modes are deterministic predicates over input. Zero false positives
+ * by construction: if a legitimate workflow ever references a honeytoken,
+ * the operator either misconfigured the set or the workflow actually does
+ * touch sensitive data and the supervisor's catch is correct.
+ *
+ * The library SHIPS NO DEFAULT TOKENS. Anti-pattern: a library shipping
+ * fake-looking AWS keys gets picked up by secret scanners + creates support
+ * load. Consumers register their own tokens via `HoneytokenSet`.
+ */
+/**
+ * A single decoy. Exactly one of `value` or `pattern` must be set.
+ *
+ * - `value` matches substring (case-sensitive). Use for fixed marker strings.
+ * - `pattern` matches against the canonical-JSON of args via regex. Use for
+ *   shape-based tokens (`/AKIA[0-9A-Z]{16}/`, etc.).
+ */
+export interface Honeytoken {
+    /** Stable id. Recorded in audit + estop reason. ASCII, short. */
+    id: string;
+    /** Free-form description for ops review. Ignored by the matcher. */
+    description?: string;
+    /** Literal substring to match. Mutually exclusive with `pattern`. */
+    value?: string;
+    /** Regex to test against canonical-JSON of args. Mutually exclusive with `value`. */
+    pattern?: RegExp;
+}
+/**
+ * A collection of honeytokens for one supervisor instance. Order does not
+ * affect detection; the matcher returns the first hit.
+ *
+ * Ids must be unique within the set.
+ */
+export interface HoneytokenSet {
+    /** Stable identifier for the set itself. */
+    id: string;
+    /** Optional description. */
+    description?: string;
+    /** Value/pattern tokens scanned against `tool.args`. */
+    tokens: Honeytoken[];
+    /**
+     * Phantom tool names. Any dispatch to one of these names triggers
+     * immediately, regardless of args.
+     */
+    phantomTools?: string[];
+}
+/**
+ * Result of a single match attempt.
+ */
+export type HoneytokenHit = {
+    kind: 'value_in_args';
+    tokenId: string;
+} | {
+    kind: 'phantom_tool';
+    toolName: string;
+};
+/**
+ * Build a honeytoken set with id-uniqueness + xor-validation enforced.
+ *
+ * Throws on:
+ *   - empty `tokens` AND empty `phantomTools` (the set would never fire)
+ *   - duplicate token ids
+ *   - duplicate phantom tool names
+ *   - a token with neither `value` nor `pattern`
+ *   - a token with BOTH `value` and `pattern`
+ */
+export declare function defineHoneytokenSet(id: string, tokens: Honeytoken[], phantomTools?: string[], description?: string): HoneytokenSet;
+/**
+ * Test whether a tool name is a phantom tool in the set. Returns the hit
+ * descriptor on match, `null` otherwise.
+ */
+export declare function matchPhantomTool(set: HoneytokenSet, toolName: string): HoneytokenHit | null;
+/**
+ * Test whether any honeytoken value or pattern appears in the canonical-JSON
+ * representation of `args`. Returns the FIRST hit. Order of `tokens` in the
+ * set determines which hit wins when multiple match.
+ *
+ * `args` is canonicalized to JSON before scanning so the matcher catches
+ * tokens regardless of nesting depth, key/value placement, or array index.
+ */
+export declare function matchHoneytokenInArgs(set: HoneytokenSet, args: unknown): HoneytokenHit | null;
+/**
+ * Compose phantom-tool + value-in-args checks. Phantom-tool match wins over
+ * value-in-args when both would fire (phantom-tool is the stronger signal:
+ * a literal call to a forbidden name).
+ */
+export declare function checkHoneytoken(set: HoneytokenSet, toolName: string, args: unknown): HoneytokenHit | null;
+//# sourceMappingURL=honeytokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"honeytokens.d.ts","sourceRoot":"","sources":["../../src/runtime/honeytokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,UAAU,EAAE,EACpB,YAAY,GAAE,MAAM,EAAO,EAC3B,WAAW,CAAC,EAAE,MAAM,GACnB,aAAa,CAiCf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAM3F;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,OAAO,GACZ,aAAa,GAAG,IAAI,CAetB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,GACZ,aAAa,GAAG,IAAI,CAEtB"}

package/dist/runtime/honeytokens.js

@@ -0,0 +1,115 @@
+/**
+ * Honeytoken detection. SPEC §11 (v0.3.0+).
+ *
+ * The library exposes two zero-false-positive-by-construction defenses:
+ *
+ * 1. **Value match.** Consumer registers a set of decoy strings or regexes
+ *    that should NEVER legitimately appear in a tool call's arguments
+ *    (e.g., a fake `AKIA...` key stashed in a never-read env var, a
+ *    phantom file path `~/.flowdot/keys/recovery.pem` that exists but
+ *    contains only a marker). The matcher walks the canonical-JSON
+ *    representation of every tool call's args; any hit means an agent has
+ *    been probing.
+ *
+ * 2. **Phantom tool.** Consumer registers a tool name that is documented
+ *    internally as "do not call" — never advertised to legitimate agents.
+ *    Any dispatch to that tool name → immediate fire.
+ *
+ * Both modes are deterministic predicates over input. Zero false positives
+ * by construction: if a legitimate workflow ever references a honeytoken,
+ * the operator either misconfigured the set or the workflow actually does
+ * touch sensitive data and the supervisor's catch is correct.
+ *
+ * The library SHIPS NO DEFAULT TOKENS. Anti-pattern: a library shipping
+ * fake-looking AWS keys gets picked up by secret scanners + creates support
+ * load. Consumers register their own tokens via `HoneytokenSet`.
+ */
+import { canonicalJsonStringify } from '../audit/chain.js';
+/**
+ * Build a honeytoken set with id-uniqueness + xor-validation enforced.
+ *
+ * Throws on:
+ *   - empty `tokens` AND empty `phantomTools` (the set would never fire)
+ *   - duplicate token ids
+ *   - duplicate phantom tool names
+ *   - a token with neither `value` nor `pattern`
+ *   - a token with BOTH `value` and `pattern`
+ */
+export function defineHoneytokenSet(id, tokens, phantomTools = [], description) {
+    if (tokens.length === 0 && phantomTools.length === 0) {
+        throw new Error('defineHoneytokenSet: provide at least one token or phantom tool');
+    }
+    const tokenIds = new Set();
+    for (const t of tokens) {
+        if (tokenIds.has(t.id)) {
+            throw new Error(`defineHoneytokenSet: duplicate token id ${JSON.stringify(t.id)}`);
+        }
+        tokenIds.add(t.id);
+        const hasValue = t.value !== undefined;
+        const hasPattern = t.pattern !== undefined;
+        if (!hasValue && !hasPattern) {
+            throw new Error(`defineHoneytokenSet: token ${JSON.stringify(t.id)} must set either value or pattern`);
+        }
+        if (hasValue && hasPattern) {
+            throw new Error(`defineHoneytokenSet: token ${JSON.stringify(t.id)} sets both value and pattern; choose one`);
+        }
+    }
+    const phantomSet = new Set();
+    for (const name of phantomTools) {
+        if (phantomSet.has(name)) {
+            throw new Error(`defineHoneytokenSet: duplicate phantom tool ${JSON.stringify(name)}`);
+        }
+        phantomSet.add(name);
+    }
+    const out = { id, tokens, phantomTools };
+    if (description !== undefined)
+        out.description = description;
+    return out;
+}
+/**
+ * Test whether a tool name is a phantom tool in the set. Returns the hit
+ * descriptor on match, `null` otherwise.
+ */
+export function matchPhantomTool(set, toolName) {
+    if (!set.phantomTools)
+        return null;
+    if (set.phantomTools.includes(toolName)) {
+        return { kind: 'phantom_tool', toolName };
+    }
+    return null;
+}
+/**
+ * Test whether any honeytoken value or pattern appears in the canonical-JSON
+ * representation of `args`. Returns the FIRST hit. Order of `tokens` in the
+ * set determines which hit wins when multiple match.
+ *
+ * `args` is canonicalized to JSON before scanning so the matcher catches
+ * tokens regardless of nesting depth, key/value placement, or array index.
+ */
+export function matchHoneytokenInArgs(set, args) {
+    if (set.tokens.length === 0)
+        return null;
+    const json = canonicalJsonStringify(args);
+    for (const t of set.tokens) {
+        if (t.value !== undefined) {
+            if (json.includes(t.value)) {
+                return { kind: 'value_in_args', tokenId: t.id };
+            }
+        }
+        else if (t.pattern !== undefined) {
+            if (t.pattern.test(json)) {
+                return { kind: 'value_in_args', tokenId: t.id };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Compose phantom-tool + value-in-args checks. Phantom-tool match wins over
+ * value-in-args when both would fire (phantom-tool is the stronger signal:
+ * a literal call to a forbidden name).
+ */
+export function checkHoneytoken(set, toolName, args) {
+    return matchPhantomTool(set, toolName) ?? matchHoneytokenInArgs(set, args);
+}
+//# sourceMappingURL=honeytokens.js.map

package/dist/runtime/honeytokens.js.map

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

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

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+import type { CapabilityClass } from './capability.js';
+/**
+ * Bucket configuration for one capability class.
+ */
+export interface BucketConfig {
+    /** Sustained calls per second. */
+    maxCallsPerSecond: number;
+    /** Burst capacity. Default = maxCallsPerSecond. */
+    bucketCapacity?: number;
+}
+export interface MultiRateLimiterOptions {
+    /**
+     * Per-class buckets. Classes not present in this map get the default
+     * fallback bucket. Pass `unknown` explicitly if you want untagged tools
+     * to share a specific bucket (vs. the default).
+     */
+    buckets: Partial<Record<CapabilityClass, BucketConfig>>;
+    /**
+     * Fallback for classes not in `buckets`. When omitted, classes without
+     * an explicit config are NOT rate-limited (every call allowed).
+     */
+    defaultBucket?: BucketConfig;
+    /** Time source (testing). */
+    now?: () => number;
+}
+export interface ConsumeAllowed {
+    allowed: true;
+}
+export interface ConsumeDenied {
+    allowed: false;
+    /** Which class's bucket denied first. */
+    class: CapabilityClass;
+    /** Estimated ms until the denied bucket has a token again. */
+    retryAfterMs: number;
+}
+export type ConsumeResult = ConsumeAllowed | ConsumeDenied;
+/**
+ * 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 declare const DEFAULT_BUCKETS: Partial<Record<CapabilityClass, BucketConfig>>;
+/**
+ * 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 declare class MultiRateLimiter {
+    private readonly buckets;
+    private readonly defaultBucket;
+    private readonly now;
+    private readonly configMap;
+    private readonly defaultConfig;
+    constructor(options: MultiRateLimiterOptions);
+    /**
+     * 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: readonly CapabilityClass[]): ConsumeResult;
+    /** Current token count per class (tests + introspection). */
+    snapshot(): Record<string, number>;
+}
+//# sourceMappingURL=multi-rate-limiter.d.ts.map