@caupulican/pi-adaptative 0.81.39 → 0.81.41

package/dist/core/agent-paths.js

@@ -9,11 +9,14 @@
  * ```
  * <agentDir>/
  *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)
+ *   okf-memory/                                                                            authored memory (root, kept)
  *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)
+ *     profiles/directories/<workspace-hash>/settings.json                                 directory overlays
  *   state/     durable machine state (model adaptation/fitness, tool performance,
- *              learning observations, trust decisions, …)                                 -- stateDir/stateFile
+ *              learning observations, trust decisions, config backups, …)                 -- stateDir/stateFile
  *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile
- *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease)        -- re-exported below
+ *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease),
+ *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below
  *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir
  *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir
  *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir
@@ -32,12 +35,50 @@
  * and would blur the "pure function" contract readers rely on.
  */
 import { join } from "node:path";
-import { acquireWorkRun, createWorkRunId, getProcessWorkRun, getWorkRoot, getWorkRunDir, getWorkTenantDir, pruneWorkTenant, } from "../utils/work-directory.js";
+import { acquireWorkRun, assertPortablePathSegment, boundedWorkRetention, createWorkRunId, getProcessWorkRun, getWorkRoot, getWorkRunDir, getWorkTenantDir, hasActiveWorkRunLease, pruneWorkTenant, } from "../utils/work-directory.js";
 import { getReloadCoordinationDir } from "./reload-blockers.js";
+/** Root entries reserved for user-authored configuration and memory. */
+export const AGENT_ROOT_FILE_NAMES = [
+    "auth.json",
+    "settings.json",
+    "models.json",
+    "keybindings.json",
+    "MEMORY.md",
+    "USER.md",
+    "SYSTEM.md",
+    "APPEND_SYSTEM.md",
+];
+/** Root entries reserved for user resources and machine-managed storage classes. */
+export const AGENT_ROOT_DIRECTORY_NAMES = [
+    "okf-memory",
+    "skills",
+    "extensions",
+    "prompts",
+    "themes",
+    "profiles",
+    "state",
+    "cache",
+    "bin",
+    "work",
+    "runtimes",
+    "models",
+    "sessions",
+    "npm",
+    "git",
+    "worktrees",
+];
+const AGENT_ROOT_ENTRY_NAMES = new Set([...AGENT_ROOT_FILE_NAMES, ...AGENT_ROOT_DIRECTORY_NAMES]);
+export function isCanonicalAgentRootEntry(name) {
+    return AGENT_ROOT_ENTRY_NAMES.has(name);
+}
 /** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */
 export function configFile(agentDir, name) {
     return join(agentDir, name);
 }
+/** `<agentDir>/okf-memory` -- user-authored durable OKF memory documents. */
+export function okfMemoryDir(agentDir) {
+    return join(agentDir, "okf-memory");
+}
 /** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */
 export function stateDir(agentDir) {
     return join(agentDir, "state");
@@ -46,6 +87,31 @@ export function stateDir(agentDir) {
 export function stateFile(agentDir, ...segments) {
     return join(stateDir(agentDir), ...segments);
 }
+/** `<agentDir>/state/attachments` -- bounded, session-keyed clipboard image attachments. */
+export function attachmentsDir(agentDir) {
+    return stateFile(agentDir, "attachments");
+}
+/** `<agentDir>/state/secrets` -- encrypted credential vault and owner-approved materializations. */
+export function secretsDir(agentDir) {
+    return stateFile(agentDir, "secrets");
+}
+/** `<agentDir>/state/secrets/vault.json` -- encrypted, versioned generic credential vault. */
+export function secretVaultFile(agentDir) {
+    return join(secretsDir(agentDir), "vault.json");
+}
+/** `<agentDir>/state/secrets/materialized` -- private generated dotenv files, grouped by profile. */
+export function managedSecretEnvDir(agentDir) {
+    return join(secretsDir(agentDir), "materialized");
+}
+/** `<agentDir>/state/extensions/<namespace>` -- durable state owned by one extension. */
+export function extensionStateDir(agentDir, namespace) {
+    assertPortablePathSegment("Extension namespace", namespace);
+    return stateFile(agentDir, "extensions", namespace);
+}
+/** `<agentDir>/state/backups/config` -- explicit user-requested configuration snapshots. */
+export function configBackupsDir(agentDir) {
+    return stateFile(agentDir, "backups", "config");
+}
 /** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */
 export function cacheDir(agentDir) {
     return join(agentDir, "cache");
@@ -54,6 +120,11 @@ export function cacheDir(agentDir) {
 export function cacheFile(agentDir, ...segments) {
     return join(cacheDir(agentDir), ...segments);
 }
+/** `<agentDir>/cache/extensions/<namespace>` -- rebuildable cache owned by one extension. */
+export function extensionCacheDir(agentDir, namespace) {
+    assertPortablePathSegment("Extension namespace", namespace);
+    return cacheFile(agentDir, "extensions", namespace);
+}
 /** `<agentDir>/bin` -- managed executable helpers (fd, rg). */
 export function binDir(agentDir) {
     return join(agentDir, "bin");
@@ -91,13 +162,17 @@ export function gitDir(agentDir) {
 export function resourceDir(kind, agentDir) {
     return join(agentDir, kind);
 }
+/** `<agentDir>/profiles/directories` -- durable per-directory resource-profile overlays. */
+export function directoryProfilesDir(agentDir) {
+    return join(resourceDir("profiles", agentDir), "directories");
+}
 /**
  * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery
  * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these
  * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one
  * module without duplicating `work-directory.ts`'s logic.
  */
-export { getWorkRoot, getWorkTenantDir, getWorkRunDir, getProcessWorkRun, acquireWorkRun, createWorkRunId, pruneWorkTenant, };
+export { getWorkRoot, assertPortablePathSegment, boundedWorkRetention, getWorkTenantDir, getWorkRunDir, getProcessWorkRun, hasActiveWorkRunLease, acquireWorkRun, createWorkRunId, pruneWorkTenant, };
 /**
  * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly
  * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate

package/dist/core/agent-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-paths.js","sourceRoot":"","sources":["../../src/core/agent-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACN,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,eAAe,GACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,8GAA4G;AAC5G,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,IAAY,EAAU;IAClE,OAAO,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAAA,CAC5B;AAED,2GAA2G;AAC3G,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAU;IAClD,OAAO,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAAA,CAC/B;AAED,uCAAqC;AACrC,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,GAAG,QAAkB,EAAU;IAC1E,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;AAAA,CAC7C;AAED,kGAAkG;AAClG,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAU;IAClD,OAAO,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAAA,CAC/B;AAED,uCAAqC;AACrC,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,GAAG,QAAkB,EAAU;IAC1E,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;AAAA,CAC7C;AAED,+DAA+D;AAC/D,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAU;IAChD,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAAA,CAC7B;AAED,+GAA6G;AAC7G,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,QAAgB,EAAU;IACnE,OAAO,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AAAA,CACxC;AAED,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,QAAgB,EAAU;IACjE,OAAO,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAAA,CACtC;AAED,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAU;IACrD,OAAO,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAAA,CAClC;AAED,wDAAwD;AACxD,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAU;IAChD,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAAA,CAC7B;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAU;IACtD,OAAO,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAAA,CACnC;AAED,gEAAgE;AAChE,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAU;IAChD,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAAA,CAC7B;AAID,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,IAAuB,EAAE,QAAgB,EAAU;IAC9E,OAAO,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAAA,CAC5B;AAED;;;;;GAKG;AACH,OAAO,EACN,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,eAAe,GACf,CAAC;AAGF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC","sourcesContent":["/**\n * Typed path SSOT for everything machine-managed under `<agentDir>` (`~/.pi/agent/` by default,\n * `getAgentDir()` in `../config.ts`). Every writer that persists machine data (stores, caches, managed\n * runtimes/models, cross-process coordination) MUST resolve its path through one of the accessors\n * below instead of hand-rolling `join(agentDir, …)` — that ad-hoc pattern is exactly how root-level\n * stragglers like `trust.json` accumulated, and nothing stopped the next writer from doing it again.\n *\n * Canonical layout:\n * ```\n * <agentDir>/\n *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)\n *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)\n *   state/     durable machine state (model adaptation/fitness, tool performance,\n *              learning observations, trust decisions, …)                                 -- stateDir/stateFile\n *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile\n *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease)        -- re-exported below\n *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir\n *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir\n *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir\n * ```\n *\n * Every accessor takes `agentDir` as an explicit, required first argument -- deliberately mirroring\n * `work-directory.ts`'s existing `getWorkRoot(agentDir)` convention rather than defaulting to\n * `getAgentDir()` internally. Several real callers (stores' `forAgentDir`, test harnesses with a temp\n * agentDir) build paths for a NON-default agentDir; a hidden default would silently resolve the wrong\n * root for those callers instead of failing loudly. Callers operating on the process-wide default pass\n * `getAgentDir()` explicitly at the call site.\n *\n * These accessors are pure path builders -- no directory creation, no I/O. Every existing writer\n * already creates its parent directory at write time (see `util/atomic-file.ts`'s\n * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant\n * and would blur the \"pure function\" contract readers rely on.\n */\nimport { join } from \"node:path\";\nimport {\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tgetProcessWorkRun,\n\tgetWorkRoot,\n\tgetWorkRunDir,\n\tgetWorkTenantDir,\n\tpruneWorkTenant,\n} from \"../utils/work-directory.ts\";\nimport { getReloadCoordinationDir } from \"./reload-blockers.ts\";\n\n/** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */\nexport function configFile(agentDir: string, name: string): string {\n\treturn join(agentDir, name);\n}\n\n/** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */\nexport function stateDir(agentDir: string): string {\n\treturn join(agentDir, \"state\");\n}\n\n/** `<agentDir>/state/<segments…>` */\nexport function stateFile(agentDir: string, ...segments: string[]): string {\n\treturn join(stateDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */\nexport function cacheDir(agentDir: string): string {\n\treturn join(agentDir, \"cache\");\n}\n\n/** `<agentDir>/cache/<segments…>` */\nexport function cacheFile(agentDir: string, ...segments: string[]): string {\n\treturn join(cacheDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/bin` -- managed executable helpers (fd, rg). */\nexport function binDir(agentDir: string): string {\n\treturn join(agentDir, \"bin\");\n}\n\n/** `<agentDir>/runtimes/<kind>` -- a managed runtime install (ollama, python, prism-llamacpp, needle, …). */\nexport function runtimesDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"runtimes\", kind);\n}\n\n/** `<agentDir>/models/<kind>` -- downloaded model weights, grouped by provider/runtime. */\nexport function modelsDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"models\", kind);\n}\n\n/** `<agentDir>/sessions` -- session transcript storage (large, established; not a \"loose file\"). */\nexport function sessionsDir(agentDir: string): string {\n\treturn join(agentDir, \"sessions\");\n}\n\n/** `<agentDir>/npm` -- managed npm package installs. */\nexport function npmDir(agentDir: string): string {\n\treturn join(agentDir, \"npm\");\n}\n\n/**\n * `<agentDir>/worktrees` -- lane worktree checkouts for the worktree-sync subsystem\n * (`core/worktree-sync/`), grouped as `worktrees/<repo-slug>/<laneKey>`. These hold REAL\n * uncommitted agent work, so they are durable like `state/` -- never under transient `work/`,\n * whose retention would silently eat in-progress code.\n */\nexport function worktreesDir(agentDir: string): string {\n\treturn join(agentDir, \"worktrees\");\n}\n\n/** `<agentDir>/git` -- managed git-sourced package installs. */\nexport function gitDir(agentDir: string): string {\n\treturn join(agentDir, \"git\");\n}\n\nexport type AgentResourceKind = \"skills\" | \"prompts\" | \"themes\" | \"extensions\" | \"profiles\";\n\n/** `<agentDir>/<kind>` -- a user-managed resource directory. Root, kept: moving it breaks users. */\nexport function resourceDir(kind: AgentResourceKind, agentDir: string): string {\n\treturn join(agentDir, kind);\n}\n\n/**\n * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery\n * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these\n * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one\n * module without duplicating `work-directory.ts`'s logic.\n */\nexport {\n\tgetWorkRoot,\n\tgetWorkTenantDir,\n\tgetWorkRunDir,\n\tgetProcessWorkRun,\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tpruneWorkTenant,\n};\nexport type { AcquireWorkRunOptions, WorkRetentionOptions, WorkRunLease } from \"../utils/work-directory.ts\";\n\n/**\n * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly\n * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate\n * logic there); re-exported here under the taxonomy's canonical name for SSOT discoverability.\n */\nexport const reloadCoordinationDir = getReloadCoordinationDir;\n"]}
+{"version":3,"file":"agent-paths.js","sourceRoot":"","sources":["../../src/core/agent-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed path SSOT for everything machine-managed under `<agentDir>` (`~/.pi/agent/` by default,\n * `getAgentDir()` in `../config.ts`). Every writer that persists machine data (stores, caches, managed\n * runtimes/models, cross-process coordination) MUST resolve its path through one of the accessors\n * below instead of hand-rolling `join(agentDir, …)` — that ad-hoc pattern is exactly how root-level\n * stragglers like `trust.json` accumulated, and nothing stopped the next writer from doing it again.\n *\n * Canonical layout:\n * ```\n * <agentDir>/\n *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)\n *   okf-memory/                                                                            authored memory (root, kept)\n *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)\n *     profiles/directories/<workspace-hash>/settings.json                                 directory overlays\n *   state/     durable machine state (model adaptation/fitness, tool performance,\n *              learning observations, trust decisions, config backups, …)                 -- stateDir/stateFile\n *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile\n *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease),\n *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below\n *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir\n *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir\n *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir\n * ```\n *\n * Every accessor takes `agentDir` as an explicit, required first argument -- deliberately mirroring\n * `work-directory.ts`'s existing `getWorkRoot(agentDir)` convention rather than defaulting to\n * `getAgentDir()` internally. Several real callers (stores' `forAgentDir`, test harnesses with a temp\n * agentDir) build paths for a NON-default agentDir; a hidden default would silently resolve the wrong\n * root for those callers instead of failing loudly. Callers operating on the process-wide default pass\n * `getAgentDir()` explicitly at the call site.\n *\n * These accessors are pure path builders -- no directory creation, no I/O. Every existing writer\n * already creates its parent directory at write time (see `util/atomic-file.ts`'s\n * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant\n * and would blur the \"pure function\" contract readers rely on.\n */\nimport { join } from \"node:path\";\nimport {\n\tacquireWorkRun,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tcreateWorkRunId,\n\tgetProcessWorkRun,\n\tgetWorkRoot,\n\tgetWorkRunDir,\n\tgetWorkTenantDir,\n\thasActiveWorkRunLease,\n\tpruneWorkTenant,\n} from \"../utils/work-directory.ts\";\nimport { getReloadCoordinationDir } from \"./reload-blockers.ts\";\n\n/** Root entries reserved for user-authored configuration and memory. */\nexport const AGENT_ROOT_FILE_NAMES = [\n\t\"auth.json\",\n\t\"settings.json\",\n\t\"models.json\",\n\t\"keybindings.json\",\n\t\"MEMORY.md\",\n\t\"USER.md\",\n\t\"SYSTEM.md\",\n\t\"APPEND_SYSTEM.md\",\n] as const;\n\n/** Root entries reserved for user resources and machine-managed storage classes. */\nexport const AGENT_ROOT_DIRECTORY_NAMES = [\n\t\"okf-memory\",\n\t\"skills\",\n\t\"extensions\",\n\t\"prompts\",\n\t\"themes\",\n\t\"profiles\",\n\t\"state\",\n\t\"cache\",\n\t\"bin\",\n\t\"work\",\n\t\"runtimes\",\n\t\"models\",\n\t\"sessions\",\n\t\"npm\",\n\t\"git\",\n\t\"worktrees\",\n] as const;\n\nconst AGENT_ROOT_ENTRY_NAMES = new Set<string>([...AGENT_ROOT_FILE_NAMES, ...AGENT_ROOT_DIRECTORY_NAMES]);\n\nexport function isCanonicalAgentRootEntry(name: string): boolean {\n\treturn AGENT_ROOT_ENTRY_NAMES.has(name);\n}\n\n/** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */\nexport function configFile(agentDir: string, name: string): string {\n\treturn join(agentDir, name);\n}\n\n/** `<agentDir>/okf-memory` -- user-authored durable OKF memory documents. */\nexport function okfMemoryDir(agentDir: string): string {\n\treturn join(agentDir, \"okf-memory\");\n}\n\n/** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */\nexport function stateDir(agentDir: string): string {\n\treturn join(agentDir, \"state\");\n}\n\n/** `<agentDir>/state/<segments…>` */\nexport function stateFile(agentDir: string, ...segments: string[]): string {\n\treturn join(stateDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/state/attachments` -- bounded, session-keyed clipboard image attachments. */\nexport function attachmentsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"attachments\");\n}\n\n/** `<agentDir>/state/secrets` -- encrypted credential vault and owner-approved materializations. */\nexport function secretsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"secrets\");\n}\n\n/** `<agentDir>/state/secrets/vault.json` -- encrypted, versioned generic credential vault. */\nexport function secretVaultFile(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"vault.json\");\n}\n\n/** `<agentDir>/state/secrets/materialized` -- private generated dotenv files, grouped by profile. */\nexport function managedSecretEnvDir(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"materialized\");\n}\n\n/** `<agentDir>/state/extensions/<namespace>` -- durable state owned by one extension. */\nexport function extensionStateDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn stateFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/state/backups/config` -- explicit user-requested configuration snapshots. */\nexport function configBackupsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"backups\", \"config\");\n}\n\n/** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */\nexport function cacheDir(agentDir: string): string {\n\treturn join(agentDir, \"cache\");\n}\n\n/** `<agentDir>/cache/<segments…>` */\nexport function cacheFile(agentDir: string, ...segments: string[]): string {\n\treturn join(cacheDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/cache/extensions/<namespace>` -- rebuildable cache owned by one extension. */\nexport function extensionCacheDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn cacheFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/bin` -- managed executable helpers (fd, rg). */\nexport function binDir(agentDir: string): string {\n\treturn join(agentDir, \"bin\");\n}\n\n/** `<agentDir>/runtimes/<kind>` -- a managed runtime install (ollama, python, prism-llamacpp, needle, …). */\nexport function runtimesDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"runtimes\", kind);\n}\n\n/** `<agentDir>/models/<kind>` -- downloaded model weights, grouped by provider/runtime. */\nexport function modelsDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"models\", kind);\n}\n\n/** `<agentDir>/sessions` -- session transcript storage (large, established; not a \"loose file\"). */\nexport function sessionsDir(agentDir: string): string {\n\treturn join(agentDir, \"sessions\");\n}\n\n/** `<agentDir>/npm` -- managed npm package installs. */\nexport function npmDir(agentDir: string): string {\n\treturn join(agentDir, \"npm\");\n}\n\n/**\n * `<agentDir>/worktrees` -- lane worktree checkouts for the worktree-sync subsystem\n * (`core/worktree-sync/`), grouped as `worktrees/<repo-slug>/<laneKey>`. These hold REAL\n * uncommitted agent work, so they are durable like `state/` -- never under transient `work/`,\n * whose retention would silently eat in-progress code.\n */\nexport function worktreesDir(agentDir: string): string {\n\treturn join(agentDir, \"worktrees\");\n}\n\n/** `<agentDir>/git` -- managed git-sourced package installs. */\nexport function gitDir(agentDir: string): string {\n\treturn join(agentDir, \"git\");\n}\n\nexport type AgentResourceKind = \"skills\" | \"prompts\" | \"themes\" | \"extensions\" | \"profiles\";\n\n/** `<agentDir>/<kind>` -- a user-managed resource directory. Root, kept: moving it breaks users. */\nexport function resourceDir(kind: AgentResourceKind, agentDir: string): string {\n\treturn join(agentDir, kind);\n}\n\n/** `<agentDir>/profiles/directories` -- durable per-directory resource-profile overlays. */\nexport function directoryProfilesDir(agentDir: string): string {\n\treturn join(resourceDir(\"profiles\", agentDir), \"directories\");\n}\n\n/**\n * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery\n * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these\n * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one\n * module without duplicating `work-directory.ts`'s logic.\n */\nexport {\n\tgetWorkRoot,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tgetWorkTenantDir,\n\tgetWorkRunDir,\n\tgetProcessWorkRun,\n\thasActiveWorkRunLease,\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tpruneWorkTenant,\n};\nexport type { AcquireWorkRunOptions, WorkRetentionOptions, WorkRunLease } from \"../utils/work-directory.ts\";\n\n/**\n * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly\n * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate\n * logic there); re-exported here under the taxonomy's canonical name for SSOT discoverability.\n */\nexport const reloadCoordinationDir = getReloadCoordinationDir;\n"]}

package/dist/core/agent-session-contracts.d.ts

@@ -0,0 +1,293 @@
+import type { Agent, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, StreamIdleOptions, ThinkingLevel } from "@caupulican/pi-agent-core";
+import type { CompactionResult, SessionManager } from "@caupulican/pi-agent-core/node";
+import type { Api, CacheRetention, ImageContent, Message, Model, StopReason, Usage } from "@caupulican/pi-ai";
+import type { LaneRecord, LaneTerminalStatus } from "./autonomy/lane-tracker.ts";
+import type { WorkerRunOutcome } from "./delegation/worker-runner.ts";
+import type { ContextUsage, ExtensionCommandContextActions, ExtensionContext, ExtensionErrorListener, ExtensionRunner, ExtensionUIContext, InputSource, SessionStartEvent, ShutdownHandler, ToolDefinition } from "./extensions/index.ts";
+import type { GoalContinuationPrompt } from "./goals/goal-continuation-prompt.ts";
+import type { GoalRuntimeSnapshot } from "./goals/goal-runtime-snapshot.ts";
+import type { ModelRegistry } from "./model-registry.ts";
+import type { LocalRuntimeDeps } from "./models/local-runtime.ts";
+import type { OrchestrationProfile } from "./orchestration/contracts.ts";
+import type { ResearchRunResult } from "./research/research-runner.ts";
+import type { collectWorkspaceSources } from "./research/workspace-collector.ts";
+import type { ResourceLoader } from "./resource-loader.ts";
+import type { ResourceProfileFilterSettings, SettingsManager } from "./settings-manager.ts";
+import type { ToolArgumentValidationStats } from "./tool-recovery-stats.ts";
+/** Parsed skill block from a user message. */
+export interface ParsedSkillBlock {
+    name: string;
+    location: string;
+    content: string;
+    userMessage: string | undefined;
+}
+/** Parse a skill block from message text, or return null when none is present. */
+export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
+/** Session-specific events that extend the core AgentEvent. */
+export type AgentSessionEvent = Exclude<AgentEvent, {
+    type: "agent_end";
+}> | {
+    type: "agent_end";
+    messages: AgentMessage[];
+    willRetry: boolean;
+} | {
+    type: "queue_update";
+    steering: readonly string[];
+    followUp: readonly string[];
+    commands: readonly string[];
+} | {
+    type: "compaction_start";
+    reason: "manual" | "threshold" | "overflow";
+} | {
+    type: "session_info_changed";
+    name: string | undefined;
+} | {
+    type: "thinking_level_changed";
+    level: ThinkingLevel;
+} | {
+    type: "warning";
+    message: string;
+} | {
+    type: "compaction_end";
+    reason: "manual" | "threshold" | "overflow";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+    /** Benign no-op explanation when compaction did not produce a result. */
+    skipReason?: string;
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+}
+/** UI-only bracket around foreground routing/preparation. Always paired with `routing_end`. */
+ | {
+    type: "routing_start";
+} | {
+    type: "routing_end";
+} | {
+    type: "delegate_workers";
+    active: number;
+    queued: number;
+    running: number;
+    completedSinceFlush: number;
+    failedSinceFlush: number;
+    terminalSinceFlush: Array<{
+        laneId: string;
+        status: LaneTerminalStatus;
+        reasonCode?: string;
+    }>;
+};
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+export interface AgentSessionConfig {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settingsManager: SettingsManager;
+    cwd: string;
+    /** User-level agent state directory for generated runtime artifacts. */
+    agentDir?: string;
+    /** Models available to the interactive model-cycle action. */
+    scopedModels?: Array<{
+        model: Model<Api>;
+        thinkingLevel?: ThinkingLevel;
+    }>;
+    resourceLoader: ResourceLoader;
+    /** SDK tools registered outside extensions. */
+    customTools?: ToolDefinition[];
+    modelRegistry: ModelRegistry;
+    /** Initial active tool names before profile and UAC filtering. */
+    initialActiveToolNames?: string[];
+    /** Optional tool allowlist. */
+    allowedToolNames?: string[];
+    /** Optional tool denylist. */
+    excludedToolNames?: string[];
+    toolProfileFilter?: ResourceProfileFilterSettings;
+    /** Preserve an explicit launch-time model across profile reloads. */
+    isExplicitModel?: boolean;
+    /** Preserve an explicit launch-time thinking level across profile reloads. */
+    isExplicitThinking?: boolean;
+    /** Child sessions receive the worker UAC and write ceilings. */
+    isChildSession?: boolean;
+    /** Alternate base tool instances for embedded/custom runtimes. */
+    baseToolsOverride?: Record<string, AgentTool>;
+    /** Mutable bridge used by the agent loop to reach the current extension generation. */
+    extensionRunnerRef?: {
+        current?: ExtensionRunner;
+    };
+    sessionStartEvent?: SessionStartEvent;
+    /** Injectable pointer-first workspace collector; tests use this to avoid process execution. */
+    collectWorkspaceSources?: typeof collectWorkspaceSources;
+    /** Immutable owner-authored orchestration policy. */
+    orchestrationProfile?: OrchestrationProfile;
+    /** Injectable local-runtime I/O dependencies. */
+    localRuntimeDeps?: LocalRuntimeDeps;
+}
+export interface ExtensionBindings {
+    uiContext?: ExtensionUIContext;
+    mode?: ExtensionContext["mode"];
+    commandContextActions?: ExtensionCommandContextActions;
+    abortHandler?: () => void;
+    shutdownHandler?: ShutdownHandler;
+    onError?: ExtensionErrorListener;
+}
+export interface PromptOptions {
+    /** Expand file prompt templates and skills. Defaults to true. */
+    expandPromptTemplates?: boolean;
+    /** Process slash commands before model submission. Defaults to `expandPromptTemplates`. */
+    processSlashCommands?: boolean;
+    images?: ImageContent[];
+    /** Required queue behavior when a foreground turn is already streaming. */
+    streamingBehavior?: "steer" | "followUp";
+    source?: InputSource;
+    /** Observe whether prompt preflight accepted the request. */
+    preflightResult?: (success: boolean) => void;
+    /** Permit idle goal continuation after this prompt settles. Defaults to true. */
+    autoContinueGoal?: boolean;
+    /** Hidden internal turn persisted as a typed context marker. */
+    internalContextType?: string;
+}
+export interface ModelCycleResult {
+    model: Model<Api>;
+    thinkingLevel: ThinkingLevel;
+    /** Whether cycling was constrained to launch-scoped models. */
+    isScoped: boolean;
+}
+export interface CompactionGateCheckStats {
+    failures: number;
+    minScore?: number;
+    maxScore?: number;
+    threshold?: number;
+    comparator?: "minimum" | "maximum";
+}
+export interface CompactionGateStats {
+    gateFailures: number;
+    deterministicGapFills: number;
+    compactionsWithGateFailures: number;
+    checks: Record<string, CompactionGateCheckStats>;
+}
+export interface SessionStats {
+    sessionFile: string | undefined;
+    sessionId: string;
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    toolResults: number;
+    totalMessages: number;
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    cost: number;
+    contextUsage?: ContextUsage;
+    toolArgumentValidation: ToolArgumentValidationStats;
+    compactionGates: CompactionGateStats;
+}
+export declare const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
+export declare const RUNAWAY_STOP_CUSTOM_TYPE = "runaway_stop";
+export declare const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = "tool_validation_escalation";
+export interface RunawayStopRecord {
+    signature: string;
+    repeats: number;
+    model?: string;
+    provider?: string;
+    at: string;
+}
+export interface ToolValidationEscalationRecord {
+    tool: string;
+    signature: string;
+    repeats: number;
+    model: string;
+    provider: string;
+    at: string;
+}
+export interface SpawnedUsageReport {
+    /** Cumulative child usage, including that child's already-rolled-up descendants. */
+    usage: Usage;
+    label?: string;
+    sourceSessionId?: string;
+    /** Stable idempotency identity for retry-safe ingestion. */
+    reportId?: string;
+}
+export interface SpawnedUsageTotals {
+    cost: number;
+    reports: number;
+}
+export interface IsolatedCompletionOptions {
+    systemPrompt: string;
+    /** Isolated conversation; foreground session history is never inherited. */
+    messages: Message[];
+    model?: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+    maxTokens?: number;
+    /** Fresh child-owned tool instances. Omission preserves one-shot behavior. */
+    tools?: AgentTool[];
+    /** Explicit child-loop turn cap. */
+    maxTurns?: number;
+    /** Optional tool-free finalization prompt after the bounded tool loop. */
+    finalTextPrompt?: string;
+    /** Child-only capability/path gate. */
+    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
+    /** Child-only result observer. */
+    afterToolCall?: AgentLoopConfig["afterToolCall"];
+    signal?: AbortSignal;
+    /** Required cache policy; isolated calls never inherit a provider default implicitly. */
+    cacheRetention: CacheRetention;
+    /** Stable namespace used to derive provider cache affinity. */
+    laneKind?: string;
+}
+export declare const DEFAULT_ISOLATED_LANE_KIND = "isolated";
+export declare function computeLaneAffinityKey(laneKind: string, model: Model<Api> | undefined, systemPrompt: string): string;
+export interface IsolatedCompletionResult {
+    text: string;
+    usage: Usage;
+    stopReason: StopReason;
+}
+export interface ResearchLaneRunOutcome {
+    started: boolean;
+    skipReason?: string;
+    record?: LaneRecord;
+    result?: ResearchRunResult;
+}
+export interface WorkerDelegationRunOutcome {
+    started: boolean;
+    skipReason?: string;
+    record?: LaneRecord;
+    outcome?: WorkerRunOutcome;
+}
+export interface GoalContinuationOnceOptions {
+    /** Consecutive non-progress passes allowed before deterministic escalation; 0 disables the gate. */
+    maxStallTurns: number;
+}
+export interface GoalContinuationOnceResult {
+    submitted: boolean;
+    snapshot: GoalRuntimeSnapshot;
+    prompt?: GoalContinuationPrompt;
+}
+export type GoalContinuationLoopStopReason = "continuation_not_allowed" | "max_turns_reached" | "wall_clock_budget_reached" | "goal_budget_exhausted" | "already_continuing" | "session_disposed" | "goal_tool_unavailable" | "worker_in_flight";
+export interface GoalContinuationLoopOptions extends GoalContinuationOnceOptions {
+    /** Explicit per-invocation turn limit; 0 means unbounded. */
+    maxTurns: number;
+    /** Explicit per-invocation active-time limit; 0/undefined means unbounded. */
+    maxWallClockMinutes?: number;
+    /** Injectable monotonic-enough clock for deterministic tests. */
+    now?: () => number;
+}
+export interface GoalContinuationLoopResult {
+    turnsSubmitted: number;
+    stopReason: GoalContinuationLoopStopReason;
+    finalSnapshot: GoalRuntimeSnapshot;
+}
+/** Test-only stream watchdog override contract retained in the public session module. */
+export type StreamIdleOptionsOverride = Partial<StreamIdleOptions> | undefined;
+//# sourceMappingURL=agent-session-contracts.d.ts.map

package/dist/core/agent-session-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-contracts.d.ts","sourceRoot":"","sources":["../../src/core/agent-session-contracts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,KAAK,EACL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACvF,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC9G,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EACX,YAAY,EACZ,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAE5E,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CASrE;AAED,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAC1B,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACnE;IACA,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,GACD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IACA,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IAC5C,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE;AACpF,+FAA+F;GAC7F;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACA,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9F,CAAC;AAEL,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,aAAa,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAC3E,cAAc,EAAE,cAAc,CAAC;IAC/B,+CAA+C;IAC/C,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,kEAAkE;IAClE,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,6BAA6B,CAAC;IAClD,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9C,uFAAuF;IACvF,kBAAkB,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;IACnD,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,+FAA+F;IAC/F,uBAAuB,CAAC,EAAE,OAAO,uBAAuB,CAAC;IACzD,qDAAqD;IACrD,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IACjC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,qBAAqB,CAAC,EAAE,8BAA8B,CAAC;IACvD,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC7B,iEAAiE;IACjE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,2FAA2F;IAC3F,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B,EAAE,MAAM,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC5B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChG,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sBAAsB,EAAE,2BAA2B,CAAC;IACpD,eAAe,EAAE,mBAAmB,CAAC;CACrC;AAED,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AACzD,eAAO,MAAM,wBAAwB,iBAAiB,CAAC;AACvD,eAAO,MAAM,sCAAsC,+BAA+B,CAAC;AAEnF,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,8BAA8B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,kBAAkB;IAClC,oFAAoF;IACpF,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,cAAc,CAAC,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC;IACnD,kCAAkC;IAClC,aAAa,CAAC,EAAE,eAAe,CAAC,eAAe,CAAC,CAAC;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yFAAyF;IACzF,cAAc,EAAE,cAAc,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,0BAA0B,aAAa,CAAC;AAErD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOpH;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC3C,oGAAoG;IACpG,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,MAAM,MAAM,8BAA8B,GACvC,0BAA0B,GAC1B,mBAAmB,GACnB,2BAA2B,GAC3B,uBAAuB,GACvB,oBAAoB,GACpB,kBAAkB,GAClB,uBAAuB,GACvB,kBAAkB,CAAC;AAEtB,MAAM,WAAW,2BAA4B,SAAQ,2BAA2B;IAC/E,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,8BAA8B,CAAC;IAC3C,aAAa,EAAE,mBAAmB,CAAC;CACnC;AAED,yFAAyF;AACzF,MAAM,MAAM,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type {\n\tAgent,\n\tAgentEvent,\n\tAgentLoopConfig,\n\tAgentMessage,\n\tAgentTool,\n\tStreamIdleOptions,\n\tThinkingLevel,\n} from \"@caupulican/pi-agent-core\";\nimport type { CompactionResult, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { Api, CacheRetention, ImageContent, Message, Model, StopReason, Usage } from \"@caupulican/pi-ai\";\nimport type { LaneRecord, LaneTerminalStatus } from \"./autonomy/lane-tracker.ts\";\nimport type { WorkerRunOutcome } from \"./delegation/worker-runner.ts\";\nimport type {\n\tContextUsage,\n\tExtensionCommandContextActions,\n\tExtensionContext,\n\tExtensionErrorListener,\n\tExtensionRunner,\n\tExtensionUIContext,\n\tInputSource,\n\tSessionStartEvent,\n\tShutdownHandler,\n\tToolDefinition,\n} from \"./extensions/index.ts\";\nimport type { GoalContinuationPrompt } from \"./goals/goal-continuation-prompt.ts\";\nimport type { GoalRuntimeSnapshot } from \"./goals/goal-runtime-snapshot.ts\";\nimport type { ModelRegistry } from \"./model-registry.ts\";\nimport type { LocalRuntimeDeps } from \"./models/local-runtime.ts\";\nimport type { OrchestrationProfile } from \"./orchestration/contracts.ts\";\nimport type { ResearchRunResult } from \"./research/research-runner.ts\";\nimport type { collectWorkspaceSources } from \"./research/workspace-collector.ts\";\nimport type { ResourceLoader } from \"./resource-loader.ts\";\nimport type { ResourceProfileFilterSettings, SettingsManager } from \"./settings-manager.ts\";\nimport type { ToolArgumentValidationStats } from \"./tool-recovery-stats.ts\";\n\n/** Parsed skill block from a user message. */\nexport interface ParsedSkillBlock {\n\tname: string;\n\tlocation: string;\n\tcontent: string;\n\tuserMessage: string | undefined;\n}\n\n/** Parse a skill block from message text, or return null when none is present. */\nexport function parseSkillBlock(text: string): ParsedSkillBlock | null {\n\tconst match = text.match(/^<skill name=\"([^\"]+)\" location=\"([^\"]+)\">\\n([\\s\\S]*?)\\n<\\/skill>(?:\\n\\n([\\s\\S]+))?$/);\n\tif (!match) return null;\n\treturn {\n\t\tname: match[1],\n\t\tlocation: match[2],\n\t\tcontent: match[3],\n\t\tuserMessage: match[4]?.trim() || undefined,\n\t};\n}\n\n/** Session-specific events that extend the core AgentEvent. */\nexport type AgentSessionEvent =\n\t| Exclude<AgentEvent, { type: \"agent_end\" }>\n\t| { type: \"agent_end\"; messages: AgentMessage[]; willRetry: boolean }\n\t| {\n\t\t\ttype: \"queue_update\";\n\t\t\tsteering: readonly string[];\n\t\t\tfollowUp: readonly string[];\n\t\t\tcommands: readonly string[];\n\t  }\n\t| { type: \"compaction_start\"; reason: \"manual\" | \"threshold\" | \"overflow\" }\n\t| { type: \"session_info_changed\"; name: string | undefined }\n\t| { type: \"thinking_level_changed\"; level: ThinkingLevel }\n\t| { type: \"warning\"; message: string }\n\t| {\n\t\t\ttype: \"compaction_end\";\n\t\t\treason: \"manual\" | \"threshold\" | \"overflow\";\n\t\t\tresult: CompactionResult | undefined;\n\t\t\taborted: boolean;\n\t\t\twillRetry: boolean;\n\t\t\terrorMessage?: string;\n\t\t\t/** Benign no-op explanation when compaction did not produce a result. */\n\t\t\tskipReason?: string;\n\t  }\n\t| { type: \"auto_retry_start\"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }\n\t| { type: \"auto_retry_end\"; success: boolean; attempt: number; finalError?: string }\n\t/** UI-only bracket around foreground routing/preparation. Always paired with `routing_end`. */\n\t| { type: \"routing_start\" }\n\t| { type: \"routing_end\" }\n\t| {\n\t\t\ttype: \"delegate_workers\";\n\t\t\tactive: number;\n\t\t\tqueued: number;\n\t\t\trunning: number;\n\t\t\tcompletedSinceFlush: number;\n\t\t\tfailedSinceFlush: number;\n\t\t\tterminalSinceFlush: Array<{ laneId: string; status: LaneTerminalStatus; reasonCode?: string }>;\n\t  };\n\nexport type AgentSessionEventListener = (event: AgentSessionEvent) => void;\n\nexport interface AgentSessionConfig {\n\tagent: Agent;\n\tsessionManager: SessionManager;\n\tsettingsManager: SettingsManager;\n\tcwd: string;\n\t/** User-level agent state directory for generated runtime artifacts. */\n\tagentDir?: string;\n\t/** Models available to the interactive model-cycle action. */\n\tscopedModels?: Array<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }>;\n\tresourceLoader: ResourceLoader;\n\t/** SDK tools registered outside extensions. */\n\tcustomTools?: ToolDefinition[];\n\tmodelRegistry: ModelRegistry;\n\t/** Initial active tool names before profile and UAC filtering. */\n\tinitialActiveToolNames?: string[];\n\t/** Optional tool allowlist. */\n\tallowedToolNames?: string[];\n\t/** Optional tool denylist. */\n\texcludedToolNames?: string[];\n\ttoolProfileFilter?: ResourceProfileFilterSettings;\n\t/** Preserve an explicit launch-time model across profile reloads. */\n\tisExplicitModel?: boolean;\n\t/** Preserve an explicit launch-time thinking level across profile reloads. */\n\tisExplicitThinking?: boolean;\n\t/** Child sessions receive the worker UAC and write ceilings. */\n\tisChildSession?: boolean;\n\t/** Alternate base tool instances for embedded/custom runtimes. */\n\tbaseToolsOverride?: Record<string, AgentTool>;\n\t/** Mutable bridge used by the agent loop to reach the current extension generation. */\n\textensionRunnerRef?: { current?: ExtensionRunner };\n\tsessionStartEvent?: SessionStartEvent;\n\t/** Injectable pointer-first workspace collector; tests use this to avoid process execution. */\n\tcollectWorkspaceSources?: typeof collectWorkspaceSources;\n\t/** Immutable owner-authored orchestration policy. */\n\torchestrationProfile?: OrchestrationProfile;\n\t/** Injectable local-runtime I/O dependencies. */\n\tlocalRuntimeDeps?: LocalRuntimeDeps;\n}\n\nexport interface ExtensionBindings {\n\tuiContext?: ExtensionUIContext;\n\tmode?: ExtensionContext[\"mode\"];\n\tcommandContextActions?: ExtensionCommandContextActions;\n\tabortHandler?: () => void;\n\tshutdownHandler?: ShutdownHandler;\n\tonError?: ExtensionErrorListener;\n}\n\nexport interface PromptOptions {\n\t/** Expand file prompt templates and skills. Defaults to true. */\n\texpandPromptTemplates?: boolean;\n\t/** Process slash commands before model submission. Defaults to `expandPromptTemplates`. */\n\tprocessSlashCommands?: boolean;\n\timages?: ImageContent[];\n\t/** Required queue behavior when a foreground turn is already streaming. */\n\tstreamingBehavior?: \"steer\" | \"followUp\";\n\tsource?: InputSource;\n\t/** Observe whether prompt preflight accepted the request. */\n\tpreflightResult?: (success: boolean) => void;\n\t/** Permit idle goal continuation after this prompt settles. Defaults to true. */\n\tautoContinueGoal?: boolean;\n\t/** Hidden internal turn persisted as a typed context marker. */\n\tinternalContextType?: string;\n}\n\nexport interface ModelCycleResult {\n\tmodel: Model<Api>;\n\tthinkingLevel: ThinkingLevel;\n\t/** Whether cycling was constrained to launch-scoped models. */\n\tisScoped: boolean;\n}\n\nexport interface CompactionGateCheckStats {\n\tfailures: number;\n\tminScore?: number;\n\tmaxScore?: number;\n\tthreshold?: number;\n\tcomparator?: \"minimum\" | \"maximum\";\n}\n\nexport interface CompactionGateStats {\n\tgateFailures: number;\n\tdeterministicGapFills: number;\n\tcompactionsWithGateFailures: number;\n\tchecks: Record<string, CompactionGateCheckStats>;\n}\n\nexport interface SessionStats {\n\tsessionFile: string | undefined;\n\tsessionId: string;\n\tuserMessages: number;\n\tassistantMessages: number;\n\ttoolCalls: number;\n\ttoolResults: number;\n\ttotalMessages: number;\n\ttokens: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };\n\tcost: number;\n\tcontextUsage?: ContextUsage;\n\ttoolArgumentValidation: ToolArgumentValidationStats;\n\tcompactionGates: CompactionGateStats;\n}\n\nexport const SPAWNED_USAGE_CUSTOM_TYPE = \"spawned_usage\";\nexport const RUNAWAY_STOP_CUSTOM_TYPE = \"runaway_stop\";\nexport const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = \"tool_validation_escalation\";\n\nexport interface RunawayStopRecord {\n\tsignature: string;\n\trepeats: number;\n\tmodel?: string;\n\tprovider?: string;\n\tat: string;\n}\n\nexport interface ToolValidationEscalationRecord {\n\ttool: string;\n\tsignature: string;\n\trepeats: number;\n\tmodel: string;\n\tprovider: string;\n\tat: string;\n}\n\nexport interface SpawnedUsageReport {\n\t/** Cumulative child usage, including that child's already-rolled-up descendants. */\n\tusage: Usage;\n\tlabel?: string;\n\tsourceSessionId?: string;\n\t/** Stable idempotency identity for retry-safe ingestion. */\n\treportId?: string;\n}\n\nexport interface SpawnedUsageTotals {\n\tcost: number;\n\treports: number;\n}\n\nexport interface IsolatedCompletionOptions {\n\tsystemPrompt: string;\n\t/** Isolated conversation; foreground session history is never inherited. */\n\tmessages: Message[];\n\tmodel?: Model<Api>;\n\tthinkingLevel?: ThinkingLevel;\n\tmaxTokens?: number;\n\t/** Fresh child-owned tool instances. Omission preserves one-shot behavior. */\n\ttools?: AgentTool[];\n\t/** Explicit child-loop turn cap. */\n\tmaxTurns?: number;\n\t/** Optional tool-free finalization prompt after the bounded tool loop. */\n\tfinalTextPrompt?: string;\n\t/** Child-only capability/path gate. */\n\tbeforeToolCall?: AgentLoopConfig[\"beforeToolCall\"];\n\t/** Child-only result observer. */\n\tafterToolCall?: AgentLoopConfig[\"afterToolCall\"];\n\tsignal?: AbortSignal;\n\t/** Required cache policy; isolated calls never inherit a provider default implicitly. */\n\tcacheRetention: CacheRetention;\n\t/** Stable namespace used to derive provider cache affinity. */\n\tlaneKind?: string;\n}\n\nexport const DEFAULT_ISOLATED_LANE_KIND = \"isolated\";\n\nexport function computeLaneAffinityKey(laneKind: string, model: Model<Api> | undefined, systemPrompt: string): string {\n\tconst modelKey = model ? `${model.provider}/${model.id}` : \"unknown-model\";\n\tconst digest = createHash(\"sha256\")\n\t\t.update([\"pi-lane-affinity-v1\", laneKind, modelKey, systemPrompt].join(\"\\u0000\"))\n\t\t.digest(\"hex\")\n\t\t.slice(0, 32);\n\treturn `lane:${laneKind}:${digest}`;\n}\n\nexport interface IsolatedCompletionResult {\n\ttext: string;\n\tusage: Usage;\n\tstopReason: StopReason;\n}\n\nexport interface ResearchLaneRunOutcome {\n\tstarted: boolean;\n\tskipReason?: string;\n\trecord?: LaneRecord;\n\tresult?: ResearchRunResult;\n}\n\nexport interface WorkerDelegationRunOutcome {\n\tstarted: boolean;\n\tskipReason?: string;\n\trecord?: LaneRecord;\n\toutcome?: WorkerRunOutcome;\n}\n\nexport interface GoalContinuationOnceOptions {\n\t/** Consecutive non-progress passes allowed before deterministic escalation; 0 disables the gate. */\n\tmaxStallTurns: number;\n}\n\nexport interface GoalContinuationOnceResult {\n\tsubmitted: boolean;\n\tsnapshot: GoalRuntimeSnapshot;\n\tprompt?: GoalContinuationPrompt;\n}\n\nexport type GoalContinuationLoopStopReason =\n\t| \"continuation_not_allowed\"\n\t| \"max_turns_reached\"\n\t| \"wall_clock_budget_reached\"\n\t| \"goal_budget_exhausted\"\n\t| \"already_continuing\"\n\t| \"session_disposed\"\n\t| \"goal_tool_unavailable\"\n\t| \"worker_in_flight\";\n\nexport interface GoalContinuationLoopOptions extends GoalContinuationOnceOptions {\n\t/** Explicit per-invocation turn limit; 0 means unbounded. */\n\tmaxTurns: number;\n\t/** Explicit per-invocation active-time limit; 0/undefined means unbounded. */\n\tmaxWallClockMinutes?: number;\n\t/** Injectable monotonic-enough clock for deterministic tests. */\n\tnow?: () => number;\n}\n\nexport interface GoalContinuationLoopResult {\n\tturnsSubmitted: number;\n\tstopReason: GoalContinuationLoopStopReason;\n\tfinalSnapshot: GoalRuntimeSnapshot;\n}\n\n/** Test-only stream watchdog override contract retained in the public session module. */\nexport type StreamIdleOptionsOverride = Partial<StreamIdleOptions> | undefined;\n"]}

package/dist/core/agent-session-contracts.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+/** Parse a skill block from message text, or return null when none is present. */
+export function parseSkillBlock(text) {
+    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+    if (!match)
+        return null;
+    return {
+        name: match[1],
+        location: match[2],
+        content: match[3],
+        userMessage: match[4]?.trim() || undefined,
+    };
+}
+export const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
+export const RUNAWAY_STOP_CUSTOM_TYPE = "runaway_stop";
+export const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = "tool_validation_escalation";
+export const DEFAULT_ISOLATED_LANE_KIND = "isolated";
+export function computeLaneAffinityKey(laneKind, model, systemPrompt) {
+    const modelKey = model ? `${model.provider}/${model.id}` : "unknown-model";
+    const digest = createHash("sha256")
+        .update(["pi-lane-affinity-v1", laneKind, modelKey, systemPrompt].join("\u0000"))
+        .digest("hex")
+        .slice(0, 32);
+    return `lane:${laneKind}:${digest}`;
+}
+//# sourceMappingURL=agent-session-contracts.js.map

package/dist/core/agent-session-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-contracts.js","sourceRoot":"","sources":["../../src/core/agent-session-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA6CzC,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,IAAY,EAA2B;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,sFAAsF,CAAC,CAAC;IACjH,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACN,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QACd,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QAClB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QACjB,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS;KAC1C,CAAC;AAAA,CACF;AAiJD,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CAAC;AACvD,MAAM,CAAC,MAAM,sCAAsC,GAAG,4BAA4B,CAAC;AAyDnF,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC;AAErD,MAAM,UAAU,sBAAsB,CAAC,QAAgB,EAAE,KAA6B,EAAE,YAAoB,EAAU;IACrH,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;IAC3E,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;SACjC,MAAM,CAAC,CAAC,qBAAqB,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;SAChF,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACf,OAAO,QAAQ,QAAQ,IAAI,MAAM,EAAE,CAAC;AAAA,CACpC","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type {\n\tAgent,\n\tAgentEvent,\n\tAgentLoopConfig,\n\tAgentMessage,\n\tAgentTool,\n\tStreamIdleOptions,\n\tThinkingLevel,\n} from \"@caupulican/pi-agent-core\";\nimport type { CompactionResult, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { Api, CacheRetention, ImageContent, Message, Model, StopReason, Usage } from \"@caupulican/pi-ai\";\nimport type { LaneRecord, LaneTerminalStatus } from \"./autonomy/lane-tracker.ts\";\nimport type { WorkerRunOutcome } from \"./delegation/worker-runner.ts\";\nimport type {\n\tContextUsage,\n\tExtensionCommandContextActions,\n\tExtensionContext,\n\tExtensionErrorListener,\n\tExtensionRunner,\n\tExtensionUIContext,\n\tInputSource,\n\tSessionStartEvent,\n\tShutdownHandler,\n\tToolDefinition,\n} from \"./extensions/index.ts\";\nimport type { GoalContinuationPrompt } from \"./goals/goal-continuation-prompt.ts\";\nimport type { GoalRuntimeSnapshot } from \"./goals/goal-runtime-snapshot.ts\";\nimport type { ModelRegistry } from \"./model-registry.ts\";\nimport type { LocalRuntimeDeps } from \"./models/local-runtime.ts\";\nimport type { OrchestrationProfile } from \"./orchestration/contracts.ts\";\nimport type { ResearchRunResult } from \"./research/research-runner.ts\";\nimport type { collectWorkspaceSources } from \"./research/workspace-collector.ts\";\nimport type { ResourceLoader } from \"./resource-loader.ts\";\nimport type { ResourceProfileFilterSettings, SettingsManager } from \"./settings-manager.ts\";\nimport type { ToolArgumentValidationStats } from \"./tool-recovery-stats.ts\";\n\n/** Parsed skill block from a user message. */\nexport interface ParsedSkillBlock {\n\tname: string;\n\tlocation: string;\n\tcontent: string;\n\tuserMessage: string | undefined;\n}\n\n/** Parse a skill block from message text, or return null when none is present. */\nexport function parseSkillBlock(text: string): ParsedSkillBlock | null {\n\tconst match = text.match(/^<skill name=\"([^\"]+)\" location=\"([^\"]+)\">\\n([\\s\\S]*?)\\n<\\/skill>(?:\\n\\n([\\s\\S]+))?$/);\n\tif (!match) return null;\n\treturn {\n\t\tname: match[1],\n\t\tlocation: match[2],\n\t\tcontent: match[3],\n\t\tuserMessage: match[4]?.trim() || undefined,\n\t};\n}\n\n/** Session-specific events that extend the core AgentEvent. */\nexport type AgentSessionEvent =\n\t| Exclude<AgentEvent, { type: \"agent_end\" }>\n\t| { type: \"agent_end\"; messages: AgentMessage[]; willRetry: boolean }\n\t| {\n\t\t\ttype: \"queue_update\";\n\t\t\tsteering: readonly string[];\n\t\t\tfollowUp: readonly string[];\n\t\t\tcommands: readonly string[];\n\t  }\n\t| { type: \"compaction_start\"; reason: \"manual\" | \"threshold\" | \"overflow\" }\n\t| { type: \"session_info_changed\"; name: string | undefined }\n\t| { type: \"thinking_level_changed\"; level: ThinkingLevel }\n\t| { type: \"warning\"; message: string }\n\t| {\n\t\t\ttype: \"compaction_end\";\n\t\t\treason: \"manual\" | \"threshold\" | \"overflow\";\n\t\t\tresult: CompactionResult | undefined;\n\t\t\taborted: boolean;\n\t\t\twillRetry: boolean;\n\t\t\terrorMessage?: string;\n\t\t\t/** Benign no-op explanation when compaction did not produce a result. */\n\t\t\tskipReason?: string;\n\t  }\n\t| { type: \"auto_retry_start\"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }\n\t| { type: \"auto_retry_end\"; success: boolean; attempt: number; finalError?: string }\n\t/** UI-only bracket around foreground routing/preparation. Always paired with `routing_end`. */\n\t| { type: \"routing_start\" }\n\t| { type: \"routing_end\" }\n\t| {\n\t\t\ttype: \"delegate_workers\";\n\t\t\tactive: number;\n\t\t\tqueued: number;\n\t\t\trunning: number;\n\t\t\tcompletedSinceFlush: number;\n\t\t\tfailedSinceFlush: number;\n\t\t\tterminalSinceFlush: Array<{ laneId: string; status: LaneTerminalStatus; reasonCode?: string }>;\n\t  };\n\nexport type AgentSessionEventListener = (event: AgentSessionEvent) => void;\n\nexport interface AgentSessionConfig {\n\tagent: Agent;\n\tsessionManager: SessionManager;\n\tsettingsManager: SettingsManager;\n\tcwd: string;\n\t/** User-level agent state directory for generated runtime artifacts. */\n\tagentDir?: string;\n\t/** Models available to the interactive model-cycle action. */\n\tscopedModels?: Array<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }>;\n\tresourceLoader: ResourceLoader;\n\t/** SDK tools registered outside extensions. */\n\tcustomTools?: ToolDefinition[];\n\tmodelRegistry: ModelRegistry;\n\t/** Initial active tool names before profile and UAC filtering. */\n\tinitialActiveToolNames?: string[];\n\t/** Optional tool allowlist. */\n\tallowedToolNames?: string[];\n\t/** Optional tool denylist. */\n\texcludedToolNames?: string[];\n\ttoolProfileFilter?: ResourceProfileFilterSettings;\n\t/** Preserve an explicit launch-time model across profile reloads. */\n\tisExplicitModel?: boolean;\n\t/** Preserve an explicit launch-time thinking level across profile reloads. */\n\tisExplicitThinking?: boolean;\n\t/** Child sessions receive the worker UAC and write ceilings. */\n\tisChildSession?: boolean;\n\t/** Alternate base tool instances for embedded/custom runtimes. */\n\tbaseToolsOverride?: Record<string, AgentTool>;\n\t/** Mutable bridge used by the agent loop to reach the current extension generation. */\n\textensionRunnerRef?: { current?: ExtensionRunner };\n\tsessionStartEvent?: SessionStartEvent;\n\t/** Injectable pointer-first workspace collector; tests use this to avoid process execution. */\n\tcollectWorkspaceSources?: typeof collectWorkspaceSources;\n\t/** Immutable owner-authored orchestration policy. */\n\torchestrationProfile?: OrchestrationProfile;\n\t/** Injectable local-runtime I/O dependencies. */\n\tlocalRuntimeDeps?: LocalRuntimeDeps;\n}\n\nexport interface ExtensionBindings {\n\tuiContext?: ExtensionUIContext;\n\tmode?: ExtensionContext[\"mode\"];\n\tcommandContextActions?: ExtensionCommandContextActions;\n\tabortHandler?: () => void;\n\tshutdownHandler?: ShutdownHandler;\n\tonError?: ExtensionErrorListener;\n}\n\nexport interface PromptOptions {\n\t/** Expand file prompt templates and skills. Defaults to true. */\n\texpandPromptTemplates?: boolean;\n\t/** Process slash commands before model submission. Defaults to `expandPromptTemplates`. */\n\tprocessSlashCommands?: boolean;\n\timages?: ImageContent[];\n\t/** Required queue behavior when a foreground turn is already streaming. */\n\tstreamingBehavior?: \"steer\" | \"followUp\";\n\tsource?: InputSource;\n\t/** Observe whether prompt preflight accepted the request. */\n\tpreflightResult?: (success: boolean) => void;\n\t/** Permit idle goal continuation after this prompt settles. Defaults to true. */\n\tautoContinueGoal?: boolean;\n\t/** Hidden internal turn persisted as a typed context marker. */\n\tinternalContextType?: string;\n}\n\nexport interface ModelCycleResult {\n\tmodel: Model<Api>;\n\tthinkingLevel: ThinkingLevel;\n\t/** Whether cycling was constrained to launch-scoped models. */\n\tisScoped: boolean;\n}\n\nexport interface CompactionGateCheckStats {\n\tfailures: number;\n\tminScore?: number;\n\tmaxScore?: number;\n\tthreshold?: number;\n\tcomparator?: \"minimum\" | \"maximum\";\n}\n\nexport interface CompactionGateStats {\n\tgateFailures: number;\n\tdeterministicGapFills: number;\n\tcompactionsWithGateFailures: number;\n\tchecks: Record<string, CompactionGateCheckStats>;\n}\n\nexport interface SessionStats {\n\tsessionFile: string | undefined;\n\tsessionId: string;\n\tuserMessages: number;\n\tassistantMessages: number;\n\ttoolCalls: number;\n\ttoolResults: number;\n\ttotalMessages: number;\n\ttokens: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };\n\tcost: number;\n\tcontextUsage?: ContextUsage;\n\ttoolArgumentValidation: ToolArgumentValidationStats;\n\tcompactionGates: CompactionGateStats;\n}\n\nexport const SPAWNED_USAGE_CUSTOM_TYPE = \"spawned_usage\";\nexport const RUNAWAY_STOP_CUSTOM_TYPE = \"runaway_stop\";\nexport const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = \"tool_validation_escalation\";\n\nexport interface RunawayStopRecord {\n\tsignature: string;\n\trepeats: number;\n\tmodel?: string;\n\tprovider?: string;\n\tat: string;\n}\n\nexport interface ToolValidationEscalationRecord {\n\ttool: string;\n\tsignature: string;\n\trepeats: number;\n\tmodel: string;\n\tprovider: string;\n\tat: string;\n}\n\nexport interface SpawnedUsageReport {\n\t/** Cumulative child usage, including that child's already-rolled-up descendants. */\n\tusage: Usage;\n\tlabel?: string;\n\tsourceSessionId?: string;\n\t/** Stable idempotency identity for retry-safe ingestion. */\n\treportId?: string;\n}\n\nexport interface SpawnedUsageTotals {\n\tcost: number;\n\treports: number;\n}\n\nexport interface IsolatedCompletionOptions {\n\tsystemPrompt: string;\n\t/** Isolated conversation; foreground session history is never inherited. */\n\tmessages: Message[];\n\tmodel?: Model<Api>;\n\tthinkingLevel?: ThinkingLevel;\n\tmaxTokens?: number;\n\t/** Fresh child-owned tool instances. Omission preserves one-shot behavior. */\n\ttools?: AgentTool[];\n\t/** Explicit child-loop turn cap. */\n\tmaxTurns?: number;\n\t/** Optional tool-free finalization prompt after the bounded tool loop. */\n\tfinalTextPrompt?: string;\n\t/** Child-only capability/path gate. */\n\tbeforeToolCall?: AgentLoopConfig[\"beforeToolCall\"];\n\t/** Child-only result observer. */\n\tafterToolCall?: AgentLoopConfig[\"afterToolCall\"];\n\tsignal?: AbortSignal;\n\t/** Required cache policy; isolated calls never inherit a provider default implicitly. */\n\tcacheRetention: CacheRetention;\n\t/** Stable namespace used to derive provider cache affinity. */\n\tlaneKind?: string;\n}\n\nexport const DEFAULT_ISOLATED_LANE_KIND = \"isolated\";\n\nexport function computeLaneAffinityKey(laneKind: string, model: Model<Api> | undefined, systemPrompt: string): string {\n\tconst modelKey = model ? `${model.provider}/${model.id}` : \"unknown-model\";\n\tconst digest = createHash(\"sha256\")\n\t\t.update([\"pi-lane-affinity-v1\", laneKind, modelKey, systemPrompt].join(\"\\u0000\"))\n\t\t.digest(\"hex\")\n\t\t.slice(0, 32);\n\treturn `lane:${laneKind}:${digest}`;\n}\n\nexport interface IsolatedCompletionResult {\n\ttext: string;\n\tusage: Usage;\n\tstopReason: StopReason;\n}\n\nexport interface ResearchLaneRunOutcome {\n\tstarted: boolean;\n\tskipReason?: string;\n\trecord?: LaneRecord;\n\tresult?: ResearchRunResult;\n}\n\nexport interface WorkerDelegationRunOutcome {\n\tstarted: boolean;\n\tskipReason?: string;\n\trecord?: LaneRecord;\n\toutcome?: WorkerRunOutcome;\n}\n\nexport interface GoalContinuationOnceOptions {\n\t/** Consecutive non-progress passes allowed before deterministic escalation; 0 disables the gate. */\n\tmaxStallTurns: number;\n}\n\nexport interface GoalContinuationOnceResult {\n\tsubmitted: boolean;\n\tsnapshot: GoalRuntimeSnapshot;\n\tprompt?: GoalContinuationPrompt;\n}\n\nexport type GoalContinuationLoopStopReason =\n\t| \"continuation_not_allowed\"\n\t| \"max_turns_reached\"\n\t| \"wall_clock_budget_reached\"\n\t| \"goal_budget_exhausted\"\n\t| \"already_continuing\"\n\t| \"session_disposed\"\n\t| \"goal_tool_unavailable\"\n\t| \"worker_in_flight\";\n\nexport interface GoalContinuationLoopOptions extends GoalContinuationOnceOptions {\n\t/** Explicit per-invocation turn limit; 0 means unbounded. */\n\tmaxTurns: number;\n\t/** Explicit per-invocation active-time limit; 0/undefined means unbounded. */\n\tmaxWallClockMinutes?: number;\n\t/** Injectable monotonic-enough clock for deterministic tests. */\n\tnow?: () => number;\n}\n\nexport interface GoalContinuationLoopResult {\n\tturnsSubmitted: number;\n\tstopReason: GoalContinuationLoopStopReason;\n\tfinalSnapshot: GoalRuntimeSnapshot;\n}\n\n/** Test-only stream watchdog override contract retained in the public session module. */\nexport type StreamIdleOptionsOverride = Partial<StreamIdleOptions> | undefined;\n"]}