@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/models/prism-llamacpp-lifecycle.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Core lifecycle logic for pi-managed prism llama.cpp models (Bonsai-27B first), shared between the
+ * `/models add` install pipeline (modes/interactive/local-model-commands.ts) and the router's
+ * readiness gate (local-runtime-controller.ts). ONE place owns "ensure both GGUF files exist, then
+ * serve" so a turn routed to a cold Bonsai-27B and a fresh `/models add` both go through the
+ * identical self-healing path instead of two parallel, potentially-diverging implementations.
+ *
+ * Lives in core/models/ (not modes/) so the headless readiness gate — used by print/RPC/interactive
+ * sessions and isolated/background lanes alike — never depends on the interactive-only UI layer;
+ * mirrors the existing local-runtime.ts (mechanics) / local-runtime-controller.ts (gate) split.
+ */
+import { type PrismLlamaCppRuntime, type PrismModelDescriptor } from "./llamacpp-runtime.ts";
+/**
+ * Curated prism llama.cpp descriptors, keyed by repo id — matches the modelId model-ref.ts's
+ * curated `PRISM_LLAMACPP_MODEL_IDS` route returns, and the id `registerPrismLlamaCppModel` writes
+ * as the model's id in models.json. Add future curated prism-ml models to both places together.
+ *
+ * Also the pi-managed-vs-user-owned discriminator (see {@link isPiManagedPrismLlamaCppModel}): a
+ * `llama-cpp` provider model is gated/self-healed by pi ONLY when its id is a key here — a user's
+ * own hand-configured entry (e.g. the built-in `llama-cpp/local` catalog model on port 8080,
+ * pointing at a server the user runs themselves) is never touched.
+ */
+export declare const PRISM_LLAMACPP_DESCRIPTORS: Record<string, PrismModelDescriptor>;
+/**
+ * True only for a `llama-cpp` provider model pi itself registered (id present in
+ * {@link PRISM_LLAMACPP_DESCRIPTORS}) — never true for a user's own hand-configured llama-cpp
+ * model, including the built-in `llama-cpp/local` catalog entry. This is the gate that must run
+ * before ANY self-heal/serve action so pi never touches a server it doesn't own.
+ */
+export declare function isPiManagedPrismLlamaCppModel(model: {
+    provider: string;
+    id: string;
+}): boolean;
+/**
+ * Fixed local port for pi's own managed prism llama.cpp server. Deliberately NOT the generic
+ * built-in `llama-cpp/local` catalog model's conventional port 8080 (models.generated.ts) — that
+ * port is the convention for a user's OWN manually started llama-server pi merely points at; pi's
+ * managed instance must never collide with it.
+ */
+export declare const PRISM_LLAMACPP_SERVE_PORT = 8090;
+/**
+ * Conservative RAM-only context cap for the pi-managed prism llama.cpp server, used at FIRST
+ * install time only (`/models add`) — a later self-heal re-serve reuses the model's already
+ * registered `contextWindow` instead (see the readiness gate in local-runtime-controller.ts), never
+ * re-deriving from current RAM, so a served context size can't drift from what pi already told the
+ * rest of the session (compaction, etc.) to expect. PrismLlamaCppRuntime has no `/api/show`-
+ * equivalent GGUF metadata endpoint (unlike Ollama, which context-sizing.ts's
+ * deriveLocalContextSizing depends on), so this is a coarse rung table mirroring
+ * context-sizing.ts's CONTEXT_RUNGS, hard-capped at 32768 regardless of headroom: Bonsai-27B
+ * advertises a 262K-class context, but that is not a realistic KV budget for a CPU-served model on
+ * consumer hardware, and there is no larger validated rung to grow into yet.
+ */
+export declare function derivePrismLlamaCppNumCtx(totalMemBytes: number): number;
+export type EnsurePrismModelServedResult = {
+    ok: true;
+    baseUrl: string;
+} | {
+    ok: false;
+    stage: "model-download" | "mmproj-download" | "serve";
+    error: string;
+};
+/**
+ * The SOLE path allowed to call `runtime.serve()` for a prism llama.cpp model — no caller may spawn
+ * llama-server without first passing through here (both `addPrismLlamaCppModel`'s install pipeline
+ * and the readiness gate's self-heal path call this, never `runtime.serve()` directly).
+ * Unconditionally re-verifies BOTH GGUF files via `runtime.downloadModel()` immediately before every
+ * serve — that call is idempotent (skips a re-download when the local file already matches the
+ * remote size, so the happy path costs one stat) and self-heals a file that went missing from disk
+ * (deleted, a partial download from a prior crash, host cleanup, etc.) by re-fetching it instead of
+ * ever starting llama-server without it. The vision projector is mandatory whenever the descriptor
+ * declares one (Bonsai-27B always does — see BONSAI_27B.mmprojFile): a download failure on EITHER
+ * file means llama-server is never spawned. There is no text-only fallback — Bonsai-27B never
+ * silently degrades to a vision-less serve because the projector went missing.
+ */
+export declare function ensurePrismModelFilesThenServe(runtime: PrismLlamaCppRuntime, descriptor: PrismModelDescriptor, args: {
+    port: number;
+    numCtx: number;
+}, onProgress: (message: string) => void): Promise<EnsurePrismModelServedResult>;
+/**
+ * Direct HTTP reachability probe against a prism llama.cpp server root (NOT the `/v1` OpenAI-compat
+ * suffix models.json registers — same root/health split as llama-server's own health endpoint used
+ * internally by PrismLlamaCppRuntime#serve). PrismLlamaCppRuntime has no public method for this (its
+ * own equivalent, `_healthUp`, is private and scoped to a `serve()` call in progress), so the
+ * readiness gate needs its own — this is deliberately independent of any single runtime instance:
+ * it answers "is a server already alive at this URL", true even for a server this session never
+ * spawned (started earlier, or by a different process).
+ */
+export declare function isPrismLlamaCppServerHealthy(serverUrl: string, fetchFn?: typeof fetch, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=prism-llamacpp-lifecycle.d.ts.map

package/dist/core/models/prism-llamacpp-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prism-llamacpp-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/core/models/prism-llamacpp-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAc,KAAK,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGzG;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAE3E,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE9F;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED,MAAM,MAAM,4BAA4B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF;;;;;;;;;;;;GAYG;AACH,wBAAsB,8BAA8B,CACnD,OAAO,EAAE,oBAAoB,EAC7B,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACtC,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACnC,OAAO,CAAC,4BAA4B,CAAC,CA6BvC;AAID;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CACjD,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,OAAO,KAAa,EAC7B,SAAS,GAAE,MAAwC,GACjD,OAAO,CAAC,OAAO,CAAC,CAOlB","sourcesContent":["/**\n * Core lifecycle logic for pi-managed prism llama.cpp models (Bonsai-27B first), shared between the\n * `/models add` install pipeline (modes/interactive/local-model-commands.ts) and the router's\n * readiness gate (local-runtime-controller.ts). ONE place owns \"ensure both GGUF files exist, then\n * serve\" so a turn routed to a cold Bonsai-27B and a fresh `/models add` both go through the\n * identical self-healing path instead of two parallel, potentially-diverging implementations.\n *\n * Lives in core/models/ (not modes/) so the headless readiness gate — used by print/RPC/interactive\n * sessions and isolated/background lanes alike — never depends on the interactive-only UI layer;\n * mirrors the existing local-runtime.ts (mechanics) / local-runtime-controller.ts (gate) split.\n */\n\nimport { BONSAI_27B, type PrismLlamaCppRuntime, type PrismModelDescriptor } from \"./llamacpp-runtime.ts\";\nimport { PRISM_LLAMACPP_PROVIDER } from \"./local-registration.ts\";\n\n/**\n * Curated prism llama.cpp descriptors, keyed by repo id — matches the modelId model-ref.ts's\n * curated `PRISM_LLAMACPP_MODEL_IDS` route returns, and the id `registerPrismLlamaCppModel` writes\n * as the model's id in models.json. Add future curated prism-ml models to both places together.\n *\n * Also the pi-managed-vs-user-owned discriminator (see {@link isPiManagedPrismLlamaCppModel}): a\n * `llama-cpp` provider model is gated/self-healed by pi ONLY when its id is a key here — a user's\n * own hand-configured entry (e.g. the built-in `llama-cpp/local` catalog model on port 8080,\n * pointing at a server the user runs themselves) is never touched.\n */\nexport const PRISM_LLAMACPP_DESCRIPTORS: Record<string, PrismModelDescriptor> = {\n\t[BONSAI_27B.repo]: BONSAI_27B,\n};\n\n/**\n * True only for a `llama-cpp` provider model pi itself registered (id present in\n * {@link PRISM_LLAMACPP_DESCRIPTORS}) — never true for a user's own hand-configured llama-cpp\n * model, including the built-in `llama-cpp/local` catalog entry. This is the gate that must run\n * before ANY self-heal/serve action so pi never touches a server it doesn't own.\n */\nexport function isPiManagedPrismLlamaCppModel(model: { provider: string; id: string }): boolean {\n\treturn model.provider === PRISM_LLAMACPP_PROVIDER && Object.hasOwn(PRISM_LLAMACPP_DESCRIPTORS, model.id);\n}\n\n/**\n * Fixed local port for pi's own managed prism llama.cpp server. Deliberately NOT the generic\n * built-in `llama-cpp/local` catalog model's conventional port 8080 (models.generated.ts) — that\n * port is the convention for a user's OWN manually started llama-server pi merely points at; pi's\n * managed instance must never collide with it.\n */\nexport const PRISM_LLAMACPP_SERVE_PORT = 8090;\n\n/**\n * Conservative RAM-only context cap for the pi-managed prism llama.cpp server, used at FIRST\n * install time only (`/models add`) — a later self-heal re-serve reuses the model's already\n * registered `contextWindow` instead (see the readiness gate in local-runtime-controller.ts), never\n * re-deriving from current RAM, so a served context size can't drift from what pi already told the\n * rest of the session (compaction, etc.) to expect. PrismLlamaCppRuntime has no `/api/show`-\n * equivalent GGUF metadata endpoint (unlike Ollama, which context-sizing.ts's\n * deriveLocalContextSizing depends on), so this is a coarse rung table mirroring\n * context-sizing.ts's CONTEXT_RUNGS, hard-capped at 32768 regardless of headroom: Bonsai-27B\n * advertises a 262K-class context, but that is not a realistic KV budget for a CPU-served model on\n * consumer hardware, and there is no larger validated rung to grow into yet.\n */\nexport function derivePrismLlamaCppNumCtx(totalMemBytes: number): number {\n\tconst totalGb = totalMemBytes / 1e9;\n\tif (totalGb >= 64) return 32_768;\n\tif (totalGb >= 32) return 16_384;\n\tif (totalGb >= 16) return 8_192;\n\treturn 4_096;\n}\n\nexport type EnsurePrismModelServedResult =\n\t| { ok: true; baseUrl: string }\n\t| { ok: false; stage: \"model-download\" | \"mmproj-download\" | \"serve\"; error: string };\n\n/**\n * The SOLE path allowed to call `runtime.serve()` for a prism llama.cpp model — no caller may spawn\n * llama-server without first passing through here (both `addPrismLlamaCppModel`'s install pipeline\n * and the readiness gate's self-heal path call this, never `runtime.serve()` directly).\n * Unconditionally re-verifies BOTH GGUF files via `runtime.downloadModel()` immediately before every\n * serve — that call is idempotent (skips a re-download when the local file already matches the\n * remote size, so the happy path costs one stat) and self-heals a file that went missing from disk\n * (deleted, a partial download from a prior crash, host cleanup, etc.) by re-fetching it instead of\n * ever starting llama-server without it. The vision projector is mandatory whenever the descriptor\n * declares one (Bonsai-27B always does — see BONSAI_27B.mmprojFile): a download failure on EITHER\n * file means llama-server is never spawned. There is no text-only fallback — Bonsai-27B never\n * silently degrades to a vision-less serve because the projector went missing.\n */\nexport async function ensurePrismModelFilesThenServe(\n\truntime: PrismLlamaCppRuntime,\n\tdescriptor: PrismModelDescriptor,\n\targs: { port: number; numCtx: number },\n\tonProgress: (message: string) => void,\n): Promise<EnsurePrismModelServedResult> {\n\tconst downloadedModel = await runtime.downloadModel({ repo: descriptor.repo, file: descriptor.file }, (progress) =>\n\t\tonProgress(`  ${descriptor.file}: ${progress}`),\n\t);\n\tif (!downloadedModel.ok || !downloadedModel.path) {\n\t\treturn { ok: false, stage: \"model-download\", error: downloadedModel.error ?? \"unknown error\" };\n\t}\n\n\tlet mmprojPath: string | undefined;\n\tif (descriptor.mmprojFile) {\n\t\tconst downloadedMmproj = await runtime.downloadModel(\n\t\t\t{ repo: descriptor.repo, file: descriptor.mmprojFile },\n\t\t\t(progress) => onProgress(`  ${descriptor.mmprojFile}: ${progress}`),\n\t\t);\n\t\tif (!downloadedMmproj.ok || !downloadedMmproj.path) {\n\t\t\treturn { ok: false, stage: \"mmproj-download\", error: downloadedMmproj.error ?? \"unknown error\" };\n\t\t}\n\t\tmmprojPath = downloadedMmproj.path;\n\t}\n\n\tonProgress(`Starting ${descriptor.displayName} on 127.0.0.1:${args.port} (context ${args.numCtx})…`);\n\tconst served = await runtime.serve({\n\t\tmodelPath: downloadedModel.path,\n\t\tmmprojPath,\n\t\tport: args.port,\n\t\tnumCtx: args.numCtx,\n\t});\n\tif (!served.ok) return { ok: false, stage: \"serve\", error: served.error };\n\treturn { ok: true, baseUrl: served.baseUrl };\n}\n\nconst DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 2_000;\n\n/**\n * Direct HTTP reachability probe against a prism llama.cpp server root (NOT the `/v1` OpenAI-compat\n * suffix models.json registers — same root/health split as llama-server's own health endpoint used\n * internally by PrismLlamaCppRuntime#serve). PrismLlamaCppRuntime has no public method for this (its\n * own equivalent, `_healthUp`, is private and scoped to a `serve()` call in progress), so the\n * readiness gate needs its own — this is deliberately independent of any single runtime instance:\n * it answers \"is a server already alive at this URL\", true even for a server this session never\n * spawned (started earlier, or by a different process).\n */\nexport async function isPrismLlamaCppServerHealthy(\n\tserverUrl: string,\n\tfetchFn: typeof fetch = fetch,\n\ttimeoutMs: number = DEFAULT_HEALTH_CHECK_TIMEOUT_MS,\n): Promise<boolean> {\n\ttry {\n\t\tconst response = await fetchFn(`${serverUrl}/health`, { signal: AbortSignal.timeout(timeoutMs) });\n\t\treturn response.ok;\n\t} catch {\n\t\treturn false;\n\t}\n}\n"]}

package/dist/core/models/prism-llamacpp-lifecycle.js

@@ -0,0 +1,121 @@
+/**
+ * Core lifecycle logic for pi-managed prism llama.cpp models (Bonsai-27B first), shared between the
+ * `/models add` install pipeline (modes/interactive/local-model-commands.ts) and the router's
+ * readiness gate (local-runtime-controller.ts). ONE place owns "ensure both GGUF files exist, then
+ * serve" so a turn routed to a cold Bonsai-27B and a fresh `/models add` both go through the
+ * identical self-healing path instead of two parallel, potentially-diverging implementations.
+ *
+ * Lives in core/models/ (not modes/) so the headless readiness gate — used by print/RPC/interactive
+ * sessions and isolated/background lanes alike — never depends on the interactive-only UI layer;
+ * mirrors the existing local-runtime.ts (mechanics) / local-runtime-controller.ts (gate) split.
+ */
+import { BONSAI_27B } from "./llamacpp-runtime.js";
+import { PRISM_LLAMACPP_PROVIDER } from "./local-registration.js";
+/**
+ * Curated prism llama.cpp descriptors, keyed by repo id — matches the modelId model-ref.ts's
+ * curated `PRISM_LLAMACPP_MODEL_IDS` route returns, and the id `registerPrismLlamaCppModel` writes
+ * as the model's id in models.json. Add future curated prism-ml models to both places together.
+ *
+ * Also the pi-managed-vs-user-owned discriminator (see {@link isPiManagedPrismLlamaCppModel}): a
+ * `llama-cpp` provider model is gated/self-healed by pi ONLY when its id is a key here — a user's
+ * own hand-configured entry (e.g. the built-in `llama-cpp/local` catalog model on port 8080,
+ * pointing at a server the user runs themselves) is never touched.
+ */
+export const PRISM_LLAMACPP_DESCRIPTORS = {
+    [BONSAI_27B.repo]: BONSAI_27B,
+};
+/**
+ * True only for a `llama-cpp` provider model pi itself registered (id present in
+ * {@link PRISM_LLAMACPP_DESCRIPTORS}) — never true for a user's own hand-configured llama-cpp
+ * model, including the built-in `llama-cpp/local` catalog entry. This is the gate that must run
+ * before ANY self-heal/serve action so pi never touches a server it doesn't own.
+ */
+export function isPiManagedPrismLlamaCppModel(model) {
+    return model.provider === PRISM_LLAMACPP_PROVIDER && Object.hasOwn(PRISM_LLAMACPP_DESCRIPTORS, model.id);
+}
+/**
+ * Fixed local port for pi's own managed prism llama.cpp server. Deliberately NOT the generic
+ * built-in `llama-cpp/local` catalog model's conventional port 8080 (models.generated.ts) — that
+ * port is the convention for a user's OWN manually started llama-server pi merely points at; pi's
+ * managed instance must never collide with it.
+ */
+export const PRISM_LLAMACPP_SERVE_PORT = 8090;
+/**
+ * Conservative RAM-only context cap for the pi-managed prism llama.cpp server, used at FIRST
+ * install time only (`/models add`) — a later self-heal re-serve reuses the model's already
+ * registered `contextWindow` instead (see the readiness gate in local-runtime-controller.ts), never
+ * re-deriving from current RAM, so a served context size can't drift from what pi already told the
+ * rest of the session (compaction, etc.) to expect. PrismLlamaCppRuntime has no `/api/show`-
+ * equivalent GGUF metadata endpoint (unlike Ollama, which context-sizing.ts's
+ * deriveLocalContextSizing depends on), so this is a coarse rung table mirroring
+ * context-sizing.ts's CONTEXT_RUNGS, hard-capped at 32768 regardless of headroom: Bonsai-27B
+ * advertises a 262K-class context, but that is not a realistic KV budget for a CPU-served model on
+ * consumer hardware, and there is no larger validated rung to grow into yet.
+ */
+export function derivePrismLlamaCppNumCtx(totalMemBytes) {
+    const totalGb = totalMemBytes / 1e9;
+    if (totalGb >= 64)
+        return 32_768;
+    if (totalGb >= 32)
+        return 16_384;
+    if (totalGb >= 16)
+        return 8_192;
+    return 4_096;
+}
+/**
+ * The SOLE path allowed to call `runtime.serve()` for a prism llama.cpp model — no caller may spawn
+ * llama-server without first passing through here (both `addPrismLlamaCppModel`'s install pipeline
+ * and the readiness gate's self-heal path call this, never `runtime.serve()` directly).
+ * Unconditionally re-verifies BOTH GGUF files via `runtime.downloadModel()` immediately before every
+ * serve — that call is idempotent (skips a re-download when the local file already matches the
+ * remote size, so the happy path costs one stat) and self-heals a file that went missing from disk
+ * (deleted, a partial download from a prior crash, host cleanup, etc.) by re-fetching it instead of
+ * ever starting llama-server without it. The vision projector is mandatory whenever the descriptor
+ * declares one (Bonsai-27B always does — see BONSAI_27B.mmprojFile): a download failure on EITHER
+ * file means llama-server is never spawned. There is no text-only fallback — Bonsai-27B never
+ * silently degrades to a vision-less serve because the projector went missing.
+ */
+export async function ensurePrismModelFilesThenServe(runtime, descriptor, args, onProgress) {
+    const downloadedModel = await runtime.downloadModel({ repo: descriptor.repo, file: descriptor.file }, (progress) => onProgress(`  ${descriptor.file}: ${progress}`));
+    if (!downloadedModel.ok || !downloadedModel.path) {
+        return { ok: false, stage: "model-download", error: downloadedModel.error ?? "unknown error" };
+    }
+    let mmprojPath;
+    if (descriptor.mmprojFile) {
+        const downloadedMmproj = await runtime.downloadModel({ repo: descriptor.repo, file: descriptor.mmprojFile }, (progress) => onProgress(`  ${descriptor.mmprojFile}: ${progress}`));
+        if (!downloadedMmproj.ok || !downloadedMmproj.path) {
+            return { ok: false, stage: "mmproj-download", error: downloadedMmproj.error ?? "unknown error" };
+        }
+        mmprojPath = downloadedMmproj.path;
+    }
+    onProgress(`Starting ${descriptor.displayName} on 127.0.0.1:${args.port} (context ${args.numCtx})…`);
+    const served = await runtime.serve({
+        modelPath: downloadedModel.path,
+        mmprojPath,
+        port: args.port,
+        numCtx: args.numCtx,
+    });
+    if (!served.ok)
+        return { ok: false, stage: "serve", error: served.error };
+    return { ok: true, baseUrl: served.baseUrl };
+}
+const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 2_000;
+/**
+ * Direct HTTP reachability probe against a prism llama.cpp server root (NOT the `/v1` OpenAI-compat
+ * suffix models.json registers — same root/health split as llama-server's own health endpoint used
+ * internally by PrismLlamaCppRuntime#serve). PrismLlamaCppRuntime has no public method for this (its
+ * own equivalent, `_healthUp`, is private and scoped to a `serve()` call in progress), so the
+ * readiness gate needs its own — this is deliberately independent of any single runtime instance:
+ * it answers "is a server already alive at this URL", true even for a server this session never
+ * spawned (started earlier, or by a different process).
+ */
+export async function isPrismLlamaCppServerHealthy(serverUrl, fetchFn = fetch, timeoutMs = DEFAULT_HEALTH_CHECK_TIMEOUT_MS) {
+    try {
+        const response = await fetchFn(`${serverUrl}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=prism-llamacpp-lifecycle.js.map

package/dist/core/models/prism-llamacpp-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prism-llamacpp-lifecycle.js","sourceRoot":"","sources":["../../../src/core/models/prism-llamacpp-lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Core lifecycle logic for pi-managed prism llama.cpp models (Bonsai-27B first), shared between the\n * `/models add` install pipeline (modes/interactive/local-model-commands.ts) and the router's\n * readiness gate (local-runtime-controller.ts). ONE place owns \"ensure both GGUF files exist, then\n * serve\" so a turn routed to a cold Bonsai-27B and a fresh `/models add` both go through the\n * identical self-healing path instead of two parallel, potentially-diverging implementations.\n *\n * Lives in core/models/ (not modes/) so the headless readiness gate — used by print/RPC/interactive\n * sessions and isolated/background lanes alike — never depends on the interactive-only UI layer;\n * mirrors the existing local-runtime.ts (mechanics) / local-runtime-controller.ts (gate) split.\n */\n\nimport { BONSAI_27B, type PrismLlamaCppRuntime, type PrismModelDescriptor } from \"./llamacpp-runtime.ts\";\nimport { PRISM_LLAMACPP_PROVIDER } from \"./local-registration.ts\";\n\n/**\n * Curated prism llama.cpp descriptors, keyed by repo id — matches the modelId model-ref.ts's\n * curated `PRISM_LLAMACPP_MODEL_IDS` route returns, and the id `registerPrismLlamaCppModel` writes\n * as the model's id in models.json. Add future curated prism-ml models to both places together.\n *\n * Also the pi-managed-vs-user-owned discriminator (see {@link isPiManagedPrismLlamaCppModel}): a\n * `llama-cpp` provider model is gated/self-healed by pi ONLY when its id is a key here — a user's\n * own hand-configured entry (e.g. the built-in `llama-cpp/local` catalog model on port 8080,\n * pointing at a server the user runs themselves) is never touched.\n */\nexport const PRISM_LLAMACPP_DESCRIPTORS: Record<string, PrismModelDescriptor> = {\n\t[BONSAI_27B.repo]: BONSAI_27B,\n};\n\n/**\n * True only for a `llama-cpp` provider model pi itself registered (id present in\n * {@link PRISM_LLAMACPP_DESCRIPTORS}) — never true for a user's own hand-configured llama-cpp\n * model, including the built-in `llama-cpp/local` catalog entry. This is the gate that must run\n * before ANY self-heal/serve action so pi never touches a server it doesn't own.\n */\nexport function isPiManagedPrismLlamaCppModel(model: { provider: string; id: string }): boolean {\n\treturn model.provider === PRISM_LLAMACPP_PROVIDER && Object.hasOwn(PRISM_LLAMACPP_DESCRIPTORS, model.id);\n}\n\n/**\n * Fixed local port for pi's own managed prism llama.cpp server. Deliberately NOT the generic\n * built-in `llama-cpp/local` catalog model's conventional port 8080 (models.generated.ts) — that\n * port is the convention for a user's OWN manually started llama-server pi merely points at; pi's\n * managed instance must never collide with it.\n */\nexport const PRISM_LLAMACPP_SERVE_PORT = 8090;\n\n/**\n * Conservative RAM-only context cap for the pi-managed prism llama.cpp server, used at FIRST\n * install time only (`/models add`) — a later self-heal re-serve reuses the model's already\n * registered `contextWindow` instead (see the readiness gate in local-runtime-controller.ts), never\n * re-deriving from current RAM, so a served context size can't drift from what pi already told the\n * rest of the session (compaction, etc.) to expect. PrismLlamaCppRuntime has no `/api/show`-\n * equivalent GGUF metadata endpoint (unlike Ollama, which context-sizing.ts's\n * deriveLocalContextSizing depends on), so this is a coarse rung table mirroring\n * context-sizing.ts's CONTEXT_RUNGS, hard-capped at 32768 regardless of headroom: Bonsai-27B\n * advertises a 262K-class context, but that is not a realistic KV budget for a CPU-served model on\n * consumer hardware, and there is no larger validated rung to grow into yet.\n */\nexport function derivePrismLlamaCppNumCtx(totalMemBytes: number): number {\n\tconst totalGb = totalMemBytes / 1e9;\n\tif (totalGb >= 64) return 32_768;\n\tif (totalGb >= 32) return 16_384;\n\tif (totalGb >= 16) return 8_192;\n\treturn 4_096;\n}\n\nexport type EnsurePrismModelServedResult =\n\t| { ok: true; baseUrl: string }\n\t| { ok: false; stage: \"model-download\" | \"mmproj-download\" | \"serve\"; error: string };\n\n/**\n * The SOLE path allowed to call `runtime.serve()` for a prism llama.cpp model — no caller may spawn\n * llama-server without first passing through here (both `addPrismLlamaCppModel`'s install pipeline\n * and the readiness gate's self-heal path call this, never `runtime.serve()` directly).\n * Unconditionally re-verifies BOTH GGUF files via `runtime.downloadModel()` immediately before every\n * serve — that call is idempotent (skips a re-download when the local file already matches the\n * remote size, so the happy path costs one stat) and self-heals a file that went missing from disk\n * (deleted, a partial download from a prior crash, host cleanup, etc.) by re-fetching it instead of\n * ever starting llama-server without it. The vision projector is mandatory whenever the descriptor\n * declares one (Bonsai-27B always does — see BONSAI_27B.mmprojFile): a download failure on EITHER\n * file means llama-server is never spawned. There is no text-only fallback — Bonsai-27B never\n * silently degrades to a vision-less serve because the projector went missing.\n */\nexport async function ensurePrismModelFilesThenServe(\n\truntime: PrismLlamaCppRuntime,\n\tdescriptor: PrismModelDescriptor,\n\targs: { port: number; numCtx: number },\n\tonProgress: (message: string) => void,\n): Promise<EnsurePrismModelServedResult> {\n\tconst downloadedModel = await runtime.downloadModel({ repo: descriptor.repo, file: descriptor.file }, (progress) =>\n\t\tonProgress(`  ${descriptor.file}: ${progress}`),\n\t);\n\tif (!downloadedModel.ok || !downloadedModel.path) {\n\t\treturn { ok: false, stage: \"model-download\", error: downloadedModel.error ?? \"unknown error\" };\n\t}\n\n\tlet mmprojPath: string | undefined;\n\tif (descriptor.mmprojFile) {\n\t\tconst downloadedMmproj = await runtime.downloadModel(\n\t\t\t{ repo: descriptor.repo, file: descriptor.mmprojFile },\n\t\t\t(progress) => onProgress(`  ${descriptor.mmprojFile}: ${progress}`),\n\t\t);\n\t\tif (!downloadedMmproj.ok || !downloadedMmproj.path) {\n\t\t\treturn { ok: false, stage: \"mmproj-download\", error: downloadedMmproj.error ?? \"unknown error\" };\n\t\t}\n\t\tmmprojPath = downloadedMmproj.path;\n\t}\n\n\tonProgress(`Starting ${descriptor.displayName} on 127.0.0.1:${args.port} (context ${args.numCtx})…`);\n\tconst served = await runtime.serve({\n\t\tmodelPath: downloadedModel.path,\n\t\tmmprojPath,\n\t\tport: args.port,\n\t\tnumCtx: args.numCtx,\n\t});\n\tif (!served.ok) return { ok: false, stage: \"serve\", error: served.error };\n\treturn { ok: true, baseUrl: served.baseUrl };\n}\n\nconst DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 2_000;\n\n/**\n * Direct HTTP reachability probe against a prism llama.cpp server root (NOT the `/v1` OpenAI-compat\n * suffix models.json registers — same root/health split as llama-server's own health endpoint used\n * internally by PrismLlamaCppRuntime#serve). PrismLlamaCppRuntime has no public method for this (its\n * own equivalent, `_healthUp`, is private and scoped to a `serve()` call in progress), so the\n * readiness gate needs its own — this is deliberately independent of any single runtime instance:\n * it answers \"is a server already alive at this URL\", true even for a server this session never\n * spawned (started earlier, or by a different process).\n */\nexport async function isPrismLlamaCppServerHealthy(\n\tserverUrl: string,\n\tfetchFn: typeof fetch = fetch,\n\ttimeoutMs: number = DEFAULT_HEALTH_CHECK_TIMEOUT_MS,\n): Promise<boolean> {\n\ttry {\n\t\tconst response = await fetchFn(`${serverUrl}/health`, { signal: AbortSignal.timeout(timeoutMs) });\n\t\treturn response.ok;\n\t} catch {\n\t\treturn false;\n\t}\n}\n"]}

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

@@ -0,0 +1,24 @@
+import { type AgentIdentityContract, type AgentResumeContext } from "./contracts.ts";
+export interface PiResumeLaunchSpec {
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+}
+export interface BuildPiResumeLaunchSpecOptions {
+    executable?: string;
+    argsPrefix?: readonly string[];
+    parentPid: number;
+    parentSessionId: string;
+    taskRef?: string;
+    wakePrompt?: string;
+}
+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;
+/**
+ * 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.
+ */
+export declare function buildPiResumeLaunchSpec(agent: AgentIdentityContract, options: BuildPiResumeLaunchSpecOptions): PiResumeLaunchSpec;
+//# sourceMappingURL=agent-resume.d.ts.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,90 @@
+import { PI_ORCHESTRATION_AGENT_ID_ENV } from "../process-identity.js";
+import { isPlainRecord } from "../util/value-guards.js";
+import { isResourcePointerKind } from "./contracts.js";
+function isOptionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+export function isAgentIdentity(value) {
+    if (!isPlainRecord(value) || !isPlainRecord(value.resumeContext))
+        return false;
+    const context = value.resumeContext;
+    return (typeof value.agentId === "string" &&
+        value.agentId.trim().length > 0 &&
+        (context.provider === "pi" || context.provider === "external") &&
+        typeof context.sessionId === "string" &&
+        context.sessionId.trim().length > 0 &&
+        typeof context.cwd === "string" &&
+        context.cwd.trim().length > 0 &&
+        isOptionalString(context.sessionDir) &&
+        isOptionalString(context.sessionFile) &&
+        isOptionalString(context.worktreeLaneKey) &&
+        isOptionalString(context.orchestrationProfileId) &&
+        isOptionalString(context.modelRef) &&
+        isOptionalString(context.latestCheckpointId) &&
+        Array.isArray(context.resourceProfileNames) &&
+        context.resourceProfileNames.every((name) => typeof name === "string" && name.trim().length > 0) &&
+        Array.isArray(context.contextPointers) &&
+        context.contextPointers.every((pointer) => isPlainRecord(pointer) &&
+            typeof pointer.id === "string" &&
+            pointer.id.trim().length > 0 &&
+            isResourcePointerKind(pointer.kind) &&
+            typeof pointer.uri === "string" &&
+            pointer.uri.trim().length > 0 &&
+            typeof pointer.readOnly === "boolean" &&
+            isOptionalString(pointer.digest) &&
+            (pointer.metadata === undefined || isPlainRecord(pointer.metadata))));
+}
+/** Build and validate the one logical identity shared by orchestration and process supervision. */
+export function createAgentIdentity(agentId, resumeContext) {
+    const normalizedAgentId = agentId.trim();
+    if (!normalizedAgentId)
+        throw new TypeError("A logical agent id is required.");
+    if (!resumeContext.sessionId.trim())
+        throw new TypeError("An agent session id is required.");
+    if (!resumeContext.cwd.trim())
+        throw new TypeError("An agent working directory is required.");
+    const identity = { agentId: normalizedAgentId, resumeContext: structuredClone(resumeContext) };
+    if (!isAgentIdentity(identity))
+        throw new TypeError("Agent resume context is invalid.");
+    return identity;
+}
+/**
+ * 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.
+ */
+export function buildPiResumeLaunchSpec(agent, options) {
+    const identity = createAgentIdentity(agent.agentId, agent.resumeContext);
+    const context = identity.resumeContext;
+    if (context.provider !== "pi")
+        throw new TypeError(`Agent '${identity.agentId}' is not backed by a Pi session.`);
+    if (!Number.isSafeInteger(options.parentPid) || options.parentPid <= 0) {
+        throw new TypeError("A positive parent pid is required to resume a Pi agent.");
+    }
+    if (!options.parentSessionId.trim())
+        throw new TypeError("A parent session id is required to resume a Pi agent.");
+    const args = [...(options.argsPrefix ?? [])];
+    if (context.sessionDir)
+        args.push("--session-dir", context.sessionDir);
+    args.push("--session", context.sessionFile ?? context.sessionId);
+    args.push("--parent-pid", String(options.parentPid));
+    args.push("--parent-session", options.parentSessionId);
+    if (options.taskRef?.trim())
+        args.push("--task-ref", options.taskRef.trim());
+    if (context.worktreeLaneKey)
+        args.push("--worktree-lane", context.worktreeLaneKey);
+    if (context.orchestrationProfileId) {
+        args.push("--orchestration-profile", context.orchestrationProfileId);
+    }
+    else if (context.resourceProfileNames.length > 0) {
+        args.push("--resource-profile", context.resourceProfileNames.join(","));
+    }
+    if (options.wakePrompt?.trim())
+        args.push("--print", options.wakePrompt.trim());
+    return {
+        executable: options.executable ?? "pi",
+        args,
+        cwd: context.cwd,
+        env: { PI_SESSION_ROLE: "worker", [PI_ORCHESTRATION_AGENT_ID_ENV]: identity.agentId },
+    };
+}
+//# sourceMappingURL=agent-resume.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,61 @@
+import type { 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;
+    attemptId: string;
+    toolName: string;
+    outcome: "allow" | "deny";
+    reasonCode: GatewayDecisionCode;
+    at: string;
+}
+export interface CapabilityGatewayOptions {
+    grant: ExecutionGrant;
+    cwd: string;
+    now?: () => number;
+    onAudit?: (record: GatewayAuditRecord) => void;
+}
+export interface GatewayUsageDelta {
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+}
+export interface GatewayUsageSnapshot {
+    toolCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    wallClockMs: number;
+}
+export declare class CapabilityGatewayDeniedError extends Error {
+    readonly reasonCode: GatewayDecisionCode;
+    constructor(reasonCode: GatewayDecisionCode, message: string);
+}
+/**
+ * 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
+ * immediately before execution.
+ */
+export declare class CapabilityGateway {
+    private readonly grant;
+    private readonly cwd;
+    private readonly now;
+    private readonly onAudit?;
+    private readonly startedAt;
+    private toolCalls;
+    private inputTokens;
+    private outputTokens;
+    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;
+    getUsage(): GatewayUsageSnapshot;
+    private authorize;
+    private enforceBudget;
+    private pathAllowed;
+    private deny;
+    private audit;
+}
+//# sourceMappingURL=capability-gateway.d.ts.map

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

@@ -0,0 +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"]}