@vauban-org/agent-sdk 0.16.0

package/dist/patterns/escalation/pyramid.js

@@ -0,0 +1,86 @@
+/**
+ * Pattern C: Escalation Pyramid — factory implementation.
+ * @public
+ */
+import { logToBrain } from "../_shared/brain-logger.js";
+const NOOP = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+const UNKNOWN_DEFAULT = "L3_hitl_required";
+export function createEscalationPyramid(config) {
+    const l1 = config.l1ConfidenceThreshold ?? 0.85;
+    const l2 = config.l2ConfidenceThreshold ?? 0.60;
+    if (l2 >= l1) {
+        throw new Error(`[escalation:${config.name}] l2ConfidenceThreshold(${l2}) must be < l1ConfidenceThreshold(${l1})`);
+    }
+    const logger = config.logger ?? NOOP;
+    const declared = new Map(config.declarations.map((d) => [d.actionType, d.level]));
+    const overrides = new Map();
+    function getNominal(actionType) {
+        return overrides.get(actionType) ?? declared.get(actionType) ?? UNKNOWN_DEFAULT;
+    }
+    function escalate(nominal, confidence, isDryRun) {
+        if (isDryRun)
+            return "L1_autonomous";
+        switch (nominal) {
+            case "L1_autonomous":
+                return confidence < l1 ? "L2_async_review" : "L1_autonomous";
+            case "L2_async_review":
+                return confidence < l2 ? "L3_hitl_required" : "L2_async_review";
+            case "L3_hitl_required":
+                return "L3_hitl_required";
+        }
+    }
+    return {
+        async canProceed(actionType, confidence, ctx) {
+            const nominal = getNominal(actionType);
+            const isDryRun = ctx.executionMode === "dry-run";
+            const effectiveLevel = escalate(nominal, confidence, isDryRun);
+            const proceed = effectiveLevel !== "L3_hitl_required";
+            const reason = isDryRun
+                ? `dry-run → L1_autonomous`
+                : nominal === effectiveLevel
+                    ? `'${actionType}' at ${nominal} (confidence=${confidence.toFixed(3)})`
+                    : `'${actionType}' escalated ${nominal} → ${effectiveLevel} (confidence=${confidence.toFixed(3)})`;
+            const decision = { proceed, effectiveLevel, reason };
+            logger.info({ pyramid: config.name, actionType, confidence, effectiveLevel, proceed }, `[escalation:${config.name}] ${reason}`);
+            logToBrain(config.brain, {
+                content: `Escalation '${config.name}': ${reason}`,
+                content_type: "decision",
+                author: `escalation:${config.name}`,
+                category: "decision",
+                tags: ["escalation-pyramid", config.name, effectiveLevel, actionType],
+                confidence,
+                metadata: {
+                    actionType,
+                    confidence,
+                    nominal,
+                    effectiveLevel,
+                    proceed,
+                    agentId: ctx.agentId,
+                    runId: ctx.runId,
+                },
+            });
+            if (!proceed) {
+                logger.warn({ pyramid: config.name, actionType }, `[escalation:${config.name}] L3 block on '${actionType}'`);
+                try {
+                    config.onHitlRequired?.(actionType, confidence, decision, ctx);
+                }
+                catch {
+                    /* suppress */
+                }
+            }
+            return decision;
+        },
+        override(actionType, level) {
+            overrides.set(actionType, level);
+        },
+        clearOverride(actionType) {
+            overrides.delete(actionType);
+        },
+    };
+}
+//# sourceMappingURL=pyramid.js.map

package/dist/patterns/escalation/pyramid.js.map

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

package/dist/patterns/escalation/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pattern C: Escalation Pyramid — types.
+ *
+ * Declares action autonomy levels and validates before execution.
+ * Confidence-based escalation: insufficient confidence escalates the level.
+ * Unknown action types default to L3 (fail-safe).
+ * dry-run always resolves to L1 (no real effects).
+ *
+ * NOTE: `confidence` must be provided by the agent's DECIDE phase.
+ * The SDK does not infer it automatically from the LLM.
+ *
+ * @public
+ */
+import type { BrainPort } from "../../ports/brain.js";
+import type { LoggerPort } from "../../ports/logger.js";
+import type { OODAContext } from "../../orchestration/ooda/types.js";
+export type EscalationLevel = "L1_autonomous" | "L2_async_review" | "L3_hitl_required";
+export interface ActionDeclaration {
+    readonly actionType: string;
+    readonly level: EscalationLevel;
+}
+export interface EscalationDecision {
+    readonly proceed: boolean;
+    readonly effectiveLevel: EscalationLevel;
+    readonly reason: string;
+}
+export interface EscalationPyramidConfig {
+    readonly name: string;
+    readonly declarations: ReadonlyArray<ActionDeclaration>;
+    /** Min confidence for L1 without escalating to L2. Default: 0.85 */
+    readonly l1ConfidenceThreshold?: number;
+    /** Min confidence for L2 without escalating to L3. Default: 0.60 */
+    readonly l2ConfidenceThreshold?: number;
+    readonly brain?: BrainPort;
+    readonly logger?: LoggerPort;
+    /** Called when effectiveLevel = L3. Must not throw. */
+    readonly onHitlRequired?: (actionType: string, confidence: number, decision: EscalationDecision, ctx: OODAContext) => void;
+}
+export interface EscalationPyramid {
+    canProceed(actionType: string, confidence: number, ctx: OODAContext): Promise<EscalationDecision>;
+    /** Runtime override without redeployment. */
+    override(actionType: string, level: EscalationLevel): void;
+    /** Remove override — restores declared level (or L3 default). */
+    clearOverride(actionType: string): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/patterns/escalation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/patterns/escalation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACxD,oEAAoE;IACpE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,oEAAoE;IACpE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,CACxB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,WAAW,KACb,IAAI,CAAC;CACX;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CACR,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3D,iEAAiE;IACjE,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC"}

package/dist/patterns/escalation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/patterns/escalation/types.js.map

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

package/dist/patterns/quality-gate/gate.d.ts

@@ -0,0 +1,3 @@
+import type { QualityGate, QualityGateConfig } from "./types.js";
+export declare function createQualityGate<T>(config: QualityGateConfig<T>): QualityGate<T>;
+//# sourceMappingURL=gate.d.ts.map

package/dist/patterns/quality-gate/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/patterns/quality-gate/gate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AASpB,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,WAAW,CAAC,CAAC,CAAC,CAgFhB"}

package/dist/patterns/quality-gate/gate.js

@@ -0,0 +1,73 @@
+/**
+ * Pattern B: Quality Gate — factory implementation.
+ * @public
+ */
+import { logToBrain } from "../_shared/brain-logger.js";
+const NOOP = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+export function createQualityGate(config) {
+    if (config.evaluators.length === 0) {
+        throw new Error(`[quality-gate:${config.name}] evaluators must not be empty`);
+    }
+    const autoProceed = config.autoProceedThreshold ?? 0.8;
+    const asyncReview = config.asyncReviewThreshold ?? 0.5;
+    if (asyncReview >= autoProceed) {
+        throw new Error(`[quality-gate:${config.name}] asyncReviewThreshold(${asyncReview}) must be < autoProceedThreshold(${autoProceed})`);
+    }
+    const logger = config.logger ?? NOOP;
+    return {
+        async evaluate(subject) {
+            const dims = [];
+            let totalWeight = 0;
+            let weightedSum = 0;
+            for (const ev of config.evaluators) {
+                const w = ev.weight ?? 1;
+                let s = 0;
+                try {
+                    const raw = await ev.evaluate(subject);
+                    // NaN/Infinity guard — misbehaving evaluators score 0 without propagating
+                    s = Number.isFinite(raw) ? Math.max(0, Math.min(1, raw)) : 0;
+                }
+                catch (err) {
+                    logger.error({ evaluator: ev.name, err }, `[quality-gate:${config.name}] evaluator '${ev.name}' threw — scoring 0`);
+                }
+                dims.push({ name: ev.name, score: s, weight: w });
+                totalWeight += w;
+                weightedSum += s * w;
+            }
+            const overall = totalWeight > 0 ? weightedSum / totalWeight : 0;
+            const routing = overall >= autoProceed
+                ? "auto"
+                : overall >= asyncReview
+                    ? "async_review"
+                    : "hitl_block";
+            const score = { overall, routing, dimensions: dims };
+            logger.info({ gate: config.name, overall, routing }, `[quality-gate:${config.name}] ${overall.toFixed(3)} → ${routing}`);
+            // category: "operations" — these are production quality metrics, not debug logs
+            logToBrain(config.brain, {
+                content: `Quality gate '${config.name}': overall=${overall.toFixed(3)} routing=${routing}. ${dims.map((d) => `${d.name}=${d.score.toFixed(3)}`).join(", ")}`,
+                content_type: "metric",
+                author: `quality-gate:${config.name}`,
+                category: "operations",
+                tags: ["quality-gate", config.name, routing],
+                confidence: overall,
+                metadata: { score: score },
+            });
+            if (routing === "hitl_block") {
+                logger.warn({ gate: config.name, overall }, `[quality-gate:${config.name}] hitl_block triggered`);
+                try {
+                    config.onHitlBlock?.(score, subject);
+                }
+                catch {
+                    /* suppress */
+                }
+            }
+            return score;
+        },
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/patterns/quality-gate/gate.js.map

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

package/dist/patterns/quality-gate/index.d.ts

@@ -0,0 +1,3 @@
+export { createQualityGate } from "./gate.js";
+export type { QualityGate, QualityGateConfig, QualityScore, QualityRouting, QualityEvaluator, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/patterns/quality-gate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/patterns/quality-gate/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/patterns/quality-gate/index.js

@@ -0,0 +1,2 @@
+export { createQualityGate } from "./gate.js";
+//# sourceMappingURL=index.js.map

package/dist/patterns/quality-gate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/patterns/quality-gate/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}

package/dist/patterns/quality-gate/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pattern B: Quality Gate — types.
+ *
+ * Evaluates OODA output quality using weighted evaluator functions before
+ * action dispatch. Routes to auto / async_review / hitl_block.
+ *
+ * @public
+ */
+import type { BrainPort } from "../../ports/brain.js";
+import type { LoggerPort } from "../../ports/logger.js";
+export type QualityRouting = "auto" | "async_review" | "hitl_block";
+export interface QualityEvaluator<T> {
+    readonly name: string;
+    readonly weight?: number;
+    evaluate(subject: T): Promise<number>;
+}
+export interface QualityScore {
+    readonly overall: number;
+    readonly routing: QualityRouting;
+    readonly dimensions: ReadonlyArray<{
+        readonly name: string;
+        readonly score: number;
+        readonly weight: number;
+    }>;
+}
+export interface QualityGateConfig<T> {
+    readonly name: string;
+    readonly evaluators: ReadonlyArray<QualityEvaluator<T>>;
+    /** Score >= this → auto. Default: 0.8 */
+    readonly autoProceedThreshold?: number;
+    /** Score >= this (and < auto) → async_review. Default: 0.5 */
+    readonly asyncReviewThreshold?: number;
+    readonly brain?: BrainPort;
+    readonly logger?: LoggerPort;
+    /** Called when routing = hitl_block. Must not throw. */
+    readonly onHitlBlock?: (score: QualityScore, subject: T) => void;
+}
+export interface QualityGate<T> {
+    evaluate(subject: T): Promise<QualityScore>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/patterns/quality-gate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/patterns/quality-gate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,cAAc,GAAG,YAAY,CAAC;AAEpE,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,yCAAyC;IACzC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;CAClE;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7C"}

package/dist/patterns/quality-gate/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/patterns/quality-gate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/patterns/quality-gate/types.ts"],"names":[],"mappings":""}

package/dist/permissions/capability-gate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * CapabilityGate — pre-dispatch hook for tool calls.
+ *
+ * Decouples the SDK loops from the concrete Biscuit/JWT implementation.
+ * Hosts (e.g. the Command Center) wire a `CapabilityGate` whose
+ * `verify(call)` consults a Biscuit capability token (and optionally
+ * intersects with the SDK's pinned `cc:*` scopes).
+ *
+ * Contract:
+ *  - `verify` MUST be synchronous-or-promise, but MUST NOT throw — every
+ *    failure mode is encoded in the returned `CapabilityGateVerdict`.
+ *  - `allowed: true` is the only path that authorises a tool call.
+ *  - Any non-`allowed:true` verdict denies the call AND emits a structured
+ *    reason that the loop relays via the `tool_denied` event hook.
+ */
+export interface CapabilityGateCall {
+    /** Tool name about to be invoked. */
+    readonly toolName: string;
+    /** Cumulative budget already spent (USD). Loop maintains the counter. */
+    readonly budgetUsed: number;
+    /** Optional MCP sub-scopes the tool declares (intersected by the host). */
+    readonly mcpScopes?: readonly string[];
+}
+export type CapabilityGateVerdict = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+export interface CapabilityGate {
+    verify(call: CapabilityGateCall): CapabilityGateVerdict | Promise<CapabilityGateVerdict>;
+    /**
+     * OPTIONAL — current token expiry (epoch seconds). Hosts that
+     * implement automatic renewal expose this so the loop can detect when
+     * 80% of the token's lifetime has elapsed and trigger a re-issue.
+     */
+    getExpiresAt?(): number;
+    /**
+     * OPTIONAL — current token issuance time (epoch seconds). Used with
+     * `getExpiresAt()` to compute the 80% threshold.
+     */
+    getIssuedAt?(): number;
+    /**
+     * OPTIONAL — replace the current capability token. Hosts that support
+     * auto-renewal call this with the freshly issued token. The gate MUST
+     * preserve cumulative `budgetUsed` across token rotations (per-session,
+     * not per-token).
+     */
+    rotateToken?(newTokenB64: string, newExpiresAt: number): void;
+}
+/**
+ * A no-op gate that allows every call. Suitable for tests and for
+ * agents running behind external authorisation (e.g. tier-1 read-only
+ * loops where Biscuit is enforced upstream).
+ */
+export declare const ALLOW_ALL_GATE: CapabilityGate;
+//# sourceMappingURL=capability-gate.d.ts.map

package/dist/permissions/capability-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-gate.d.ts","sourceRoot":"","sources":["../../src/permissions/capability-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,MAAM,CACJ,IAAI,EAAE,kBAAkB,GACvB,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1D;;;;OAIG;IACH,YAAY,CAAC,IAAI,MAAM,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,IAAI,MAAM,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/D;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,cAI3B,CAAC"}

package/dist/permissions/capability-gate.js

@@ -0,0 +1,26 @@
+/**
+ * CapabilityGate — pre-dispatch hook for tool calls.
+ *
+ * Decouples the SDK loops from the concrete Biscuit/JWT implementation.
+ * Hosts (e.g. the Command Center) wire a `CapabilityGate` whose
+ * `verify(call)` consults a Biscuit capability token (and optionally
+ * intersects with the SDK's pinned `cc:*` scopes).
+ *
+ * Contract:
+ *  - `verify` MUST be synchronous-or-promise, but MUST NOT throw — every
+ *    failure mode is encoded in the returned `CapabilityGateVerdict`.
+ *  - `allowed: true` is the only path that authorises a tool call.
+ *  - Any non-`allowed:true` verdict denies the call AND emits a structured
+ *    reason that the loop relays via the `tool_denied` event hook.
+ */
+/**
+ * A no-op gate that allows every call. Suitable for tests and for
+ * agents running behind external authorisation (e.g. tier-1 read-only
+ * loops where Biscuit is enforced upstream).
+ */
+export const ALLOW_ALL_GATE = Object.freeze({
+    verify() {
+        return { allowed: true };
+    },
+});
+//# sourceMappingURL=capability-gate.js.map

package/dist/permissions/capability-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-gate.js","sourceRoot":"","sources":["../../src/permissions/capability-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAuCH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAmB,MAAM,CAAC,MAAM,CAAC;IAC1D,MAAM;QACJ,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;CACF,CAAC,CAAC"}

package/dist/permissions/index.d.ts

@@ -0,0 +1,3 @@
+export { mapScopesToSdkPermissions, permitsCapability, permitsMcpScopes, } from "./sdk-permissions.js";
+export type { SdkCapability, SdkPermissions, FileIOMode, BashMode, } from "./sdk-permissions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/permissions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,QAAQ,GACT,MAAM,sBAAsB,CAAC"}

package/dist/permissions/index.js

@@ -0,0 +1,2 @@
+export { mapScopesToSdkPermissions, permitsCapability, permitsMcpScopes, } from "./sdk-permissions.js";
+//# sourceMappingURL=index.js.map

package/dist/permissions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC"}

package/dist/permissions/renewal-manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * RenewalManager — coordinates capability-token auto-renewal.
+ *
+ * Triggers a re-issue when ≥80% of the token lifetime has elapsed.
+ * Debounced: a renewal in flight blocks duplicate triggers; once it
+ * resolves, the gate is rotated and the timer is reset.
+ *
+ * The manager is loop-agnostic: any caller (minimal-loop, sdk-loop, or
+ * a long-running background job) can `await maybeRenew()` between tool
+ * calls. The decision is purely time-based; no per-call cost reset.
+ */
+import type { CapabilityGate } from "./capability-gate.js";
+export interface RenewalRequest {
+    readonly currentToken?: string;
+    readonly issuedAtEpochSeconds: number;
+    readonly expiresAtEpochSeconds: number;
+}
+export interface RenewedToken {
+    readonly token: string;
+    readonly issuedAtEpochSeconds: number;
+    readonly expiresAtEpochSeconds: number;
+}
+export interface RenewalManagerOptions {
+    /** Capability gate exposing getExpiresAt / getIssuedAt / rotateToken. */
+    readonly gate: CapabilityGate;
+    /** Re-issue callback — host computes the new token (e.g. via boot_agent). */
+    readonly reissue: (req: RenewalRequest) => Promise<RenewedToken>;
+    /**
+     * Lifetime fraction at which renewal triggers. Default 0.80. Must be
+     * in (0, 1).
+     */
+    readonly thresholdFraction?: number;
+    /** Clock injection for tests. Default `() => Date.now() / 1000`. */
+    readonly now?: () => number;
+}
+export declare class RenewalManager {
+    private readonly gate;
+    private readonly reissue;
+    private readonly thresholdFraction;
+    private readonly now;
+    private inFlight;
+    constructor(opts: RenewalManagerOptions);
+    /**
+     * Trigger renewal if the current token is past the threshold. Idempotent
+     * across concurrent callers via the in-flight promise.
+     */
+    maybeRenew(): Promise<boolean>;
+}
+//# sourceMappingURL=renewal-manager.d.ts.map

package/dist/permissions/renewal-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renewal-manager.d.ts","sourceRoot":"","sources":["../../src/permissions/renewal-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACjE;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAA8B;gBAElC,IAAI,EAAE,qBAAqB;IAUvC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;CA2BrC"}

package/dist/permissions/renewal-manager.js

@@ -0,0 +1,60 @@
+/**
+ * RenewalManager — coordinates capability-token auto-renewal.
+ *
+ * Triggers a re-issue when ≥80% of the token lifetime has elapsed.
+ * Debounced: a renewal in flight blocks duplicate triggers; once it
+ * resolves, the gate is rotated and the timer is reset.
+ *
+ * The manager is loop-agnostic: any caller (minimal-loop, sdk-loop, or
+ * a long-running background job) can `await maybeRenew()` between tool
+ * calls. The decision is purely time-based; no per-call cost reset.
+ */
+export class RenewalManager {
+    gate;
+    reissue;
+    thresholdFraction;
+    now;
+    inFlight = null;
+    constructor(opts) {
+        this.gate = opts.gate;
+        this.reissue = opts.reissue;
+        this.thresholdFraction = opts.thresholdFraction ?? 0.8;
+        if (this.thresholdFraction <= 0 || this.thresholdFraction >= 1) {
+            throw new RangeError("thresholdFraction must be in (0, 1)");
+        }
+        this.now = opts.now ?? (() => Date.now() / 1000);
+    }
+    /**
+     * Trigger renewal if the current token is past the threshold. Idempotent
+     * across concurrent callers via the in-flight promise.
+     */
+    async maybeRenew() {
+        if (this.inFlight) {
+            await this.inFlight;
+            return true;
+        }
+        const expiresAt = this.gate.getExpiresAt?.();
+        const issuedAt = this.gate.getIssuedAt?.();
+        if (expiresAt === undefined || issuedAt === undefined)
+            return false;
+        const lifetime = expiresAt - issuedAt;
+        if (lifetime <= 0)
+            return false;
+        const elapsed = this.now() - issuedAt;
+        if (elapsed / lifetime < this.thresholdFraction)
+            return false;
+        const promise = (async () => {
+            const renewed = await this.reissue({
+                issuedAtEpochSeconds: issuedAt,
+                expiresAtEpochSeconds: expiresAt,
+            });
+            this.gate.rotateToken?.(renewed.token, renewed.expiresAtEpochSeconds);
+        })();
+        this.inFlight = promise.finally(() => {
+            this.inFlight = null;
+        });
+        await this.inFlight;
+        return true;
+    }
+}
+//# sourceMappingURL=renewal-manager.js.map

package/dist/permissions/renewal-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renewal-manager.js","sourceRoot":"","sources":["../../src/permissions/renewal-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8BH,MAAM,OAAO,cAAc;IACR,IAAI,CAAiB;IACrB,OAAO,CAAmC;IAC1C,iBAAiB,CAAS;IAC1B,GAAG,CAAe;IAC3B,QAAQ,GAAyB,IAAI,CAAC;IAE9C,YAAY,IAA2B;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,GAAG,CAAC;QACvD,IAAI,IAAI,CAAC,iBAAiB,IAAI,CAAC,IAAI,IAAI,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,QAAQ,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3C,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAEpE,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;QACtC,IAAI,QAAQ,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC;QACtC,IAAI,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC,iBAAiB;YAAE,OAAO,KAAK,CAAC;QAE9D,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;gBACjC,oBAAoB,EAAE,QAAQ;gBAC9B,qBAAqB,EAAE,SAAS;aACjC,CAAC,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;QACxE,CAAC,CAAC,EAAE,CAAC;QACL,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,QAAQ,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/permissions/sdk-permissions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SDK permission mapping — projects vauban-auth `cc:*` scopes onto the
+ * capability surface exposed to agent loops.
+ *
+ * Contract: scope hierarchy mirrors cc-scope-middleware.ts
+ *   admin > execute > read
+ *
+ * Worker boot MUST call `mapScopesToSdkPermissions` once at init. Tools that
+ * declare a capability absent from the derived permissions are refused at
+ * dispatch time — fail-closed, never silently downgrade.
+ */
+/** Capability surface the SDK loop exposes to tools. */
+export type SdkCapability = "bash" | "fileIO" | "web" | "mcp";
+/** Severity of filesystem access granted to tools. */
+export type FileIOMode = "none" | "ro" | "sandboxed";
+/** Severity of shell access granted to tools. */
+export type BashMode = false | "restricted";
+/**
+ * Runtime permission envelope. An SDK loop instance is pinned to exactly one
+ * of these at construction and never mutates it.
+ */
+export interface SdkPermissions {
+    readonly bash: BashMode;
+    readonly fileIO: FileIOMode;
+    readonly web: boolean;
+    readonly mcp: readonly string[];
+}
+/**
+ * Project a JWT scope list onto SDK capabilities. Unknown scopes are ignored.
+ *
+ * Rules:
+ * - `cc:admin` → full surface (bash restricted, fileIO sandboxed, web, mcp *)
+ * - `cc:execute` → bash:restricted + fileIO:sandboxed + web:false + mcp R/W
+ * - `cc:read` → bash:false + fileIO:ro + web:false + mcp R only
+ * - no `cc:*` scope → fail-closed: no capabilities at all
+ */
+export declare function mapScopesToSdkPermissions(scopes: readonly string[]): SdkPermissions;
+/**
+ * Returns true iff `permissions` authorises `capability`. Canonical gate
+ * used by the SDK loop before dispatching a tool.
+ */
+export declare function permitsCapability(permissions: SdkPermissions, capability: SdkCapability): boolean;
+/**
+ * Returns true iff the caller holds every MCP permission in `required`.
+ * Used when a tool declares a specific MCP sub-scope (e.g. "brain:write").
+ */
+export declare function permitsMcpScopes(permissions: SdkPermissions, required: readonly string[]): boolean;
+//# sourceMappingURL=sdk-permissions.d.ts.map

package/dist/permissions/sdk-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-permissions.d.ts","sourceRoot":"","sources":["../../src/permissions/sdk-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAE9D,sDAAsD;AACtD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,WAAW,CAAC;AAErD,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AA6CD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,cAAc,CAKhB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,cAAc,EAC3B,UAAU,EAAE,aAAa,GACxB,OAAO,CAWT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,cAAc,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAGT"}