@caupulican/pi-adaptative 0.81.41 → 0.81.43

package/dist/core/models/runtime-process.js

@@ -0,0 +1,183 @@
+import { spawn } from "node:child_process";
+import { createWriteStream, existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { spawnProcess, spawnProcessSync, waitForChildProcessWithTermination } from "../../utils/child-process.js";
+import { sleep } from "../../utils/sleep.js";
+import { createRollingOutputBuffer } from "../exec.js";
+const DEFAULT_RUNTIME_OUTPUT_UNITS = 1024 * 1024;
+/**
+ * Build a runtime-management command runner with one bounded process lifecycle.
+ * Output is retained as chunk tails and flattened once, after the child reaches a terminal state.
+ */
+export function createRuntimeCommandRunner(limits) {
+    const requestedOutputUnits = limits.maxOutputUnits ?? DEFAULT_RUNTIME_OUTPUT_UNITS;
+    const maxOutputUnits = Number.isFinite(requestedOutputUnits) && requestedOutputUnits > 0
+        ? Math.floor(requestedOutputUnits)
+        : DEFAULT_RUNTIME_OUTPUT_UNITS;
+    return async (command, args, options = {}) => {
+        try {
+            const proc = spawnProcess(command, args, {
+                detached: process.platform !== "win32",
+                stdio: ["ignore", "pipe", "pipe"],
+                env: options.env ? { ...process.env, ...options.env } : process.env,
+            });
+            const stdout = createRollingOutputBuffer(maxOutputUnits);
+            const stderr = createRollingOutputBuffer(maxOutputUnits);
+            proc.stdout.setEncoding("utf8");
+            proc.stderr.setEncoding("utf8");
+            proc.stdout.on("data", (chunk) => {
+                stdout.push(chunk);
+                options.onOutput?.(chunk);
+            });
+            proc.stderr.on("data", (chunk) => {
+                stderr.push(chunk);
+                options.onOutput?.(chunk);
+            });
+            const terminal = await waitForChildProcessWithTermination(proc, {
+                timeoutMs: limits.timeoutMs,
+                killGraceMs: limits.killGraceMs,
+            });
+            const stdoutText = stdout.text();
+            const stderrText = stderr.text();
+            return {
+                ok: terminal.code === 0,
+                stdout: stdoutText,
+                stderr: stderrText,
+                code: terminal.code,
+                ...(terminal.code === 0
+                    ? {}
+                    : {
+                        error: terminal.reason === "timeout"
+                            ? `${command} timed out after ${limits.timeoutMs}ms`
+                            : stderrText.trim() || stdoutText.trim() || `exit code ${terminal.code ?? "unknown"}`,
+                    }),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: "",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    };
+}
+export function runtimeCommandAvailable(command) {
+    return spawnProcessSync(command, ["--version"], { encoding: "utf8", timeout: 5_000 }).error === undefined;
+}
+export function runtimeSleep(ms) {
+    return sleep(ms);
+}
+export function spawnManagedRuntime(command, args, options) {
+    return spawn(command, args, { ...options, stdio: "ignore" });
+}
+/** Resolve the common runtime lifecycle boundary once, during construction. */
+export function resolveRuntimeLifecycleDependencies(overrides) {
+    return [
+        overrides?.fetchFn ?? fetch,
+        overrides?.spawnFn ?? spawnManagedRuntime,
+        overrides?.existsFn ?? existsSync,
+        overrides?.sleepFn ?? runtimeSleep,
+    ];
+}
+/** Validate a runtime download without consuming, decoding, or copying its response body. */
+export async function fetchRuntimeDownload(fetchFn, url, init) {
+    let response;
+    try {
+        response = await fetchFn(url, init);
+    }
+    catch (error) {
+        return { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (!response.ok || !response.body)
+        return { ok: false, error: `download-fail: HTTP ${response.status}` };
+    return { ok: true, response, body: response.body };
+}
+/** Download and extract a runtime archive without materializing or copying its body. */
+export async function installRuntimeArchive(fetchFn, downloadUrl, destDir, asset, extractArchive, onProgress) {
+    onProgress?.(`Downloading ${asset.name}…`);
+    const download = await fetchRuntimeDownload(fetchFn, downloadUrl);
+    if (!download.ok)
+        return download;
+    mkdirSync(destDir, { recursive: true });
+    onProgress?.(`Extracting ${asset.name}…`);
+    return extractArchive(download.body, destDir, asset.kind);
+}
+export function tryFileSizeBytes(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function removePartialDownload(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // best-effort cleanup
+    }
+}
+/** Wait for a failed pipeline's file descriptor to close before deleting its partial output. */
+export function waitForWritableClosed(stream) {
+    if (stream.closed)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        stream.once("close", resolve);
+        stream.destroy();
+    });
+}
+/** Stream a runtime payload to disk, closing and deleting partial output on any failure. */
+export async function writeRuntimeDownload(input, destPath, transform) {
+    const writeStream = createWriteStream(destPath);
+    try {
+        if (transform)
+            await pipeline(input, transform, writeStream);
+        else
+            await pipeline(input, writeStream);
+        return { ok: true };
+    }
+    catch (error) {
+        await waitForWritableClosed(writeStream);
+        removePartialDownload(destPath);
+        return { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export function requireRuntimeStdin(proc, label) {
+    if (!proc.stdin)
+        throw new Error(`${label}: no stdin pipe`);
+    return proc.stdin;
+}
+/** Shared seekable-file extraction path for managed runtime zip archives. */
+export async function extractZipArchive(options) {
+    const zipPath = join(options.destDir, "..", `${options.tempPrefix}-${process.pid}-${Date.now()}.zip`);
+    try {
+        await pipeline(options.input, createWriteStream(zipPath));
+        const extractCommand = options.platform() === "win32" && options.hasCommand("tar") ? "tar" : "unzip";
+        const args = extractCommand === "tar" ? ["-xf", zipPath, "-C", options.destDir] : ["-q", zipPath, "-d", options.destDir];
+        const proc = spawnProcess(extractCommand, args, {
+            detached: process.platform !== "win32",
+            stdio: "ignore",
+        });
+        const terminal = await waitForChildProcessWithTermination(proc, {
+            timeoutMs: options.timeoutMs,
+            killGraceMs: options.killGraceMs,
+        });
+        if (terminal.reason === "timeout" || terminal.code !== 0) {
+            return {
+                ok: false,
+                error: terminal.reason === "timeout"
+                    ? `extract-fail: ${extractCommand} timed out after ${options.timeoutMs}ms`
+                    : `extract-fail: ${extractCommand} exited with code ${terminal.code ?? "unknown"}`,
+            };
+        }
+        return { ok: true };
+    }
+    finally {
+        removePartialDownload(zipPath);
+    }
+}
+//# sourceMappingURL=runtime-process.js.map

package/dist/core/models/runtime-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-process.js","sourceRoot":"","sources":["../../../src/core/models/runtime-process.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, spawn } from \"node:child_process\";\nimport { createWriteStream, existsSync, mkdirSync, rmSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { Readable, Transform, Writable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport { spawnProcess, spawnProcessSync, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport { sleep } from \"../../utils/sleep.ts\";\nimport { createRollingOutputBuffer } from \"../exec.ts\";\n\nexport interface RuntimeCommandResult {\n\tok: boolean;\n\tstdout: string;\n\tstderr: string;\n\tcode?: number | null;\n\terror?: string;\n}\n\nexport interface RuntimeCommandOptions {\n\tenv?: NodeJS.ProcessEnv;\n\tonOutput?: (chunk: string) => void;\n}\n\nexport type RuntimeCommandRunner = (\n\tcommand: string,\n\targs: string[],\n\toptions?: RuntimeCommandOptions,\n) => Promise<RuntimeCommandResult>;\n\nexport interface RuntimeCommandRunnerLimits {\n\ttimeoutMs: number;\n\tkillGraceMs: number;\n\tmaxOutputUnits?: number;\n}\n\nconst DEFAULT_RUNTIME_OUTPUT_UNITS = 1024 * 1024;\n\n/**\n * Build a runtime-management command runner with one bounded process lifecycle.\n * Output is retained as chunk tails and flattened once, after the child reaches a terminal state.\n */\nexport function createRuntimeCommandRunner(limits: RuntimeCommandRunnerLimits): RuntimeCommandRunner {\n\tconst requestedOutputUnits = limits.maxOutputUnits ?? DEFAULT_RUNTIME_OUTPUT_UNITS;\n\tconst maxOutputUnits =\n\t\tNumber.isFinite(requestedOutputUnits) && requestedOutputUnits > 0\n\t\t\t? Math.floor(requestedOutputUnits)\n\t\t\t: DEFAULT_RUNTIME_OUTPUT_UNITS;\n\treturn async (command, args, options = {}) => {\n\t\ttry {\n\t\t\tconst proc = spawnProcess(command, args, {\n\t\t\t\tdetached: process.platform !== \"win32\",\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\tenv: options.env ? { ...process.env, ...options.env } : process.env,\n\t\t\t});\n\t\t\tconst stdout = createRollingOutputBuffer(maxOutputUnits);\n\t\t\tconst stderr = createRollingOutputBuffer(maxOutputUnits);\n\t\t\tproc.stdout.setEncoding(\"utf8\");\n\t\t\tproc.stderr.setEncoding(\"utf8\");\n\t\t\tproc.stdout.on(\"data\", (chunk: string) => {\n\t\t\t\tstdout.push(chunk);\n\t\t\t\toptions.onOutput?.(chunk);\n\t\t\t});\n\t\t\tproc.stderr.on(\"data\", (chunk: string) => {\n\t\t\t\tstderr.push(chunk);\n\t\t\t\toptions.onOutput?.(chunk);\n\t\t\t});\n\t\t\tconst terminal = await waitForChildProcessWithTermination(proc, {\n\t\t\t\ttimeoutMs: limits.timeoutMs,\n\t\t\t\tkillGraceMs: limits.killGraceMs,\n\t\t\t});\n\t\t\tconst stdoutText = stdout.text();\n\t\t\tconst stderrText = stderr.text();\n\t\t\treturn {\n\t\t\t\tok: terminal.code === 0,\n\t\t\t\tstdout: stdoutText,\n\t\t\t\tstderr: stderrText,\n\t\t\t\tcode: terminal.code,\n\t\t\t\t...(terminal.code === 0\n\t\t\t\t\t? {}\n\t\t\t\t\t: {\n\t\t\t\t\t\t\terror:\n\t\t\t\t\t\t\t\tterminal.reason === \"timeout\"\n\t\t\t\t\t\t\t\t\t? `${command} timed out after ${limits.timeoutMs}ms`\n\t\t\t\t\t\t\t\t\t: stderrText.trim() || stdoutText.trim() || `exit code ${terminal.code ?? \"unknown\"}`,\n\t\t\t\t\t\t}),\n\t\t\t};\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\tstdout: \"\",\n\t\t\t\tstderr: \"\",\n\t\t\t\terror: error instanceof Error ? error.message : String(error),\n\t\t\t};\n\t\t}\n\t};\n}\n\nexport function runtimeCommandAvailable(command: string): boolean {\n\treturn spawnProcessSync(command, [\"--version\"], { encoding: \"utf8\", timeout: 5_000 }).error === undefined;\n}\n\nexport function runtimeSleep(ms: number): Promise<void> {\n\treturn sleep(ms);\n}\n\nexport type ManagedRuntimeChild = Pick<ChildProcess, \"pid\" | \"kill\" | \"unref\" | \"on\">;\nexport interface ManagedRuntimeSpawnOptions {\n\tdetached?: boolean;\n\tstdio?: \"ignore\";\n\tenv: NodeJS.ProcessEnv;\n}\nexport type ManagedRuntimeSpawn = (\n\tcommand: string,\n\targs: string[],\n\toptions: ManagedRuntimeSpawnOptions,\n) => ManagedRuntimeChild;\n\nexport function spawnManagedRuntime(\n\tcommand: string,\n\targs: string[],\n\toptions: ManagedRuntimeSpawnOptions,\n): ManagedRuntimeChild {\n\treturn spawn(command, args, { ...options, stdio: \"ignore\" });\n}\n\nexport interface RuntimeLifecycleDependencyOverrides {\n\tfetchFn?: typeof fetch;\n\tspawnFn?: ManagedRuntimeSpawn;\n\texistsFn?: (path: string) => boolean;\n\tsleepFn?: (ms: number) => Promise<void>;\n}\n\nexport type RuntimeLifecycleDependencies = readonly [\n\tfetchFn: typeof fetch,\n\tspawnFn: ManagedRuntimeSpawn,\n\texistsFn: (path: string) => boolean,\n\tsleepFn: (ms: number) => Promise<void>,\n];\n\n/** Resolve the common runtime lifecycle boundary once, during construction. */\nexport function resolveRuntimeLifecycleDependencies(\n\toverrides?: RuntimeLifecycleDependencyOverrides,\n): RuntimeLifecycleDependencies {\n\treturn [\n\t\toverrides?.fetchFn ?? fetch,\n\t\toverrides?.spawnFn ?? spawnManagedRuntime,\n\t\toverrides?.existsFn ?? existsSync,\n\t\toverrides?.sleepFn ?? runtimeSleep,\n\t];\n}\n\nexport type RuntimeDownloadResult =\n\t| { ok: true; response: Response; body: ReadableStream<Uint8Array> }\n\t| { ok: false; error: string };\n\ntype RuntimeFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;\n\n/** Validate a runtime download without consuming, decoding, or copying its response body. */\nexport async function fetchRuntimeDownload(\n\tfetchFn: RuntimeFetch,\n\turl: string,\n\tinit?: RequestInit,\n): Promise<RuntimeDownloadResult> {\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetchFn(url, init);\n\t} catch (error) {\n\t\treturn { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };\n\t}\n\tif (!response.ok || !response.body) return { ok: false, error: `download-fail: HTTP ${response.status}` };\n\treturn { ok: true, response, body: response.body };\n}\n\n/** Download and extract a runtime archive without materializing or copying its body. */\nexport async function installRuntimeArchive<TInput extends NodeJS.ReadableStream, TKind extends string>(\n\tfetchFn: RuntimeFetch,\n\tdownloadUrl: string,\n\tdestDir: string,\n\tasset: { name: string; kind: TKind },\n\textractArchive: (input: TInput, destDir: string, kind: TKind) => Promise<{ ok: boolean; error?: string }>,\n\tonProgress?: (status: string) => void,\n): Promise<{ ok: boolean; error?: string }> {\n\tonProgress?.(`Downloading ${asset.name}…`);\n\tconst download = await fetchRuntimeDownload(fetchFn, downloadUrl);\n\tif (!download.ok) return download;\n\tmkdirSync(destDir, { recursive: true });\n\tonProgress?.(`Extracting ${asset.name}…`);\n\treturn extractArchive(download.body as unknown as TInput, destDir, asset.kind);\n}\n\nexport function tryFileSizeBytes(path: string): number | undefined {\n\ttry {\n\t\treturn statSync(path).size;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport function removePartialDownload(path: string): void {\n\ttry {\n\t\trmSync(path, { force: true });\n\t} catch {\n\t\t// best-effort cleanup\n\t}\n}\n\n/** Wait for a failed pipeline's file descriptor to close before deleting its partial output. */\nexport function waitForWritableClosed(stream: Writable & { closed?: boolean }): Promise<void> {\n\tif (stream.closed) return Promise.resolve();\n\treturn new Promise((resolve) => {\n\t\tstream.once(\"close\", resolve);\n\t\tstream.destroy();\n\t});\n}\n\n/** Stream a runtime payload to disk, closing and deleting partial output on any failure. */\nexport async function writeRuntimeDownload(\n\tinput: Readable,\n\tdestPath: string,\n\ttransform?: Transform,\n): Promise<{ ok: true } | { ok: false; error: string }> {\n\tconst writeStream = createWriteStream(destPath);\n\ttry {\n\t\tif (transform) await pipeline(input, transform, writeStream);\n\t\telse await pipeline(input, writeStream);\n\t\treturn { ok: true };\n\t} catch (error) {\n\t\tawait waitForWritableClosed(writeStream);\n\t\tremovePartialDownload(destPath);\n\t\treturn { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };\n\t}\n}\n\nexport function requireRuntimeStdin(proc: ChildProcess, label: string): Writable {\n\tif (!proc.stdin) throw new Error(`${label}: no stdin pipe`);\n\treturn proc.stdin;\n}\n\nexport interface ExtractZipArchiveOptions {\n\tinput: Readable;\n\tdestDir: string;\n\ttempPrefix: string;\n\tplatform: () => string;\n\thasCommand: (command: string) => boolean;\n\ttimeoutMs: number;\n\tkillGraceMs: number;\n}\n\n/** Shared seekable-file extraction path for managed runtime zip archives. */\nexport async function extractZipArchive(options: ExtractZipArchiveOptions): Promise<{ ok: boolean; error?: string }> {\n\tconst zipPath = join(options.destDir, \"..\", `${options.tempPrefix}-${process.pid}-${Date.now()}.zip`);\n\ttry {\n\t\tawait pipeline(options.input, createWriteStream(zipPath));\n\t\tconst extractCommand = options.platform() === \"win32\" && options.hasCommand(\"tar\") ? \"tar\" : \"unzip\";\n\t\tconst args =\n\t\t\textractCommand === \"tar\" ? [\"-xf\", zipPath, \"-C\", options.destDir] : [\"-q\", zipPath, \"-d\", options.destDir];\n\t\tconst proc = spawnProcess(extractCommand, args, {\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t\tstdio: \"ignore\",\n\t\t});\n\t\tconst terminal = await waitForChildProcessWithTermination(proc, {\n\t\t\ttimeoutMs: options.timeoutMs,\n\t\t\tkillGraceMs: options.killGraceMs,\n\t\t});\n\t\tif (terminal.reason === \"timeout\" || terminal.code !== 0) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror:\n\t\t\t\t\tterminal.reason === \"timeout\"\n\t\t\t\t\t\t? `extract-fail: ${extractCommand} timed out after ${options.timeoutMs}ms`\n\t\t\t\t\t\t: `extract-fail: ${extractCommand} exited with code ${terminal.code ?? \"unknown\"}`,\n\t\t\t};\n\t\t}\n\t\treturn { ok: true };\n\t} finally {\n\t\tremovePartialDownload(zipPath);\n\t}\n}\n"]}

package/dist/core/orchestration/agent-resume.d.ts

@@ -16,6 +16,8 @@ export interface BuildPiResumeLaunchSpecOptions {
 export declare function isAgentIdentity(value: unknown): value is AgentIdentityContract;
 /** Build and validate the one logical identity shared by orchestration and process supervision. */
 export declare function createAgentIdentity(agentId: string, resumeContext: AgentResumeContext): AgentIdentityContract;
+/** Compare only the immutable identity behind a resumable agent; checkpoint position is mutable. */
+export declare function sameAgentResumeIdentity(left: AgentResumeContext, right: AgentResumeContext): boolean;
 /**
  * Build an argv-safe launch specification for the exact persisted Pi session behind a logical
  * agent. The caller passes argv directly to spawn; no shell quoting or command string is involved.

package/dist/core/orchestration/agent-resume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-resume.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/agent-resume.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,qBAAqB,EAAE,KAAK,kBAAkB,EAAyB,MAAM,gBAAgB,CAAC;AAE5G,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,8BAA8B;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAiC9E;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,kBAAkB,GAAG,qBAAqB,CAQ7G;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,8BAA8B,GACrC,kBAAkB,CA2BpB","sourcesContent":["import { PI_ORCHESTRATION_AGENT_ID_ENV } from \"../process-identity.ts\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\nimport { type AgentIdentityContract, type AgentResumeContext, isResourcePointerKind } from \"./contracts.ts\";\n\nexport interface PiResumeLaunchSpec {\n\texecutable: string;\n\targs: readonly string[];\n\tcwd: string;\n\tenv: Readonly<Record<string, string>>;\n}\n\nexport interface BuildPiResumeLaunchSpecOptions {\n\texecutable?: string;\n\targsPrefix?: readonly string[];\n\tparentPid: number;\n\tparentSessionId: string;\n\ttaskRef?: string;\n\twakePrompt?: string;\n}\n\nfunction isOptionalString(value: unknown): value is string | undefined {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nexport function isAgentIdentity(value: unknown): value is AgentIdentityContract {\n\tif (!isPlainRecord(value) || !isPlainRecord(value.resumeContext)) return false;\n\tconst context = value.resumeContext;\n\treturn (\n\t\ttypeof value.agentId === \"string\" &&\n\t\tvalue.agentId.trim().length > 0 &&\n\t\t(context.provider === \"pi\" || context.provider === \"external\") &&\n\t\ttypeof context.sessionId === \"string\" &&\n\t\tcontext.sessionId.trim().length > 0 &&\n\t\ttypeof context.cwd === \"string\" &&\n\t\tcontext.cwd.trim().length > 0 &&\n\t\tisOptionalString(context.sessionDir) &&\n\t\tisOptionalString(context.sessionFile) &&\n\t\tisOptionalString(context.worktreeLaneKey) &&\n\t\tisOptionalString(context.orchestrationProfileId) &&\n\t\tisOptionalString(context.modelRef) &&\n\t\tisOptionalString(context.latestCheckpointId) &&\n\t\tArray.isArray(context.resourceProfileNames) &&\n\t\tcontext.resourceProfileNames.every((name) => typeof name === \"string\" && name.trim().length > 0) &&\n\t\tArray.isArray(context.contextPointers) &&\n\t\tcontext.contextPointers.every(\n\t\t\t(pointer) =>\n\t\t\t\tisPlainRecord(pointer) &&\n\t\t\t\ttypeof pointer.id === \"string\" &&\n\t\t\t\tpointer.id.trim().length > 0 &&\n\t\t\t\tisResourcePointerKind(pointer.kind) &&\n\t\t\t\ttypeof pointer.uri === \"string\" &&\n\t\t\t\tpointer.uri.trim().length > 0 &&\n\t\t\t\ttypeof pointer.readOnly === \"boolean\" &&\n\t\t\t\tisOptionalString(pointer.digest) &&\n\t\t\t\t(pointer.metadata === undefined || isPlainRecord(pointer.metadata)),\n\t\t)\n\t);\n}\n\n/** Build and validate the one logical identity shared by orchestration and process supervision. */\nexport function createAgentIdentity(agentId: string, resumeContext: AgentResumeContext): AgentIdentityContract {\n\tconst normalizedAgentId = agentId.trim();\n\tif (!normalizedAgentId) throw new TypeError(\"A logical agent id is required.\");\n\tif (!resumeContext.sessionId.trim()) throw new TypeError(\"An agent session id is required.\");\n\tif (!resumeContext.cwd.trim()) throw new TypeError(\"An agent working directory is required.\");\n\tconst identity = { agentId: normalizedAgentId, resumeContext: structuredClone(resumeContext) };\n\tif (!isAgentIdentity(identity)) throw new TypeError(\"Agent resume context is invalid.\");\n\treturn identity;\n}\n\n/**\n * Build an argv-safe launch specification for the exact persisted Pi session behind a logical\n * agent. The caller passes argv directly to spawn; no shell quoting or command string is involved.\n */\nexport function buildPiResumeLaunchSpec(\n\tagent: AgentIdentityContract,\n\toptions: BuildPiResumeLaunchSpecOptions,\n): PiResumeLaunchSpec {\n\tconst identity = createAgentIdentity(agent.agentId, agent.resumeContext);\n\tconst context = identity.resumeContext;\n\tif (context.provider !== \"pi\") throw new TypeError(`Agent '${identity.agentId}' is not backed by a Pi session.`);\n\tif (!Number.isSafeInteger(options.parentPid) || options.parentPid <= 0) {\n\t\tthrow new TypeError(\"A positive parent pid is required to resume a Pi agent.\");\n\t}\n\tif (!options.parentSessionId.trim()) throw new TypeError(\"A parent session id is required to resume a Pi agent.\");\n\tconst args: string[] = [...(options.argsPrefix ?? [])];\n\tif (context.sessionDir) args.push(\"--session-dir\", context.sessionDir);\n\targs.push(\"--session\", context.sessionFile ?? context.sessionId);\n\targs.push(\"--parent-pid\", String(options.parentPid));\n\targs.push(\"--parent-session\", options.parentSessionId);\n\tif (options.taskRef?.trim()) args.push(\"--task-ref\", options.taskRef.trim());\n\tif (context.worktreeLaneKey) args.push(\"--worktree-lane\", context.worktreeLaneKey);\n\tif (context.orchestrationProfileId) {\n\t\targs.push(\"--orchestration-profile\", context.orchestrationProfileId);\n\t} else if (context.resourceProfileNames.length > 0) {\n\t\targs.push(\"--resource-profile\", context.resourceProfileNames.join(\",\"));\n\t}\n\tif (options.wakePrompt?.trim()) args.push(\"--print\", options.wakePrompt.trim());\n\treturn {\n\t\texecutable: options.executable ?? \"pi\",\n\t\targs,\n\t\tcwd: context.cwd,\n\t\tenv: { PI_SESSION_ROLE: \"worker\", [PI_ORCHESTRATION_AGENT_ID_ENV]: identity.agentId },\n\t};\n}\n"]}
+{"version":3,"file":"agent-resume.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/agent-resume.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,qBAAqB,EAAE,KAAK,kBAAkB,EAAyB,MAAM,gBAAgB,CAAC;AAE5G,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,8BAA8B;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAiC9E;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,kBAAkB,GAAG,qBAAqB,CAQ7G;AAED,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAIpG;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,8BAA8B,GACrC,kBAAkB,CA2BpB"}

package/dist/core/orchestration/agent-resume.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import { PI_ORCHESTRATION_AGENT_ID_ENV } from "../process-identity.js";
 import { isPlainRecord } from "../util/value-guards.js";
 import { isResourcePointerKind } from "./contracts.js";
@@ -48,6 +49,12 @@ export function createAgentIdentity(agentId, resumeContext) {
         throw new TypeError("Agent resume context is invalid.");
     return identity;
 }
+/** Compare only the immutable identity behind a resumable agent; checkpoint position is mutable. */
+export function sameAgentResumeIdentity(left, right) {
+    const { latestCheckpointId: _leftCheckpoint, ...leftIdentity } = left;
+    const { latestCheckpointId: _rightCheckpoint, ...rightIdentity } = right;
+    return isDeepStrictEqual(leftIdentity, rightIdentity);
+}
 /**
  * Build an argv-safe launch specification for the exact persisted Pi session behind a logical
  * agent. The caller passes argv directly to spawn; no shell quoting or command string is involved.

package/dist/core/orchestration/agent-resume.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-resume.js","sourceRoot":"","sources":["../../../src/core/orchestration/agent-resume.ts"],"names":[],"mappings":"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","sourcesContent":["import { PI_ORCHESTRATION_AGENT_ID_ENV } from \"../process-identity.ts\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\nimport { type AgentIdentityContract, type AgentResumeContext, isResourcePointerKind } from \"./contracts.ts\";\n\nexport interface PiResumeLaunchSpec {\n\texecutable: string;\n\targs: readonly string[];\n\tcwd: string;\n\tenv: Readonly<Record<string, string>>;\n}\n\nexport interface BuildPiResumeLaunchSpecOptions {\n\texecutable?: string;\n\targsPrefix?: readonly string[];\n\tparentPid: number;\n\tparentSessionId: string;\n\ttaskRef?: string;\n\twakePrompt?: string;\n}\n\nfunction isOptionalString(value: unknown): value is string | undefined {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nexport function isAgentIdentity(value: unknown): value is AgentIdentityContract {\n\tif (!isPlainRecord(value) || !isPlainRecord(value.resumeContext)) return false;\n\tconst context = value.resumeContext;\n\treturn (\n\t\ttypeof value.agentId === \"string\" &&\n\t\tvalue.agentId.trim().length > 0 &&\n\t\t(context.provider === \"pi\" || context.provider === \"external\") &&\n\t\ttypeof context.sessionId === \"string\" &&\n\t\tcontext.sessionId.trim().length > 0 &&\n\t\ttypeof context.cwd === \"string\" &&\n\t\tcontext.cwd.trim().length > 0 &&\n\t\tisOptionalString(context.sessionDir) &&\n\t\tisOptionalString(context.sessionFile) &&\n\t\tisOptionalString(context.worktreeLaneKey) &&\n\t\tisOptionalString(context.orchestrationProfileId) &&\n\t\tisOptionalString(context.modelRef) &&\n\t\tisOptionalString(context.latestCheckpointId) &&\n\t\tArray.isArray(context.resourceProfileNames) &&\n\t\tcontext.resourceProfileNames.every((name) => typeof name === \"string\" && name.trim().length > 0) &&\n\t\tArray.isArray(context.contextPointers) &&\n\t\tcontext.contextPointers.every(\n\t\t\t(pointer) =>\n\t\t\t\tisPlainRecord(pointer) &&\n\t\t\t\ttypeof pointer.id === \"string\" &&\n\t\t\t\tpointer.id.trim().length > 0 &&\n\t\t\t\tisResourcePointerKind(pointer.kind) &&\n\t\t\t\ttypeof pointer.uri === \"string\" &&\n\t\t\t\tpointer.uri.trim().length > 0 &&\n\t\t\t\ttypeof pointer.readOnly === \"boolean\" &&\n\t\t\t\tisOptionalString(pointer.digest) &&\n\t\t\t\t(pointer.metadata === undefined || isPlainRecord(pointer.metadata)),\n\t\t)\n\t);\n}\n\n/** Build and validate the one logical identity shared by orchestration and process supervision. */\nexport function createAgentIdentity(agentId: string, resumeContext: AgentResumeContext): AgentIdentityContract {\n\tconst normalizedAgentId = agentId.trim();\n\tif (!normalizedAgentId) throw new TypeError(\"A logical agent id is required.\");\n\tif (!resumeContext.sessionId.trim()) throw new TypeError(\"An agent session id is required.\");\n\tif (!resumeContext.cwd.trim()) throw new TypeError(\"An agent working directory is required.\");\n\tconst identity = { agentId: normalizedAgentId, resumeContext: structuredClone(resumeContext) };\n\tif (!isAgentIdentity(identity)) throw new TypeError(\"Agent resume context is invalid.\");\n\treturn identity;\n}\n\n/**\n * Build an argv-safe launch specification for the exact persisted Pi session behind a logical\n * agent. The caller passes argv directly to spawn; no shell quoting or command string is involved.\n */\nexport function buildPiResumeLaunchSpec(\n\tagent: AgentIdentityContract,\n\toptions: BuildPiResumeLaunchSpecOptions,\n): PiResumeLaunchSpec {\n\tconst identity = createAgentIdentity(agent.agentId, agent.resumeContext);\n\tconst context = identity.resumeContext;\n\tif (context.provider !== \"pi\") throw new TypeError(`Agent '${identity.agentId}' is not backed by a Pi session.`);\n\tif (!Number.isSafeInteger(options.parentPid) || options.parentPid <= 0) {\n\t\tthrow new TypeError(\"A positive parent pid is required to resume a Pi agent.\");\n\t}\n\tif (!options.parentSessionId.trim()) throw new TypeError(\"A parent session id is required to resume a Pi agent.\");\n\tconst args: string[] = [...(options.argsPrefix ?? [])];\n\tif (context.sessionDir) args.push(\"--session-dir\", context.sessionDir);\n\targs.push(\"--session\", context.sessionFile ?? context.sessionId);\n\targs.push(\"--parent-pid\", String(options.parentPid));\n\targs.push(\"--parent-session\", options.parentSessionId);\n\tif (options.taskRef?.trim()) args.push(\"--task-ref\", options.taskRef.trim());\n\tif (context.worktreeLaneKey) args.push(\"--worktree-lane\", context.worktreeLaneKey);\n\tif (context.orchestrationProfileId) {\n\t\targs.push(\"--orchestration-profile\", context.orchestrationProfileId);\n\t} else if (context.resourceProfileNames.length > 0) {\n\t\targs.push(\"--resource-profile\", context.resourceProfileNames.join(\",\"));\n\t}\n\tif (options.wakePrompt?.trim()) args.push(\"--print\", options.wakePrompt.trim());\n\treturn {\n\t\texecutable: options.executable ?? \"pi\",\n\t\targs,\n\t\tcwd: context.cwd,\n\t\tenv: { PI_SESSION_ROLE: \"worker\", [PI_ORCHESTRATION_AGENT_ID_ENV]: identity.agentId },\n\t};\n}\n"]}
+{"version":3,"file":"agent-resume.js","sourceRoot":"","sources":["../../../src/core/orchestration/agent-resume.ts"],"names":[],"mappings":"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","sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { PI_ORCHESTRATION_AGENT_ID_ENV } from \"../process-identity.ts\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\nimport { type AgentIdentityContract, type AgentResumeContext, isResourcePointerKind } from \"./contracts.ts\";\n\nexport interface PiResumeLaunchSpec {\n\texecutable: string;\n\targs: readonly string[];\n\tcwd: string;\n\tenv: Readonly<Record<string, string>>;\n}\n\nexport interface BuildPiResumeLaunchSpecOptions {\n\texecutable?: string;\n\targsPrefix?: readonly string[];\n\tparentPid: number;\n\tparentSessionId: string;\n\ttaskRef?: string;\n\twakePrompt?: string;\n}\n\nfunction isOptionalString(value: unknown): value is string | undefined {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nexport function isAgentIdentity(value: unknown): value is AgentIdentityContract {\n\tif (!isPlainRecord(value) || !isPlainRecord(value.resumeContext)) return false;\n\tconst context = value.resumeContext;\n\treturn (\n\t\ttypeof value.agentId === \"string\" &&\n\t\tvalue.agentId.trim().length > 0 &&\n\t\t(context.provider === \"pi\" || context.provider === \"external\") &&\n\t\ttypeof context.sessionId === \"string\" &&\n\t\tcontext.sessionId.trim().length > 0 &&\n\t\ttypeof context.cwd === \"string\" &&\n\t\tcontext.cwd.trim().length > 0 &&\n\t\tisOptionalString(context.sessionDir) &&\n\t\tisOptionalString(context.sessionFile) &&\n\t\tisOptionalString(context.worktreeLaneKey) &&\n\t\tisOptionalString(context.orchestrationProfileId) &&\n\t\tisOptionalString(context.modelRef) &&\n\t\tisOptionalString(context.latestCheckpointId) &&\n\t\tArray.isArray(context.resourceProfileNames) &&\n\t\tcontext.resourceProfileNames.every((name) => typeof name === \"string\" && name.trim().length > 0) &&\n\t\tArray.isArray(context.contextPointers) &&\n\t\tcontext.contextPointers.every(\n\t\t\t(pointer) =>\n\t\t\t\tisPlainRecord(pointer) &&\n\t\t\t\ttypeof pointer.id === \"string\" &&\n\t\t\t\tpointer.id.trim().length > 0 &&\n\t\t\t\tisResourcePointerKind(pointer.kind) &&\n\t\t\t\ttypeof pointer.uri === \"string\" &&\n\t\t\t\tpointer.uri.trim().length > 0 &&\n\t\t\t\ttypeof pointer.readOnly === \"boolean\" &&\n\t\t\t\tisOptionalString(pointer.digest) &&\n\t\t\t\t(pointer.metadata === undefined || isPlainRecord(pointer.metadata)),\n\t\t)\n\t);\n}\n\n/** Build and validate the one logical identity shared by orchestration and process supervision. */\nexport function createAgentIdentity(agentId: string, resumeContext: AgentResumeContext): AgentIdentityContract {\n\tconst normalizedAgentId = agentId.trim();\n\tif (!normalizedAgentId) throw new TypeError(\"A logical agent id is required.\");\n\tif (!resumeContext.sessionId.trim()) throw new TypeError(\"An agent session id is required.\");\n\tif (!resumeContext.cwd.trim()) throw new TypeError(\"An agent working directory is required.\");\n\tconst identity = { agentId: normalizedAgentId, resumeContext: structuredClone(resumeContext) };\n\tif (!isAgentIdentity(identity)) throw new TypeError(\"Agent resume context is invalid.\");\n\treturn identity;\n}\n\n/** Compare only the immutable identity behind a resumable agent; checkpoint position is mutable. */\nexport function sameAgentResumeIdentity(left: AgentResumeContext, right: AgentResumeContext): boolean {\n\tconst { latestCheckpointId: _leftCheckpoint, ...leftIdentity } = left;\n\tconst { latestCheckpointId: _rightCheckpoint, ...rightIdentity } = right;\n\treturn isDeepStrictEqual(leftIdentity, rightIdentity);\n}\n\n/**\n * Build an argv-safe launch specification for the exact persisted Pi session behind a logical\n * agent. The caller passes argv directly to spawn; no shell quoting or command string is involved.\n */\nexport function buildPiResumeLaunchSpec(\n\tagent: AgentIdentityContract,\n\toptions: BuildPiResumeLaunchSpecOptions,\n): PiResumeLaunchSpec {\n\tconst identity = createAgentIdentity(agent.agentId, agent.resumeContext);\n\tconst context = identity.resumeContext;\n\tif (context.provider !== \"pi\") throw new TypeError(`Agent '${identity.agentId}' is not backed by a Pi session.`);\n\tif (!Number.isSafeInteger(options.parentPid) || options.parentPid <= 0) {\n\t\tthrow new TypeError(\"A positive parent pid is required to resume a Pi agent.\");\n\t}\n\tif (!options.parentSessionId.trim()) throw new TypeError(\"A parent session id is required to resume a Pi agent.\");\n\tconst args: string[] = [...(options.argsPrefix ?? [])];\n\tif (context.sessionDir) args.push(\"--session-dir\", context.sessionDir);\n\targs.push(\"--session\", context.sessionFile ?? context.sessionId);\n\targs.push(\"--parent-pid\", String(options.parentPid));\n\targs.push(\"--parent-session\", options.parentSessionId);\n\tif (options.taskRef?.trim()) args.push(\"--task-ref\", options.taskRef.trim());\n\tif (context.worktreeLaneKey) args.push(\"--worktree-lane\", context.worktreeLaneKey);\n\tif (context.orchestrationProfileId) {\n\t\targs.push(\"--orchestration-profile\", context.orchestrationProfileId);\n\t} else if (context.resourceProfileNames.length > 0) {\n\t\targs.push(\"--resource-profile\", context.resourceProfileNames.join(\",\"));\n\t}\n\tif (options.wakePrompt?.trim()) args.push(\"--print\", options.wakePrompt.trim());\n\treturn {\n\t\texecutable: options.executable ?? \"pi\",\n\t\targs,\n\t\tcwd: context.cwd,\n\t\tenv: { PI_SESSION_ROLE: \"worker\", [PI_ORCHESTRATION_AGENT_ID_ENV]: identity.agentId },\n\t};\n}\n"]}

package/dist/core/orchestration/attempt-usage.d.ts

@@ -0,0 +1,28 @@
+import type { Usage } from "@caupulican/pi-ai";
+import type { AttemptUsageSnapshot } from "./contracts.ts";
+export declare const EMPTY_ATTEMPT_USAGE: AttemptUsageSnapshot;
+/** Parse an untrusted provider-neutral usage report into a closed, known-field value. */
+export declare function validateProviderUsage(value: unknown, label?: string): Usage;
+/** Validate the one durable cumulative usage shape shared by checkpoints, recovery, and results. */
+export declare function validateAttemptUsageSnapshot(usage: AttemptUsageSnapshot, label?: string): AttemptUsageSnapshot;
+export declare function attemptUsageFromGatewayUsage(usage: {
+    toolCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    wallClockMs: number;
+}): AttemptUsageSnapshot;
+export declare function addAttemptUsage(base: AttemptUsageSnapshot, delta: AttemptUsageSnapshot, label?: string): AttemptUsageSnapshot;
+/**
+ * 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 declare function reconcileAttemptUsage(checkpoint: AttemptUsageSnapshot, transcript: AttemptUsageSnapshot): AttemptUsageSnapshot;
+export declare function remainingTokenBudget(maxTokens: number | undefined, usage: AttemptUsageSnapshot): number | undefined;
+/** Convert durable cumulative accounting into the provider-neutral report shape exactly once. */
+export declare function providerUsageFromAttemptUsage(usage: AttemptUsageSnapshot): Usage;
+//# sourceMappingURL=attempt-usage.d.ts.map

package/dist/core/orchestration/attempt-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-usage.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/attempt-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,eAAO,MAAM,mBAAmB,EAAE,oBASjC,CAAC;AAwBF,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAmB,GAAG,KAAK,CAyCrF;AAED,oGAAoG;AACpG,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,KAAK,SAAkB,GACrB,oBAAoB,CA0BtB;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACpB,GAAG,oBAAoB,CAcvB;AAED,wBAAgB,eAAe,CAC9B,IAAI,EAAE,oBAAoB,EAC1B,KAAK,EAAE,oBAAoB,EAC3B,KAAK,SAAkB,GACrB,oBAAoB,CAgBtB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,UAAU,EAAE,oBAAoB,EAChC,UAAU,EAAE,oBAAoB,GAC9B,oBAAoB,CAatB;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAInH;AAED,iGAAiG;AACjG,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,oBAAoB,GAAG,KAAK,CAUhF"}

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;