@fastagent-sh/fastagent 0.18.0 → 0.20.0

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

@@ -0,0 +1,30 @@
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+/** What a Caller names when a new session should start from an existing one. */
+export interface SessionInheritance {
+    /** The session to inherit from. Missing or unreadable → start empty, with a warn: context is not
+     *  the ask, and losing it must not cost the turn. */
+    parentSession: string;
+    /** Opaque markers that MAY locate the branch point on the parent's active path (searched in
+     *  message content, first hit wins, most recent occurrence). No match → the parent's present. */
+    branchHints?: string[];
+}
+/**
+ * The branch point this inheritance should copy up to, and the parent's path — the decision half,
+ * shared by both backends because WHERE a thread branches is policy, not storage.
+ */
+export declare function inheritanceCut(parent: SessionManager, branchHints?: string[]): {
+    at: string;
+} | undefined;
+/**
+ * Copy the parent's path up to `at` into `child`, entry by entry — what a backend with no FILE to
+ * fork has to do instead. Kinds pi models as facts about an entry rather than positions (labels,
+ * the session name) are not copied: they describe the parent's record, not the thread's history.
+ *
+ * The COPY only. Bounding what the child's model sees is {@link markInheritanceWindow}, which only
+ * {@link copyBranchForInheritance} applies: a lifecycle fork that marked a window would hide the
+ * exact entries its user forked to keep.
+ */
+export declare function copyBranchInto(parent: SessionManager, child: SessionManager, at: string): void;
+/** {@link copyBranchInto} plus the inheritance window — what a new THREAD gets and a fork does not.
+ *  Both backends call THIS one, so neither can drift on where a child's context begins. */
+export declare function copyBranchForInheritance(parent: SessionManager, child: SessionManager, at: string): void;

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

@@ -0,0 +1,261 @@
+import { log } from "../../log.js";
+import { isPlaneMarker } from "./session-markers.js";
+/** Inheritance window: at most this many exchanges of the parent reach the child's model context. */
+const INHERIT_MAX_EXCHANGES = 50;
+/** …and at most roughly this many tokens (~1/4 of a 200K context: generous, not everything). Both
+ *  limits govern how far the window EXTENDS into older history — the newest exchange is a FLOOR,
+ *  kept whole even when it alone exceeds the budget: the mark's boundary is entry-granular, and an
+ *  inheritance that drops the exchange the thread branched off would be no inheritance at all. */
+const INHERIT_MAX_TOKENS = 50_000;
+/** Branch hints are IDS, not payloads: each one costs a scan over the parent's serialized path, and
+ *  the wire accepts arbitrary arrays — so the engine caps them where the cost lives. */
+const MAX_BRANCH_HINTS = 16;
+const MAX_BRANCH_HINT_CHARS = 128;
+/** A vision image is priced FLAT — what a provider bills for a resized image, roughly — because its
+ *  base64 length (~1M chars for a photo) measures storage, not context: pricing it by chars would
+ *  let one photo evict the whole text window. */
+const INHERIT_IMAGE_TOKENS = 1_600;
+function isUserMessage(entry) {
+    return entry?.type === "message" && entry.message?.role === "user";
+}
+/** Rough token estimate for windowing — text at chars/4, images flat. Precision is not the point:
+ *  the window is a budget, and being 20% off moves a boundary by an exchange, not correctness. */
+function estimateContentTokens(content) {
+    if (typeof content === "string")
+        return Math.ceil(content.length / 4);
+    if (!Array.isArray(content))
+        return 0;
+    let tokens = 0;
+    for (const block of content) {
+        if (block.type === "image")
+            tokens += INHERIT_IMAGE_TOKENS;
+        else if (typeof block.text === "string")
+            tokens += Math.ceil(block.text.length / 4);
+        else
+            tokens += Math.ceil(JSON.stringify(block).length / 4);
+    }
+    return tokens;
+}
+/** Both entry kinds pi projects into model context from a copied path: a `custom_message` is an
+ *  extension's injection INTO the conversation, so it charges the budget like any message. */
+function estimateEntryTokens(entry) {
+    if (entry.type === "message")
+        return estimateContentTokens(entry.message?.content);
+    if (entry.type === "custom_message")
+        return estimateContentTokens(entry.content);
+    return 0;
+}
+/** A compaction entry's summary AND its retained tail — the entries from `firstKeptEntryId` up to
+ *  the compaction — DO reach the model. They are the floor under every window that starts above the
+ *  compaction, so the budget must count them; the tail is read off the path, since pi-coding-agent's
+ *  SessionManager stores it as a POINTER and not as messages on the entry (0.84: `appendCompaction`
+ *  writes `firstKeptEntryId`, and both of AgentSession's compaction paths go through it).
+ *
+ *  pi-agent-core's harness writes the newer self-contained form instead — `retainedTail` on the entry,
+ *  no pointer. If pi-coding-agent adopts it the pointer stops resolving, and this function prices the
+ *  tail at zero while {@link copyBranchInto} drops it. Adopting it the way pi-agent-core did, by
+ *  REPLACING the pointer, fails to typecheck at `Entry.firstKeptEntryId` rather than running quietly;
+ *  a `retainedTail` added BESIDE the pointer would not, and is the case to watch on the next bump.
+ *  Either way this is the place to change — not a reason to read both shapes today. */
+function estimateCompactionTokens(path, compactionIdx) {
+    const compaction = path[compactionIdx];
+    if (compaction?.type !== "compaction")
+        return 0;
+    let tokens = Math.ceil((compaction.summary ?? "").length / 4);
+    const firstKept = path.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+    if (firstKept < 0)
+        return tokens; // an unresolvable pointer keeps nothing — pi's own reading
+    for (let i = firstKept; i < compactionIdx; i++) {
+        const entry = path[i];
+        if (entry)
+            tokens += estimateEntryTokens(entry);
+    }
+    return tokens;
+}
+/**
+ * Find the fork target on the parent's active path: the LAST message whose content carries a hint
+ * (the most recent turn that talked about that message), extended forward to the end of its exchange
+ * — forking mid-exchange would inherit a question without its answer. Hints are tried in caller
+ * order; the first that matches anywhere wins. No match → undefined (the caller forks the present).
+ */
+function locateBranchPoint(path, hints) {
+    const usable = hints
+        .filter((hint) => hint.length > 0 && hint.length <= MAX_BRANCH_HINT_CHARS)
+        .slice(0, MAX_BRANCH_HINTS);
+    if (usable.length < hints.length) {
+        log.warn(`[fastagent] ignored ${hints.length - usable.length} branch hint(s) (over ${MAX_BRANCH_HINTS} hints or ${MAX_BRANCH_HINT_CHARS} chars each) — hints are message ids, not payloads`);
+    }
+    if (usable.length === 0)
+        return undefined;
+    // Serialize each message ONCE — the scan is hints × entries, and stringify must not sit in the
+    // inner loop. The whole message, not just content: shape-agnostic, and a hint is a platform id —
+    // a false positive would need the id to appear outside content, which is where ids live anyway.
+    const serialized = path.map((entry) => (entry.type === "message" ? JSON.stringify(entry.message) : ""));
+    for (const hint of usable) {
+        for (let i = path.length - 1; i >= 0; i--) {
+            if (!serialized[i]?.includes(hint))
+                continue;
+            let j = i + 1;
+            while (j < path.length && !isUserMessage(path[j]))
+                j++;
+            return path[j - 1]?.id;
+        }
+    }
+    return undefined;
+}
+/**
+ * Bound what the child's MODEL CONTEXT starts with: keep the newest exchange unconditionally, extend
+ * older while both window limits hold, and mark the boundary with a mechanical compaction entry.
+ * Entries above the parent's own last compaction are already outside model context and need no mark;
+ * a child whose visible history fits the window gets no mark at all.
+ */
+function markInheritanceWindow(child) {
+    const path = child.getBranch();
+    let scanFrom = 0;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (path[i]?.type === "compaction") {
+            scanFrom = i + 1;
+            break;
+        }
+    }
+    const scanned = path.slice(scanFrom);
+    // The compaction's own summary + retained tail reach the model regardless of where the window
+    // lands, so they charge the budget as a base cost — not estimating them would over-admit.
+    const baseTokens = estimateCompactionTokens(path, scanFrom - 1);
+    const starts = [];
+    scanned.forEach((entry, i) => {
+        if (isUserMessage(entry))
+            starts.push(i);
+    });
+    if (starts.length <= 1)
+        return; // zero or one visible exchange — nothing to cut
+    const suffixTokens = new Array(scanned.length + 1).fill(0);
+    for (let i = scanned.length - 1; i >= 0; i--) {
+        const entry = scanned[i];
+        suffixTokens[i] = (suffixTokens[i + 1] ?? 0) + (entry ? estimateEntryTokens(entry) : 0);
+    }
+    let chosen = starts.length - 1;
+    for (let k = starts.length - 2; k >= 0; k--) {
+        const exchanges = starts.length - k;
+        const startIdx = starts[k];
+        if (startIdx === undefined)
+            break;
+        if (exchanges > INHERIT_MAX_EXCHANGES || baseTokens + (suffixTokens[startIdx] ?? 0) > INHERIT_MAX_TOKENS)
+            break;
+        chosen = k;
+    }
+    if (chosen === 0)
+        return; // the whole visible history fits the window
+    const boundaryIdx = starts[chosen];
+    if (boundaryIdx === undefined)
+        return;
+    const boundary = scanned[boundaryIdx];
+    if (boundary === undefined)
+        return;
+    child.appendCompaction(`Inherited from the parent conversation; ${chosen} earlier exchange(s) are not shown.`, boundary.id, (suffixTokens[0] ?? 0) - (suffixTokens[boundaryIdx] ?? 0));
+}
+/**
+ * The branch point this inheritance should copy up to, and the parent's path — the decision half,
+ * shared by both backends because WHERE a thread branches is policy, not storage.
+ */
+export function inheritanceCut(parent, branchHints) {
+    const path = parent.getBranch();
+    const leaf = path[path.length - 1];
+    if (!leaf)
+        return undefined; // an empty parent has nothing to inherit
+    const hints = branchHints ?? [];
+    const at = locateBranchPoint(path, hints);
+    if (at === undefined && hints.length > 0) {
+        log.warn("[fastagent] no branch hint matched in the parent session — inheriting from its present");
+    }
+    return { at: at ?? leaf.id };
+}
+/**
+ * Copy the parent's path up to `at` into `child`, entry by entry — what a backend with no FILE to
+ * fork has to do instead. Kinds pi models as facts about an entry rather than positions (labels,
+ * the session name) are not copied: they describe the parent's record, not the thread's history.
+ *
+ * The COPY only. Bounding what the child's model sees is {@link markInheritanceWindow}, which only
+ * {@link copyBranchForInheritance} applies: a lifecycle fork that marked a window would hide the
+ * exact entries its user forked to keep.
+ */
+export function copyBranchInto(parent, child, at) {
+    /** Parent entry id → the child's id for that entry: the copy mints its own, and a compaction
+     *  points BACK into the path it was appended to. */
+    const copied = new Map();
+    /** Ids of entries this copy did NOT append. A compaction's `firstKeptEntryId` routinely names one:
+     *  pi walks the cut point backwards onto the metadata entries adjacent to it, which carry no
+     *  context. They resolve to the next entry that survived — the retained tail starts there — so a
+     *  dropped anchor moves the boundary by an invisible entry instead of erasing the whole tail. */
+    let unanchored = [];
+    const record = (parentId, childId) => {
+        for (const id of unanchored)
+            copied.set(id, childId);
+        unanchored = [];
+        copied.set(parentId, childId);
+    };
+    for (const raw of parent.getBranch(at)) {
+        const entry = raw;
+        let childId;
+        switch (entry.type) {
+            case "message":
+                if (entry.message) {
+                    childId = child.appendMessage(entry.message);
+                }
+                break;
+            case "custom_message":
+                // Model-visible history, unlike the `custom` entries below it: an extension injected it INTO
+                // the conversation, and the assistant messages answering it are being copied.
+                childId = child.appendCustomMessageEntry(entry.customType ?? "", entry.content, entry.display ?? false, entry.details);
+                break;
+            case "compaction":
+                // `firstKeptEntryId` is where the RETAINED TAIL starts — the entries pi did not summarize,
+                // which still reach the model. Translated through the copy rather than pinned to the child's
+                // leaf: pinning kept exactly ONE entry, and when that entry was a toolResult (a compaction
+                // lands wherever the turn ended) the child's first request opened with a tool result whose
+                // call had been summarized away, which every provider rejects. An id the copy never saw
+                // keeps nothing, which is what pi itself does with a pointer it cannot resolve.
+                childId = child.appendCompaction(entry.summary ?? "", copied.get(entry.firstKeptEntryId ?? "") ?? "", entry.tokensBefore ?? 0, entry.details);
+                break;
+            case "model_change":
+                if (entry.provider && entry.modelId)
+                    childId = child.appendModelChange(entry.provider, entry.modelId);
+                break;
+            case "thinking_level_change":
+                if (entry.thinkingLevel)
+                    childId = child.appendThinkingLevelChange(entry.thinkingLevel);
+                break;
+            case "custom":
+                // The plane's markers describe the parent's RECORD, not the thread's history: a copied
+                // provenance would make a fork of a fork claim its grandparent's branch point (the
+                // idempotency check reads that value), and a copied leaf anchor would pin the child's head
+                // to a position its own history never chose. Every other custom entry is history and travels
+                // — the engine's tool-activation delta above all, since the copied assistant messages call
+                // the tools it records.
+                if (entry.customType && !isPlaneMarker(entry)) {
+                    childId = child.appendCustomEntry(entry.customType, entry.data);
+                }
+                break;
+            default:
+                break; // label / session_info / branch_summary: the parent's facts, not the thread's history
+        }
+        if (childId === undefined)
+            unanchored.push(entry.id);
+        else
+            record(entry.id, childId);
+    }
+}
+/** {@link copyBranchInto} plus the inheritance window — what a new THREAD gets and a fork does not.
+ *  Both backends call THIS one, so neither can drift on where a child's context begins. */
+export function copyBranchForInheritance(parent, child, at) {
+    copyBranchInto(parent, child, at);
+    markInheritanceWindow(child);
+}
+/*
+ * There is deliberately NO file-level fork here. pi can copy a path into a new file
+ * (`createBranchedSession` + `forkFrom`), but that pair writes the intermediate only when the copied
+ * path contains an ASSISTANT message — so forking at a user entry hands `forkFrom` a path that does
+ * not exist, and the failure reads as retryable for a condition no retry can change. Copying entries
+ * is what a backend with no file to fork has to do anyway, so both share these functions and one
+ * semantics; a fork is not hot enough to buy a second path back.
+ */

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

@@ -0,0 +1,48 @@
+/**
+ * Which journal entries are POSITIONS and which are the control plane's own bookkeeping.
+ *
+ * pi's journal has one shape for everything, so the plane writes what it needs to remember into the
+ * same log the conversation lives in: what fork a record is, and the anchor that makes a leaf move
+ * survive a reopen. Both the record store and the history copier have to agree on which is which —
+ * one publishes and navigates, the other copies — and a disagreement is invisible until a fork comes
+ * back missing something. Hence one module, imported by both, depending on neither.
+ */
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+/** What pins a leaf move to disk. pi's `branch()` writes nothing — the leaf is runtime state, and
+ *  `open()` puts it back on the file's last entry — so a move that no other write follows is
+ *  forgotten. Carries no data: its PARENT is the position, which is the whole point of appending it. */
+export declare const LEAF_ANCHOR = "fastagent.leaf";
+/**
+ * The CONTROL PLANE's bookkeeping — not a place in a conversation, so never published, never
+ * navigable, and never copied by a fork: these describe THIS record, not the history it holds.
+ *
+ * An EXACT list, not a `fastagent` prefix. The prefix was tried and was wrong for one entry, at a
+ * cost worth remembering: `fastagent:tool-activation` is written by the ENGINE and is thread history
+ * (which deferred tools this conversation discovered), so matching it here dropped it from every
+ * fork and every inherited thread — while the assistant messages that call those tools came along.
+ * A new marker joins this list deliberately, which is the point of it being a list.
+ */
+export declare function isPlaneMarker(entry: {
+    type?: string;
+    customType?: string;
+}): boolean;
+/** Every position a client may move the branch head to, and everything `entries()` publishes — ONE
+ *  predicate, so "anything published is navigable" holds by construction. `label` is metadata ABOUT
+ *  an entry rather than a place; {@link isPlaneMarker} is ours rather than the conversation's. */
+export declare function isNavigable(entry: {
+    type?: string;
+    customType?: string;
+}): boolean;
+/**
+ * The head a client SEES: the last publishable entry on the active path.
+ *
+ * Not pi's leaf, which may be a marker — a solo leaf move anchors itself with one — so reporting
+ * pi's answer would hand back an id the client did not ask for and cannot find in `entries()`.
+ */
+export declare function publishedLeaf(record: SessionManager): string | undefined;
+/** Stamp a fresh fork with where it came from. */
+export declare function stampProvenance(record: SessionManager, provenance: string): void;
+/** What fork this record IS, or undefined for a record that was not forked. The LAST stamp wins — a
+ *  fork of a fork carries its own — and the whole journal is read rather than the active path, so a
+ *  later leaf move cannot make a fork stop being one. */
+export declare function forkProvenance(record: SessionManager): string | undefined;

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

@@ -0,0 +1,59 @@
+/** "This record is a fork of X at Y." Its own entry rather than pi's header `parentSession`, which
+ *  pi fills from its own fork path and names a FILE, not the branch point idempotency needs. */
+const FORK_PROVENANCE = "fastagent.fork";
+/** What pins a leaf move to disk. pi's `branch()` writes nothing — the leaf is runtime state, and
+ *  `open()` puts it back on the file's last entry — so a move that no other write follows is
+ *  forgotten. Carries no data: its PARENT is the position, which is the whole point of appending it. */
+export const LEAF_ANCHOR = "fastagent.leaf";
+/**
+ * The CONTROL PLANE's bookkeeping — not a place in a conversation, so never published, never
+ * navigable, and never copied by a fork: these describe THIS record, not the history it holds.
+ *
+ * An EXACT list, not a `fastagent` prefix. The prefix was tried and was wrong for one entry, at a
+ * cost worth remembering: `fastagent:tool-activation` is written by the ENGINE and is thread history
+ * (which deferred tools this conversation discovered), so matching it here dropped it from every
+ * fork and every inherited thread — while the assistant messages that call those tools came along.
+ * A new marker joins this list deliberately, which is the point of it being a list.
+ */
+export function isPlaneMarker(entry) {
+    return entry.type === "custom" && (entry.customType === FORK_PROVENANCE || entry.customType === LEAF_ANCHOR);
+}
+/** Every position a client may move the branch head to, and everything `entries()` publishes — ONE
+ *  predicate, so "anything published is navigable" holds by construction. `label` is metadata ABOUT
+ *  an entry rather than a place; {@link isPlaneMarker} is ours rather than the conversation's. */
+export function isNavigable(entry) {
+    return entry.type !== "label" && !isPlaneMarker(entry);
+}
+/**
+ * The head a client SEES: the last publishable entry on the active path.
+ *
+ * Not pi's leaf, which may be a marker — a solo leaf move anchors itself with one — so reporting
+ * pi's answer would hand back an id the client did not ask for and cannot find in `entries()`.
+ */
+export function publishedLeaf(record) {
+    const path = record.getBranch();
+    for (let i = path.length - 1; i >= 0; i--) {
+        const entry = path[i];
+        if (entry && isNavigable(entry))
+            return entry.id;
+    }
+    return undefined;
+}
+/** Stamp a fresh fork with where it came from. */
+export function stampProvenance(record, provenance) {
+    record.appendCustomEntry(FORK_PROVENANCE, { provenance });
+}
+/** What fork this record IS, or undefined for a record that was not forked. The LAST stamp wins — a
+ *  fork of a fork carries its own — and the whole journal is read rather than the active path, so a
+ *  later leaf move cannot make a fork stop being one. */
+export function forkProvenance(record) {
+    let found;
+    for (const raw of record.getEntries()) {
+        if (raw.type !== "custom" || raw.customType !== FORK_PROVENANCE)
+            continue;
+        const value = raw.data?.provenance;
+        if (typeof value === "string")
+            found = value;
+    }
+    return found;
+}

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

@@ -1,7 +1,7 @@
 /**
  * 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.
+ * `update({ thinkingLevel })` gate and the per-invoke binding 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
@@ -10,7 +10,8 @@
  */
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
-import type { AnyModel } from "./harness.ts";
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { AnyModel } from "./models.ts";
 export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
 /** The shape both override consumers walk — a session entry, structurally. */
 export interface OverrideEntryLike {
@@ -32,7 +33,7 @@ export interface SessionSettings {
     model: AnyModel;
     /** Already clamped to what {@link model} supports. */
     thinkingLevel: ThinkingLevel;
-    /** What `set_thinking` accepts for this session. */
+    /** What `update({ thinkingLevel })` accepts for this session. */
     availableThinkingLevels: string[];
     /** Recorded but not honored — only the execution path reports it (as a warn). */
     dropped?: {
@@ -49,3 +50,14 @@ export declare function resolveSessionSettings(entries: OverrideEntryLike[], mod
     model: AnyModel;
     thinkingLevel: ThinkingLevel;
 }): SessionSettings;
+/**
+ * The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks.
+ * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a leaf move,
+ * and reading it flat would run the session on a setting it moved away from.
+ *
+ * A chain that is not intact THROWS. `getBranch()` stops where a parent is missing and answers the
+ * SHORT path, which reads exactly like a short session — every override above the gap gone, the next
+ * turn silently on assembly defaults. The caller decides what to do with the fault (state() reports
+ * the settings as absent, dispatch answers with a code); what it must not do is guess.
+ */
+export declare function activePath(record: SessionManager, from?: string): OverrideEntryLike[];

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

@@ -1,7 +1,8 @@
 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. */
+ *  level pi adds becomes a type error here rather than a value `update({ thinkingLevel })` silently
+ *  rejects. */
 const ALL_THINKING_LEVELS = {
     off: true,
     minimal: true,
@@ -71,3 +72,23 @@ export function resolveSessionSettings(entries, models, defaults) {
         ...(dropped.model || dropped.thinkingLevel ? { dropped } : {}),
     };
 }
+/**
+ * The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks.
+ * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a leaf move,
+ * and reading it flat would run the session on a setting it moved away from.
+ *
+ * A chain that is not intact THROWS. `getBranch()` stops where a parent is missing and answers the
+ * SHORT path, which reads exactly like a short session — every override above the gap gone, the next
+ * turn silently on assembly defaults. The caller decides what to do with the fault (state() reports
+ * the settings as absent, dispatch answers with a code); what it must not do is guess.
+ */
+export function activePath(record, from) {
+    // `from` asks a different question: the path a leaf move is ABOUT to make active, which a caller
+    // validating a patch needs before the move exists. Absent, it is the session's current path.
+    const path = record.getBranch(from);
+    const root = path[0];
+    if (root?.parentId != null) {
+        throw new Error(`session entry "${root.parentId}" is missing from the journal (parent of "${root.id}")`);
+    }
+    return path;
+}

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

@@ -0,0 +1,140 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { SessionSummary, SessionUpdateField } from "../../session.ts";
+import { type OverrideEntryLike } from "./session-settings.ts";
+import { type SessionInheritance } from "./session-inheritance.ts";
+/**
+ * The session RECORDS, as operations rather than as pi handles.
+ *
+ * The distinction is the point. `openOrCreate`/`openIfExists` hand out a live `SessionManager` for
+ * the two things that genuinely need one — driving a turn, and reading a session's contents — and
+ * everything else is a whole-record operation implemented HERE. That line was drawn after the
+ * lifecycle work: when the control plane wrote properties by calling pi's append methods itself, it
+ * had to know pi's rules to do it (every append advances the single leaf pointer, so order decides
+ * where a fork's head lands; `appendSessionInfo` rewrites the name it is given; a record buffers in
+ * memory until its first assistant message). Every caller learning those separately is how the same
+ * fact ended up half-known in two modules — so they are known once, here.
+ */
+export interface PiSessionRecordStore {
+    openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<SessionManager>;
+    /** OPEN-EXISTING sibling: an unknown session answers undefined, never creates one — sessions are
+     *  the data plane's monopoly. The READ path (state/entries) and the turn binding use this; the
+     *  write path does not, because a caller holding a handle is a caller learning pi's rules. */
+    openIfExists(sessionId: string): Promise<SessionManager | undefined>;
+    /**
+     * Write session properties, in the order pi's leaf pointer requires, and report what LANDED.
+     *
+     * Each property is its own journal entry — pi has no "append these together" — so a failure
+     * partway is a real state, and this answers it rather than pretending a rollback happened. The
+     * caller supplies an already-VALIDATED patch (a model resolved to provider+id, a level this model
+     * accepts): what belongs here is how a record is written, not what a value means.
+     *
+     * `undefined` = no such record (it vanished between the caller's check and this call).
+     */
+    applyProperties(sessionId: string, writes: PropertyWrites): Promise<AppliedProperties | undefined>;
+    /** Every record this store holds, in CALLER ids. Rejects when the store cannot be enumerated —
+     *  `[]` means "no sessions", so it must not double as "could not look". Answers the CONTRACT's row
+     *  type: the hub forwards it, and a second identical shape here would only be a thing to keep in
+     *  sync. */
+    list(): Promise<SessionSummary[]>;
+    /** Copy `from`'s history up to entry `at` into a new record named `into`, stamped with `provenance`
+     *  so a repeat of the SAME fork can be recognised as one ({@link forkProvenance}) instead of
+     *  becoming a second record or an overwrite. Throws on any failure: a half-copied fork is never
+     *  left in place, and the caller turns the throw into a coded result. */
+    fork(from: string, at: string, into: string, provenance: string): Promise<void>;
+    /** Destroy a record. `false` = there was none (the caller answers `no_such_session`). */
+    delete(sessionId: string): Promise<boolean>;
+}
+/** A validated property patch, in the shape a RECORD takes it: the model already resolved to the
+ *  provider + id pi's append wants, so this layer never asks what a model spec means. */
+export interface PropertyWrites {
+    name?: string;
+    model?: {
+        provider: string;
+        id: string;
+    };
+    thinkingLevel?: string;
+    leafEntryId?: string;
+}
+/** What a property write actually did, and what the record holds after it. */
+interface AppliedProperties {
+    /** In write order. A field asked for but absent here did not land. */
+    landed: SessionUpdateField[];
+    /** Why the rest stopped, if anything did. The caller turns this into a coded result; the record
+     *  already reflects `landed`. */
+    failure?: unknown;
+    /** The record AFTER the writes — what the caller reports, rather than echoing the request. pi
+     *  rewrites a name (newlines collapse, ends trim), so the request is not what was stored. */
+    name?: string;
+    leafEntryId?: string;
+    /** The active path after the writes, for a caller that resolves settings against a model registry
+     *  this layer has no business knowing. Absent when the chain cannot be walked — the caller decides
+     *  what an unreadable chain means (design §7); it is never silently a short path. */
+    path?: OverrideEntryLike[];
+}
+/**
+ * A Caller's session id, as a name pi will accept.
+ *
+ * `SessionManager` enforces `^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$` — which no built-in
+ * channel satisfies: telegram's `-1001234567890` leads with a dash, feishu and slack keys carry
+ * `:` and `/`, and any custom `route()` may mint anything at all.
+ *
+ * The mapping is INJECTIVE, because two conversations resolving to one record is two rooms sharing a
+ * memory. `s` prefix (the pattern demands an alphanumeric head, and prefixing unconditionally is what
+ * keeps it injective — a conditional one would map `-a` and `s-a` alike), then each character
+ * outside `[A-Za-z0-9.-]` becomes `_XX` / `_uXXXX`, self-describing widths so no two inputs can
+ * produce one output. `_` escapes itself for the same reason. A trailing `.` or `-` is legal
+ * mid-name but not at the end, so it escapes too.
+ *
+ * Injective within this encoding — which is only sufficient because new records live in their own
+ * directory. The older spelling draws names from the same character set (it stored a room literally
+ * called `s42` as `s42`, which is also this encoding of `42`), so one directory would make some
+ * names ambiguous no matter how either side spells them.
+ *
+ * Readability is deliberate: `-1001234567890` becomes `s-1001234567890`, so an operator can still
+ * tell which room a file belongs to.
+ */
+export declare function piSessionId(sessionId: string): string;
+/**
+ * {@link piSessionId} backwards — what `list()` needs, because a session id belongs to the CALLER and
+ * a record name is storage detail. The encoding is self-describing (fixed widths, `_` escapes
+ * itself), so this is a decode rather than a guess; a name this store did not write (no `s` head, a
+ * truncated escape) answers undefined and is left out of the listing rather than reported under a
+ * name nobody can dial.
+ */
+export declare function callerSessionId(recordId: string): string | undefined;
+/**
+ * Disk-backed store under `dir`: restart the process, conversations continue.
+ *
+ * Lookup is a directory scan of THIS store's own directory, reading ids out of the filenames pi
+ * writes (`<timestamp>_<id>.jsonl`) — not `SessionManager.list`, which filters by the cwd recorded in
+ * each header and would make a renamed agent directory look like an empty store (see
+ * {@link recordFiles}).
+ *
+ * NEW records live in a subdirectory of their own, because the two engines cannot share a namespace:
+ * both spell ids into `[A-Za-z0-9._-]`, so neither can claim a prefix the other cannot produce, and
+ * a directory holding both would have names that belong to two conversations at once — in whichever
+ * direction it is read. Separate directories make each side's own injectivity sufficient.
+ *
+ * A PRE-EXISTING record is continued in place: looked up by the older spelling, which is injective
+ * on its own terms, and appended to where it lies. Both spellings are the same v3 jsonl, so a
+ * conversation started before this store keeps going rather than restarting empty. Nothing on disk
+ * is rewritten.
+ *
+ * SCOPE OF "open-or-create": idempotent against a store that is serialized per session, which is what
+ * the serving path provides — the single-writer lease is taken before any store call, so no two
+ * turns of one conversation reach this at once. What it does NOT do is arbitrate a FIRST open racing
+ * across processes: two instances that scan before either writes will both create, and the
+ * conversation forks into two records. sessions.ts states the same boundary for the same reason
+ * ("the serving path serializes it with the single-writer lease before reaching any store"), and a
+ * horizontally-scaled deployment that wants more owes a lease that spans its instances — an
+ * in-process one cannot arbitrate between them, and a file lock here would only look like it could.
+ */
+export declare function piSessionRecordStore(options: {
+    dir: string;
+    cwd?: string;
+}): PiSessionRecordStore;
+/** In-process store: continuity lives and dies with the instance. */
+export declare function piInMemorySessionRecordStore(options?: {
+    cwd?: string;
+}): PiSessionRecordStore;
+export {};