@fastagent-sh/fastagent 0.16.1 → 0.16.2

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/session.d.ts

@@ -21,12 +21,17 @@ export interface SessionControl {
     dispatch(session: string, command: SessionCommand): Promise<SessionResult>;
 }
 /**
- * Static support declaration, two kinds of flag:
- * - COMMAND GATES (`steering`, `followUp`, `manualCompaction`, `modelSelection`, `thinkingLevel`):
+ * STATIC support declaration — sessionless, so nothing here may depend on a session. Two kinds of flag:
+ * - COMMAND GATES (`steering`, `followUp`, `manualCompaction`, `modelSelection`, `thinkingLevel`,
+ *   `navigate`):
  *   clients MUST gate dispatch on them; an unsupported command is rejected before acceptance with
  *   {@link UNSUPPORTED_CAPABILITY_CODE}.
  * - OBSERVATION-QUALITY flags (`toolProgress`, `usage`): whether those events/state fields appear
  *   at all — nothing to dispatch, nothing to reject.
+ *
+ * `modelSelection` may carry a list because the registry is a deployment fact; thinking levels
+ * depend on the session's current model, so they live on {@link SessionState.availableThinkingLevels}.
+ *
  * `state`/`entries`/`events` are mandatory (the reconnect contract) and deliberately absent here.
  */
 export interface SessionCapabilities {
@@ -36,9 +41,15 @@ export interface SessionCapabilities {
     modelSelection: false | {
         allowedModels: string[];
     };
-    thinkingLevel: false | {
-        allowedLevels: string[];
-    };
+    /** Whether `set_thinking` is servable at all. WHICH levels is per-session — see
+     *  {@link SessionState.availableThinkingLevels}. */
+    thinkingLevel: boolean;
+    /** Whether `navigate` is servable at all — `false` both when the engine's sessions are linear and
+     *  when this deployment has no write path for them; either way the tree the contract publishes
+     *  (`SessionEntry.parentId` + `SessionEntries.leafEntryId`) is read-only here. Named after its COMMAND, unlike the older gates (`manualCompaction` gates
+     *  `compact`, `thinkingLevel` gates `set_thinking`): those already force a client to translate,
+     *  and a gate keyed by the command literal is the only naming a derived map could ever produce. */
+    navigate: boolean;
     toolProgress: boolean;
     usage: boolean;
 }
@@ -79,7 +90,7 @@ export declare const NOTHING_TO_COMPACT_CODE = "nothing_to_compact";
  *  command as-is fails again. (A run registered without modulation controls is a capability
  *  problem, not a run problem, and rejects with {@link UNSUPPORTED_CAPABILITY_CODE}.) */
 export declare const RUN_COMMAND_FAILED_CODE = "run_command_failed";
-/** Six commands; deliberately NO `prompt` — starting work is the data plane's definition. */
+/** Seven commands; deliberately NO `prompt` — starting work is the data plane's definition. */
 export type SessionCommand = {
     type: "steer";
     prompt: Prompt;
@@ -97,6 +108,14 @@ export type SessionCommand = {
 } | {
     type: "set_thinking";
     level: string;
+}
+/** Move the session's active leaf to `targetId`, an existing entry — the write verb for the tree
+ *  `entries()` already publishes (and how sibling branches come to exist: the next turn hangs off
+ *  the new leaf). Every entry `entries()` publishes is a legal target; a `targetId` that is not
+ *  one rejects `invalid_command`. A boundary mutation otherwise: same lease as a run. */
+ | {
+    type: "navigate";
+    targetId: string;
 };
 /**
  * Acceptance is not outcome: `ok: true` means admitted or applied, never that the run ultimately
@@ -125,10 +144,13 @@ export interface SessionState {
      *  compaction happens inside a run's activity window and reports as `running`. */
     status: "idle" | "running" | "compacting";
     activeRunId?: string;
-    /** The session's durable overrides (set_model / set_thinking), read from the record — so a
-     *  reconnecting client sees them without scanning entries. Absent = the assembly default. */
+    /** What this session will RUN with, not what was recorded: overrides resolved against the
+     *  deployment (a model the registry lost falls back to the configured one; a level the current
+     *  model cannot do is clamped). Absent where the implementation exposes no model control. */
     model?: string;
     thinkingLevel?: string;
+    /** What `set_thinking` accepts for THIS session — re-read after a `set_model`. */
+    availableThinkingLevels?: string[];
     pending: {
         steering: number;
         followUp: number;
@@ -222,10 +244,13 @@ export type QueueChangedEvent = SessionEvent<"queue_changed", {
     runId: string;
 };
 /** A boundary mutation changed durable session state (L2; no runId — boundary mutations happen
- *  between runs). */
+ *  between runs). `leafEntryId` reports a `navigate` — a deliberate move of the branch head, which
+ *  a second attached client would otherwise have no signal for. It is NOT a general leaf feed:
+ *  every turn advances the leaf too, and that is read from `entries()`/`state()` after the run. */
 export type StateChangedEvent = SessionEvent<"state_changed", {
     model?: string;
     thinkingLevel?: string;
+    leafEntryId?: string;
 }>;
 /** Manual compaction bounds (L2): every `compaction_started` is closed by exactly one
  *  `compaction_finished` — `summary` on success, `error` on failure, `aborted: true` on a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, Telegram, Slack, or behind any channel.",
   "keywords": [
     "agent",