@caupulican/pi-adaptative 0.81.39 → 0.81.41

package/dist/core/session-role.d.ts

@@ -5,7 +5,8 @@
  * tool's worker scoping, and the read-only store options threaded through the persistence layer).
  *
  * A session is a worker iff EITHER:
- * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or
+ * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),
+ * - a valid `PI_PARENT_PID` declares this process as a managed child, or
  * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a
  *   lane-bound session is a worker by construction, regardless of how it was launched.
  *
@@ -14,15 +15,21 @@
  * var is additive evidence for "worker", never a downgrade signal.
  */
 export type SessionRole = "main" | "worker";
+export type TerminalSessionMode = "user" | "worker";
+export declare const PI_SESSION_ROLE_ENV = "PI_SESSION_ROLE";
+export declare function isTerminalSessionMode(value: string): value is TerminalSessionMode;
+/** Apply the terminal audience declaration without bypassing worker inference or UAC ceilings. */
+export declare function setTerminalSessionMode(mode: TerminalSessionMode, env?: NodeJS.ProcessEnv): void;
 /** Derive this process's session role from the environment (env-injectable for tests). */
 export declare function getSessionRole(env?: NodeJS.ProcessEnv): SessionRole;
 /** True iff this process is a worker session (lane-bound or explicitly declared). */
 export declare function isWorkerSession(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Tools a worker session may never activate: the orchestration/self-adaptation surface that would
- * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or
- * shell out to the unbounded `python` execution contract. `python` is load-bearing for the
- * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is
+ * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate
+ * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.
+ * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter
+ * can reach); `context_scout` is
  * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it
  * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same
  * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.

package/dist/core/session-role.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-role.d.ts","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAI5C,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CAIhF;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAYrD,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\n\nconst PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or\n * shell out to the unbounded `python` execution contract. `python` is load-bearing for the\n * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}
+{"version":3,"file":"session-role.d.ts","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC5C,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,mBAAmB,CAEjF;AAED,kGAAkG;AAClG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAM5G;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CAKhF;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAcrD,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),\n * - a valid `PI_PARENT_PID` declares this process as a managed child, or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getParentPid } from \"./process-identity.ts\";\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\nexport type TerminalSessionMode = \"user\" | \"worker\";\n\nexport const PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\nexport function isTerminalSessionMode(value: string): value is TerminalSessionMode {\n\treturn value === \"user\" || value === \"worker\";\n}\n\n/** Apply the terminal audience declaration without bypassing worker inference or UAC ceilings. */\nexport function setTerminalSessionMode(mode: TerminalSessionMode, env: NodeJS.ProcessEnv = process.env): void {\n\tif (mode === \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"worker\";\n\t} else if (env[PI_SESSION_ROLE_ENV] !== \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"main\";\n\t}\n}\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getParentPid(env) !== undefined) return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate\n * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.\n * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter\n * can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"ask_question\",\n\t\"secret_store\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}

package/dist/core/session-role.js

@@ -5,7 +5,8 @@
  * tool's worker scoping, and the read-only store options threaded through the persistence layer).
  *
  * A session is a worker iff EITHER:
- * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or
+ * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),
+ * - a valid `PI_PARENT_PID` declares this process as a managed child, or
  * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a
  *   lane-bound session is a worker by construction, regardless of how it was launched.
  *
@@ -13,12 +14,27 @@
  * There is no environment value a lane-bound process can set to shed the worker ceiling — the env
  * var is additive evidence for "worker", never a downgrade signal.
  */
+import { getParentPid } from "./process-identity.js";
 import { getBoundWorktreeLaneKey } from "./worktree-sync/runtime.js";
-const PI_SESSION_ROLE_ENV = "PI_SESSION_ROLE";
+export const PI_SESSION_ROLE_ENV = "PI_SESSION_ROLE";
+export function isTerminalSessionMode(value) {
+    return value === "user" || value === "worker";
+}
+/** Apply the terminal audience declaration without bypassing worker inference or UAC ceilings. */
+export function setTerminalSessionMode(mode, env = process.env) {
+    if (mode === "worker") {
+        env[PI_SESSION_ROLE_ENV] = "worker";
+    }
+    else if (env[PI_SESSION_ROLE_ENV] !== "worker") {
+        env[PI_SESSION_ROLE_ENV] = "main";
+    }
+}
 /** Derive this process's session role from the environment (env-injectable for tests). */
 export function getSessionRole(env = process.env) {
     if (env[PI_SESSION_ROLE_ENV] === "worker")
         return "worker";
+    if (getParentPid(env) !== undefined)
+        return "worker";
     if (getBoundWorktreeLaneKey(env) !== undefined)
         return "worker";
     return "main";
@@ -29,15 +45,18 @@ export function isWorkerSession(env = process.env) {
 }
 /**
  * Tools a worker session may never activate: the orchestration/self-adaptation surface that would
- * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or
- * shell out to the unbounded `python` execution contract. `python` is load-bearing for the
- * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is
+ * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate
+ * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.
+ * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter
+ * can reach); `context_scout` is
  * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it
  * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same
  * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.
  */
 export const WORKER_FORBIDDEN_TOOLS = new Set([
     "goal",
+    "ask_question",
+    "secret_store",
     "delegate",
     "delegate_status",
     "improvement_loop",

package/dist/core/session-role.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-role.js","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAIrE,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAE9C,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAe;IACjF,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChE,OAAO,MAAM,CAAC;AAAA,CACd;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAW;IAC9E,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AAAA,CACxC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAClE,MAAM;IACN,UAAU;IACV,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,QAAQ;CACR,CAAC,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\n\nconst PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or\n * shell out to the unbounded `python` execution contract. `python` is load-bearing for the\n * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}
+{"version":3,"file":"session-role.js","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAKrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAgC;IAClF,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ,CAAC;AAAA,CAC9C;AAED,kGAAkG;AAClG,MAAM,UAAU,sBAAsB,CAAC,IAAyB,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAQ;IAC7G,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvB,GAAG,CAAC,mBAAmB,CAAC,GAAG,QAAQ,CAAC;IACrC,CAAC;SAAM,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ,EAAE,CAAC;QAClD,GAAG,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC;IACnC,CAAC;AAAA,CACD;AAED,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAe;IACjF,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrD,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChE,OAAO,MAAM,CAAC;AAAA,CACd;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAW;IAC9E,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AAAA,CACxC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAClE,MAAM;IACN,cAAc;IACd,cAAc;IACd,UAAU;IACV,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,QAAQ;CACR,CAAC,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),\n * - a valid `PI_PARENT_PID` declares this process as a managed child, or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getParentPid } from \"./process-identity.ts\";\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\nexport type TerminalSessionMode = \"user\" | \"worker\";\n\nexport const PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\nexport function isTerminalSessionMode(value: string): value is TerminalSessionMode {\n\treturn value === \"user\" || value === \"worker\";\n}\n\n/** Apply the terminal audience declaration without bypassing worker inference or UAC ceilings. */\nexport function setTerminalSessionMode(mode: TerminalSessionMode, env: NodeJS.ProcessEnv = process.env): void {\n\tif (mode === \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"worker\";\n\t} else if (env[PI_SESSION_ROLE_ENV] !== \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"main\";\n\t}\n}\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getParentPid(env) !== undefined) return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate\n * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.\n * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter\n * can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"ask_question\",\n\t\"secret_store\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}

package/dist/core/session-snapshot.d.ts

@@ -0,0 +1,34 @@
+import type { SessionEntry, SessionManager } from "@caupulican/pi-agent-core/node";
+export type SessionSnapshotPayload<ValueKey extends string, Value extends object> = {
+    version: 1;
+} & {
+    [Key in ValueKey]: Value;
+};
+export interface SessionSnapshotCodec<Value extends object, ValueKey extends string> {
+    customType: string;
+    valueKey: ValueKey;
+    isValue(value: unknown): value is Value;
+    clone(value: Value): Value;
+}
+export interface SessionBranchEntrySource {
+    getBranch?: () => readonly SessionEntry[];
+    getEntries?: () => readonly SessionEntry[];
+}
+type VersionOneSnapshotPayload = Record<string, unknown> & {
+    version: 1;
+};
+/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */
+export declare function getActiveSessionBranchEntries(source: SessionBranchEntrySource): readonly SessionEntry[];
+export declare function isVersionOneSessionSnapshotPayload(data: unknown): data is VersionOneSnapshotPayload;
+export declare function createSessionSnapshotPayload<Value extends object, ValueKey extends string>(codec: SessionSnapshotCodec<Value, ValueKey>, value: Value): SessionSnapshotPayload<ValueKey, Value>;
+export declare function appendSessionSnapshot<Value extends object, ValueKey extends string>(sessionManager: Pick<SessionManager, "appendCustomEntry">, codec: SessionSnapshotCodec<Value, ValueKey>, value: Value): string;
+export declare function decodeSessionSnapshotPayload<Value extends object, ValueKey extends string>(data: unknown, codec: SessionSnapshotCodec<Value, ValueKey>): Value | undefined;
+export declare function getSessionSnapshots<Value extends object, ValueKey extends string>(entries: readonly SessionEntry[], codec: SessionSnapshotCodec<Value, ValueKey>): Value[];
+export declare function getLatestSessionSnapshot<Value extends object, ValueKey extends string>(entries: readonly SessionEntry[], codec: SessionSnapshotCodec<Value, ValueKey>): Value | undefined;
+/**
+ * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while
+ * walking leaf to root so they cannot hide an older valid checkpoint.
+ */
+export declare function getLatestSessionSnapshotOnBranch<Value extends object, ValueKey extends string>(sessionManager: Pick<SessionManager, "getLatestCustomEntryOnBranch">, codec: SessionSnapshotCodec<Value, ValueKey>): Value | undefined;
+export {};
+//# sourceMappingURL=session-snapshot.d.ts.map

package/dist/core/session-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-snapshot.d.ts","sourceRoot":"","sources":["../../src/core/session-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGnF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,IAAI;IACnF,OAAO,EAAE,CAAC,CAAC;CACX,GAAG;KACF,GAAG,IAAI,QAAQ,GAAG,KAAK;CACxB,CAAC;AAEF,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAAC;IACxC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACxC,SAAS,CAAC,EAAE,MAAM,SAAS,YAAY,EAAE,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,KAAK,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE1E,2GAA2G;AAC3G,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,YAAY,EAAE,CAIvG;AAED,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,yBAAyB,CAEnG;AAED,wBAAgB,4BAA4B,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EACzF,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAC5C,KAAK,EAAE,KAAK,GACV,sBAAsB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAKzC;AAED,wBAAgB,qBAAqB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAClF,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAC5C,KAAK,EAAE,KAAK,GACV,MAAM,CAER;AAED,wBAAgB,4BAA4B,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EACzF,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,GAAG,SAAS,CAInB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAChF,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,EAAE,CAQT;AAED,wBAAgB,wBAAwB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EACrF,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,GAAG,SAAS,CAQnB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAC7F,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,8BAA8B,CAAC,EACpE,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,GAAG,SAAS,CAUnB","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport { isPlainRecord } from \"./util/value-guards.ts\";\n\nexport type SessionSnapshotPayload<ValueKey extends string, Value extends object> = {\n\tversion: 1;\n} & {\n\t[Key in ValueKey]: Value;\n};\n\nexport interface SessionSnapshotCodec<Value extends object, ValueKey extends string> {\n\tcustomType: string;\n\tvalueKey: ValueKey;\n\tisValue(value: unknown): value is Value;\n\tclone(value: Value): Value;\n}\n\nexport interface SessionBranchEntrySource {\n\tgetBranch?: () => readonly SessionEntry[];\n\tgetEntries?: () => readonly SessionEntry[];\n}\n\ntype VersionOneSnapshotPayload = Record<string, unknown> & { version: 1 };\n\n/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */\nexport function getActiveSessionBranchEntries(source: SessionBranchEntrySource): readonly SessionEntry[] {\n\tif (typeof source.getBranch === \"function\") return source.getBranch();\n\tif (typeof source.getEntries === \"function\") return source.getEntries();\n\tthrow new TypeError(\"Session branch entry source exposes neither getBranch nor getEntries\");\n}\n\nexport function isVersionOneSessionSnapshotPayload(data: unknown): data is VersionOneSnapshotPayload {\n\treturn isPlainRecord(data) && data.version === 1;\n}\n\nexport function createSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): SessionSnapshotPayload<ValueKey, Value> {\n\treturn {\n\t\tversion: 1,\n\t\t[codec.valueKey]: codec.clone(value),\n\t} as SessionSnapshotPayload<ValueKey, Value>;\n}\n\nexport function appendSessionSnapshot<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): string {\n\treturn sessionManager.appendCustomEntry(codec.customType, createSessionSnapshotPayload(codec, value));\n}\n\nexport function decodeSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tdata: unknown,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tif (!isVersionOneSessionSnapshotPayload(data)) return undefined;\n\tconst value = data[codec.valueKey];\n\treturn codec.isValue(value) ? codec.clone(value) : undefined;\n}\n\nexport function getSessionSnapshots<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value[] {\n\tconst snapshots: Value[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) snapshots.push(snapshot);\n\t}\n\treturn snapshots;\n}\n\nexport function getLatestSessionSnapshot<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tfor (let index = entries.length - 1; index >= 0; index--) {\n\t\tconst entry = entries[index];\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t}\n\treturn undefined;\n}\n\n/**\n * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while\n * walking leaf to root so they cannot hide an older valid checkpoint.\n */\nexport function getLatestSessionSnapshotOnBranch<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"getLatestCustomEntryOnBranch\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tlet fromId: string | undefined;\n\tfor (;;) {\n\t\tconst entry = sessionManager.getLatestCustomEntryOnBranch(codec.customType, fromId);\n\t\tif (!entry) return undefined;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t\tif (entry.parentId === null) return undefined;\n\t\tfromId = entry.parentId;\n\t}\n}\n"]}

package/dist/core/session-snapshot.js

@@ -0,0 +1,68 @@
+import { isPlainRecord } from "./util/value-guards.js";
+/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */
+export function getActiveSessionBranchEntries(source) {
+    if (typeof source.getBranch === "function")
+        return source.getBranch();
+    if (typeof source.getEntries === "function")
+        return source.getEntries();
+    throw new TypeError("Session branch entry source exposes neither getBranch nor getEntries");
+}
+export function isVersionOneSessionSnapshotPayload(data) {
+    return isPlainRecord(data) && data.version === 1;
+}
+export function createSessionSnapshotPayload(codec, value) {
+    return {
+        version: 1,
+        [codec.valueKey]: codec.clone(value),
+    };
+}
+export function appendSessionSnapshot(sessionManager, codec, value) {
+    return sessionManager.appendCustomEntry(codec.customType, createSessionSnapshotPayload(codec, value));
+}
+export function decodeSessionSnapshotPayload(data, codec) {
+    if (!isVersionOneSessionSnapshotPayload(data))
+        return undefined;
+    const value = data[codec.valueKey];
+    return codec.isValue(value) ? codec.clone(value) : undefined;
+}
+export function getSessionSnapshots(entries, codec) {
+    const snapshots = [];
+    for (const entry of entries) {
+        if (entry.type !== "custom" || entry.customType !== codec.customType)
+            continue;
+        const snapshot = decodeSessionSnapshotPayload(entry.data, codec);
+        if (snapshot !== undefined)
+            snapshots.push(snapshot);
+    }
+    return snapshots;
+}
+export function getLatestSessionSnapshot(entries, codec) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type !== "custom" || entry.customType !== codec.customType)
+            continue;
+        const snapshot = decodeSessionSnapshotPayload(entry.data, codec);
+        if (snapshot !== undefined)
+            return snapshot;
+    }
+    return undefined;
+}
+/**
+ * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while
+ * walking leaf to root so they cannot hide an older valid checkpoint.
+ */
+export function getLatestSessionSnapshotOnBranch(sessionManager, codec) {
+    let fromId;
+    for (;;) {
+        const entry = sessionManager.getLatestCustomEntryOnBranch(codec.customType, fromId);
+        if (!entry)
+            return undefined;
+        const snapshot = decodeSessionSnapshotPayload(entry.data, codec);
+        if (snapshot !== undefined)
+            return snapshot;
+        if (entry.parentId === null)
+            return undefined;
+        fromId = entry.parentId;
+    }
+}
+//# sourceMappingURL=session-snapshot.js.map

package/dist/core/session-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-snapshot.js","sourceRoot":"","sources":["../../src/core/session-snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport { isPlainRecord } from \"./util/value-guards.ts\";\n\nexport type SessionSnapshotPayload<ValueKey extends string, Value extends object> = {\n\tversion: 1;\n} & {\n\t[Key in ValueKey]: Value;\n};\n\nexport interface SessionSnapshotCodec<Value extends object, ValueKey extends string> {\n\tcustomType: string;\n\tvalueKey: ValueKey;\n\tisValue(value: unknown): value is Value;\n\tclone(value: Value): Value;\n}\n\nexport interface SessionBranchEntrySource {\n\tgetBranch?: () => readonly SessionEntry[];\n\tgetEntries?: () => readonly SessionEntry[];\n}\n\ntype VersionOneSnapshotPayload = Record<string, unknown> & { version: 1 };\n\n/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */\nexport function getActiveSessionBranchEntries(source: SessionBranchEntrySource): readonly SessionEntry[] {\n\tif (typeof source.getBranch === \"function\") return source.getBranch();\n\tif (typeof source.getEntries === \"function\") return source.getEntries();\n\tthrow new TypeError(\"Session branch entry source exposes neither getBranch nor getEntries\");\n}\n\nexport function isVersionOneSessionSnapshotPayload(data: unknown): data is VersionOneSnapshotPayload {\n\treturn isPlainRecord(data) && data.version === 1;\n}\n\nexport function createSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): SessionSnapshotPayload<ValueKey, Value> {\n\treturn {\n\t\tversion: 1,\n\t\t[codec.valueKey]: codec.clone(value),\n\t} as SessionSnapshotPayload<ValueKey, Value>;\n}\n\nexport function appendSessionSnapshot<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): string {\n\treturn sessionManager.appendCustomEntry(codec.customType, createSessionSnapshotPayload(codec, value));\n}\n\nexport function decodeSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tdata: unknown,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tif (!isVersionOneSessionSnapshotPayload(data)) return undefined;\n\tconst value = data[codec.valueKey];\n\treturn codec.isValue(value) ? codec.clone(value) : undefined;\n}\n\nexport function getSessionSnapshots<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value[] {\n\tconst snapshots: Value[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) snapshots.push(snapshot);\n\t}\n\treturn snapshots;\n}\n\nexport function getLatestSessionSnapshot<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tfor (let index = entries.length - 1; index >= 0; index--) {\n\t\tconst entry = entries[index];\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t}\n\treturn undefined;\n}\n\n/**\n * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while\n * walking leaf to root so they cannot hide an older valid checkpoint.\n */\nexport function getLatestSessionSnapshotOnBranch<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"getLatestCustomEntryOnBranch\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tlet fromId: string | undefined;\n\tfor (;;) {\n\t\tconst entry = sessionManager.getLatestCustomEntryOnBranch(codec.customType, fromId);\n\t\tif (!entry) return undefined;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t\tif (entry.parentId === null) return undefined;\n\t\tfromId = entry.parentId;\n\t}\n}\n"]}

package/dist/core/session-supervision-runtime.d.ts

@@ -0,0 +1,31 @@
+import type { AgentSession } from "./agent-session.ts";
+import type { AgentSessionRuntimeResource } from "./agent-session-runtime.ts";
+import type { ResumablePayload } from "./process-matrix/codes.ts";
+import { type ResumeWorkerLaunchOutcome } from "./process-matrix/runtime.ts";
+export interface SessionSupervisionRuntimeOptions {
+    agentDir: string;
+    hasUI: boolean;
+    orchestrationProfileId?: string;
+    isProcessAlive: (pid: number) => boolean;
+    promptConfirm: (message: string) => Promise<boolean>;
+    resumeWorker: (payload: ResumablePayload, parentSessionId: string) => Promise<ResumeWorkerLaunchOutcome>;
+    onDiagnostic: (message: string) => void;
+    requestExit: (session: AgentSession) => void;
+}
+/**
+ * Owns the process-matrix and worktree-sync handles for the currently active session.
+ * Replacement stops the old generation before a new one is started, so no watcher can retain a
+ * disposed session or deliver a notice across a `/new`, `/resume`, or `/fork` boundary.
+ */
+export declare class SessionSupervisionRuntime implements AgentSessionRuntimeResource {
+    private readonly options;
+    private generation;
+    private processMatrix?;
+    private worktreeSync?;
+    constructor(options: SessionSupervisionRuntimeOptions);
+    start(session: AgentSession): Promise<void>;
+    stop(): Promise<void>;
+    private stopHandles;
+    private notify;
+}
+//# sourceMappingURL=session-supervision-runtime.d.ts.map

package/dist/core/session-supervision-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-supervision-runtime.d.ts","sourceRoot":"","sources":["../../src/core/session-supervision-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAIN,KAAK,yBAAyB,EAE9B,MAAM,6BAA6B,CAAC;AAIrC,MAAM,WAAW,gCAAgC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACzG,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,WAAW,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;CAC7C;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,2BAA2B;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,aAAa,CAAC,CAA6B;IACnD,OAAO,CAAC,YAAY,CAAC,CAA4B;IAEjD,YAAY,OAAO,EAAE,gCAAgC,EAEpD;IAEK,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhD;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG1B;YAEa,WAAW;YAQX,MAAM;CAYpB","sourcesContent":["import type { AgentSession } from \"./agent-session.ts\";\nimport type { AgentSessionRuntimeResource } from \"./agent-session-runtime.ts\";\nimport { createAgentIdentity } from \"./orchestration/agent-resume.ts\";\nimport type { ResumablePayload } from \"./process-matrix/codes.ts\";\nimport {\n\tgetOrchestrationAgentId,\n\tgetProcessTaskRef,\n\ttype ProcessMatrixRuntimeHandle,\n\ttype ResumeWorkerLaunchOutcome,\n\tstartProcessMatrixRuntime,\n} from \"./process-matrix/runtime.ts\";\nimport type { WorktreeSyncRuntimeHandle } from \"./worktree-sync/runtime.ts\";\nimport { getBoundWorktreeLaneKey, startWorktreeSyncRuntime } from \"./worktree-sync/runtime.ts\";\n\nexport interface SessionSupervisionRuntimeOptions {\n\tagentDir: string;\n\thasUI: boolean;\n\torchestrationProfileId?: string;\n\tisProcessAlive: (pid: number) => boolean;\n\tpromptConfirm: (message: string) => Promise<boolean>;\n\tresumeWorker: (payload: ResumablePayload, parentSessionId: string) => Promise<ResumeWorkerLaunchOutcome>;\n\tonDiagnostic: (message: string) => void;\n\trequestExit: (session: AgentSession) => void;\n}\n\n/**\n * Owns the process-matrix and worktree-sync handles for the currently active session.\n * Replacement stops the old generation before a new one is started, so no watcher can retain a\n * disposed session or deliver a notice across a `/new`, `/resume`, or `/fork` boundary.\n */\nexport class SessionSupervisionRuntime implements AgentSessionRuntimeResource {\n\tprivate readonly options: SessionSupervisionRuntimeOptions;\n\tprivate generation = 0;\n\tprivate processMatrix?: ProcessMatrixRuntimeHandle;\n\tprivate worktreeSync?: WorktreeSyncRuntimeHandle;\n\n\tconstructor(options: SessionSupervisionRuntimeOptions) {\n\t\tthis.options = options;\n\t}\n\n\tasync start(session: AgentSession): Promise<void> {\n\t\tconst generation = ++this.generation;\n\t\tawait this.stopHandles();\n\t\tconst sessionManager = session.sessionManager;\n\t\tconst sessionId = sessionManager.getSessionId();\n\t\tconst boundWorktreeLaneKey = getBoundWorktreeLaneKey();\n\t\tconst orchestrationProfileId =\n\t\t\tthis.options.orchestrationProfileId ??\n\t\t\tsession.capabilityEnvelope?.profileId ??\n\t\t\tsession.settingsManager.getActiveOrchestrationProfile();\n\t\tconst sessionFile = sessionManager.getSessionFile();\n\t\tconst goal = session.getGoalStateSnapshot();\n\t\tconst taskRef = getProcessTaskRef() ?? goal?.goalId;\n\t\tconst agent = createAgentIdentity(getOrchestrationAgentId() ?? sessionId, {\n\t\t\tprovider: \"pi\",\n\t\t\tsessionId,\n\t\t\tsessionDir: sessionManager.getSessionDir(),\n\t\t\t...(sessionFile ? { sessionFile } : {}),\n\t\t\tcwd: sessionManager.getCwd(),\n\t\t\t...(boundWorktreeLaneKey ? { worktreeLaneKey: boundWorktreeLaneKey } : {}),\n\t\t\t...(orchestrationProfileId ? { orchestrationProfileId } : {}),\n\t\t\tresourceProfileNames: session.settingsManager.getActiveResourceProfileNames(),\n\t\t\t...(session.model ? { modelRef: `${session.model.provider}/${session.model.id}` } : {}),\n\t\t\tcontextPointers: [],\n\t\t});\n\n\t\tconst [worktreeSync, processMatrix] = await Promise.all([\n\t\t\tstartWorktreeSyncRuntime({\n\t\t\t\tcwd: sessionManager.getCwd(),\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tsettingsManager: session.settingsManager,\n\t\t\t\tsessionId,\n\t\t\t\tnotify: (text) => {\n\t\t\t\t\tvoid this.notify(session, \"worktree-sync-notice\", text).catch(() => {});\n\t\t\t\t},\n\t\t\t\tonDiagnostic: this.options.onDiagnostic,\n\t\t\t}),\n\t\t\tstartProcessMatrixRuntime({\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tagent,\n\t\t\t\t...(taskRef ? { taskRef } : {}),\n\t\t\t\ttaskSummary: goal?.userGoal,\n\t\t\t\tallowAutomaticRecovery: goal === undefined || goal.status === \"active\",\n\t\t\t\tresumeWorker: (payload) => this.options.resumeWorker(payload, sessionId),\n\t\t\t\thasUI: this.options.hasUI,\n\t\t\t\tsettings: session.settingsManager.getProcessMatrixSettings(),\n\t\t\t\tisProcessAlive: this.options.isProcessAlive,\n\t\t\t\tpromptConfirm: this.options.promptConfirm,\n\t\t\t\tnotify: (text) => this.notify(session, \"process-matrix-notice\", text),\n\t\t\t\tonDiagnostic: this.options.onDiagnostic,\n\t\t\t\trequestExit: () => this.options.requestExit(session),\n\t\t\t}),\n\t\t]);\n\n\t\tif (generation !== this.generation) {\n\t\t\tawait Promise.all([worktreeSync.stop(), processMatrix.stop()]);\n\t\t\treturn;\n\t\t}\n\t\tthis.worktreeSync = worktreeSync;\n\t\tthis.processMatrix = processMatrix;\n\t}\n\n\tasync stop(): Promise<void> {\n\t\tthis.generation++;\n\t\tawait this.stopHandles();\n\t}\n\n\tprivate async stopHandles(): Promise<void> {\n\t\tconst worktreeSync = this.worktreeSync;\n\t\tconst processMatrix = this.processMatrix;\n\t\tthis.worktreeSync = undefined;\n\t\tthis.processMatrix = undefined;\n\t\tawait Promise.all([worktreeSync?.stop(), processMatrix?.stop()]);\n\t}\n\n\tprivate async notify(session: AgentSession, customType: string, text: string): Promise<void> {\n\t\ttry {\n\t\t\tawait session.sendCustomMessage(\n\t\t\t\t{ customType, content: text, display: true },\n\t\t\t\t{ triggerTurn: true, deliverAs: \"steer\" },\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tthis.options.onDiagnostic(`${customType}: failed to notify session: ${message}`);\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n"]}

package/dist/core/session-supervision-runtime.js

@@ -0,0 +1,97 @@
+import { createAgentIdentity } from "./orchestration/agent-resume.js";
+import { getOrchestrationAgentId, getProcessTaskRef, startProcessMatrixRuntime, } from "./process-matrix/runtime.js";
+import { getBoundWorktreeLaneKey, startWorktreeSyncRuntime } from "./worktree-sync/runtime.js";
+/**
+ * Owns the process-matrix and worktree-sync handles for the currently active session.
+ * Replacement stops the old generation before a new one is started, so no watcher can retain a
+ * disposed session or deliver a notice across a `/new`, `/resume`, or `/fork` boundary.
+ */
+export class SessionSupervisionRuntime {
+    options;
+    generation = 0;
+    processMatrix;
+    worktreeSync;
+    constructor(options) {
+        this.options = options;
+    }
+    async start(session) {
+        const generation = ++this.generation;
+        await this.stopHandles();
+        const sessionManager = session.sessionManager;
+        const sessionId = sessionManager.getSessionId();
+        const boundWorktreeLaneKey = getBoundWorktreeLaneKey();
+        const orchestrationProfileId = this.options.orchestrationProfileId ??
+            session.capabilityEnvelope?.profileId ??
+            session.settingsManager.getActiveOrchestrationProfile();
+        const sessionFile = sessionManager.getSessionFile();
+        const goal = session.getGoalStateSnapshot();
+        const taskRef = getProcessTaskRef() ?? goal?.goalId;
+        const agent = createAgentIdentity(getOrchestrationAgentId() ?? sessionId, {
+            provider: "pi",
+            sessionId,
+            sessionDir: sessionManager.getSessionDir(),
+            ...(sessionFile ? { sessionFile } : {}),
+            cwd: sessionManager.getCwd(),
+            ...(boundWorktreeLaneKey ? { worktreeLaneKey: boundWorktreeLaneKey } : {}),
+            ...(orchestrationProfileId ? { orchestrationProfileId } : {}),
+            resourceProfileNames: session.settingsManager.getActiveResourceProfileNames(),
+            ...(session.model ? { modelRef: `${session.model.provider}/${session.model.id}` } : {}),
+            contextPointers: [],
+        });
+        const [worktreeSync, processMatrix] = await Promise.all([
+            startWorktreeSyncRuntime({
+                cwd: sessionManager.getCwd(),
+                agentDir: this.options.agentDir,
+                settingsManager: session.settingsManager,
+                sessionId,
+                notify: (text) => {
+                    void this.notify(session, "worktree-sync-notice", text).catch(() => { });
+                },
+                onDiagnostic: this.options.onDiagnostic,
+            }),
+            startProcessMatrixRuntime({
+                agentDir: this.options.agentDir,
+                agent,
+                ...(taskRef ? { taskRef } : {}),
+                taskSummary: goal?.userGoal,
+                allowAutomaticRecovery: goal === undefined || goal.status === "active",
+                resumeWorker: (payload) => this.options.resumeWorker(payload, sessionId),
+                hasUI: this.options.hasUI,
+                settings: session.settingsManager.getProcessMatrixSettings(),
+                isProcessAlive: this.options.isProcessAlive,
+                promptConfirm: this.options.promptConfirm,
+                notify: (text) => this.notify(session, "process-matrix-notice", text),
+                onDiagnostic: this.options.onDiagnostic,
+                requestExit: () => this.options.requestExit(session),
+            }),
+        ]);
+        if (generation !== this.generation) {
+            await Promise.all([worktreeSync.stop(), processMatrix.stop()]);
+            return;
+        }
+        this.worktreeSync = worktreeSync;
+        this.processMatrix = processMatrix;
+    }
+    async stop() {
+        this.generation++;
+        await this.stopHandles();
+    }
+    async stopHandles() {
+        const worktreeSync = this.worktreeSync;
+        const processMatrix = this.processMatrix;
+        this.worktreeSync = undefined;
+        this.processMatrix = undefined;
+        await Promise.all([worktreeSync?.stop(), processMatrix?.stop()]);
+    }
+    async notify(session, customType, text) {
+        try {
+            await session.sendCustomMessage({ customType, content: text, display: true }, { triggerTurn: true, deliverAs: "steer" });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.options.onDiagnostic(`${customType}: failed to notify session: ${message}`);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=session-supervision-runtime.js.map

package/dist/core/session-supervision-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-supervision-runtime.js","sourceRoot":"","sources":["../../src/core/session-supervision-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentSession } from \"./agent-session.ts\";\nimport type { AgentSessionRuntimeResource } from \"./agent-session-runtime.ts\";\nimport { createAgentIdentity } from \"./orchestration/agent-resume.ts\";\nimport type { ResumablePayload } from \"./process-matrix/codes.ts\";\nimport {\n\tgetOrchestrationAgentId,\n\tgetProcessTaskRef,\n\ttype ProcessMatrixRuntimeHandle,\n\ttype ResumeWorkerLaunchOutcome,\n\tstartProcessMatrixRuntime,\n} from \"./process-matrix/runtime.ts\";\nimport type { WorktreeSyncRuntimeHandle } from \"./worktree-sync/runtime.ts\";\nimport { getBoundWorktreeLaneKey, startWorktreeSyncRuntime } from \"./worktree-sync/runtime.ts\";\n\nexport interface SessionSupervisionRuntimeOptions {\n\tagentDir: string;\n\thasUI: boolean;\n\torchestrationProfileId?: string;\n\tisProcessAlive: (pid: number) => boolean;\n\tpromptConfirm: (message: string) => Promise<boolean>;\n\tresumeWorker: (payload: ResumablePayload, parentSessionId: string) => Promise<ResumeWorkerLaunchOutcome>;\n\tonDiagnostic: (message: string) => void;\n\trequestExit: (session: AgentSession) => void;\n}\n\n/**\n * Owns the process-matrix and worktree-sync handles for the currently active session.\n * Replacement stops the old generation before a new one is started, so no watcher can retain a\n * disposed session or deliver a notice across a `/new`, `/resume`, or `/fork` boundary.\n */\nexport class SessionSupervisionRuntime implements AgentSessionRuntimeResource {\n\tprivate readonly options: SessionSupervisionRuntimeOptions;\n\tprivate generation = 0;\n\tprivate processMatrix?: ProcessMatrixRuntimeHandle;\n\tprivate worktreeSync?: WorktreeSyncRuntimeHandle;\n\n\tconstructor(options: SessionSupervisionRuntimeOptions) {\n\t\tthis.options = options;\n\t}\n\n\tasync start(session: AgentSession): Promise<void> {\n\t\tconst generation = ++this.generation;\n\t\tawait this.stopHandles();\n\t\tconst sessionManager = session.sessionManager;\n\t\tconst sessionId = sessionManager.getSessionId();\n\t\tconst boundWorktreeLaneKey = getBoundWorktreeLaneKey();\n\t\tconst orchestrationProfileId =\n\t\t\tthis.options.orchestrationProfileId ??\n\t\t\tsession.capabilityEnvelope?.profileId ??\n\t\t\tsession.settingsManager.getActiveOrchestrationProfile();\n\t\tconst sessionFile = sessionManager.getSessionFile();\n\t\tconst goal = session.getGoalStateSnapshot();\n\t\tconst taskRef = getProcessTaskRef() ?? goal?.goalId;\n\t\tconst agent = createAgentIdentity(getOrchestrationAgentId() ?? sessionId, {\n\t\t\tprovider: \"pi\",\n\t\t\tsessionId,\n\t\t\tsessionDir: sessionManager.getSessionDir(),\n\t\t\t...(sessionFile ? { sessionFile } : {}),\n\t\t\tcwd: sessionManager.getCwd(),\n\t\t\t...(boundWorktreeLaneKey ? { worktreeLaneKey: boundWorktreeLaneKey } : {}),\n\t\t\t...(orchestrationProfileId ? { orchestrationProfileId } : {}),\n\t\t\tresourceProfileNames: session.settingsManager.getActiveResourceProfileNames(),\n\t\t\t...(session.model ? { modelRef: `${session.model.provider}/${session.model.id}` } : {}),\n\t\t\tcontextPointers: [],\n\t\t});\n\n\t\tconst [worktreeSync, processMatrix] = await Promise.all([\n\t\t\tstartWorktreeSyncRuntime({\n\t\t\t\tcwd: sessionManager.getCwd(),\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tsettingsManager: session.settingsManager,\n\t\t\t\tsessionId,\n\t\t\t\tnotify: (text) => {\n\t\t\t\t\tvoid this.notify(session, \"worktree-sync-notice\", text).catch(() => {});\n\t\t\t\t},\n\t\t\t\tonDiagnostic: this.options.onDiagnostic,\n\t\t\t}),\n\t\t\tstartProcessMatrixRuntime({\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tagent,\n\t\t\t\t...(taskRef ? { taskRef } : {}),\n\t\t\t\ttaskSummary: goal?.userGoal,\n\t\t\t\tallowAutomaticRecovery: goal === undefined || goal.status === \"active\",\n\t\t\t\tresumeWorker: (payload) => this.options.resumeWorker(payload, sessionId),\n\t\t\t\thasUI: this.options.hasUI,\n\t\t\t\tsettings: session.settingsManager.getProcessMatrixSettings(),\n\t\t\t\tisProcessAlive: this.options.isProcessAlive,\n\t\t\t\tpromptConfirm: this.options.promptConfirm,\n\t\t\t\tnotify: (text) => this.notify(session, \"process-matrix-notice\", text),\n\t\t\t\tonDiagnostic: this.options.onDiagnostic,\n\t\t\t\trequestExit: () => this.options.requestExit(session),\n\t\t\t}),\n\t\t]);\n\n\t\tif (generation !== this.generation) {\n\t\t\tawait Promise.all([worktreeSync.stop(), processMatrix.stop()]);\n\t\t\treturn;\n\t\t}\n\t\tthis.worktreeSync = worktreeSync;\n\t\tthis.processMatrix = processMatrix;\n\t}\n\n\tasync stop(): Promise<void> {\n\t\tthis.generation++;\n\t\tawait this.stopHandles();\n\t}\n\n\tprivate async stopHandles(): Promise<void> {\n\t\tconst worktreeSync = this.worktreeSync;\n\t\tconst processMatrix = this.processMatrix;\n\t\tthis.worktreeSync = undefined;\n\t\tthis.processMatrix = undefined;\n\t\tawait Promise.all([worktreeSync?.stop(), processMatrix?.stop()]);\n\t}\n\n\tprivate async notify(session: AgentSession, customType: string, text: string): Promise<void> {\n\t\ttry {\n\t\t\tawait session.sendCustomMessage(\n\t\t\t\t{ customType, content: text, display: true },\n\t\t\t\t{ triggerTurn: true, deliverAs: \"steer\" },\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tthis.options.onDiagnostic(`${customType}: failed to notify session: ${message}`);\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n"]}

package/dist/core/session-tree-navigator.d.ts

@@ -9,21 +9,19 @@
  */
 import type { Agent } from "@caupulican/pi-agent-core";
 import { type BranchSummaryEntry, type SessionManager } from "@caupulican/pi-agent-core/node";
-import type { Model } from "@caupulican/pi-ai";
+import type { Api, Model } from "@caupulican/pi-ai";
 import type { ExtensionRunner } from "./extensions/index.ts";
+import type { RequestAuth } from "./request-auth.ts";
 import type { SettingsManager } from "./settings-manager.ts";
 export interface SessionTreeNavigatorDeps {
     /** Session log — leaf/branch reads and writes go through this. */
     getSessionManager(): SessionManager;
     /** Current model — required to run the default branch summarizer. */
-    getModel(): Model<any> | undefined;
+    getModel(): Model<Api> | undefined;
     /** Extension runner — `session_before_tree`/`session_tree` hooks fire here. */
     getExtensionRunner(): ExtensionRunner;
     /** Resolve request auth for the summarizer call (session-owned, also used by compaction). */
-    getRequiredRequestAuth(model: Model<any>): Promise<{
-        apiKey: string;
-        headers?: Record<string, string>;
-    }>;
+    getRequiredRequestAuth(model: Model<Api>): Promise<RequestAuth>;
     /** Settings — branch-summary reserve tokens. */
     getSettingsManager(): SettingsManager;
     /** The underlying agent — the rebuilt message view is assigned to `agent.state.messages`. */

package/dist/core/session-tree-navigator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-tree-navigator.d.ts","sourceRoot":"","sources":["../../src/core/session-tree-navigator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACN,KAAK,kBAAkB,EAGvB,KAAK,cAAc,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAA4C,MAAM,uBAAuB,CAAC;AACvG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACxC,oEAAkE;IAClE,iBAAiB,IAAI,cAAc,CAAC;IACpC,uEAAqE;IACrE,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACnC,iFAA+E;IAC/E,kBAAkB,IAAI,eAAe,CAAC;IACtC,6FAA6F;IAC7F,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IACzG,kDAAgD;IAChD,kBAAkB,IAAI,eAAe,CAAC;IACtC,+FAA6F;IAC7F,QAAQ,IAAI,KAAK,CAAC;IAClB,uGAAuG;IACvG,qBAAqB,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;CACrE;AAED,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAEhD,YAAY,IAAI,EAAE,wBAAwB,EAEzC;IAED;;;;;;;;;;OAUG;IACG,YAAY,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/G,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAoL5G;IAED;;OAEG;IACH,yBAAyB,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAepE;IAED,OAAO,CAAC,uBAAuB;CAU/B","sourcesContent":["/**\n * Session-tree navigation (in-file branch switching + fork-selector reads).\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). `navigateTree` moves the leaf\n * to another node in the SAME session file (unlike fork(), which creates a new file), optionally\n * summarizing the abandoned branch via the model or an extension override. It owns no state: the\n * branch-summary abort controller stays on the session (also read by `isCompacting`) and is set/cleared\n * here through a dep so the session's abort/compacting surface is untouched.\n */\n\nimport type { Agent } from \"@caupulican/pi-agent-core\";\nimport {\n\ttype BranchSummaryEntry,\n\tcollectEntriesForBranchSummary,\n\tgenerateBranchSummary,\n\ttype SessionManager,\n} from \"@caupulican/pi-agent-core/node\";\nimport type { Model } from \"@caupulican/pi-ai\";\nimport type { ExtensionRunner, SessionBeforeTreeResult, TreePreparation } from \"./extensions/index.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\nexport interface SessionTreeNavigatorDeps {\n\t/** Session log — leaf/branch reads and writes go through this. */\n\tgetSessionManager(): SessionManager;\n\t/** Current model — required to run the default branch summarizer. */\n\tgetModel(): Model<any> | undefined;\n\t/** Extension runner — `session_before_tree`/`session_tree` hooks fire here. */\n\tgetExtensionRunner(): ExtensionRunner;\n\t/** Resolve request auth for the summarizer call (session-owned, also used by compaction). */\n\tgetRequiredRequestAuth(model: Model<any>): Promise<{ apiKey: string; headers?: Record<string, string> }>;\n\t/** Settings — branch-summary reserve tokens. */\n\tgetSettingsManager(): SettingsManager;\n\t/** The underlying agent — the rebuilt message view is assigned to `agent.state.messages`. */\n\tgetAgent(): Agent;\n\t/** Store/clear the in-flight branch-summary abort controller on the session (read by isCompacting). */\n\tsetBranchSummaryAbort(controller: AbortController | undefined): void;\n}\n\nexport class SessionTreeNavigator {\n\tprivate readonly deps: SessionTreeNavigatorDeps;\n\n\tconstructor(deps: SessionTreeNavigatorDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/**\n\t * Navigate to a different node in the session tree.\n\t * Unlike fork() which creates a new session file, this stays in the same file.\n\t *\n\t * @param targetId The entry ID to navigate to\n\t * @param options.summarize Whether user wants to summarize abandoned branch\n\t * @param options.customInstructions Custom instructions for summarizer\n\t * @param options.replaceInstructions If true, customInstructions replaces the default prompt\n\t * @param options.label Label to attach to the branch summary entry\n\t * @returns Result with editorText (if user message) and cancelled status\n\t */\n\tasync navigateTree(\n\t\ttargetId: string,\n\t\toptions: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string } = {},\n\t): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }> {\n\t\tconst sessionManager = this.deps.getSessionManager();\n\t\tconst extensionRunner = this.deps.getExtensionRunner();\n\t\tconst oldLeafId = sessionManager.getLeafId();\n\n\t\t// No-op if already at target\n\t\tif (targetId === oldLeafId) {\n\t\t\treturn { cancelled: false };\n\t\t}\n\n\t\t// Model required for summarization\n\t\tif (options.summarize && !this.deps.getModel()) {\n\t\t\tthrow new Error(\"No model available for summarization\");\n\t\t}\n\n\t\tconst targetEntry = sessionManager.getEntry(targetId);\n\t\tif (!targetEntry) {\n\t\t\tthrow new Error(`Entry ${targetId} not found`);\n\t\t}\n\n\t\t// Collect entries to summarize (from old leaf to common ancestor)\n\t\tconst { entries: entriesToSummarize, commonAncestorId } = collectEntriesForBranchSummary(\n\t\t\tsessionManager,\n\t\t\toldLeafId,\n\t\t\ttargetId,\n\t\t);\n\n\t\t// Prepare event data - mutable so extensions can override\n\t\tlet customInstructions = options.customInstructions;\n\t\tlet replaceInstructions = options.replaceInstructions;\n\t\tlet label = options.label;\n\n\t\tconst preparation: TreePreparation = {\n\t\t\ttargetId,\n\t\t\toldLeafId,\n\t\t\tcommonAncestorId,\n\t\t\tentriesToSummarize,\n\t\t\tuserWantsSummary: options.summarize ?? false,\n\t\t\tcustomInstructions,\n\t\t\treplaceInstructions,\n\t\t\tlabel,\n\t\t};\n\n\t\t// Set up abort controller for summarization\n\t\tconst branchSummaryAbort = new AbortController();\n\t\tthis.deps.setBranchSummaryAbort(branchSummaryAbort);\n\n\t\ttry {\n\t\t\tlet extensionSummary: { summary: string; details?: unknown } | undefined;\n\t\t\tlet fromExtension = false;\n\n\t\t\t// Emit session_before_tree event\n\t\t\tif (extensionRunner.hasHandlers(\"session_before_tree\")) {\n\t\t\t\tconst result = (await extensionRunner.emit({\n\t\t\t\t\ttype: \"session_before_tree\",\n\t\t\t\t\tpreparation,\n\t\t\t\t\tsignal: branchSummaryAbort.signal,\n\t\t\t\t})) as SessionBeforeTreeResult | undefined;\n\n\t\t\t\tif (result?.cancel) {\n\t\t\t\t\treturn { cancelled: true };\n\t\t\t\t}\n\n\t\t\t\tif (result?.summary && options.summarize) {\n\t\t\t\t\textensionSummary = result.summary;\n\t\t\t\t\tfromExtension = true;\n\t\t\t\t}\n\n\t\t\t\t// Allow extensions to override instructions and label\n\t\t\t\tif (result?.customInstructions !== undefined) {\n\t\t\t\t\tcustomInstructions = result.customInstructions;\n\t\t\t\t}\n\t\t\t\tif (result?.replaceInstructions !== undefined) {\n\t\t\t\t\treplaceInstructions = result.replaceInstructions;\n\t\t\t\t}\n\t\t\t\tif (result?.label !== undefined) {\n\t\t\t\t\tlabel = result.label;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Run default summarizer if needed\n\t\t\tlet summaryText: string | undefined;\n\t\t\tlet summaryDetails: unknown;\n\t\t\tif (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {\n\t\t\t\tconst model = this.deps.getModel()!;\n\t\t\t\tconst { apiKey, headers } = await this.deps.getRequiredRequestAuth(model);\n\t\t\t\tconst branchSummarySettings = this.deps.getSettingsManager().getBranchSummarySettings();\n\t\t\t\tconst result = await generateBranchSummary(entriesToSummarize, {\n\t\t\t\t\tmodel,\n\t\t\t\t\tapiKey,\n\t\t\t\t\theaders,\n\t\t\t\t\tsignal: branchSummaryAbort.signal,\n\t\t\t\t\tcustomInstructions,\n\t\t\t\t\treplaceInstructions,\n\t\t\t\t\treserveTokens: branchSummarySettings.reserveTokens,\n\t\t\t\t\tstreamFn: this.deps.getAgent().streamFn,\n\t\t\t\t});\n\t\t\t\tif (result.aborted) {\n\t\t\t\t\treturn { cancelled: true, aborted: true };\n\t\t\t\t}\n\t\t\t\tif (result.error) {\n\t\t\t\t\tthrow new Error(result.error);\n\t\t\t\t}\n\t\t\t\tsummaryText = result.summary;\n\t\t\t\tsummaryDetails = {\n\t\t\t\t\treadFiles: result.readFiles || [],\n\t\t\t\t\tmodifiedFiles: result.modifiedFiles || [],\n\t\t\t\t};\n\t\t\t} else if (extensionSummary) {\n\t\t\t\tsummaryText = extensionSummary.summary;\n\t\t\t\tsummaryDetails = extensionSummary.details;\n\t\t\t}\n\n\t\t\t// Determine the new leaf position based on target type\n\t\t\tlet newLeafId: string | null;\n\t\t\tlet editorText: string | undefined;\n\n\t\t\tif (targetEntry.type === \"message\" && targetEntry.message.role === \"user\") {\n\t\t\t\t// User message: leaf = parent (null if root), text goes to editor\n\t\t\t\tnewLeafId = targetEntry.parentId;\n\t\t\t\teditorText = this._extractUserMessageText(targetEntry.message.content);\n\t\t\t} else if (targetEntry.type === \"custom_message\") {\n\t\t\t\t// Custom message: leaf = parent (null if root), text goes to editor\n\t\t\t\tnewLeafId = targetEntry.parentId;\n\t\t\t\teditorText =\n\t\t\t\t\ttypeof targetEntry.content === \"string\"\n\t\t\t\t\t\t? targetEntry.content\n\t\t\t\t\t\t: targetEntry.content\n\t\t\t\t\t\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t\t\t\t\t\t.map((c) => c.text)\n\t\t\t\t\t\t\t\t.join(\"\");\n\t\t\t} else {\n\t\t\t\t// Non-user message: leaf = selected node\n\t\t\t\tnewLeafId = targetId;\n\t\t\t}\n\n\t\t\t// Switch leaf (with or without summary)\n\t\t\t// Summary is attached at the navigation target position (newLeafId), not the old branch\n\t\t\tlet summaryEntry: BranchSummaryEntry | undefined;\n\t\t\tif (summaryText) {\n\t\t\t\t// Create summary at target position (can be null for root)\n\t\t\t\tconst summaryId = sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension);\n\t\t\t\tsummaryEntry = sessionManager.getEntry(summaryId) as BranchSummaryEntry;\n\n\t\t\t\t// Attach label to the summary entry\n\t\t\t\tif (label) {\n\t\t\t\t\tsessionManager.appendLabelChange(summaryId, label);\n\t\t\t\t}\n\t\t\t} else if (newLeafId === null) {\n\t\t\t\t// No summary, navigating to root - reset leaf\n\t\t\t\tsessionManager.resetLeaf();\n\t\t\t} else {\n\t\t\t\t// No summary, navigating to non-root\n\t\t\t\tsessionManager.branch(newLeafId);\n\t\t\t}\n\n\t\t\t// Attach label to target entry when not summarizing (no summary entry to label)\n\t\t\tif (label && !summaryText) {\n\t\t\t\tsessionManager.appendLabelChange(targetId, label);\n\t\t\t}\n\n\t\t\t// Update agent state\n\t\t\tconst sessionContext = sessionManager.buildSessionContext();\n\t\t\tthis.deps.getAgent().state.messages = sessionContext.messages;\n\n\t\t\t// Emit session_tree event\n\t\t\tawait extensionRunner.emit({\n\t\t\t\ttype: \"session_tree\",\n\t\t\t\tnewLeafId: sessionManager.getLeafId(),\n\t\t\t\toldLeafId,\n\t\t\t\tsummaryEntry,\n\t\t\t\tfromExtension: summaryText ? fromExtension : undefined,\n\t\t\t});\n\n\t\t\t// Emit to custom tools\n\n\t\t\treturn { editorText, cancelled: false, summaryEntry };\n\t\t} finally {\n\t\t\tthis.deps.setBranchSummaryAbort(undefined);\n\t\t}\n\t}\n\n\t/**\n\t * Get all user messages from session for fork selector.\n\t */\n\tgetUserMessagesForForking(): Array<{ entryId: string; text: string }> {\n\t\tconst entries = this.deps.getSessionManager().getEntries();\n\t\tconst result: Array<{ entryId: string; text: string }> = [];\n\n\t\tfor (const entry of entries) {\n\t\t\tif (entry.type !== \"message\") continue;\n\t\t\tif (entry.message.role !== \"user\") continue;\n\n\t\t\tconst text = this._extractUserMessageText(entry.message.content);\n\t\t\tif (text) {\n\t\t\t\tresult.push({ entryId: entry.id, text });\n\t\t\t}\n\t\t}\n\n\t\treturn result;\n\t}\n\n\tprivate _extractUserMessageText(content: string | Array<{ type: string; text?: string }>): string {\n\t\tif (typeof content === \"string\") return content;\n\t\tif (Array.isArray(content)) {\n\t\t\treturn content\n\t\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t\t.map((c) => c.text)\n\t\t\t\t.join(\"\");\n\t\t}\n\t\treturn \"\";\n\t}\n}\n"]}
+{"version":3,"file":"session-tree-navigator.d.ts","sourceRoot":"","sources":["../../src/core/session-tree-navigator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACN,KAAK,kBAAkB,EAGvB,KAAK,cAAc,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAS,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAA4C,MAAM,uBAAuB,CAAC;AACvG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACxC,oEAAkE;IAClE,iBAAiB,IAAI,cAAc,CAAC;IACpC,uEAAqE;IACrE,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACnC,iFAA+E;IAC/E,kBAAkB,IAAI,eAAe,CAAC;IACtC,6FAA6F;IAC7F,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAChE,kDAAgD;IAChD,kBAAkB,IAAI,eAAe,CAAC;IACtC,+FAA6F;IAC7F,QAAQ,IAAI,KAAK,CAAC;IAClB,uGAAuG;IACvG,qBAAqB,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;CACrE;AAED,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAEhD,YAAY,IAAI,EAAE,wBAAwB,EAEzC;IAED;;;;;;;;;;OAUG;IACG,YAAY,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/G,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,kBAAkB,CAAA;KAAE,CAAC,CA6L5G;IAED;;OAEG;IACH,yBAAyB,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAepE;IAED,OAAO,CAAC,uBAAuB;CAU/B","sourcesContent":["/**\n * Session-tree navigation (in-file branch switching + fork-selector reads).\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). `navigateTree` moves the leaf\n * to another node in the SAME session file (unlike fork(), which creates a new file), optionally\n * summarizing the abandoned branch via the model or an extension override. It owns no state: the\n * branch-summary abort controller stays on the session (also read by `isCompacting`) and is set/cleared\n * here through a dep so the session's abort/compacting surface is untouched.\n */\n\nimport type { Agent } from \"@caupulican/pi-agent-core\";\nimport {\n\ttype BranchSummaryEntry,\n\tcollectEntriesForBranchSummary,\n\tgenerateBranchSummary,\n\ttype SessionManager,\n} from \"@caupulican/pi-agent-core/node\";\nimport type { Api, Model, Usage } from \"@caupulican/pi-ai\";\nimport type { ExtensionRunner, SessionBeforeTreeResult, TreePreparation } from \"./extensions/index.ts\";\nimport type { RequestAuth } from \"./request-auth.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\nexport interface SessionTreeNavigatorDeps {\n\t/** Session log — leaf/branch reads and writes go through this. */\n\tgetSessionManager(): SessionManager;\n\t/** Current model — required to run the default branch summarizer. */\n\tgetModel(): Model<Api> | undefined;\n\t/** Extension runner — `session_before_tree`/`session_tree` hooks fire here. */\n\tgetExtensionRunner(): ExtensionRunner;\n\t/** Resolve request auth for the summarizer call (session-owned, also used by compaction). */\n\tgetRequiredRequestAuth(model: Model<Api>): Promise<RequestAuth>;\n\t/** Settings — branch-summary reserve tokens. */\n\tgetSettingsManager(): SettingsManager;\n\t/** The underlying agent — the rebuilt message view is assigned to `agent.state.messages`. */\n\tgetAgent(): Agent;\n\t/** Store/clear the in-flight branch-summary abort controller on the session (read by isCompacting). */\n\tsetBranchSummaryAbort(controller: AbortController | undefined): void;\n}\n\nexport class SessionTreeNavigator {\n\tprivate readonly deps: SessionTreeNavigatorDeps;\n\n\tconstructor(deps: SessionTreeNavigatorDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/**\n\t * Navigate to a different node in the session tree.\n\t * Unlike fork() which creates a new session file, this stays in the same file.\n\t *\n\t * @param targetId The entry ID to navigate to\n\t * @param options.summarize Whether user wants to summarize abandoned branch\n\t * @param options.customInstructions Custom instructions for summarizer\n\t * @param options.replaceInstructions If true, customInstructions replaces the default prompt\n\t * @param options.label Label to attach to the branch summary entry\n\t * @returns Result with editorText (if user message) and cancelled status\n\t */\n\tasync navigateTree(\n\t\ttargetId: string,\n\t\toptions: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string } = {},\n\t): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }> {\n\t\tconst sessionManager = this.deps.getSessionManager();\n\t\tconst extensionRunner = this.deps.getExtensionRunner();\n\t\tconst oldLeafId = sessionManager.getLeafId();\n\n\t\t// No-op if already at target\n\t\tif (targetId === oldLeafId) {\n\t\t\treturn { cancelled: false };\n\t\t}\n\n\t\t// Model required for summarization\n\t\tif (options.summarize && !this.deps.getModel()) {\n\t\t\tthrow new Error(\"No model available for summarization\");\n\t\t}\n\n\t\tconst targetEntry = sessionManager.getEntry(targetId);\n\t\tif (!targetEntry) {\n\t\t\tthrow new Error(`Entry ${targetId} not found`);\n\t\t}\n\n\t\t// Collect entries to summarize (from old leaf to common ancestor)\n\t\tconst { entries: entriesToSummarize, commonAncestorId } = collectEntriesForBranchSummary(\n\t\t\tsessionManager,\n\t\t\toldLeafId,\n\t\t\ttargetId,\n\t\t);\n\n\t\t// Prepare event data - mutable so extensions can override\n\t\tlet customInstructions = options.customInstructions;\n\t\tlet replaceInstructions = options.replaceInstructions;\n\t\tlet label = options.label;\n\n\t\tconst preparation: TreePreparation = {\n\t\t\ttargetId,\n\t\t\toldLeafId,\n\t\t\tcommonAncestorId,\n\t\t\tentriesToSummarize,\n\t\t\tuserWantsSummary: options.summarize ?? false,\n\t\t\tcustomInstructions,\n\t\t\treplaceInstructions,\n\t\t\tlabel,\n\t\t};\n\n\t\t// Set up abort controller for summarization\n\t\tconst branchSummaryAbort = new AbortController();\n\t\tthis.deps.setBranchSummaryAbort(branchSummaryAbort);\n\n\t\ttry {\n\t\t\tlet extensionSummary: { summary: string; details?: unknown; usage?: Usage } | undefined;\n\t\t\tlet fromExtension = false;\n\n\t\t\t// Emit session_before_tree event\n\t\t\tif (extensionRunner.hasHandlers(\"session_before_tree\")) {\n\t\t\t\tconst result = (await extensionRunner.emit({\n\t\t\t\t\ttype: \"session_before_tree\",\n\t\t\t\t\tpreparation,\n\t\t\t\t\tsignal: branchSummaryAbort.signal,\n\t\t\t\t})) as SessionBeforeTreeResult | undefined;\n\n\t\t\t\tif (result?.cancel) {\n\t\t\t\t\treturn { cancelled: true };\n\t\t\t\t}\n\n\t\t\t\tif (result?.summary && options.summarize) {\n\t\t\t\t\textensionSummary = result.summary;\n\t\t\t\t\tfromExtension = true;\n\t\t\t\t}\n\n\t\t\t\t// Allow extensions to override instructions and label\n\t\t\t\tif (result?.customInstructions !== undefined) {\n\t\t\t\t\tcustomInstructions = result.customInstructions;\n\t\t\t\t}\n\t\t\t\tif (result?.replaceInstructions !== undefined) {\n\t\t\t\t\treplaceInstructions = result.replaceInstructions;\n\t\t\t\t}\n\t\t\t\tif (result?.label !== undefined) {\n\t\t\t\t\tlabel = result.label;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Run default summarizer if needed\n\t\t\tlet summaryText: string | undefined;\n\t\t\tlet summaryDetails: unknown;\n\t\t\tlet summaryUsage: Usage | undefined;\n\t\t\tif (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {\n\t\t\t\tconst model = this.deps.getModel()!;\n\t\t\t\tconst { apiKey, headers } = await this.deps.getRequiredRequestAuth(model);\n\t\t\t\tconst branchSummarySettings = this.deps.getSettingsManager().getBranchSummarySettings();\n\t\t\t\tconst result = await generateBranchSummary(entriesToSummarize, {\n\t\t\t\t\tmodel,\n\t\t\t\t\tapiKey,\n\t\t\t\t\theaders,\n\t\t\t\t\tsignal: branchSummaryAbort.signal,\n\t\t\t\t\tcustomInstructions,\n\t\t\t\t\treplaceInstructions,\n\t\t\t\t\treserveTokens: branchSummarySettings.reserveTokens,\n\t\t\t\t\tstreamFn: this.deps.getAgent().streamFn,\n\t\t\t\t});\n\t\t\t\tif (result.aborted) {\n\t\t\t\t\treturn { cancelled: true, aborted: true };\n\t\t\t\t}\n\t\t\t\tif (result.error) {\n\t\t\t\t\tthrow new Error(result.error);\n\t\t\t\t}\n\t\t\t\tsummaryText = result.summary;\n\t\t\t\tsummaryUsage = result.usage;\n\t\t\t\tsummaryDetails = {\n\t\t\t\t\treadFiles: result.readFiles || [],\n\t\t\t\t\tmodifiedFiles: result.modifiedFiles || [],\n\t\t\t\t};\n\t\t\t} else if (extensionSummary) {\n\t\t\t\tsummaryText = extensionSummary.summary;\n\t\t\t\tsummaryDetails = extensionSummary.details;\n\t\t\t\tsummaryUsage = extensionSummary.usage;\n\t\t\t}\n\n\t\t\t// Determine the new leaf position based on target type\n\t\t\tlet newLeafId: string | null;\n\t\t\tlet editorText: string | undefined;\n\n\t\t\tif (targetEntry.type === \"message\" && targetEntry.message.role === \"user\") {\n\t\t\t\t// User message: leaf = parent (null if root), text goes to editor\n\t\t\t\tnewLeafId = targetEntry.parentId;\n\t\t\t\teditorText = this._extractUserMessageText(targetEntry.message.content);\n\t\t\t} else if (targetEntry.type === \"custom_message\") {\n\t\t\t\t// Custom message: leaf = parent (null if root), text goes to editor\n\t\t\t\tnewLeafId = targetEntry.parentId;\n\t\t\t\teditorText =\n\t\t\t\t\ttypeof targetEntry.content === \"string\"\n\t\t\t\t\t\t? targetEntry.content\n\t\t\t\t\t\t: targetEntry.content\n\t\t\t\t\t\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t\t\t\t\t\t.map((c) => c.text)\n\t\t\t\t\t\t\t\t.join(\"\");\n\t\t\t} else {\n\t\t\t\t// Non-user message: leaf = selected node\n\t\t\t\tnewLeafId = targetId;\n\t\t\t}\n\n\t\t\t// Switch leaf (with or without summary)\n\t\t\t// Summary is attached at the navigation target position (newLeafId), not the old branch\n\t\t\tlet summaryEntry: BranchSummaryEntry | undefined;\n\t\t\tif (summaryText) {\n\t\t\t\t// Create summary at target position (can be null for root)\n\t\t\t\tconst summaryId = sessionManager.branchWithSummary(\n\t\t\t\t\tnewLeafId,\n\t\t\t\t\tsummaryText,\n\t\t\t\t\tsummaryDetails,\n\t\t\t\t\tfromExtension,\n\t\t\t\t\tsummaryUsage,\n\t\t\t\t);\n\t\t\t\tsummaryEntry = sessionManager.getEntry(summaryId) as BranchSummaryEntry;\n\n\t\t\t\t// Attach label to the summary entry\n\t\t\t\tif (label) {\n\t\t\t\t\tsessionManager.appendLabelChange(summaryId, label);\n\t\t\t\t}\n\t\t\t} else if (newLeafId === null) {\n\t\t\t\t// No summary, navigating to root - reset leaf\n\t\t\t\tsessionManager.resetLeaf();\n\t\t\t} else {\n\t\t\t\t// No summary, navigating to non-root\n\t\t\t\tsessionManager.branch(newLeafId);\n\t\t\t}\n\n\t\t\t// Attach label to target entry when not summarizing (no summary entry to label)\n\t\t\tif (label && !summaryText) {\n\t\t\t\tsessionManager.appendLabelChange(targetId, label);\n\t\t\t}\n\n\t\t\t// Update agent state\n\t\t\tconst sessionContext = sessionManager.buildSessionContext();\n\t\t\tthis.deps.getAgent().state.messages = sessionContext.messages;\n\n\t\t\t// Emit session_tree event\n\t\t\tawait extensionRunner.emit({\n\t\t\t\ttype: \"session_tree\",\n\t\t\t\tnewLeafId: sessionManager.getLeafId(),\n\t\t\t\toldLeafId,\n\t\t\t\tsummaryEntry,\n\t\t\t\tfromExtension: summaryText ? fromExtension : undefined,\n\t\t\t});\n\n\t\t\t// Emit to custom tools\n\n\t\t\treturn { editorText, cancelled: false, summaryEntry };\n\t\t} finally {\n\t\t\tthis.deps.setBranchSummaryAbort(undefined);\n\t\t}\n\t}\n\n\t/**\n\t * Get all user messages from session for fork selector.\n\t */\n\tgetUserMessagesForForking(): Array<{ entryId: string; text: string }> {\n\t\tconst entries = this.deps.getSessionManager().getEntries();\n\t\tconst result: Array<{ entryId: string; text: string }> = [];\n\n\t\tfor (const entry of entries) {\n\t\t\tif (entry.type !== \"message\") continue;\n\t\t\tif (entry.message.role !== \"user\") continue;\n\n\t\t\tconst text = this._extractUserMessageText(entry.message.content);\n\t\t\tif (text) {\n\t\t\t\tresult.push({ entryId: entry.id, text });\n\t\t\t}\n\t\t}\n\n\t\treturn result;\n\t}\n\n\tprivate _extractUserMessageText(content: string | Array<{ type: string; text?: string }>): string {\n\t\tif (typeof content === \"string\") return content;\n\t\tif (Array.isArray(content)) {\n\t\t\treturn content\n\t\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t\t.map((c) => c.text)\n\t\t\t\t.join(\"\");\n\t\t}\n\t\treturn \"\";\n\t}\n}\n"]}

package/dist/core/session-tree-navigator.js

@@ -90,6 +90,7 @@ export class SessionTreeNavigator {
             // Run default summarizer if needed
             let summaryText;
             let summaryDetails;
+            let summaryUsage;
             if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
                 const model = this.deps.getModel();
                 const { apiKey, headers } = await this.deps.getRequiredRequestAuth(model);
@@ -111,6 +112,7 @@ export class SessionTreeNavigator {
                     throw new Error(result.error);
                 }
                 summaryText = result.summary;
+                summaryUsage = result.usage;
                 summaryDetails = {
                     readFiles: result.readFiles || [],
                     modifiedFiles: result.modifiedFiles || [],
@@ -119,6 +121,7 @@ export class SessionTreeNavigator {
             else if (extensionSummary) {
                 summaryText = extensionSummary.summary;
                 summaryDetails = extensionSummary.details;
+                summaryUsage = extensionSummary.usage;
             }
             // Determine the new leaf position based on target type
             let newLeafId;
@@ -148,7 +151,7 @@ export class SessionTreeNavigator {
             let summaryEntry;
             if (summaryText) {
                 // Create summary at target position (can be null for root)
-                const summaryId = sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension);
+                const summaryId = sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension, summaryUsage);
                 summaryEntry = sessionManager.getEntry(summaryId);
                 // Attach label to the summary entry
                 if (label) {