@permission-protocol/mcp-guard 0.1.0 → 0.2.0

package/dist/src/frame.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Inbound JSON-RPC framing for the stdio proxy.
+ *
+ * The guard only ever forwards a message it parsed and evaluated, re-serialized from
+ * the parsed object, so the server cannot read a line differently than the guard did.
+ * Anything that is not a single well-formed JSON-RPC 2.0 object is answered with an
+ * error and never forwarded. MCP does not use JSON-RPC batching, so arrays are refused.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PASSTHROUGH_METHODS = exports.RELEASE_FAILED = exports.EXPIRED = exports.DENIED = exports.HELD = exports.BLOCKED = exports.INVALID_PARAMS = exports.METHOD_NOT_FOUND = exports.INVALID_REQUEST = exports.PARSE_ERROR = void 0;
+exports.isPassthrough = isPassthrough;
+exports.parseFrame = parseFrame;
+exports.errorLine = errorLine;
+exports.toolCallTarget = toolCallTarget;
+exports.stripAgentMetadata = stripAgentMetadata;
+exports.PARSE_ERROR = -32700;
+exports.INVALID_REQUEST = -32600;
+exports.METHOD_NOT_FOUND = -32601;
+exports.INVALID_PARAMS = -32602;
+exports.BLOCKED = -32001;
+exports.HELD = -32002;
+exports.DENIED = -32003;
+exports.EXPIRED = -32004;
+exports.RELEASE_FAILED = -32005;
+/**
+ * Methods that carry no action or data access of their own. Everything else — tools/call,
+ * resources/read, prompts/get, resources/subscribe and any method the guard does not
+ * know — goes through the policy.
+ */
+exports.PASSTHROUGH_METHODS = new Set([
+    'initialize',
+    'ping',
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'resources/unsubscribe',
+    'prompts/list',
+    'logging/setLevel',
+    'completion/complete',
+]);
+function isPassthrough(method) {
+    return exports.PASSTHROUGH_METHODS.has(method) || method.startsWith('notifications/');
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function validId(v) {
+    return v === null || typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v));
+}
+function parseFrame(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { kind: 'invalid', id: null, code: exports.PARSE_ERROR, message: 'Parse error' };
+    }
+    if (Array.isArray(parsed)) {
+        return { kind: 'invalid', id: null, code: exports.INVALID_REQUEST, message: 'Batch requests are not supported' };
+    }
+    if (!isPlainObject(parsed)) {
+        return { kind: 'invalid', id: null, code: exports.INVALID_REQUEST, message: 'Invalid Request' };
+    }
+    const id = validId(parsed.id) ? parsed.id : null;
+    const invalid = (message) => ({ kind: 'invalid', id, code: exports.INVALID_REQUEST, message });
+    if (parsed.jsonrpc !== '2.0')
+        return invalid('Invalid Request: jsonrpc must be "2.0"');
+    if ('id' in parsed && !validId(parsed.id))
+        return invalid('Invalid Request: bad id');
+    const msg = parsed;
+    if ('method' in parsed) {
+        if (typeof parsed.method !== 'string' || !parsed.method)
+            return invalid('Invalid Request: method must be a string');
+        if ('params' in parsed && !isPlainObject(parsed.params) && !Array.isArray(parsed.params)) {
+            return invalid('Invalid Request: params must be an object or array');
+        }
+        if ('id' in parsed)
+            return { kind: 'request', msg: msg };
+        return { kind: 'notification', msg: msg };
+    }
+    if ('id' in parsed && ('result' in parsed || 'error' in parsed))
+        return { kind: 'response', msg };
+    return invalid('Invalid Request');
+}
+function errorLine(id, code, message) {
+    return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+/**
+ * The tools/call target and arguments, validated. Returns an error message when the
+ * params are malformed (the call is then refused, never forwarded).
+ */
+function toolCallTarget(params) {
+    if (!isPlainObject(params))
+        return { error: 'Invalid params: tools/call requires an object' };
+    if (typeof params.name !== 'string' || !params.name)
+        return { error: 'Invalid params: tool name must be a string' };
+    if (params.arguments !== undefined && !isPlainObject(params.arguments)) {
+        return { error: 'Invalid params: arguments must be an object' };
+    }
+    return { name: params.name, args: params.arguments };
+}
+/** A copy of the message with Permission Deck agent metadata (`_pp`) removed from tool arguments. */
+function stripAgentMetadata(msg) {
+    const params = msg.params;
+    if (msg.method !== 'tools/call' || !isPlainObject(params) || !isPlainObject(params.arguments))
+        return msg;
+    if (!('_pp' in params.arguments))
+        return msg;
+    const { _pp, ...rest } = params.arguments;
+    return { ...msg, params: { ...params, arguments: rest } };
+}
+//# sourceMappingURL=frame.js.map

package/dist/src/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../../src/frame.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA8CH,sCAEC;AAUD,gCA8BC;AAED,8BAEC;AAMD,wCASC;AAGD,gDAMC;AAjGY,QAAA,WAAW,GAAG,CAAC,KAAK,CAAC;AACrB,QAAA,eAAe,GAAG,CAAC,KAAK,CAAC;AACzB,QAAA,gBAAgB,GAAG,CAAC,KAAK,CAAC;AAC1B,QAAA,cAAc,GAAG,CAAC,KAAK,CAAC;AACxB,QAAA,OAAO,GAAG,CAAC,KAAK,CAAC;AACjB,QAAA,IAAI,GAAG,CAAC,KAAK,CAAC;AACd,QAAA,MAAM,GAAG,CAAC,KAAK,CAAC;AAChB,QAAA,OAAO,GAAG,CAAC,KAAK,CAAC;AACjB,QAAA,cAAc,GAAG,CAAC,KAAK,CAAC;AAErC;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,IAAI,GAAG,CAAC;IACzC,YAAY;IACZ,MAAM;IACN,YAAY;IACZ,gBAAgB;IAChB,0BAA0B;IAC1B,uBAAuB;IACvB,cAAc;IACd,kBAAkB;IAClB,qBAAqB;CACtB,CAAC,CAAC;AAEH,SAAgB,aAAa,CAAC,MAAc;IAC1C,OAAO,2BAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,OAAO,CAAC,CAAU;IACzB,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9F,CAAC;AAED,SAAgB,UAAU,CAAC,IAAY;IACrC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAW,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,uBAAe,EAAE,OAAO,EAAE,kCAAkC,EAAE,CAAC;IAC3G,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,uBAAe,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC1F,CAAC;IACD,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,MAAM,OAAO,GAAG,CAAC,OAAe,EAAS,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,uBAAe,EAAE,OAAO,EAAE,CAAC,CAAC;IAEtG,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC,wCAAwC,CAAC,CAAC;IACvF,IAAI,IAAI,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAErF,MAAM,GAAG,GAAG,MAAmC,CAAC;IAChD,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,0CAA0C,CAAC,CAAC;QACpH,IAAI,QAAQ,IAAI,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACzF,OAAO,OAAO,CAAC,oDAAoD,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,IAAI,IAAI,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,GAAyD,EAAE,CAAC;QAC/G,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,GAA0C,EAAE,CAAC;IACnF,CAAC;IACD,IAAI,IAAI,IAAI,MAAM,IAAI,CAAC,QAAQ,IAAI,MAAM,IAAI,OAAO,IAAI,MAAM,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;IAClG,OAAO,OAAO,CAAC,iBAAiB,CAAC,CAAC;AACpC,CAAC;AAED,SAAgB,SAAS,CAAC,EAAa,EAAE,IAAY,EAAE,OAAe;IACpE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc,CAC5B,MAAe;IAEf,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,+CAA+C,EAAE,CAAC;IAC9F,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,4CAA4C,EAAE,CAAC;IACpH,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,KAAK,EAAE,6CAA6C,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,SAAgD,EAAE,CAAC;AAC9F,CAAC;AAED,qGAAqG;AACrG,SAAgB,kBAAkB,CAAC,GAAmB;IACpD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1G,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC;QAAE,OAAO,GAAG,CAAC;IAC7C,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC;IAC1C,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;AAC5D,CAAC"}

package/dist/src/pending.d.ts

@@ -1,20 +1,116 @@
+import type { Lane } from './engine.js';
+import type { Reversibility } from './config.js';
+import type { JsonRpcId } from './frame.js';
+/**
+ * The approval queue and its decision state machine.
+ *
+ * Every status change goes through `transition()`, driven by one table: an item starts
+ * `pending` and moves exactly once to a final state. Final states never change, so a
+ * denied item can never be approved, and an approval racing a countdown releases once.
+ *
+ * Item kinds:
+ *   - held:     a request the proxy is holding; approve/auto-release forwards it.
+ *   - acted:    a Verify-lane action that already ran under a standing rule; it can only
+ *               be acknowledged (it cannot be denied or undone after the fact).
+ *   - external: a decision with no MCP request behind it (GitHub webhook); approve
+ *               issues a scoped receipt.
+ */
+export type PendingStatus = 'pending' | 'approved' | 'denied' | 'auto_released' | 'expired' | 'acknowledged';
+export type PendingKind = 'held' | 'acted' | 'external';
+export type PendingEvent = 'approve' | 'deny' | 'auto_release' | 'expire' | 'acknowledge' | 'hold';
+/** Resolved items kept for display before the oldest are dropped. */
+export declare const MAX_RESOLVED = 200;
+export interface PendingEnrichment {
+    lane: Lane;
+    reversibility: Reversibility;
+    countdown_seconds?: number;
+    confidence?: number;
+    summary: string;
+    args_preview: string;
+}
 export interface PendingAction {
     id: string;
-    timestamp: string;
+    kind: PendingKind;
+    method: string;
     tool_name: string;
-    tool_args: any;
+    tool_args: Record<string, unknown>;
     agent_id: string;
-    rule_id: string;
-    status: 'pending' | 'approved' | 'denied';
-    /** The original JSON-RPC line to forward on approval */
-    originalLine: string;
-    /** The JSON-RPC request id for matching child responses */
-    jsonrpcId: string | number | null;
-    /** Resolver — call with the response line (or error JSON) to unblock the proxy */
+    rule_id: string | null;
+    status: PendingStatus;
+    created_at: string;
+    resolved_at?: string;
+    /** ISO time after which a pending item expires; absent = no expiry. */
+    expires_at?: string;
+    /** The JSON-RPC line to forward on release (held items only). */
+    forwardLine: string;
+    jsonrpcId: JsonRpcId;
+    /** Deliver a response line to the waiting client (held items only). */
+    resolve: (responseLine: string) => void;
+    lane: Lane;
+    reversibility: Reversibility;
+    countdown_seconds?: number;
+    confidence?: number;
+    summary: string;
+    args_preview: string;
+    receipt_id?: string;
+    scope?: string;
+    scope_ref?: string;
+    scope_sha?: string;
+    /** epoch ms when the countdown auto-release fires; undefined = no countdown */
+    releaseAt?: number;
+    countdownTimer?: NodeJS.Timeout;
+    expiryTimer?: NodeJS.Timeout;
+}
+export type TransitionResult = {
+    ok: true;
+    action: PendingAction;
+} | {
+    ok: false;
+    error: 'not_found' | 'final' | 'not_allowed';
+    action?: PendingAction;
+};
+export declare function setAutoReleaseHandler(handler: ((action: PendingAction) => void) | null): void;
+export declare function setExpireHandler(handler: ((action: PendingAction) => void) | null): void;
+/** The only place an item's status changes. */
+export declare function transition(id: string, event: PendingEvent): TransitionResult;
+interface BaseInput {
+    toolName: string;
+    toolArgs?: Record<string, unknown>;
+    agentId: string;
+    ruleId: string | null;
+    enrichment: PendingEnrichment;
+    method?: string;
+}
+export interface HeldInput extends BaseInput {
+    /** The scope the release receipt will bind, shown to the approver. */
+    scope?: string;
+    scope_ref?: string;
+    scope_sha?: string;
+    forwardLine: string;
+    jsonrpcId: JsonRpcId;
     resolve: (responseLine: string) => void;
+    ttlSeconds?: number;
+}
+/** Hold a request for a decision. Reversible holds with a countdown auto-release. */
+export declare function addPending(input: HeldInput): PendingAction;
+export interface ActedInput extends BaseInput {
+    receiptId?: string;
+    ttlSeconds?: number;
+}
+/** Surface an action that already ran under a standing rule, for acknowledgement. */
+export declare function surfaceActed(input: ActedInput): PendingAction;
+export interface ExternalInput extends BaseInput {
+    scope?: string;
+    scope_ref?: string;
+    scope_sha?: string;
 }
-export declare function addPending(toolName: string, toolArgs: any, agentId: string, ruleId: string, originalLine: string, jsonrpcId: string | number | null, resolve: (responseLine: string) => void): PendingAction;
+/** Enqueue a decision from an external source (GitHub webhook). Never auto-releases or expires. */
+export declare function addExternalDecision(input: ExternalInput): PendingAction;
 export declare function getPending(): PendingAction[];
 export declare function getAction(id: string): PendingAction | undefined;
-export declare function resolveAction(id: string, status: 'approved' | 'denied'): PendingAction | undefined;
-export declare function recentResolved(limit?: number): PendingAction[];
+export declare function queueSize(): number;
+/** Seconds remaining until auto-release, server-computed. undefined if no countdown. */
+export declare function countdownRemaining(action: PendingAction): number | undefined;
+/** Test/teardown helper: clear the queue and any live timers. */
+export declare function _resetQueue(): void;
+export {};

package/dist/src/pending.js

@@ -1,44 +1,194 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RESOLVED = void 0;
+exports.setAutoReleaseHandler = setAutoReleaseHandler;
+exports.setExpireHandler = setExpireHandler;
+exports.transition = transition;
 exports.addPending = addPending;
+exports.surfaceActed = surfaceActed;
+exports.addExternalDecision = addExternalDecision;
 exports.getPending = getPending;
 exports.getAction = getAction;
-exports.resolveAction = resolveAction;
-exports.recentResolved = recentResolved;
-const uuid_1 = require("uuid");
+exports.queueSize = queueSize;
+exports.countdownRemaining = countdownRemaining;
+exports._resetQueue = _resetQueue;
+const node_crypto_1 = require("node:crypto");
+const ALLOWED_EVENTS = {
+    held: new Set(['approve', 'deny', 'auto_release', 'expire', 'hold']),
+    acted: new Set(['acknowledge', 'expire']),
+    external: new Set(['approve', 'deny']),
+};
+const FINAL_STATUS = {
+    approve: 'approved',
+    deny: 'denied',
+    auto_release: 'auto_released',
+    expire: 'expired',
+    acknowledge: 'acknowledged',
+};
+/** Resolved items kept for display before the oldest are dropped. */
+exports.MAX_RESOLVED = 200;
 const queue = new Map();
-function addPending(toolName, toolArgs, agentId, ruleId, originalLine, jsonrpcId, resolve) {
-    const action = {
-        id: (0, uuid_1.v4)(),
-        timestamp: new Date().toISOString(),
-        tool_name: toolName,
-        tool_args: toolArgs,
-        agent_id: agentId,
-        rule_id: ruleId,
+/** Called after a countdown has moved an item to `auto_released`; the proxy releases it. */
+let autoReleaseHandler = null;
+function setAutoReleaseHandler(handler) {
+    autoReleaseHandler = handler;
+}
+/** Called after a TTL has moved an item to `expired`; the proxy answers the client. */
+let expireHandler = null;
+function setExpireHandler(handler) {
+    expireHandler = handler;
+}
+function clearTimers(action, which) {
+    if (action.countdownTimer)
+        clearTimeout(action.countdownTimer);
+    action.countdownTimer = undefined;
+    if (which === 'all') {
+        if (action.expiryTimer)
+            clearTimeout(action.expiryTimer);
+        action.expiryTimer = undefined;
+    }
+}
+function prune() {
+    let resolved = 0;
+    for (const a of queue.values())
+        if (a.status !== 'pending')
+            resolved++;
+    if (resolved <= exports.MAX_RESOLVED)
+        return;
+    for (const [id, a] of queue) {
+        if (resolved <= exports.MAX_RESOLVED)
+            break;
+        if (a.status !== 'pending') {
+            queue.delete(id);
+            resolved--;
+        }
+    }
+}
+/** The only place an item's status changes. */
+function transition(id, event) {
+    const action = queue.get(id);
+    if (!action)
+        return { ok: false, error: 'not_found' };
+    if (action.status !== 'pending')
+        return { ok: false, error: 'final', action };
+    if (!ALLOWED_EVENTS[action.kind].has(event))
+        return { ok: false, error: 'not_allowed', action };
+    if ((event === 'auto_release' || event === 'hold') && action.releaseAt === undefined) {
+        return { ok: false, error: 'not_allowed', action };
+    }
+    if (event === 'hold') {
+        clearTimers(action, 'countdown');
+        action.releaseAt = undefined;
+        return { ok: true, action };
+    }
+    clearTimers(action, 'all');
+    action.releaseAt = undefined;
+    action.status = FINAL_STATUS[event];
+    action.resolved_at = new Date().toISOString();
+    prune();
+    return { ok: true, action };
+}
+function startExpiry(action, ttlSeconds) {
+    if (!ttlSeconds || ttlSeconds <= 0)
+        return;
+    action.expires_at = new Date(Date.now() + ttlSeconds * 1000).toISOString();
+    action.expiryTimer = setTimeout(() => {
+        const r = transition(action.id, 'expire');
+        if (r.ok && expireHandler)
+            expireHandler(r.action);
+    }, ttlSeconds * 1000);
+    action.expiryTimer.unref?.();
+}
+function baseAction(kind, input) {
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        kind,
+        method: input.method ?? 'tools/call',
+        tool_name: input.toolName,
+        tool_args: input.toolArgs ?? {},
+        agent_id: input.agentId,
+        rule_id: input.ruleId,
         status: 'pending',
-        originalLine,
-        jsonrpcId,
-        resolve,
+        created_at: new Date().toISOString(),
+        forwardLine: '',
+        jsonrpcId: null,
+        resolve: () => { },
+        lane: input.enrichment.lane,
+        reversibility: input.enrichment.reversibility,
+        ...(input.enrichment.confidence !== undefined ? { confidence: input.enrichment.confidence } : {}),
+        summary: input.enrichment.summary,
+        args_preview: input.enrichment.args_preview,
     };
+}
+/** Hold a request for a decision. Reversible holds with a countdown auto-release. */
+function addPending(input) {
+    const action = baseAction('held', input);
+    action.forwardLine = input.forwardLine;
+    action.jsonrpcId = input.jsonrpcId;
+    action.resolve = input.resolve;
+    if (input.scope)
+        action.scope = input.scope;
+    if (input.scope_ref)
+        action.scope_ref = input.scope_ref;
+    if (input.scope_sha)
+        action.scope_sha = input.scope_sha;
+    const countdown = input.enrichment.countdown_seconds;
+    if (countdown !== undefined)
+        action.countdown_seconds = countdown;
+    // Irreversible (or no countdown) NEVER auto-releases; it waits for a decision or expiry.
+    if (action.reversibility === 'reversible' && countdown !== undefined && countdown > 0) {
+        action.releaseAt = Date.now() + countdown * 1000;
+        action.countdownTimer = setTimeout(() => {
+            const r = transition(action.id, 'auto_release');
+            if (r.ok && autoReleaseHandler)
+                autoReleaseHandler(r.action);
+        }, countdown * 1000);
+        action.countdownTimer.unref?.();
+    }
+    startExpiry(action, input.ttlSeconds);
+    queue.set(action.id, action);
+    return action;
+}
+/** Surface an action that already ran under a standing rule, for acknowledgement. */
+function surfaceActed(input) {
+    const action = baseAction('acted', input);
+    if (input.receiptId !== undefined)
+        action.receipt_id = input.receiptId;
+    startExpiry(action, input.ttlSeconds);
+    queue.set(action.id, action);
+    return action;
+}
+/** Enqueue a decision from an external source (GitHub webhook). Never auto-releases or expires. */
+function addExternalDecision(input) {
+    const action = baseAction('external', input);
+    if (input.scope)
+        action.scope = input.scope;
+    if (input.scope_ref)
+        action.scope_ref = input.scope_ref;
+    if (input.scope_sha)
+        action.scope_sha = input.scope_sha;
     queue.set(action.id, action);
     return action;
 }
 function getPending() {
-    return Array.from(queue.values()).filter(a => a.status === 'pending');
+    return Array.from(queue.values()).filter((a) => a.status === 'pending');
 }
 function getAction(id) {
     return queue.get(id);
 }
-function resolveAction(id, status) {
-    const action = queue.get(id);
-    if (!action || action.status !== 'pending')
+function queueSize() {
+    return queue.size;
+}
+/** Seconds remaining until auto-release, server-computed. undefined if no countdown. */
+function countdownRemaining(action) {
+    if (action.releaseAt === undefined || action.status !== 'pending')
         return undefined;
-    action.status = status;
-    return action;
+    return Math.max(0, Math.ceil((action.releaseAt - Date.now()) / 1000));
 }
-function recentResolved(limit = 50) {
-    return Array.from(queue.values())
-        .filter(a => a.status !== 'pending')
-        .slice(-limit);
+/** Test/teardown helper: clear the queue and any live timers. */
+function _resetQueue() {
+    for (const action of queue.values())
+        clearTimers(action, 'all');
+    queue.clear();
 }
 //# sourceMappingURL=pending.js.map

package/dist/src/pending.js.map

@@ -1 +1 @@
-{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../src/pending.ts"],"names":[],"mappings":";;AAoBA,gCAuBC;AAED,gCAEC;AAED,8BAEC;AAED,sCAKC;AAED,wCAIC;AAhED,+BAAoC;AAkBpC,MAAM,KAAK,GAA+B,IAAI,GAAG,EAAE,CAAC;AAEpD,SAAgB,UAAU,CACxB,QAAgB,EAChB,QAAa,EACb,OAAe,EACf,MAAc,EACd,YAAoB,EACpB,SAAiC,EACjC,OAAuC;IAEvC,MAAM,MAAM,GAAkB;QAC5B,EAAE,EAAE,IAAA,SAAM,GAAE;QACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS,EAAE,QAAQ;QACnB,SAAS,EAAE,QAAQ;QACnB,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,MAAM;QACf,MAAM,EAAE,SAAS;QACjB,YAAY;QACZ,SAAS;QACT,OAAO;KACR,CAAC;IACF,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,UAAU;IACxB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;AACxE,CAAC;AAED,SAAgB,SAAS,CAAC,EAAU;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED,SAAgB,aAAa,CAAC,EAAU,EAAE,MAA6B;IACrE,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7D,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,cAAc,CAAC,QAAgB,EAAE;IAC/C,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;SAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC;SACnC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../src/pending.ts"],"names":[],"mappings":"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"}

package/dist/src/proxy.d.ts

@@ -1,2 +1,29 @@
-import type { Config } from './config.js';
-export declare function startProxy(config: Config, agentId: string, serverCommand: string[], approvalPort?: number): void;
+import { type Config, type Rule } from './config.js';
+import { type Decision } from './engine.js';
+import { type ScopeBinding } from './receipt.js';
+import { type PendingEnrichment } from './pending.js';
+/**
+ * Derive a one-line summary + the literal artifact preview from the tool name and args,
+ * so the console can render a human-readable card. For capped spends the amount shown is
+ * the argument the rule caps (`amountArg`), the same one the classifier read.
+ */
+export declare function derivePreview(toolName: string, toolArgs: Record<string, unknown> | undefined, amountArg?: string): {
+    summary: string;
+    args_preview: string;
+};
+/** Build the enrichment record for the queue from a classified Decision + args. */
+export declare function buildEnrichment(decision: Decision, toolName: string, toolArgs: Record<string, unknown> | undefined, rule?: Rule | null): PendingEnrichment;
+/**
+ * Derive a receipt scope binding from the tool + args, for the code/infra tools the
+ * offline receipt gate verifies:
+ *   - merge_pr           -> `github:merge`, ref `refs/pull/<n>/merge`
+ *   - run_sql_migration  -> `sql:migrate:<env>`
+ *   - deploy             -> `deploy:<env>`
+ * Other tools carry no scope.
+ */
+export declare function deriveScope(toolName: string, toolArgs: Record<string, unknown> | undefined): ScopeBinding | undefined;
+export interface ProxyOptions {
+    approvalPort?: number;
+    operator?: string;
+}
+export declare function startProxy(config: Config, agentId: string, serverCommand: string[], opts?: ProxyOptions): void;