@fastagent-sh/fastagent 0.21.1 → 0.22.0

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

@@ -0,0 +1,14 @@
+/** Scoped acquisition of the two things a pi turn or control write owns: the session lease and the
+ *  bound session. The Promise crossing itself is `src/effect-port.ts`. */
+import * as Effect from "effect/Effect";
+import type { PiAgentSessionFactory } from "./invoke-session.ts";
+import type { SessionInheritance } from "./session-inheritance.ts";
+import type { Lease } from "./turn-kit.ts";
+/** Admission was refused: another turn (or another write) holds this session. Its own tag because it
+ *  is CONTROL FLOW — a caller answers it with `session_busy` and a retry — not a port failure. */
+export declare class SessionBusy extends Error {
+    readonly _tag = "SessionBusy";
+    constructor();
+}
+export declare function acquireSessionLease(lease: Lease, session: string): Effect.Effect<import("./turn-kit.ts").Release, SessionBusy, import("effect/Scope").Scope>;
+export declare function acquireSession(factory: PiAgentSessionFactory, session: string, inherit?: SessionInheritance): Effect.Effect<import("@earendil-works/pi-coding-agent").AgentSession, import("../../effect-port.ts").PortFailure, import("effect/Scope").Scope>;

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

@@ -0,0 +1,30 @@
+/** Scoped acquisition of the two things a pi turn or control write owns: the session lease and the
+ *  bound session. The Promise crossing itself is `src/effect-port.ts`. */
+import * as Effect from "effect/Effect";
+import { port, portCleanup } from "../../effect-port.js";
+/** Admission was refused: another turn (or another write) holds this session. Its own tag because it
+ *  is CONTROL FLOW — a caller answers it with `session_busy` and a retry — not a port failure. */
+export class SessionBusy extends Error {
+    _tag = "SessionBusy";
+    constructor() {
+        super("session busy: a turn or another write is already in flight");
+    }
+}
+export function acquireSessionLease(lease, session) {
+    return Effect.acquireRelease(Effect.suspend(() => {
+        const release = lease.tryAcquire(session);
+        return release ? Effect.succeed(release) : Effect.fail(new SessionBusy());
+    }), (release) => portCleanup("lease release", release));
+}
+export function acquireSession(factory, session, inherit) {
+    // Acquisition stays uninterruptible: a late factory may still publish durable state under the lease.
+    // The extension instances are this session's alone, so their end is its end: pi's `dispose()` does not tell them.
+    return Effect.acquireRelease(port(() => factory(session, inherit)), (bound) => portCleanup("dispose", async () => {
+        try {
+            await bound.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+        }
+        finally {
+            bound.dispose();
+        }
+    }));
+}

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

@@ -1,30 +1,21 @@
-import type { SessionManager } from "@earendil-works/pi-coding-agent";
+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. */
+    /**
+     * Opaque markers that MAY locate the branch point on the parent's active path (searched in message content, first
+     * hit wins, most recent occurrence).
+     */
     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.
- */
+/** The branch point this inheritance should copy up to, and the parent's path. */
 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.
+ * 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.
  */
 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. */
+/** {@link copyBranchInto} plus the inheritance window — what a new THREAD gets and a fork does not. */
 export declare function copyBranchForInheritance(parent: SessionManager, child: SessionManager, at: string): void;

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

@@ -1,83 +1,20 @@
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
-import { isPlaneMarker } from "./session-markers.js";
+import { isConversationMessage, 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. */
+/** …and at most roughly this many tokens (~1/4 of a 200K context: generous, not everything). */
 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. */
+/**
+ * Branch hints are IDS, not payloads: each one costs a scan over the parent's serialized path, and the wire accepts
+ * arbitrary arrays.
+ */
 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).
- */
+/** Find the fork target on the parent's active path. */
 function locateBranchPoint(path, hints) {
     const usable = hints
         .filter((hint) => hint.length > 0 && hint.length <= MAX_BRANCH_HINT_CHARS)
@@ -87,10 +24,10 @@ function locateBranchPoint(path, hints) {
     }
     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) : ""));
+    // Serialize each conversation message ONCE — the scan is hints × entries, and stringify must not sit in the inner
+    // loop. A hint is something a participant said, so the engine's own system entries are not searched: see
+    // `isConversationMessage` for what a hint landing in the assembled prompt would otherwise do here.
+    const serialized = path.map((entry) => (isConversationMessage(entry) ? JSON.stringify(entry.message) : ""));
     for (const hint of usable) {
         for (let i = path.length - 1; i >= 0; i--) {
             if (!serialized[i]?.includes(hint))
@@ -104,60 +41,70 @@ function locateBranchPoint(path, hints) {
     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.
+ * Bound what the child's MODEL CONTEXT starts with. Measured on pi's projection, what the model will actually see:
+ * a `context_edit` omission (an abandoned retry or overflow attempt) costs nothing, and the engine's own `system`
+ * entries are not history. The newest copied compaction (its summary, then the tail it retained) reaches the model
+ * only while no window is cut: pi reads the NEWEST compaction alone, so a mark placed after it drops that tail. Its
+ * summary, a few hundred tokens covering everything older, is carried into the mark instead.
  */
 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 position = new Map(path.map((entry, i) => [entry.id, i]));
+    const latest = path.map((entry) => entry.type).lastIndexOf("compaction");
+    const previous = latest >= 0 ? path[latest] : undefined;
+    let summaryTokens = 0;
+    let tailTokens = 0;
+    let tailExchanges = 0;
+    const scanned = [];
+    for (const { sourceEntry, messages } of child.buildSessionProjection().entries) {
+        const tokens = messages.reduce((sum, message) => (message.role === "system" ? sum : sum + estimateTokens(message)), 0);
+        const startsExchange = sourceEntry.type === "message" && sourceEntry.message.role === "user" && messages.length > 0;
+        if (sourceEntry.id === previous?.id)
+            summaryTokens += tokens;
+        else if ((position.get(sourceEntry.id) ?? -1) < latest) {
+            // The retained tail: journal entries BEFORE the compaction that pi still projects.
+            tailTokens += tokens;
+            if (startsExchange)
+                tailExchanges++;
         }
+        else
+            scanned.push({ id: sourceEntry.id, tokens, startsExchange });
     }
-    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))
+        if (entry.startsExchange)
             starts.push(i);
     });
-    if (starts.length <= 1)
-        return; // zero or one visible exchange — nothing to cut
+    if (starts.length === 0)
+        return; // no exchange after the compaction to place a mark at
     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);
+        suffixTokens[i] = (suffixTokens[i + 1] ?? 0) + (scanned[i]?.tokens ?? 0);
     }
+    const fits = (exchanges, tokens) => exchanges <= INHERIT_MAX_EXCHANGES && tokens <= INHERIT_MAX_TOKENS;
+    const everything = summaryTokens + tailTokens + (suffixTokens[0] ?? 0);
+    if (fits(tailExchanges + starts.length, everything))
+        return; // the whole visible history fits the window
+    // Cut: the tail goes, the summary stays (carried below). The newest exchange is the floor.
     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)
+        if (!fits(starts.length - k, summaryTokens + (suffixTokens[starts[k] ?? 0] ?? 0)))
             break;
         chosen = k;
     }
-    if (chosen === 0)
-        return; // the whole visible history fits the window
-    const boundaryIdx = starts[chosen];
-    if (boundaryIdx === undefined)
+    // Without a compaction, a mark at the first exchange would hide nothing that costs tokens.
+    if (!previous && chosen === 0)
         return;
-    const boundary = scanned[boundaryIdx];
+    const boundary = scanned[starts[chosen] ?? 0];
     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));
+    const hidden = tailExchanges + chosen;
+    const note = hidden > 0
+        ? `Inherited from the parent conversation; ${hidden} earlier exchange(s) are not shown.`
+        : "Inherited from the parent conversation; earlier messages are not shown.";
+    child.appendCompaction(previous ? `${previous.summary}\n\n${note}` : note, boundary.id, everything);
 }
-/**
- * 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.
- */
+/** The branch point this inheritance should copy up to, and the parent's path. */
 export function inheritanceCut(parent, branchHints) {
     const path = parent.getBranch();
     const leaf = path[path.length - 1];
@@ -171,22 +118,16 @@ export function inheritanceCut(parent, branchHints) {
     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.
+ * 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.
  */
 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. */
+    /**
+     * 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. */
+    /** Ids of entries this copy did NOT append. */
     let unanchored = [];
     const record = (parentId, childId) => {
         for (const id of unanchored)
@@ -194,50 +135,57 @@ export function copyBranchInto(parent, child, at) {
         unanchored = [];
         copied.set(parentId, childId);
     };
-    for (const raw of parent.getBranch(at)) {
-        const entry = raw;
+    // Typed by pi's own union, and exhaustive: a pi release that adds an entry type fails typecheck here instead of
+    // being dropped from every copied branch without a word.
+    for (const entry of parent.getBranch(at)) {
         let childId;
         switch (entry.type) {
             case "message":
-                if (entry.message) {
-                    childId = child.appendMessage(entry.message);
-                }
+                // Every message, INCLUDING the engine's system entries: the child starts from the prompt the parent was
+                // running under, and pi diffs its own sections against it, so the thread's first request carries that
+                // prompt once rather than twice.
+                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);
+                // 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, 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);
+                // `firstKeptEntryId` is where the RETAINED TAIL starts — the entries pi did not summarize, which still reach
+                // the model.
+                childId = child.appendCompaction(entry.summary, copied.get(entry.firstKeptEntryId) ?? "", entry.tokensBefore, entry.details);
                 break;
+            case "context_edit": {
+                // pi omits an abandoned retry/overflow attempt from the model's context this way; dropping the edit would
+                // hand that attempt back to the copy. Its target is a message, which the copy always anchors.
+                const target = copied.get(entry.targetId);
+                if (target)
+                    childId = child.appendContextEdit(target, entry.replacement);
+                break;
+            }
             case "model_change":
-                if (entry.provider && entry.modelId)
-                    childId = child.appendModelChange(entry.provider, entry.modelId);
+                childId = child.appendModelChange(entry.provider, entry.modelId);
                 break;
             case "thinking_level_change":
-                if (entry.thinkingLevel)
-                    childId = child.appendThinkingLevelChange(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)) {
+                // The plane's markers describe the parent's RECORD, not the thread's history.
+                if (!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
+            case "label":
+            case "session_info":
+            case "branch_summary":
+            case "usage":
+                break; // the parent's facts, not the thread's history
+            default: {
+                // Unreachable by type; a record written by a newer pi can still carry one, and refusing to start the thread
+                // over it would be worse than naming it.
+                const unhandled = entry;
+                log.warn(`[fastagent] inheritance skipped a session entry of unknown type "${unhandled.type}"`);
+            }
         }
         if (childId === undefined)
             unanchored.push(entry.id);
@@ -245,17 +193,12 @@ export function copyBranchInto(parent, child, at) {
             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. */
+/** {@link copyBranchInto} plus the inheritance window — what a new THREAD gets and a fork does not. */
 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.
- */
+// 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.

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

@@ -1,48 +1,49 @@
 /**
- * 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.
+ * Which journal entries are POSITIONS, which are the control plane's own bookkeeping, and which are turns in the
+ * CONVERSATION. 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) — and since 0.86 the ENGINE writes its own bookkeeping there too, as the `system` entries carrying the
+ * assembled prompt. Three questions, one file: a reader of the journal answers them here or it answers them alone,
+ * which is how one reader came to count the prompt as history.
  */
 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. */
+/** What pins a leaf move to disk. pi's `branch()` writes nothing. */
 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.
+ * The CONTROL PLANE's bookkeeping — not a place in a conversation, so never published, never navigable, and never
+ * copied by a fork.
  */
 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: {
+/**
+ * An entry that is a TURN IN THE CONVERSATION — what a reader counting, previewing or searching the history means
+ * by "a message".
+ *
+ * The line it draws is the ENGINE's prompt state. Since pi 0.86 pi writes `system` messages into the same log the
+ * conversation lives in, carrying the assembled prompt (persona, project context, skill and tool descriptions)
+ * plus one more per prompt or tool-set change. They are bookkeeping, not something anyone said, and every reader
+ * of the journal has to decide about them. Deciding once, here, is the point: the first reader that forgot cut
+ * inheritance above every exchange and handed a new thread an empty history, with no diagnostic.
+ */
+export declare function isConversationMessage(entry: {
     type?: string;
-    customType?: string;
+    message?: {
+        role?: 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()`.
+ * Every position a client may move the branch head to, and everything `entries()` publishes — ONE predicate, so
+ * "anything published is navigable" holds by construction.
  */
+export declare function isNavigable(entry: {
+    type?: string;
+    customType?: string;
+}): boolean;
+/** The head a client SEES: the last publishable entry on the active path. */
 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. */
+/** What fork this record IS, or undefined for a record that was not forked. */
 export declare function forkProvenance(record: SessionManager): string | undefined;

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

@@ -1,35 +1,38 @@
-/** "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. */
+/**
+ * "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. */
+/** What pins a leaf move to disk. pi's `branch()` writes nothing. */
 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.
+ * The CONTROL PLANE's bookkeeping — not a place in a conversation, so never published, never navigable, and never
+ * copied by a fork.
  */
 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.
+ * An entry that is a TURN IN THE CONVERSATION — what a reader counting, previewing or searching the history means
+ * by "a message".
  *
- * 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()`.
+ * The line it draws is the ENGINE's prompt state. Since pi 0.86 pi writes `system` messages into the same log the
+ * conversation lives in, carrying the assembled prompt (persona, project context, skill and tool descriptions)
+ * plus one more per prompt or tool-set change. They are bookkeeping, not something anyone said, and every reader
+ * of the journal has to decide about them. Deciding once, here, is the point: the first reader that forgot cut
+ * inheritance above every exchange and handed a new thread an empty history, with no diagnostic.
  */
+export function isConversationMessage(entry) {
+    return entry.type === "message" && entry.message?.role !== "system";
+}
+/**
+ * Every position a client may move the branch head to, and everything `entries()` publishes — ONE predicate, so
+ * "anything published is navigable" holds by construction.
+ */
+export function isNavigable(entry) {
+    return entry.type !== "label" && !isPlaneMarker(entry);
+}
+/** The head a client SEES: the last publishable entry on the active path. */
 export function publishedLeaf(record) {
     const path = record.getBranch();
     for (let i = path.length - 1; i >= 0; i--) {
@@ -43,9 +46,7 @@ export function publishedLeaf(record) {
 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. */
+/** What fork this record IS, or undefined for a record that was not forked. */
 export function forkProvenance(record) {
     let found;
     for (const raw of record.getEntries()) {