@caupulican/pi-adaptative 0.81.41 → 0.81.42

package/dist/core/orchestration/attempt-usage.js

@@ -0,0 +1,168 @@
+import { isPlainRecord } from "../util/value-guards.js";
+export const EMPTY_ATTEMPT_USAGE = {
+    toolCalls: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    totalTokens: 0,
+    costUsd: 0,
+    activeWallClockMs: 0,
+};
+/**
+ * Validate an untrusted provider-neutral usage report before it reaches durable accounting.
+ * Provider totals are authoritative and therefore need not equal the detail field sum.
+ */
+const PROVIDER_USAGE_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "cost"];
+const PROVIDER_USAGE_COST_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "total"];
+function parseExactDataRecord(value, fields, label) {
+    if (!isPlainRecord(value))
+        throw new TypeError(`${label} must be a plain object.`);
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !fields.includes(key))
+            throw new TypeError(`${label} contains an unsupported field.`);
+    }
+    const parsed = {};
+    for (const field of fields) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, field);
+        if (!descriptor || !("value" in descriptor))
+            throw new TypeError(`${label}.${field} must be a data field.`);
+        parsed[field] = descriptor.value;
+    }
+    return parsed;
+}
+/** Parse an untrusted provider-neutral usage report into a closed, known-field value. */
+export function validateProviderUsage(value, label = "provider usage") {
+    const usage = parseExactDataRecord(value, PROVIDER_USAGE_FIELDS, label);
+    const cost = parseExactDataRecord(usage.cost, PROVIDER_USAGE_COST_FIELDS, `${label}.cost`);
+    const tokenFields = [
+        ["input", usage.input],
+        ["output", usage.output],
+        ["cacheRead", usage.cacheRead],
+        ["cacheWrite", usage.cacheWrite],
+        ["totalTokens", usage.totalTokens],
+    ];
+    for (const [field, value] of tokenFields) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new Error(`${label}.${field} must be a non-negative safe integer.`);
+        }
+    }
+    const costFields = [
+        ["input", cost.input],
+        ["output", cost.output],
+        ["cacheRead", cost.cacheRead],
+        ["cacheWrite", cost.cacheWrite],
+        ["total", cost.total],
+    ];
+    for (const [field, value] of costFields) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`${label}.cost.${field} must be finite and non-negative.`);
+        }
+    }
+    return {
+        input: usage.input,
+        output: usage.output,
+        cacheRead: usage.cacheRead,
+        cacheWrite: usage.cacheWrite,
+        totalTokens: usage.totalTokens,
+        cost: {
+            input: cost.input,
+            output: cost.output,
+            cacheRead: cost.cacheRead,
+            cacheWrite: cost.cacheWrite,
+            total: cost.total,
+        },
+    };
+}
+/** Validate the one durable cumulative usage shape shared by checkpoints, recovery, and results. */
+export function validateAttemptUsageSnapshot(usage, label = "attempt usage") {
+    if (!Number.isSafeInteger(usage.toolCalls) || usage.toolCalls < 0) {
+        throw new Error(`${label}.toolCalls must be a non-negative safe integer.`);
+    }
+    if (!Number.isSafeInteger(usage.inputTokens) || usage.inputTokens < 0) {
+        throw new Error(`${label}.inputTokens must be a non-negative safe integer.`);
+    }
+    if (!Number.isSafeInteger(usage.outputTokens) || usage.outputTokens < 0) {
+        throw new Error(`${label}.outputTokens must be a non-negative safe integer.`);
+    }
+    if (!Number.isSafeInteger(usage.cacheReadTokens) || usage.cacheReadTokens < 0) {
+        throw new Error(`${label}.cacheReadTokens must be a non-negative safe integer.`);
+    }
+    if (!Number.isSafeInteger(usage.cacheWriteTokens) || usage.cacheWriteTokens < 0) {
+        throw new Error(`${label}.cacheWriteTokens must be a non-negative safe integer.`);
+    }
+    if (!Number.isSafeInteger(usage.totalTokens) || usage.totalTokens < 0) {
+        throw new Error(`${label}.totalTokens must be a non-negative safe integer.`);
+    }
+    if (!Number.isFinite(usage.costUsd) || usage.costUsd < 0) {
+        throw new Error(`${label}.costUsd must be finite and non-negative.`);
+    }
+    if (!Number.isFinite(usage.activeWallClockMs) || usage.activeWallClockMs < 0) {
+        throw new Error(`${label}.activeWallClockMs must be finite and non-negative.`);
+    }
+    return structuredClone(usage);
+}
+export function attemptUsageFromGatewayUsage(usage) {
+    return validateAttemptUsageSnapshot({
+        toolCalls: usage.toolCalls,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cacheReadTokens: usage.cacheReadTokens,
+        cacheWriteTokens: usage.cacheWriteTokens,
+        totalTokens: usage.totalTokens,
+        costUsd: usage.costUsd,
+        activeWallClockMs: usage.wallClockMs,
+    }, "gateway usage");
+}
+export function addAttemptUsage(base, delta, label = "attempt usage") {
+    validateAttemptUsageSnapshot(base, `${label} base`);
+    validateAttemptUsageSnapshot(delta, `${label} delta`);
+    return validateAttemptUsageSnapshot({
+        toolCalls: base.toolCalls + delta.toolCalls,
+        inputTokens: base.inputTokens + delta.inputTokens,
+        outputTokens: base.outputTokens + delta.outputTokens,
+        cacheReadTokens: base.cacheReadTokens + delta.cacheReadTokens,
+        cacheWriteTokens: base.cacheWriteTokens + delta.cacheWriteTokens,
+        totalTokens: base.totalTokens + delta.totalTokens,
+        costUsd: base.costUsd + delta.costUsd,
+        activeWallClockMs: base.activeWallClockMs + delta.activeWallClockMs,
+    }, label);
+}
+/**
+ * Recover the strongest cumulative evidence across an atomic checkpoint and its durable transcript.
+ * Both inputs are cumulative views of the same attempt, so summing would double-count; component
+ * maxima close append-before-checkpoint crash windows conservatively.
+ */
+export function reconcileAttemptUsage(checkpoint, transcript) {
+    validateAttemptUsageSnapshot(checkpoint, "attempt checkpoint usage");
+    validateAttemptUsageSnapshot(transcript, "attempt transcript usage");
+    return validateAttemptUsageSnapshot({
+        toolCalls: Math.max(checkpoint.toolCalls, transcript.toolCalls),
+        inputTokens: Math.max(checkpoint.inputTokens, transcript.inputTokens),
+        outputTokens: Math.max(checkpoint.outputTokens, transcript.outputTokens),
+        cacheReadTokens: Math.max(checkpoint.cacheReadTokens, transcript.cacheReadTokens),
+        cacheWriteTokens: Math.max(checkpoint.cacheWriteTokens, transcript.cacheWriteTokens),
+        totalTokens: Math.max(checkpoint.totalTokens, transcript.totalTokens),
+        costUsd: Math.max(checkpoint.costUsd, transcript.costUsd),
+        activeWallClockMs: Math.max(checkpoint.activeWallClockMs, transcript.activeWallClockMs),
+    });
+}
+export function remainingTokenBudget(maxTokens, usage) {
+    if (maxTokens === undefined)
+        return undefined;
+    const remaining = maxTokens - usage.totalTokens;
+    return Math.max(0, remaining);
+}
+/** Convert durable cumulative accounting into the provider-neutral report shape exactly once. */
+export function providerUsageFromAttemptUsage(usage) {
+    const validated = validateAttemptUsageSnapshot(usage);
+    return {
+        input: validated.inputTokens,
+        output: validated.outputTokens,
+        cacheRead: validated.cacheReadTokens,
+        cacheWrite: validated.cacheWriteTokens,
+        totalTokens: validated.totalTokens,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: validated.costUsd },
+    };
+}
+//# sourceMappingURL=attempt-usage.js.map

package/dist/core/orchestration/attempt-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-usage.js","sourceRoot":"","sources":["../../../src/core/orchestration/attempt-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Usage } from \"@caupulican/pi-ai\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\nimport type { AttemptUsageSnapshot } from \"./contracts.ts\";\n\nexport const EMPTY_ATTEMPT_USAGE: AttemptUsageSnapshot = {\n\ttoolCalls: 0,\n\tinputTokens: 0,\n\toutputTokens: 0,\n\tcacheReadTokens: 0,\n\tcacheWriteTokens: 0,\n\ttotalTokens: 0,\n\tcostUsd: 0,\n\tactiveWallClockMs: 0,\n};\n\n/**\n * Validate an untrusted provider-neutral usage report before it reaches durable accounting.\n * Provider totals are authoritative and therefore need not equal the detail field sum.\n */\nconst PROVIDER_USAGE_FIELDS = [\"input\", \"output\", \"cacheRead\", \"cacheWrite\", \"totalTokens\", \"cost\"] as const;\nconst PROVIDER_USAGE_COST_FIELDS = [\"input\", \"output\", \"cacheRead\", \"cacheWrite\", \"total\"] as const;\n\nfunction parseExactDataRecord(value: unknown, fields: readonly string[], label: string): Record<string, unknown> {\n\tif (!isPlainRecord(value)) throw new TypeError(`${label} must be a plain object.`);\n\tfor (const key of Reflect.ownKeys(value)) {\n\t\tif (typeof key !== \"string\" || !fields.includes(key))\n\t\t\tthrow new TypeError(`${label} contains an unsupported field.`);\n\t}\n\tconst parsed: Record<string, unknown> = {};\n\tfor (const field of fields) {\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(value, field);\n\t\tif (!descriptor || !(\"value\" in descriptor)) throw new TypeError(`${label}.${field} must be a data field.`);\n\t\tparsed[field] = descriptor.value;\n\t}\n\treturn parsed;\n}\n\n/** Parse an untrusted provider-neutral usage report into a closed, known-field value. */\nexport function validateProviderUsage(value: unknown, label = \"provider usage\"): Usage {\n\tconst usage = parseExactDataRecord(value, PROVIDER_USAGE_FIELDS, label);\n\tconst cost = parseExactDataRecord(usage.cost, PROVIDER_USAGE_COST_FIELDS, `${label}.cost`);\n\tconst tokenFields: Array<[string, number]> = [\n\t\t[\"input\", usage.input as number],\n\t\t[\"output\", usage.output as number],\n\t\t[\"cacheRead\", usage.cacheRead as number],\n\t\t[\"cacheWrite\", usage.cacheWrite as number],\n\t\t[\"totalTokens\", usage.totalTokens as number],\n\t];\n\tfor (const [field, value] of tokenFields) {\n\t\tif (!Number.isSafeInteger(value) || value < 0) {\n\t\t\tthrow new Error(`${label}.${field} must be a non-negative safe integer.`);\n\t\t}\n\t}\n\tconst costFields: Array<[string, number]> = [\n\t\t[\"input\", cost.input as number],\n\t\t[\"output\", cost.output as number],\n\t\t[\"cacheRead\", cost.cacheRead as number],\n\t\t[\"cacheWrite\", cost.cacheWrite as number],\n\t\t[\"total\", cost.total as number],\n\t];\n\tfor (const [field, value] of costFields) {\n\t\tif (!Number.isFinite(value) || value < 0) {\n\t\t\tthrow new Error(`${label}.cost.${field} must be finite and non-negative.`);\n\t\t}\n\t}\n\treturn {\n\t\tinput: usage.input as number,\n\t\toutput: usage.output as number,\n\t\tcacheRead: usage.cacheRead as number,\n\t\tcacheWrite: usage.cacheWrite as number,\n\t\ttotalTokens: usage.totalTokens as number,\n\t\tcost: {\n\t\t\tinput: cost.input as number,\n\t\t\toutput: cost.output as number,\n\t\t\tcacheRead: cost.cacheRead as number,\n\t\t\tcacheWrite: cost.cacheWrite as number,\n\t\t\ttotal: cost.total as number,\n\t\t},\n\t};\n}\n\n/** Validate the one durable cumulative usage shape shared by checkpoints, recovery, and results. */\nexport function validateAttemptUsageSnapshot(\n\tusage: AttemptUsageSnapshot,\n\tlabel = \"attempt usage\",\n): AttemptUsageSnapshot {\n\tif (!Number.isSafeInteger(usage.toolCalls) || usage.toolCalls < 0) {\n\t\tthrow new Error(`${label}.toolCalls must be a non-negative safe integer.`);\n\t}\n\tif (!Number.isSafeInteger(usage.inputTokens) || usage.inputTokens < 0) {\n\t\tthrow new Error(`${label}.inputTokens must be a non-negative safe integer.`);\n\t}\n\tif (!Number.isSafeInteger(usage.outputTokens) || usage.outputTokens < 0) {\n\t\tthrow new Error(`${label}.outputTokens must be a non-negative safe integer.`);\n\t}\n\tif (!Number.isSafeInteger(usage.cacheReadTokens) || usage.cacheReadTokens < 0) {\n\t\tthrow new Error(`${label}.cacheReadTokens must be a non-negative safe integer.`);\n\t}\n\tif (!Number.isSafeInteger(usage.cacheWriteTokens) || usage.cacheWriteTokens < 0) {\n\t\tthrow new Error(`${label}.cacheWriteTokens must be a non-negative safe integer.`);\n\t}\n\tif (!Number.isSafeInteger(usage.totalTokens) || usage.totalTokens < 0) {\n\t\tthrow new Error(`${label}.totalTokens must be a non-negative safe integer.`);\n\t}\n\tif (!Number.isFinite(usage.costUsd) || usage.costUsd < 0) {\n\t\tthrow new Error(`${label}.costUsd must be finite and non-negative.`);\n\t}\n\tif (!Number.isFinite(usage.activeWallClockMs) || usage.activeWallClockMs < 0) {\n\t\tthrow new Error(`${label}.activeWallClockMs must be finite and non-negative.`);\n\t}\n\treturn structuredClone(usage);\n}\n\nexport function attemptUsageFromGatewayUsage(usage: {\n\ttoolCalls: number;\n\tinputTokens: number;\n\toutputTokens: number;\n\tcacheReadTokens: number;\n\tcacheWriteTokens: number;\n\ttotalTokens: number;\n\tcostUsd: number;\n\twallClockMs: number;\n}): AttemptUsageSnapshot {\n\treturn validateAttemptUsageSnapshot(\n\t\t{\n\t\t\ttoolCalls: usage.toolCalls,\n\t\t\tinputTokens: usage.inputTokens,\n\t\t\toutputTokens: usage.outputTokens,\n\t\t\tcacheReadTokens: usage.cacheReadTokens,\n\t\t\tcacheWriteTokens: usage.cacheWriteTokens,\n\t\t\ttotalTokens: usage.totalTokens,\n\t\t\tcostUsd: usage.costUsd,\n\t\t\tactiveWallClockMs: usage.wallClockMs,\n\t\t},\n\t\t\"gateway usage\",\n\t);\n}\n\nexport function addAttemptUsage(\n\tbase: AttemptUsageSnapshot,\n\tdelta: AttemptUsageSnapshot,\n\tlabel = \"attempt usage\",\n): AttemptUsageSnapshot {\n\tvalidateAttemptUsageSnapshot(base, `${label} base`);\n\tvalidateAttemptUsageSnapshot(delta, `${label} delta`);\n\treturn validateAttemptUsageSnapshot(\n\t\t{\n\t\t\ttoolCalls: base.toolCalls + delta.toolCalls,\n\t\t\tinputTokens: base.inputTokens + delta.inputTokens,\n\t\t\toutputTokens: base.outputTokens + delta.outputTokens,\n\t\t\tcacheReadTokens: base.cacheReadTokens + delta.cacheReadTokens,\n\t\t\tcacheWriteTokens: base.cacheWriteTokens + delta.cacheWriteTokens,\n\t\t\ttotalTokens: base.totalTokens + delta.totalTokens,\n\t\t\tcostUsd: base.costUsd + delta.costUsd,\n\t\t\tactiveWallClockMs: base.activeWallClockMs + delta.activeWallClockMs,\n\t\t},\n\t\tlabel,\n\t);\n}\n\n/**\n * Recover the strongest cumulative evidence across an atomic checkpoint and its durable transcript.\n * Both inputs are cumulative views of the same attempt, so summing would double-count; component\n * maxima close append-before-checkpoint crash windows conservatively.\n */\nexport function reconcileAttemptUsage(\n\tcheckpoint: AttemptUsageSnapshot,\n\ttranscript: AttemptUsageSnapshot,\n): AttemptUsageSnapshot {\n\tvalidateAttemptUsageSnapshot(checkpoint, \"attempt checkpoint usage\");\n\tvalidateAttemptUsageSnapshot(transcript, \"attempt transcript usage\");\n\treturn validateAttemptUsageSnapshot({\n\t\ttoolCalls: Math.max(checkpoint.toolCalls, transcript.toolCalls),\n\t\tinputTokens: Math.max(checkpoint.inputTokens, transcript.inputTokens),\n\t\toutputTokens: Math.max(checkpoint.outputTokens, transcript.outputTokens),\n\t\tcacheReadTokens: Math.max(checkpoint.cacheReadTokens, transcript.cacheReadTokens),\n\t\tcacheWriteTokens: Math.max(checkpoint.cacheWriteTokens, transcript.cacheWriteTokens),\n\t\ttotalTokens: Math.max(checkpoint.totalTokens, transcript.totalTokens),\n\t\tcostUsd: Math.max(checkpoint.costUsd, transcript.costUsd),\n\t\tactiveWallClockMs: Math.max(checkpoint.activeWallClockMs, transcript.activeWallClockMs),\n\t});\n}\n\nexport function remainingTokenBudget(maxTokens: number | undefined, usage: AttemptUsageSnapshot): number | undefined {\n\tif (maxTokens === undefined) return undefined;\n\tconst remaining = maxTokens - usage.totalTokens;\n\treturn Math.max(0, remaining);\n}\n\n/** Convert durable cumulative accounting into the provider-neutral report shape exactly once. */\nexport function providerUsageFromAttemptUsage(usage: AttemptUsageSnapshot): Usage {\n\tconst validated = validateAttemptUsageSnapshot(usage);\n\treturn {\n\t\tinput: validated.inputTokens,\n\t\toutput: validated.outputTokens,\n\t\tcacheRead: validated.cacheReadTokens,\n\t\tcacheWrite: validated.cacheWriteTokens,\n\t\ttotalTokens: validated.totalTokens,\n\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: validated.costUsd },\n\t};\n}\n"]}

package/dist/core/orchestration/capability-gateway.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionGrant, ToolCapabilityManifest } from "./contracts.ts";
+import type { AttemptUsageSnapshot, ExecutionGrant, ToolCapabilityManifest } from "./contracts.ts";
 export type GatewayDecisionCode = "allowed" | "grant_expired" | "tool_not_granted" | "manifest_name_mismatch" | "capability_not_granted" | "path_argument_required" | "path_outside_scope" | "tool_call_budget_exhausted" | "token_budget_exhausted" | "cost_budget_exhausted" | "wall_clock_budget_exhausted";
 export interface GatewayAuditRecord {
     grantId: string;
@@ -11,22 +11,32 @@ export interface GatewayAuditRecord {
 export interface CapabilityGatewayOptions {
     grant: ExecutionGrant;
     cwd: string;
+    /** Durable active usage carried forward when an attempt resumes in a new process. */
+    initialUsage?: GatewayInitialUsage;
     now?: () => number;
     onAudit?: (record: GatewayAuditRecord) => void;
 }
 export interface GatewayUsageDelta {
     inputTokens?: number;
     outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Provider-authoritative total. Defaults to the supplied detail sum when omitted. */
+    totalTokens?: number;
     costUsd?: number;
 }
 export interface GatewayUsageSnapshot {
     toolCalls: number;
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
     totalTokens: number;
     costUsd: number;
     wallClockMs: number;
 }
+/** Persistable cumulative usage from a prior active segment; excludes restart downtime. */
+export type GatewayInitialUsage = AttemptUsageSnapshot;
 export declare class CapabilityGatewayDeniedError extends Error {
     readonly reasonCode: GatewayDecisionCode;
     constructor(reasonCode: GatewayDecisionCode, message: string);
@@ -42,18 +52,26 @@ export declare class CapabilityGateway {
     private readonly now;
     private readonly onAudit?;
     private readonly startedAt;
+    private readonly initialWallClockMs;
     private toolCalls;
     private inputTokens;
     private outputTokens;
+    private cacheReadTokens;
+    private cacheWriteTokens;
+    private totalTokens;
     private costUsd;
     constructor(options: CapabilityGatewayOptions);
     execute<T>(manifest: ToolCapabilityManifest, toolName: string, params: unknown, invoke: () => Promise<T> | T): Promise<T>;
     /** Immediate pre-execution authorization for runtimes that expose a before-tool-call hook. */
     authorizeToolCall(manifest: ToolCapabilityManifest, toolName: string, params: unknown): void;
     recordUsage(delta: GatewayUsageDelta): void;
+    /** Enforce resumed cumulative budgets before a provider request that has no tool-call boundary. */
+    assertBudgetAvailable(subject?: string): void;
     getUsage(): GatewayUsageSnapshot;
     private authorize;
     private enforceBudget;
+    private currentTime;
+    private wallClockMsAt;
     private pathAllowed;
     private deny;
     private audit;

package/dist/core/orchestration/capability-gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-gateway.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/capability-gateway.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAqB,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEhG,MAAM,MAAM,mBAAmB,GAC5B,SAAS,GACT,eAAe,GACf,kBAAkB,GAClB,wBAAwB,GACxB,wBAAwB,GACxB,wBAAwB,GACxB,oBAAoB,GACpB,4BAA4B,GAC5B,wBAAwB,GACxB,uBAAuB,GACvB,6BAA6B,CAAC;AAEjC,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,UAAU,EAAE,mBAAmB,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,wBAAwB;IACxC,KAAK,EAAE,cAAc,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACtD,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IAEzC,YAAY,UAAU,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAI3D;CACD;AA2BD;;;;GAIG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,OAAO,CAAK;IAEpB,YAAY,OAAO,EAAE,wBAAwB,EAM5C;IAEK,OAAO,CAAC,CAAC,EACd,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAGZ;IAED,8FAA8F;IAC9F,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAI3F;IAED,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAI1C;IAED,QAAQ,IAAI,oBAAoB,CAS/B;IAED,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,KAAK;CAUb","sourcesContent":["import { isAbsolute, relative, resolve, sep } from \"node:path\";\nimport { extractPathArguments } from \"../autonomy/envelope-enforcement.ts\";\nimport { safeRealpathSync } from \"../autonomy/path-scope.ts\";\nimport type { ExecutionGrant, HarnessCapability, ToolCapabilityManifest } from \"./contracts.ts\";\n\nexport type GatewayDecisionCode =\n\t| \"allowed\"\n\t| \"grant_expired\"\n\t| \"tool_not_granted\"\n\t| \"manifest_name_mismatch\"\n\t| \"capability_not_granted\"\n\t| \"path_argument_required\"\n\t| \"path_outside_scope\"\n\t| \"tool_call_budget_exhausted\"\n\t| \"token_budget_exhausted\"\n\t| \"cost_budget_exhausted\"\n\t| \"wall_clock_budget_exhausted\";\n\nexport interface GatewayAuditRecord {\n\tgrantId: string;\n\tattemptId: string;\n\ttoolName: string;\n\toutcome: \"allow\" | \"deny\";\n\treasonCode: GatewayDecisionCode;\n\tat: string;\n}\n\nexport interface CapabilityGatewayOptions {\n\tgrant: ExecutionGrant;\n\tcwd: string;\n\tnow?: () => number;\n\tonAudit?: (record: GatewayAuditRecord) => void;\n}\n\nexport interface GatewayUsageDelta {\n\tinputTokens?: number;\n\toutputTokens?: number;\n\tcostUsd?: number;\n}\n\nexport interface GatewayUsageSnapshot {\n\ttoolCalls: number;\n\tinputTokens: number;\n\toutputTokens: number;\n\ttotalTokens: number;\n\tcostUsd: number;\n\twallClockMs: number;\n}\n\nexport class CapabilityGatewayDeniedError extends Error {\n\treadonly reasonCode: GatewayDecisionCode;\n\n\tconstructor(reasonCode: GatewayDecisionCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"CapabilityGatewayDeniedError\";\n\t\tthis.reasonCode = reasonCode;\n\t}\n}\n\nconst PATH_CAPABILITIES: ReadonlySet<HarnessCapability> = new Set([\n\t\"filesystem.read\",\n\t\"filesystem.write\",\n\t\"worktree.read\",\n\t\"worktree.mutate\",\n]);\n\nconst WRITE_CAPABILITIES: ReadonlySet<HarnessCapability> = new Set([\"filesystem.write\", \"worktree.mutate\"]);\n\nfunction isWithinRoot(target: string, root: string): boolean {\n\tconst relativePath = relative(root, target);\n\treturn (\n\t\trelativePath === \"\" ||\n\t\t(!relativePath.startsWith(`..${sep}`) && relativePath !== \"..\" && !isAbsolute(relativePath))\n\t);\n}\n\nfunction resolveRealPath(cwd: string, value: string): string | undefined {\n\ttry {\n\t\treturn safeRealpathSync(resolve(cwd, value));\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Per-invocation enforcement for an already-compiled grant. The compiler controls what may be\n * loaded; this gateway independently rechecks authority, path scope, expiry, and cumulative budget\n * immediately before execution.\n */\nexport class CapabilityGateway {\n\tprivate readonly grant: ExecutionGrant;\n\tprivate readonly cwd: string;\n\tprivate readonly now: () => number;\n\tprivate readonly onAudit?: (record: GatewayAuditRecord) => void;\n\tprivate readonly startedAt: number;\n\tprivate toolCalls = 0;\n\tprivate inputTokens = 0;\n\tprivate outputTokens = 0;\n\tprivate costUsd = 0;\n\n\tconstructor(options: CapabilityGatewayOptions) {\n\t\tthis.grant = options.grant;\n\t\tthis.cwd = options.cwd;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.onAudit = options.onAudit;\n\t\tthis.startedAt = this.now();\n\t}\n\n\tasync execute<T>(\n\t\tmanifest: ToolCapabilityManifest,\n\t\ttoolName: string,\n\t\tparams: unknown,\n\t\tinvoke: () => Promise<T> | T,\n\t): Promise<T> {\n\t\tthis.authorizeToolCall(manifest, toolName, params);\n\t\treturn await invoke();\n\t}\n\n\t/** Immediate pre-execution authorization for runtimes that expose a before-tool-call hook. */\n\tauthorizeToolCall(manifest: ToolCapabilityManifest, toolName: string, params: unknown): void {\n\t\tthis.authorize(manifest, toolName, params);\n\t\tthis.toolCalls++;\n\t\tthis.audit(toolName, \"allow\", \"allowed\");\n\t}\n\n\trecordUsage(delta: GatewayUsageDelta): void {\n\t\tthis.inputTokens += delta.inputTokens ?? 0;\n\t\tthis.outputTokens += delta.outputTokens ?? 0;\n\t\tthis.costUsd += delta.costUsd ?? 0;\n\t}\n\n\tgetUsage(): GatewayUsageSnapshot {\n\t\treturn {\n\t\t\ttoolCalls: this.toolCalls,\n\t\t\tinputTokens: this.inputTokens,\n\t\t\toutputTokens: this.outputTokens,\n\t\t\ttotalTokens: this.inputTokens + this.outputTokens,\n\t\t\tcostUsd: this.costUsd,\n\t\t\twallClockMs: Math.max(0, this.now() - this.startedAt),\n\t\t};\n\t}\n\n\tprivate authorize(manifest: ToolCapabilityManifest, toolName: string, params: unknown): void {\n\t\tif (this.grant.expiresAt && Date.parse(this.grant.expiresAt) <= this.now()) {\n\t\t\tthis.deny(toolName, \"grant_expired\", `Execution grant '${this.grant.grantId}' expired.`);\n\t\t}\n\t\tif (!this.grant.allowedTools.includes(toolName)) {\n\t\t\tthis.deny(toolName, \"tool_not_granted\", `Tool '${toolName}' is not in grant '${this.grant.grantId}'.`);\n\t\t}\n\t\tif (manifest.toolName !== toolName) {\n\t\t\tthis.deny(toolName, \"manifest_name_mismatch\", `Tool '${toolName}' does not match its capability manifest.`);\n\t\t}\n\t\tif (!manifest.capabilities.every((capability) => this.grant.capabilities.includes(capability))) {\n\t\t\tthis.deny(toolName, \"capability_not_granted\", `Tool '${toolName}' requires an ungranted capability.`);\n\t\t}\n\t\tthis.enforceBudget(toolName);\n\n\t\tif (manifest.capabilities.some((capability) => PATH_CAPABILITIES.has(capability))) {\n\t\t\tconst allowedPaths = manifest.capabilities.some((capability) => WRITE_CAPABILITIES.has(capability))\n\t\t\t\t? this.grant.writePaths\n\t\t\t\t: this.grant.readPaths;\n\t\t\tconst paths = extractPathArguments(params);\n\t\t\tif (paths.length === 0) {\n\t\t\t\tthis.deny(toolName, \"path_argument_required\", `Tool '${toolName}' requires an explicit path argument.`);\n\t\t\t}\n\t\t\tfor (const rawPath of paths) {\n\t\t\t\tif (!this.pathAllowed(rawPath, allowedPaths)) {\n\t\t\t\t\tthis.deny(toolName, \"path_outside_scope\", `Path '${rawPath}' is outside grant '${this.grant.grantId}'.`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate enforceBudget(toolName: string): void {\n\t\tconst budget = this.grant.budget;\n\t\tif (budget.maxToolCalls !== undefined && this.toolCalls >= budget.maxToolCalls) {\n\t\t\tthis.deny(toolName, \"tool_call_budget_exhausted\", \"Tool-call budget exhausted.\");\n\t\t}\n\t\tif (budget.maxTokens !== undefined && this.inputTokens + this.outputTokens >= budget.maxTokens) {\n\t\t\tthis.deny(toolName, \"token_budget_exhausted\", \"Token budget exhausted.\");\n\t\t}\n\t\tif (budget.maxCostUsd !== undefined && this.costUsd >= budget.maxCostUsd) {\n\t\t\tthis.deny(toolName, \"cost_budget_exhausted\", \"Cost budget exhausted.\");\n\t\t}\n\t\tif (budget.maxWallClockMs !== undefined && this.now() - this.startedAt >= budget.maxWallClockMs) {\n\t\t\tthis.deny(toolName, \"wall_clock_budget_exhausted\", \"Wall-clock budget exhausted.\");\n\t\t}\n\t}\n\n\tprivate pathAllowed(rawPath: string, allowedPaths: readonly string[]): boolean {\n\t\tconst target = resolveRealPath(this.cwd, rawPath);\n\t\tif (!target || allowedPaths.length === 0) return false;\n\t\tfor (const denied of this.grant.deniedPaths) {\n\t\t\tconst root = resolveRealPath(this.cwd, denied);\n\t\t\tif (root && isWithinRoot(target, root)) return false;\n\t\t}\n\t\treturn allowedPaths.some((allowed) => {\n\t\t\tconst root = resolveRealPath(this.cwd, allowed);\n\t\t\treturn root !== undefined && isWithinRoot(target, root);\n\t\t});\n\t}\n\n\tprivate deny(toolName: string, reasonCode: GatewayDecisionCode, message: string): never {\n\t\tthis.audit(toolName, \"deny\", reasonCode);\n\t\tthrow new CapabilityGatewayDeniedError(reasonCode, message);\n\t}\n\n\tprivate audit(toolName: string, outcome: \"allow\" | \"deny\", reasonCode: GatewayDecisionCode): void {\n\t\tthis.onAudit?.({\n\t\t\tgrantId: this.grant.grantId,\n\t\t\tattemptId: this.grant.attemptId,\n\t\t\ttoolName,\n\t\t\toutcome,\n\t\t\treasonCode,\n\t\t\tat: new Date(this.now()).toISOString(),\n\t\t});\n\t}\n}\n"]}
+{"version":3,"file":"capability-gateway.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/capability-gateway.ts"],"names":[],"mappings":"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","sourcesContent":["import { resolve } from \"node:path\";\nimport { extractPathArguments } from \"../autonomy/envelope-enforcement.ts\";\nimport { isPathWithinScope, safeRealpathSync } from \"../autonomy/path-scope.ts\";\nimport { validateAttemptUsageSnapshot } from \"./attempt-usage.ts\";\nimport type { AttemptUsageSnapshot, ExecutionGrant, HarnessCapability, ToolCapabilityManifest } from \"./contracts.ts\";\n\nexport type GatewayDecisionCode =\n\t| \"allowed\"\n\t| \"grant_expired\"\n\t| \"tool_not_granted\"\n\t| \"manifest_name_mismatch\"\n\t| \"capability_not_granted\"\n\t| \"path_argument_required\"\n\t| \"path_outside_scope\"\n\t| \"tool_call_budget_exhausted\"\n\t| \"token_budget_exhausted\"\n\t| \"cost_budget_exhausted\"\n\t| \"wall_clock_budget_exhausted\";\n\nexport interface GatewayAuditRecord {\n\tgrantId: string;\n\tattemptId: string;\n\ttoolName: string;\n\toutcome: \"allow\" | \"deny\";\n\treasonCode: GatewayDecisionCode;\n\tat: string;\n}\n\nexport interface CapabilityGatewayOptions {\n\tgrant: ExecutionGrant;\n\tcwd: string;\n\t/** Durable active usage carried forward when an attempt resumes in a new process. */\n\tinitialUsage?: GatewayInitialUsage;\n\tnow?: () => number;\n\tonAudit?: (record: GatewayAuditRecord) => void;\n}\n\nexport interface GatewayUsageDelta {\n\tinputTokens?: number;\n\toutputTokens?: number;\n\tcacheReadTokens?: number;\n\tcacheWriteTokens?: number;\n\t/** Provider-authoritative total. Defaults to the supplied detail sum when omitted. */\n\ttotalTokens?: number;\n\tcostUsd?: number;\n}\n\nexport interface GatewayUsageSnapshot {\n\ttoolCalls: number;\n\tinputTokens: number;\n\toutputTokens: number;\n\tcacheReadTokens: number;\n\tcacheWriteTokens: number;\n\ttotalTokens: number;\n\tcostUsd: number;\n\twallClockMs: number;\n}\n\n/** Persistable cumulative usage from a prior active segment; excludes restart downtime. */\nexport type GatewayInitialUsage = AttemptUsageSnapshot;\n\nexport class CapabilityGatewayDeniedError extends Error {\n\treadonly reasonCode: GatewayDecisionCode;\n\n\tconstructor(reasonCode: GatewayDecisionCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"CapabilityGatewayDeniedError\";\n\t\tthis.reasonCode = reasonCode;\n\t}\n}\n\nconst PATH_CAPABILITIES: ReadonlySet<HarnessCapability> = new Set([\n\t\"filesystem.read\",\n\t\"filesystem.write\",\n\t\"worktree.read\",\n\t\"worktree.mutate\",\n]);\n\nconst WRITE_CAPABILITIES: ReadonlySet<HarnessCapability> = new Set([\"filesystem.write\", \"worktree.mutate\"]);\n\nfunction resolveRealPath(cwd: string, value: string): string | undefined {\n\ttry {\n\t\treturn safeRealpathSync(resolve(cwd, value));\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction validateInitialUsage(usage: GatewayInitialUsage): void {\n\ttry {\n\t\tvalidateAttemptUsageSnapshot(usage, \"CapabilityGateway: initial usage\");\n\t} catch {\n\t\tthrow new Error(\n\t\t\t\"CapabilityGateway: initial usage must contain finite non-negative values and safe-integer counts.\",\n\t\t);\n\t}\n}\n\nfunction validatedUsageDelta(delta: GatewayUsageDelta): Required<GatewayUsageDelta> {\n\tconst inputTokens = delta.inputTokens === undefined ? 0 : delta.inputTokens;\n\tconst outputTokens = delta.outputTokens === undefined ? 0 : delta.outputTokens;\n\tconst cacheReadTokens = delta.cacheReadTokens === undefined ? 0 : delta.cacheReadTokens;\n\tconst cacheWriteTokens = delta.cacheWriteTokens === undefined ? 0 : delta.cacheWriteTokens;\n\tconst totalTokens =\n\t\tdelta.totalTokens === undefined\n\t\t\t? inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens\n\t\t\t: delta.totalTokens;\n\tconst costUsd = delta.costUsd === undefined ? 0 : delta.costUsd;\n\tif (\n\t\t!Number.isSafeInteger(inputTokens) ||\n\t\tinputTokens < 0 ||\n\t\t!Number.isSafeInteger(outputTokens) ||\n\t\toutputTokens < 0 ||\n\t\t!Number.isSafeInteger(cacheReadTokens) ||\n\t\tcacheReadTokens < 0 ||\n\t\t!Number.isSafeInteger(cacheWriteTokens) ||\n\t\tcacheWriteTokens < 0 ||\n\t\t!Number.isSafeInteger(totalTokens) ||\n\t\ttotalTokens < 0 ||\n\t\t!Number.isFinite(costUsd) ||\n\t\tcostUsd < 0\n\t) {\n\t\tthrow new Error(\n\t\t\t\"CapabilityGateway: usage delta must contain finite non-negative values and safe-integer token counts.\",\n\t\t);\n\t}\n\treturn { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, totalTokens, costUsd };\n}\n\n/**\n * Per-invocation enforcement for an already-compiled grant. The compiler controls what may be\n * loaded; this gateway independently rechecks authority, path scope, expiry, and cumulative budget\n * immediately before execution.\n */\nexport class CapabilityGateway {\n\tprivate readonly grant: ExecutionGrant;\n\tprivate readonly cwd: string;\n\tprivate readonly now: () => number;\n\tprivate readonly onAudit?: (record: GatewayAuditRecord) => void;\n\tprivate readonly startedAt: number;\n\tprivate readonly initialWallClockMs: number;\n\tprivate toolCalls: number;\n\tprivate inputTokens: number;\n\tprivate outputTokens: number;\n\tprivate cacheReadTokens: number;\n\tprivate cacheWriteTokens: number;\n\tprivate totalTokens: number;\n\tprivate costUsd: number;\n\n\tconstructor(options: CapabilityGatewayOptions) {\n\t\tconst initialUsage: GatewayInitialUsage = options.initialUsage ?? {\n\t\t\ttoolCalls: 0,\n\t\t\tinputTokens: 0,\n\t\t\toutputTokens: 0,\n\t\t\tcacheReadTokens: 0,\n\t\t\tcacheWriteTokens: 0,\n\t\t\ttotalTokens: 0,\n\t\t\tcostUsd: 0,\n\t\t\tactiveWallClockMs: 0,\n\t\t};\n\t\tvalidateInitialUsage(initialUsage);\n\t\tthis.grant = options.grant;\n\t\tthis.cwd = options.cwd;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.onAudit = options.onAudit;\n\t\tthis.startedAt = this.currentTime();\n\t\tthis.initialWallClockMs = initialUsage.activeWallClockMs;\n\t\tthis.toolCalls = initialUsage.toolCalls;\n\t\tthis.inputTokens = initialUsage.inputTokens;\n\t\tthis.outputTokens = initialUsage.outputTokens;\n\t\tthis.cacheReadTokens = initialUsage.cacheReadTokens;\n\t\tthis.cacheWriteTokens = initialUsage.cacheWriteTokens;\n\t\tthis.totalTokens = initialUsage.totalTokens;\n\t\tthis.costUsd = initialUsage.costUsd;\n\t}\n\n\tasync execute<T>(\n\t\tmanifest: ToolCapabilityManifest,\n\t\ttoolName: string,\n\t\tparams: unknown,\n\t\tinvoke: () => Promise<T> | T,\n\t): Promise<T> {\n\t\tthis.authorizeToolCall(manifest, toolName, params);\n\t\treturn await invoke();\n\t}\n\n\t/** Immediate pre-execution authorization for runtimes that expose a before-tool-call hook. */\n\tauthorizeToolCall(manifest: ToolCapabilityManifest, toolName: string, params: unknown): void {\n\t\tconst now = this.currentTime();\n\t\tconst wallClockMs = this.wallClockMsAt(now);\n\t\tthis.authorize(manifest, toolName, params, now, wallClockMs);\n\t\tconst toolCalls = this.toolCalls + 1;\n\t\tif (!Number.isSafeInteger(toolCalls)) {\n\t\t\tthrow new Error(\"CapabilityGateway: tool-call count would exceed safe cumulative usage bounds.\");\n\t\t}\n\t\tthis.toolCalls = toolCalls;\n\t\tthis.audit(toolName, \"allow\", \"allowed\");\n\t}\n\n\trecordUsage(delta: GatewayUsageDelta): void {\n\t\tconst validated = validatedUsageDelta(delta);\n\t\tconst inputTokens = this.inputTokens + validated.inputTokens;\n\t\tconst outputTokens = this.outputTokens + validated.outputTokens;\n\t\tconst cacheReadTokens = this.cacheReadTokens + validated.cacheReadTokens;\n\t\tconst cacheWriteTokens = this.cacheWriteTokens + validated.cacheWriteTokens;\n\t\tconst totalTokens = this.totalTokens + validated.totalTokens;\n\t\tconst costUsd = this.costUsd + validated.costUsd;\n\t\tif (\n\t\t\t!Number.isSafeInteger(inputTokens) ||\n\t\t\t!Number.isSafeInteger(outputTokens) ||\n\t\t\t!Number.isSafeInteger(cacheReadTokens) ||\n\t\t\t!Number.isSafeInteger(cacheWriteTokens) ||\n\t\t\t!Number.isSafeInteger(totalTokens) ||\n\t\t\t!Number.isFinite(costUsd)\n\t\t) {\n\t\t\tthrow new Error(\"CapabilityGateway: usage delta would exceed safe cumulative usage bounds.\");\n\t\t}\n\t\tthis.inputTokens = inputTokens;\n\t\tthis.outputTokens = outputTokens;\n\t\tthis.cacheReadTokens = cacheReadTokens;\n\t\tthis.cacheWriteTokens = cacheWriteTokens;\n\t\tthis.totalTokens = totalTokens;\n\t\tthis.costUsd = costUsd;\n\t}\n\n\t/** Enforce resumed cumulative budgets before a provider request that has no tool-call boundary. */\n\tassertBudgetAvailable(subject = \"provider\"): void {\n\t\tthis.enforceBudget(subject, this.wallClockMsAt(this.currentTime()));\n\t}\n\n\tgetUsage(): GatewayUsageSnapshot {\n\t\treturn {\n\t\t\ttoolCalls: this.toolCalls,\n\t\t\tinputTokens: this.inputTokens,\n\t\t\toutputTokens: this.outputTokens,\n\t\t\tcacheReadTokens: this.cacheReadTokens,\n\t\t\tcacheWriteTokens: this.cacheWriteTokens,\n\t\t\ttotalTokens: this.totalTokens,\n\t\t\tcostUsd: this.costUsd,\n\t\t\twallClockMs: this.wallClockMsAt(this.currentTime()),\n\t\t};\n\t}\n\n\tprivate authorize(\n\t\tmanifest: ToolCapabilityManifest,\n\t\ttoolName: string,\n\t\tparams: unknown,\n\t\tnow: number,\n\t\twallClockMs: number,\n\t): void {\n\t\tif (this.grant.expiresAt && Date.parse(this.grant.expiresAt) <= now) {\n\t\t\tthis.deny(toolName, \"grant_expired\", `Execution grant '${this.grant.grantId}' expired.`);\n\t\t}\n\t\tif (!this.grant.allowedTools.includes(toolName)) {\n\t\t\tthis.deny(toolName, \"tool_not_granted\", `Tool '${toolName}' is not in grant '${this.grant.grantId}'.`);\n\t\t}\n\t\tif (manifest.toolName !== toolName) {\n\t\t\tthis.deny(toolName, \"manifest_name_mismatch\", `Tool '${toolName}' does not match its capability manifest.`);\n\t\t}\n\t\tif (!manifest.capabilities.every((capability) => this.grant.capabilities.includes(capability))) {\n\t\t\tthis.deny(toolName, \"capability_not_granted\", `Tool '${toolName}' requires an ungranted capability.`);\n\t\t}\n\t\tthis.enforceBudget(toolName, wallClockMs);\n\n\t\tif (manifest.capabilities.some((capability) => PATH_CAPABILITIES.has(capability))) {\n\t\t\tconst allowedPaths = manifest.capabilities.some((capability) => WRITE_CAPABILITIES.has(capability))\n\t\t\t\t? this.grant.writePaths\n\t\t\t\t: this.grant.readPaths;\n\t\t\tconst paths = extractPathArguments(params);\n\t\t\tif (paths.length === 0) {\n\t\t\t\tthis.deny(toolName, \"path_argument_required\", `Tool '${toolName}' requires an explicit path argument.`);\n\t\t\t}\n\t\t\tfor (const rawPath of paths) {\n\t\t\t\tif (!this.pathAllowed(rawPath, allowedPaths)) {\n\t\t\t\t\tthis.deny(toolName, \"path_outside_scope\", `Path '${rawPath}' is outside grant '${this.grant.grantId}'.`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate enforceBudget(toolName: string, wallClockMs: number): void {\n\t\tconst budget = this.grant.budget;\n\t\tif (budget.maxToolCalls !== undefined && this.toolCalls >= budget.maxToolCalls) {\n\t\t\tthis.deny(toolName, \"tool_call_budget_exhausted\", \"Tool-call budget exhausted.\");\n\t\t}\n\t\tif (budget.maxTokens !== undefined && this.totalTokens >= budget.maxTokens) {\n\t\t\tthis.deny(toolName, \"token_budget_exhausted\", \"Token budget exhausted.\");\n\t\t}\n\t\tif (budget.maxCostUsd !== undefined && this.costUsd >= budget.maxCostUsd) {\n\t\t\tthis.deny(toolName, \"cost_budget_exhausted\", \"Cost budget exhausted.\");\n\t\t}\n\t\tif (budget.maxWallClockMs !== undefined && wallClockMs >= budget.maxWallClockMs) {\n\t\t\tthis.deny(toolName, \"wall_clock_budget_exhausted\", \"Wall-clock budget exhausted.\");\n\t\t}\n\t}\n\n\tprivate currentTime(): number {\n\t\tconst now = this.now();\n\t\tif (!Number.isFinite(now)) {\n\t\t\tthrow new Error(\"CapabilityGateway: clock source must return a finite time.\");\n\t\t}\n\t\treturn now;\n\t}\n\n\tprivate wallClockMsAt(now: number): number {\n\t\tconst elapsed = now - this.startedAt;\n\t\tif (!Number.isFinite(elapsed)) {\n\t\t\tthrow new Error(\"CapabilityGateway: active wall-clock elapsed time must be finite.\");\n\t\t}\n\t\tconst wallClockMs = this.initialWallClockMs + Math.max(0, elapsed);\n\t\tif (!Number.isFinite(wallClockMs) || wallClockMs < 0) {\n\t\t\tthrow new Error(\"CapabilityGateway: accumulated wall-clock usage must be finite and non-negative.\");\n\t\t}\n\t\treturn wallClockMs;\n\t}\n\n\tprivate pathAllowed(rawPath: string, allowedPaths: readonly string[]): boolean {\n\t\tconst target = resolveRealPath(this.cwd, rawPath);\n\t\tif (!target || allowedPaths.length === 0) return false;\n\t\tfor (const denied of this.grant.deniedPaths) {\n\t\t\tconst root = resolveRealPath(this.cwd, denied);\n\t\t\tif (root && isPathWithinScope(target, root)) return false;\n\t\t}\n\t\treturn allowedPaths.some((allowed) => {\n\t\t\tconst root = resolveRealPath(this.cwd, allowed);\n\t\t\treturn root !== undefined && isPathWithinScope(target, root);\n\t\t});\n\t}\n\n\tprivate deny(toolName: string, reasonCode: GatewayDecisionCode, message: string): never {\n\t\tthis.audit(toolName, \"deny\", reasonCode);\n\t\tthrow new CapabilityGatewayDeniedError(reasonCode, message);\n\t}\n\n\tprivate audit(toolName: string, outcome: \"allow\" | \"deny\", reasonCode: GatewayDecisionCode): void {\n\t\tthis.onAudit?.({\n\t\t\tgrantId: this.grant.grantId,\n\t\t\tattemptId: this.grant.attemptId,\n\t\t\ttoolName,\n\t\t\toutcome,\n\t\t\treasonCode,\n\t\t\tat: new Date(this.currentTime()).toISOString(),\n\t\t});\n\t}\n}\n"]}

package/dist/core/orchestration/capability-gateway.js

@@ -1,6 +1,7 @@
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { resolve } from "node:path";
 import { extractPathArguments } from "../autonomy/envelope-enforcement.js";
-import { safeRealpathSync } from "../autonomy/path-scope.js";
+import { isPathWithinScope, safeRealpathSync } from "../autonomy/path-scope.js";
+import { validateAttemptUsageSnapshot } from "./attempt-usage.js";
 export class CapabilityGatewayDeniedError extends Error {
     reasonCode;
     constructor(reasonCode, message) {
@@ -16,11 +17,6 @@ const PATH_CAPABILITIES = new Set([
     "worktree.mutate",
 ]);
 const WRITE_CAPABILITIES = new Set(["filesystem.write", "worktree.mutate"]);
-function isWithinRoot(target, root) {
-    const relativePath = relative(root, target);
-    return (relativePath === "" ||
-        (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath)));
-}
 function resolveRealPath(cwd, value) {
     try {
         return safeRealpathSync(resolve(cwd, value));
@@ -29,6 +25,39 @@ function resolveRealPath(cwd, value) {
         return undefined;
     }
 }
+function validateInitialUsage(usage) {
+    try {
+        validateAttemptUsageSnapshot(usage, "CapabilityGateway: initial usage");
+    }
+    catch {
+        throw new Error("CapabilityGateway: initial usage must contain finite non-negative values and safe-integer counts.");
+    }
+}
+function validatedUsageDelta(delta) {
+    const inputTokens = delta.inputTokens === undefined ? 0 : delta.inputTokens;
+    const outputTokens = delta.outputTokens === undefined ? 0 : delta.outputTokens;
+    const cacheReadTokens = delta.cacheReadTokens === undefined ? 0 : delta.cacheReadTokens;
+    const cacheWriteTokens = delta.cacheWriteTokens === undefined ? 0 : delta.cacheWriteTokens;
+    const totalTokens = delta.totalTokens === undefined
+        ? inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens
+        : delta.totalTokens;
+    const costUsd = delta.costUsd === undefined ? 0 : delta.costUsd;
+    if (!Number.isSafeInteger(inputTokens) ||
+        inputTokens < 0 ||
+        !Number.isSafeInteger(outputTokens) ||
+        outputTokens < 0 ||
+        !Number.isSafeInteger(cacheReadTokens) ||
+        cacheReadTokens < 0 ||
+        !Number.isSafeInteger(cacheWriteTokens) ||
+        cacheWriteTokens < 0 ||
+        !Number.isSafeInteger(totalTokens) ||
+        totalTokens < 0 ||
+        !Number.isFinite(costUsd) ||
+        costUsd < 0) {
+        throw new Error("CapabilityGateway: usage delta must contain finite non-negative values and safe-integer token counts.");
+    }
+    return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, totalTokens, costUsd };
+}
 /**
  * Per-invocation enforcement for an already-compiled grant. The compiler controls what may be
  * loaded; this gateway independently rechecks authority, path scope, expiry, and cumulative budget
@@ -40,16 +69,39 @@ export class CapabilityGateway {
     now;
     onAudit;
     startedAt;
-    toolCalls = 0;
-    inputTokens = 0;
-    outputTokens = 0;
-    costUsd = 0;
+    initialWallClockMs;
+    toolCalls;
+    inputTokens;
+    outputTokens;
+    cacheReadTokens;
+    cacheWriteTokens;
+    totalTokens;
+    costUsd;
     constructor(options) {
+        const initialUsage = options.initialUsage ?? {
+            toolCalls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            totalTokens: 0,
+            costUsd: 0,
+            activeWallClockMs: 0,
+        };
+        validateInitialUsage(initialUsage);
         this.grant = options.grant;
         this.cwd = options.cwd;
         this.now = options.now ?? Date.now;
         this.onAudit = options.onAudit;
-        this.startedAt = this.now();
+        this.startedAt = this.currentTime();
+        this.initialWallClockMs = initialUsage.activeWallClockMs;
+        this.toolCalls = initialUsage.toolCalls;
+        this.inputTokens = initialUsage.inputTokens;
+        this.outputTokens = initialUsage.outputTokens;
+        this.cacheReadTokens = initialUsage.cacheReadTokens;
+        this.cacheWriteTokens = initialUsage.cacheWriteTokens;
+        this.totalTokens = initialUsage.totalTokens;
+        this.costUsd = initialUsage.costUsd;
     }
     async execute(manifest, toolName, params, invoke) {
         this.authorizeToolCall(manifest, toolName, params);
@@ -57,27 +109,57 @@ export class CapabilityGateway {
     }
     /** Immediate pre-execution authorization for runtimes that expose a before-tool-call hook. */
     authorizeToolCall(manifest, toolName, params) {
-        this.authorize(manifest, toolName, params);
-        this.toolCalls++;
+        const now = this.currentTime();
+        const wallClockMs = this.wallClockMsAt(now);
+        this.authorize(manifest, toolName, params, now, wallClockMs);
+        const toolCalls = this.toolCalls + 1;
+        if (!Number.isSafeInteger(toolCalls)) {
+            throw new Error("CapabilityGateway: tool-call count would exceed safe cumulative usage bounds.");
+        }
+        this.toolCalls = toolCalls;
         this.audit(toolName, "allow", "allowed");
     }
     recordUsage(delta) {
-        this.inputTokens += delta.inputTokens ?? 0;
-        this.outputTokens += delta.outputTokens ?? 0;
-        this.costUsd += delta.costUsd ?? 0;
+        const validated = validatedUsageDelta(delta);
+        const inputTokens = this.inputTokens + validated.inputTokens;
+        const outputTokens = this.outputTokens + validated.outputTokens;
+        const cacheReadTokens = this.cacheReadTokens + validated.cacheReadTokens;
+        const cacheWriteTokens = this.cacheWriteTokens + validated.cacheWriteTokens;
+        const totalTokens = this.totalTokens + validated.totalTokens;
+        const costUsd = this.costUsd + validated.costUsd;
+        if (!Number.isSafeInteger(inputTokens) ||
+            !Number.isSafeInteger(outputTokens) ||
+            !Number.isSafeInteger(cacheReadTokens) ||
+            !Number.isSafeInteger(cacheWriteTokens) ||
+            !Number.isSafeInteger(totalTokens) ||
+            !Number.isFinite(costUsd)) {
+            throw new Error("CapabilityGateway: usage delta would exceed safe cumulative usage bounds.");
+        }
+        this.inputTokens = inputTokens;
+        this.outputTokens = outputTokens;
+        this.cacheReadTokens = cacheReadTokens;
+        this.cacheWriteTokens = cacheWriteTokens;
+        this.totalTokens = totalTokens;
+        this.costUsd = costUsd;
+    }
+    /** Enforce resumed cumulative budgets before a provider request that has no tool-call boundary. */
+    assertBudgetAvailable(subject = "provider") {
+        this.enforceBudget(subject, this.wallClockMsAt(this.currentTime()));
     }
     getUsage() {
         return {
             toolCalls: this.toolCalls,
             inputTokens: this.inputTokens,
             outputTokens: this.outputTokens,
-            totalTokens: this.inputTokens + this.outputTokens,
+            cacheReadTokens: this.cacheReadTokens,
+            cacheWriteTokens: this.cacheWriteTokens,
+            totalTokens: this.totalTokens,
             costUsd: this.costUsd,
-            wallClockMs: Math.max(0, this.now() - this.startedAt),
+            wallClockMs: this.wallClockMsAt(this.currentTime()),
         };
     }
-    authorize(manifest, toolName, params) {
-        if (this.grant.expiresAt && Date.parse(this.grant.expiresAt) <= this.now()) {
+    authorize(manifest, toolName, params, now, wallClockMs) {
+        if (this.grant.expiresAt && Date.parse(this.grant.expiresAt) <= now) {
             this.deny(toolName, "grant_expired", `Execution grant '${this.grant.grantId}' expired.`);
         }
         if (!this.grant.allowedTools.includes(toolName)) {
@@ -89,7 +171,7 @@ export class CapabilityGateway {
         if (!manifest.capabilities.every((capability) => this.grant.capabilities.includes(capability))) {
             this.deny(toolName, "capability_not_granted", `Tool '${toolName}' requires an ungranted capability.`);
         }
-        this.enforceBudget(toolName);
+        this.enforceBudget(toolName, wallClockMs);
         if (manifest.capabilities.some((capability) => PATH_CAPABILITIES.has(capability))) {
             const allowedPaths = manifest.capabilities.some((capability) => WRITE_CAPABILITIES.has(capability))
                 ? this.grant.writePaths
@@ -105,33 +187,51 @@ export class CapabilityGateway {
             }
         }
     }
-    enforceBudget(toolName) {
+    enforceBudget(toolName, wallClockMs) {
         const budget = this.grant.budget;
         if (budget.maxToolCalls !== undefined && this.toolCalls >= budget.maxToolCalls) {
             this.deny(toolName, "tool_call_budget_exhausted", "Tool-call budget exhausted.");
         }
-        if (budget.maxTokens !== undefined && this.inputTokens + this.outputTokens >= budget.maxTokens) {
+        if (budget.maxTokens !== undefined && this.totalTokens >= budget.maxTokens) {
             this.deny(toolName, "token_budget_exhausted", "Token budget exhausted.");
         }
         if (budget.maxCostUsd !== undefined && this.costUsd >= budget.maxCostUsd) {
             this.deny(toolName, "cost_budget_exhausted", "Cost budget exhausted.");
         }
-        if (budget.maxWallClockMs !== undefined && this.now() - this.startedAt >= budget.maxWallClockMs) {
+        if (budget.maxWallClockMs !== undefined && wallClockMs >= budget.maxWallClockMs) {
             this.deny(toolName, "wall_clock_budget_exhausted", "Wall-clock budget exhausted.");
         }
     }
+    currentTime() {
+        const now = this.now();
+        if (!Number.isFinite(now)) {
+            throw new Error("CapabilityGateway: clock source must return a finite time.");
+        }
+        return now;
+    }
+    wallClockMsAt(now) {
+        const elapsed = now - this.startedAt;
+        if (!Number.isFinite(elapsed)) {
+            throw new Error("CapabilityGateway: active wall-clock elapsed time must be finite.");
+        }
+        const wallClockMs = this.initialWallClockMs + Math.max(0, elapsed);
+        if (!Number.isFinite(wallClockMs) || wallClockMs < 0) {
+            throw new Error("CapabilityGateway: accumulated wall-clock usage must be finite and non-negative.");
+        }
+        return wallClockMs;
+    }
     pathAllowed(rawPath, allowedPaths) {
         const target = resolveRealPath(this.cwd, rawPath);
         if (!target || allowedPaths.length === 0)
             return false;
         for (const denied of this.grant.deniedPaths) {
             const root = resolveRealPath(this.cwd, denied);
-            if (root && isWithinRoot(target, root))
+            if (root && isPathWithinScope(target, root))
                 return false;
         }
         return allowedPaths.some((allowed) => {
             const root = resolveRealPath(this.cwd, allowed);
-            return root !== undefined && isWithinRoot(target, root);
+            return root !== undefined && isPathWithinScope(target, root);
         });
     }
     deny(toolName, reasonCode, message) {
@@ -145,7 +245,7 @@ export class CapabilityGateway {
             toolName,
             outcome,
             reasonCode,
-            at: new Date(this.now()).toISOString(),
+            at: new Date(this.currentTime()).toISOString(),
         });
     }
 }