@fastagent-sh/fastagent 0.16.0 → 0.16.2

package/dist/engines/pi/search-tools.js

@@ -8,7 +8,9 @@
 import { z } from "zod";
 import { log } from "../../log.js";
 import { defineTool, isDeferredTool, stripDeferredMarker } from "./tool.js";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own.
+ *  Typed on the MOUNTED tool, not the authored one: it inspects names and deferral and never executes,
+ *  so narrowing here would reject the very set it is handed (pi's defaults take the turn's context). */
 export function withSearchTool(tools) {
     if (!tools.some(isDeferredTool))
         return tools;

package/dist/engines/pi/session-builder.js

@@ -120,7 +120,7 @@ sessionManager) {
         const env = new NodeExecutionEnv({ cwd });
         const definition = await loadAgentDefinition(agentDir, { cwd, env });
         reportDefinitionWarnings(definition.collisions, definition.diagnostics);
-        const defaultNames = piDefaultTools(cwd).map((t) => t.name);
+        const defaultNames = piDefaultTools().map((t) => t.name);
         const customTools = tools.filter((t) => !defaultNames.includes(t.name));
         // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts
         // it). Each execute runs inside the turn context with the CURRENT session's activation bridge — the
@@ -141,7 +141,12 @@ sessionManager) {
                 // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
                 if (!bound)
                     throw new Error("tool executed before its session was built (lifecycle invariant broken)");
-                return turnContext.run({ cwd, sessionManager: bound.sessionManager, tools: bound.activation }, () => t.execute(id, params, signal));
+                return turnContext.run({ cwd, sessionManager: bound.sessionManager, tools: bound.activation }, 
+                // pi's per-turn TOOL context (5th parameter) is read only by its default coding tools, and
+                // those are filtered out of `customTools` above; fastagent's own take theirs from
+                // `turnContext` (AsyncLocalStorage). So this env exists to satisfy the shape, and it is the
+                // chat cwd's — the same root a default tool would have got, had one reached here.
+                () => t.execute(id, params, signal, undefined, { env }));
             },
         }));
         // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including

package/dist/engines/pi/session-control.d.ts

@@ -1,8 +1,9 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Models } from "@earendil-works/pi-ai";
 import { type SessionControl, type SessionEvent } from "../../session.ts";
 import type { Lease, SessionObserver } from "./invoke.ts";
-import { type PiHarnessFactory } from "./harness.ts";
-import type { PiSessionReader } from "./sessions.ts";
+import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
+import { type PiSessionReader } from "./sessions.ts";
 /** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
  *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
  *  has its buffer FROZEN at the cap (memory bounded — the actual goal: ≈10k small events ≈ a few
@@ -12,7 +13,7 @@ import type { PiSessionReader } from "./sessions.ts";
  *  permanently stalled one holds the frozen buffer until its TCP connection dies. Recovery either
  *  way is the standard reconnect+backfill, semantically lossless. */
 export declare const SUBSCRIBER_BUFFER_CAP = 10000;
-/** What boundary mutations (compact / set_model / set_thinking) need — the SAME instances the
+/** What boundary mutations (compact / set_model / set_thinking / navigate) need — the SAME instances the
  *  agent assembly uses: the lease (mutations must not race a run), the model registry (validation +
  *  allowedModels), and the harness factory (compaction is a model call). Writes go through the
  *  session the hub's reader opened — after an existence check, so the control plane never creates
@@ -21,6 +22,14 @@ export interface PiBoundaryWiring {
     lease: Lease;
     models: Models;
     harnessFactory: PiHarnessFactory;
+    /** The assembly's configured PAIR — what a session with no overrides runs on. One field because
+     *  model and thinking level are one setting: which levels exist is a property of the model, so a
+     *  wiring that could carry them apart could carry a pair no run uses. Must be what
+     *  {@link harnessFactory} was built with. */
+    defaults: {
+        model: AnyModel;
+        thinkingLevel: ThinkingLevel;
+    };
 }
 export interface CreatePiSessionControlOptions {
     /** Read-only access to the durable session repository (the same root the agent writes). */

package/dist/engines/pi/session-control.js

@@ -8,7 +8,7 @@
  * stays in the session repository (read via {@link PiSessionReader}), live truth in the events the
  * data plane emits, modulation in the controls the data plane registers.
  *
- * Boundary mutations (Phase 2b: compact/set_model/set_thinking) take the same lease as runs;
+ * Boundary mutations (Phase 2b: compact/set_model/set_thinking/navigate) take the same lease as runs;
  * without boundary wiring they are rejected before acceptance with `unsupported_capability` — a
  * client gating on `capabilities()` never sends them.
  */
@@ -16,8 +16,10 @@ import { DEFAULT_COMPACTION_SETTINGS, compact, prepareCompaction } from "@earend
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
 import { listModels } from "./config.js";
-import { SUMMARIZATION_RETRY_POLICY, THINKING_LEVELS, harnessSession, lastOverrideEntries, } from "./harness.js";
+import { SUMMARIZATION_RETRY_POLICY, harnessSession } from "./harness.js";
+import { THINKING_LEVELS, resolveSessionSettings } from "./session-settings.js";
 import { log } from "../../log.js";
+import { activePathEntries } from "./sessions.js";
 // ── Entry normalization (durable plane) ──────────────────────────────────────
 /** Concatenated plain text of a message's content blocks (the L0 rendering payload). A custom
  *  AgentMessage role may carry no `content` at all — that reads as empty, not a crash. */
@@ -73,6 +75,16 @@ function toSessionEntry(entry) {
     }
     return { ...base, kind: entry.type, data: {} };
 }
+/**
+ * THE invariant the client's rule rests on: everything `entries()` publishes is a legal `navigate`
+ * target. pi's `leaf` records are the exception — they journal a MOVE rather than mark a position
+ * (their parentId is the OLD leaf, nothing is ever chained onto them), so navigating to one would
+ * put the branch head off every conversation path. Withheld from the published plane and refused as
+ * a target THROUGH THIS ONE PREDICATE, so a second exclusion cannot make the two disagree.
+ */
+function isNavigable(entry) {
+    return entry.type !== "leaf";
+}
 // ── Live fan-out (events plane) ──────────────────────────────────────────────
 /** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
  *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
@@ -195,7 +207,12 @@ export function createPiSessionControl(options) {
                 followUp: true,
                 manualCompaction: !!b,
                 modelSelection: b ? { allowedModels: listModels(b.models) } : false,
-                thinkingLevel: b ? { allowedLevels: [...THINKING_LEVELS] } : false,
+                // Servable or not. WHICH levels is a property of the session's model, so it rides
+                // `state().availableThinkingLevels` — a list here could only answer for one model.
+                thinkingLevel: !!b,
+                // Gated on the boundary wiring for its LEASE, not its models: moving the leaf is a write,
+                // and a write that races a run would hang the next turn off a stale branch.
+                navigate: !!b,
                 toolProgress: true, // tool_progress IS delivered (replace-semantics snapshots)
                 usage: false,
             };
@@ -204,24 +221,33 @@ export function createPiSessionControl(options) {
             const run = active.get(session);
             const opened = await sessions.openIfExists(session);
             const leafEntryId = opened ? ((await opened.getLeafId()) ?? undefined) : undefined;
-            // The durable overrides (set_model / set_thinking), via the SAME walk the harness resolve
-            // uses (lastOverrideEntries) — one physical implementation, so the reporting surface and the
-            // execution surface can never disagree on which record is "the" override. Reported as
-            // recorded, even if the current registry lacks the model (state reports session truth; the
-            // harness resolve owns the execution fallback).
-            let model;
-            let thinkingLevel;
-            if (opened) {
-                const recorded = lastOverrideEntries((await opened.getEntries()));
-                if (recorded.model)
-                    model = `${recorded.model.provider}/${recorded.model.modelId}`;
-                thinkingLevel = recorded.thinkingLevel;
+            // What will RUN, not the raw record: a client steering a session needs the pair that executes.
+            // Without a boundary there is no model to resolve against, and the fields are absent.
+            // OBSERVATION IS TOTAL: an unreadable entry chain leaves the pair absent too (the same shape a
+            // control-less deployment answers with) rather than rejecting a read that has no error-code
+            // channel to explain itself. The fault is not swallowed — it surfaces where codes exist: the
+            // next invoke fails (the harness build walks the same chain) and a boundary dispatch answers
+            // `boundary_command_failed`. Here it is a server-side warn.
+            const b = boundary?.();
+            let settings;
+            if (opened && b) {
+                try {
+                    settings = resolveSessionSettings((await activePathEntries(opened)), b.models, b.defaults);
+                }
+                catch (error) {
+                    log.warn(`[fastagent] session ${session}: settings unreadable (entry chain): ${String(error)}`);
+                }
             }
             return {
                 status: run ? "running" : compacting.has(session) ? "compacting" : "idle",
                 ...(run ? { activeRunId: run.runId } : {}),
-                ...(model !== undefined ? { model } : {}),
-                ...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
+                ...(settings
+                    ? {
+                        model: `${settings.model.provider}/${settings.model.id}`,
+                        thinkingLevel: settings.thinkingLevel,
+                        availableThinkingLevels: settings.availableThinkingLevels,
+                    }
+                    : {}),
                 pending: run ? { ...run.pending } : { steering: 0, followUp: 0 },
                 ...(leafEntryId ? { leafEntryId } : {}),
             };
@@ -230,8 +256,12 @@ export function createPiSessionControl(options) {
             const opened = await sessions.openIfExists(session);
             if (!opened)
                 return { entries: [] };
-            const all = (await opened.getEntries()).map(toSessionEntry);
+            // LEAF FIRST, then the journal: `getEntries()` hands back a SNAPSHOT, so reading it first
+            // would race any concurrent append into a leaf the snapshot cannot contain — a live turn
+            // reading as a dangling head. This order makes the journal a superset of the leaf's chain,
+            // which is what lets the published head be trusted as one of the published entries.
             const leafEntryId = (await opened.getLeafId()) ?? undefined;
+            const all = (await opened.getEntries()).filter(isNavigable).map(toSessionEntry);
             let entries = all;
             if (opts?.since !== undefined) {
                 const idx = all.findIndex((e) => e.id === opts.since);
@@ -361,7 +391,8 @@ export function createPiSessionControl(options) {
                 }
                 case "compact":
                 case "set_model":
-                case "set_thinking": {
+                case "set_thinking":
+                case "navigate": {
                     const b = boundary?.();
                     if (!b) {
                         // No boundary wiring: rejected before acceptance; a capability-gating client never
@@ -376,7 +407,8 @@ export function createPiSessionControl(options) {
                         };
                     }
                     // Payload validation BEFORE the lease — an invalid value must not briefly block a run.
-                    /** The entry-append for set_model/set_thinking — undefined for compact (harness path). */
+                    /** The durable write for set_model/set_thinking/navigate — undefined for compact (harness
+                     *  path). Answers the event to emit. */
                     let apply;
                     if (command.type === "set_model") {
                         const slash = command.model.indexOf("/");
@@ -393,18 +425,26 @@ export function createPiSessionControl(options) {
                         }
                         apply = async (s) => {
                             await s.appendModelChange(model.provider, model.id);
-                            // The CANONICAL spec, same string the durable entry and state() report — the event
-                            // must not echo a client alias the other two surfaces would disagree with.
-                            return { type: "state_changed", timestamp: Date.now(), data: { model: `${model.provider}/${model.id}` } };
+                            // Both halves: a new model can change which level executes. Nothing is re-recorded to
+                            // make that true — the resolve reports it, so the preference survives a round trip.
+                            const settings = resolveSessionSettings((await activePathEntries(s)), b.models, b.defaults);
+                            return {
+                                type: "state_changed",
+                                timestamp: Date.now(),
+                                // The CANONICAL spec, same string the durable entry and state() report — the event
+                                // must not echo a client alias the other two surfaces would disagree with.
+                                data: { model: `${model.provider}/${model.id}`, thinkingLevel: settings.thinkingLevel },
+                            };
                         };
                     }
                     else if (command.type === "set_thinking") {
+                        // A payload that is not a level at all — invalid before any session question.
                         if (!THINKING_LEVELS.has(command.level)) {
                             return {
                                 ok: false,
                                 error: {
                                     code: INVALID_COMMAND_CODE,
-                                    message: `unknown thinking level "${command.level}" — capabilities().thinkingLevel lists the allowed values`,
+                                    message: `unknown thinking level "${command.level}" — state().availableThinkingLevels lists what this session accepts`,
                                     retryable: false,
                                 },
                             };
@@ -414,10 +454,54 @@ export function createPiSessionControl(options) {
                             return { type: "state_changed", timestamp: Date.now(), data: { thinkingLevel: command.level } };
                         };
                     }
+                    else if (command.type === "navigate") {
+                        apply = async (s) => {
+                            // A move to where the leaf already is writes nothing: pi journals a move as a `leaf`
+                            // record, so an idempotent re-dispatch (a client retry, a UI firing on every
+                            // selection) would otherwise grow the session by a record no plane publishes. The
+                            // EVENT is emitted either way — it reports the resulting position, not the fact that
+                            // a record was written, and a client that dispatched must not have to poll for it.
+                            if ((await s.getLeafId()) !== command.targetId)
+                                await s.moveTo(command.targetId);
+                            // moveTo's postcondition IS "targetId is the leaf" (it validates, then sets); a
+                            // failure throws and travels as boundary_command_failed, so a read-back could only
+                            // re-report what this line already knows. The SETTINGS ride along because a move can
+                            // change them — an override recorded on the branch just left stops applying, and a
+                            // client tracking model/level from the event stream would otherwise show what the
+                            // next turn will not use.
+                            // The move is already durable here, so a settings read that throws (the new path is
+                            // above a gap) must NOT turn into "nothing took effect": report the position without
+                            // the settings and let `state()`'s rejection be where the broken chain surfaces.
+                            let settings;
+                            try {
+                                settings = resolveSessionSettings((await activePathEntries(s)), b.models, b.defaults);
+                            }
+                            catch (error) {
+                                // Absent rather than stale: the session cannot RUN with an unreadable chain either
+                                // (the harness build walks the same path), so the next invoke fails visibly — this
+                                // event does not need to carry a second signal for it.
+                                log.warn(`[fastagent] session ${session}: leaf moved, settings unreadable: ${String(error)}`);
+                            }
+                            return {
+                                type: "state_changed",
+                                timestamp: Date.now(),
+                                data: {
+                                    leafEntryId: command.targetId,
+                                    ...(settings
+                                        ? {
+                                            model: `${settings.model.provider}/${settings.model.id}`,
+                                            thinkingLevel: settings.thinkingLevel,
+                                        }
+                                        : {}),
+                                },
+                            };
+                        };
+                    }
                     // Sessions are created by invoke, never here: a mutation on an unknown id is rejected,
                     // not minted into a ghost record. (Existence check before the lease — read-only; the
                     // WRITE handle is re-opened under the lease below, this one is discarded.)
-                    if (!(await sessions.openIfExists(session))) {
+                    const existing = await sessions.openIfExists(session);
+                    if (!existing) {
                         return {
                             ok: false,
                             error: {
@@ -427,6 +511,51 @@ export function createPiSessionControl(options) {
                             },
                         };
                     }
+                    if (command.type === "navigate") {
+                        // A target that cannot BE a leaf is a permanent payload error, not a session error — the
+                        // same disposition as an unknown model spec. Same predicate `entries()` publishes by, so
+                        // "everything published is navigable" holds by construction rather than by two literals
+                        // agreeing.
+                        const entry = await existing.getEntry(command.targetId);
+                        if (!entry || !isNavigable(entry)) {
+                            return {
+                                ok: false,
+                                error: {
+                                    code: INVALID_COMMAND_CODE,
+                                    message: entry
+                                        ? `entry "${command.targetId}" is a leaf-move record — entries() does not publish those, and they are not positions; navigate to the entry it points at`
+                                        : `entry "${command.targetId}" does not exist in session "${session}" — entries() lists the navigable ids`,
+                                    retryable: false,
+                                },
+                            };
+                        }
+                    }
+                    if (command.type === "set_thinking") {
+                        // The same set `state()` showed the client. Reject here rather than record a level the
+                        // run would not use. The read is guarded because `dispatch` must never REJECT — the
+                        // transport promises a SessionResult, so an unreadable chain has to arrive as a code.
+                        let resolved;
+                        try {
+                            resolved = resolveSessionSettings((await activePathEntries(existing)), b.models, b.defaults);
+                        }
+                        catch (error) {
+                            return {
+                                ok: false,
+                                error: { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(error), retryable: true },
+                            };
+                        }
+                        const { model, availableThinkingLevels } = resolved;
+                        if (!availableThinkingLevels.includes(command.level)) {
+                            return {
+                                ok: false,
+                                error: {
+                                    code: INVALID_COMMAND_CODE,
+                                    message: `thinking level "${command.level}" is not supported by ${model.provider}/${model.id} (allowed: ${availableThinkingLevels.join(", ")})`,
+                                    retryable: false,
+                                },
+                            };
+                        }
+                    }
                     // Boundary mutations are the control plane's only writers: same lease as every run — a
                     // mutation must never race one (design §9).
                     const release = b.lease.tryAcquire(session);
@@ -567,8 +696,8 @@ export function createPiSessionControl(options) {
                                 },
                             };
                         }
-                        // Unreachable by construction: only set_model/set_thinking reach this branch, and
-                        // both assign `apply` in validation. Throw rather than silently skip (fail visibly).
+                        // Unreachable by construction: only set_model/set_thinking/navigate reach this branch,
+                        // and all three assign `apply` in validation. Throw rather than silently skip (fail visibly).
                         if (!apply)
                             throw new Error("apply unset outside the compact branch (dispatch invariant broken)");
                         emitOwn(session, await apply(fresh));

package/dist/engines/pi/session-settings.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a session is SET TO, and what it may be set to. Model and thinking level are ONE setting —
+ * which levels exist is a property of the model — so they resolve together, here, and `state()`, the
+ * `set_thinking` gate and the fresh-harness resolve all read this rather than deriving their own.
+ *
+ * Read-only by design. The durable record may hold a level the current model cannot do; that record
+ * is the user's PREFERENCE, so resolving per read restores it when the session returns to a capable
+ * model. (It could not be made unrepresentable anyway: `model_change`/`thinking_level_change` are
+ * pi's entries, and pi appends them itself.)
+ */
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type Models } from "@earendil-works/pi-ai";
+import type { AnyModel } from "./harness.ts";
+export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
+/** The shape both override consumers walk — a session entry, structurally. */
+export interface OverrideEntryLike {
+    type: string;
+    provider?: string;
+    modelId?: string;
+    thinkingLevel?: string;
+}
+/** The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through
+ *  to an earlier record — which record is "the" override must not depend on who is asking. */
+export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    thinkingLevel?: string;
+};
+export interface SessionSettings {
+    model: AnyModel;
+    /** Already clamped to what {@link model} supports. */
+    thinkingLevel: ThinkingLevel;
+    /** What `set_thinking` accepts for this session. */
+    availableThinkingLevels: string[];
+    /** Recorded but not honored — only the execution path reports it (as a warn). */
+    dropped?: {
+        model?: string;
+        thinkingLevel?: {
+            recorded: string;
+            running: string;
+            known: boolean;
+        };
+    };
+}
+/** `defaults` is the assembly's configured pair — what a session with no overrides runs on. */
+export declare function resolveSessionSettings(entries: OverrideEntryLike[], models: Models, defaults: {
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel;
+}): SessionSettings;

package/dist/engines/pi/session-settings.js

@@ -0,0 +1,73 @@
+import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+/** Which strings are levels at all — the vocabulary. What a MODEL supports is
+ *  `getSupportedThinkingLevels`. The `satisfies` anchor keeps this exhaustive against pi's union: a
+ *  level pi adds becomes a type error here rather than a value `set_thinking` silently rejects. */
+const ALL_THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
+/** The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through
+ *  to an earlier record — which record is "the" override must not depend on who is asking. */
+export function lastOverrideEntries(entries) {
+    let model;
+    let modelSeen = false;
+    let thinkingLevel;
+    let thinkingSeen = false;
+    for (let i = entries.length - 1; i >= 0 && !(modelSeen && thinkingSeen); i--) {
+        const e = entries[i];
+        if (!modelSeen && e?.type === "model_change") {
+            modelSeen = true;
+            if (e.provider !== undefined && e.modelId !== undefined)
+                model = { provider: e.provider, modelId: e.modelId };
+        }
+        if (!thinkingSeen && e?.type === "thinking_level_change") {
+            thinkingSeen = true;
+            if (e.thinkingLevel !== undefined)
+                thinkingLevel = e.thinkingLevel;
+        }
+    }
+    return { model, thinkingLevel };
+}
+/** `defaults` is the assembly's configured pair — what a session with no overrides runs on. */
+export function resolveSessionSettings(entries, models, defaults) {
+    const recorded = lastOverrideEntries(entries);
+    const dropped = {};
+    // A registry change across deploys must not brick the conversation.
+    let model = defaults.model;
+    if (recorded.model) {
+        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
+        if (found)
+            model = found;
+        else
+            dropped.model = `${recorded.model.provider}/${recorded.model.modelId}`;
+    }
+    const availableThinkingLevels = getSupportedThinkingLevels(model);
+    let thinkingLevel = defaults.thinkingLevel;
+    if (recorded.thinkingLevel !== undefined) {
+        const level = recorded.thinkingLevel;
+        if (!THINKING_LEVELS.has(level)) {
+            dropped.thinkingLevel = { recorded: level, running: thinkingLevel, known: false };
+        }
+        else {
+            // pi's clamp takes the lowest supported level AT OR ABOVE the recorded one, falling back
+            // downward only when nothing is above: a gap resolves UPWARD and costs more, not less. Which is
+            // why `dropped` names both levels rather than reporting a substitution.
+            thinkingLevel = clampThinkingLevel(model, level);
+            if (thinkingLevel !== level) {
+                dropped.thinkingLevel = { recorded: level, running: thinkingLevel, known: true };
+            }
+        }
+    }
+    return {
+        model,
+        thinkingLevel,
+        availableThinkingLevels,
+        ...(dropped.model || dropped.thinkingLevel ? { dropped } : {}),
+    };
+}

package/dist/engines/pi/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { Session } from "@earendil-works/pi-agent-core";
+import type { Session, SessionTreeEntry } from "@earendil-works/pi-agent-core";
 /** What fastagent needs from a session backend: open-or-create by opaque id. */
 export interface PiSessionStore {
     openOrCreate(sessionId: string): Promise<Session>;
@@ -7,17 +7,31 @@ export interface PiSessionStore {
  * OPEN-EXISTING sibling of {@link PiSessionStore} (session-control.ts): an unknown session answers
  * `undefined`, never creates one — sessions are the data plane's monopoly. Two consumers:
  * - the OBSERVATION plane (`state()`/`entries()`), strictly read-only (design §16 invariant 4);
- * - the control plane's BOUNDARY writers (`set_model`/`set_thinking`), which append override
- *   records to the returned handle after an existence check, under the run lease.
+ * - the control plane's BOUNDARY writers (`set_model`/`set_thinking` append override records to the
+ *   returned handle; `navigate` moves its leaf) after an existence check, under the run lease.
  * `openIfExists` skips the open-time crash reconciliation (that appends repair entries — a write
- * the observation plane must not perform). The boundary writers are safe WITHOUT it only because
- * override records are not messages — they cannot create or interact with a dangling tool_use
- * pair. Writing MESSAGE-class records through this handle would bypass that repair: use
- * `openOrCreate` for anything that enters the transcript.
+ * the observation plane must not perform). The boundary writers are safe WITHOUT it for two
+ * different reasons: an override record is not a message, so it cannot create or pair with a
+ * dangling tool_use; a `navigate` writes no message either, but it CAN expose one — parking the
+ * leaf on an assistant entry whose tool results are now off-path is the dangling-pair state
+ * {@link reconcileInterruptedToolCalls} exists for. That is repaired at the next `openOrCreate`,
+ * which repairs AT THE LEAF — exactly where a move puts it.
+ *
+ * Writing MESSAGE-class records through this handle would bypass that repair: use `openOrCreate`
+ * for anything that enters the transcript.
  */
 export interface PiSessionReader {
     openIfExists(sessionId: string): Promise<Session | undefined>;
 }
+/**
+ * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
+ * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
+ * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
+ * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
+ * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
+ * recorded before a compaction is a preference, and it still governs the session after one.
+ */
+export declare function activePathEntries(session: Session): Promise<SessionTreeEntry[]>;
 /** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
 export declare function inMemorySessionStore(): PiSessionStore & PiSessionReader;
 /**

package/dist/engines/pi/sessions.js

@@ -88,6 +88,49 @@ async function reconcileInterruptedToolCalls(session) {
         await session.appendMessage(result);
     }
 }
+/**
+ * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
+ * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
+ * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
+ * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
+ * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
+ * recorded before a compaction is a preference, and it still governs the session after one.
+ */
+export async function activePathEntries(session) {
+    // LEAF FIRST, then the journal — the order is load-bearing, not incidental: `getEntries()` is a
+    // SNAPSHOT, so reading it first would let any concurrent append (i.e. any turn in progress) leave
+    // a leaf the snapshot cannot contain, and the integrity throw below would fire on a live session
+    // instead of a corrupt one. This way the snapshot is always a superset of the leaf's chain.
+    const leafId = await session.getLeafId();
+    const entries = await session.getEntries();
+    // A null leaf is pi's ROOT position (what `moveTo(null)` sets), so the active path is EMPTY — not
+    // "the whole journal", which on a branched session would mean every abandoned branch at once.
+    if (leafId === null)
+        return [];
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    // A chain that is not intact THROWS: any other disposition returns a short path that reads like a
+    // short session (every override and activation above the gap gone, the next turn silently on
+    // assembly defaults). pi's storages already reject a leaf outside the journal in `getLeafId()`,
+    // but the port is swappable — so the walk names it here rather than dying on `undefined.parentId`.
+    const start = byId.get(leafId);
+    if (!start)
+        throw new Error(`session leaf "${leafId}" is missing from the journal`);
+    const path = [];
+    for (let cur = start;;) {
+        path.push(cur);
+        // A path cannot be longer than the journal it walks; anything more is a parentId cycle, which
+        // would otherwise hang the turn with no `failed` event at all.
+        if (path.length > entries.length)
+            throw new Error(`session entry "${cur.id}" cycles through its parents`);
+        if (!cur.parentId)
+            break;
+        const parent = byId.get(cur.parentId);
+        if (!parent)
+            throw new Error(`session entry "${cur.parentId}" is missing from the journal (parent of "${cur.id}")`);
+        cur = parent;
+    }
+    return path.reverse(); // walked leaf→root; every consumer reads it root→leaf
+}
 /** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
 export function inMemorySessionStore() {
     const repo = new InMemorySessionRepo();

package/dist/engines/pi/tool.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { AgentHarnessTool, ExecutionToolContext, AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
 import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
@@ -34,6 +34,14 @@ export interface DefineToolOptions<I extends z.ZodType> {
     executionMode?: "sequential" | "parallel";
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
+/**
+ * A tool as MOUNTED: what the harness actually runs. Wider than the authored {@link AgentTool} on
+ * purpose — pi's default coding tools read the turn's tool context (its ExecutionEnv) as a fifth
+ * `execute` parameter, while fastagent's own tools take four and are assignable to it unchanged.
+ * Naming the wider type is what lets `defineTool` stay context-free for authors while both families
+ * live in one array; every helper that only inspects or reorders tools is typed on THIS.
+ */
+export type MountedTool = AgentHarnessTool<ExecutionToolContext>;
 /** An AgentTool with fastagent's deferral marker — the type for raw tools handed to fastagent
  *  (`config.tools`, L1/L2 `tools`): plain `AgentTool` has no `deferred`, so an object literal with the
  *  marker would fail excess-property checking against upstream's type. `defineTool` produces it. */
@@ -42,10 +50,10 @@ export type FastagentTool = AgentTool & {
 };
 /** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
  *  AgentTool object — pi ignores it). */
-export declare function isDeferredTool(tool: AgentTool): boolean;
+export declare function isDeferredTool(tool: MountedTool): boolean;
 /** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
  *  could never be activated and would strand every deferred tool). */
-export declare function stripDeferredMarker(tool: AgentTool): AgentTool;
+export declare function stripDeferredMarker(tool: MountedTool): MountedTool;
 export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): FastagentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
 export interface ToolCollision {
@@ -68,7 +76,7 @@ export declare function loadTools(dir: string): Promise<{
  * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
-export declare function mergeDiscoveredTools(existing: AgentTool[], discovered: AgentTool[]): {
-    tools: AgentTool[];
+export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {
+    tools: MountedTool[];
     collisions: ToolCollision[];
 };

package/dist/engines/pi/wake-tool.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type MountedTool } from "./tool.ts";
 /**
  * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"`
  * ("30m", "2h", "1d"). Undefined for anything else, INCLUDING a bare numeric string like "120": one
@@ -12,6 +12,6 @@ export declare function parseDelayMs(input: string | number): number | undefined
  * scheduler poller honors a wake-up) and only when the workspace hasn't defined its own `wake` (that
  * wins, like any tool collision). The single place the mount decision + collision rule run.
  */
-export declare function withWakeTool(tools: AgentTool[], stateRoot: string, enabled: boolean): AgentTool[];
+export declare function withWakeTool(tools: MountedTool[], stateRoot: string, enabled: boolean): MountedTool[];
 /** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
-export declare function makeWakeTool(stateRoot: string, now?: () => Date): AgentTool;
+export declare function makeWakeTool(stateRoot: string, now?: () => Date): MountedTool;