one-code-extension 0.5.0 → 0.6.0

package/extensions/lib/deferred.ts

@@ -14,6 +14,7 @@ import { createHash } from "node:crypto";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import { toolResultsOnBranch } from "./branch-restore.ts";
 import { parseClaudeId } from "./claude-id.ts";
+import { leadingToolsItem, toolsItemFor } from "./ledger/wire.ts";
 import { RESPONSES_APIS } from "./system-role.ts";
 import { ADDENDUM_HEAD } from "./tool-additions.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
@@ -37,6 +38,47 @@ export interface DeferRequest {
 	keywords?: string[];
 }
 
+/**
+ * Ask the session's tool-search which tools it defers: emit a `DeferredQuery`
+ * and it adds one request per deferred tool. A subagent defers the same tools
+ * its parent injects into it (MCP, cron, SendMessage), whose owners run only
+ * in the parent.
+ */
+export const DEFERRED_QUERY_CHANNEL = "one-code:deferred-query";
+
+export interface DeferredQuery {
+	tools: DeferRequest[];
+}
+
+/** The tools this session defers, as its tool-search answers DEFERRED_QUERY_CHANNEL (none without one). */
+export function queryDeferred(events: { emit(channel: string, data: unknown): void }): DeferRequest[] {
+	const query: DeferredQuery = { tools: [] };
+	events.emit(DEFERRED_QUERY_CHANNEL, query);
+	return query.tools;
+}
+
+/**
+ * The tools a child gets from its parent rather than its own extensions: the
+ * shared MCP tools (`mcp__*`, which no child extension owns) and `extra`, the
+ * ones the caller injects by name (the spawn and cron tools).
+ */
+export function injectedByParent(extra: readonly { name: string }[]): (name: string) => boolean {
+	const names = new Set(extra.map((tool) => tool.name));
+	return (name) => name.startsWith("mcp__") || names.has(name);
+}
+
+/**
+ * An inline child extension that defers, at load, the parent's deferral of each
+ * tool `injected` names, whose owners run only in the parent. A tool the
+ * child's own extensions own stays theirs to defer or withhold per the child's
+ * model.
+ */
+export function deferLikeParentExtension(parentDeferred: readonly DeferRequest[], injected: (name: string) => boolean) {
+	return (pi: { events: { emit(channel: string, data: unknown): void } }) => {
+		for (const request of parentDeferred) if (injected(request.name)) pi.events.emit(DEFER_CHANNEL, request);
+	};
+}
+
 export interface SearchableTool {
 	name: string;
 	description: string;
@@ -101,6 +143,17 @@ export function deferredAddendumText(added: readonly string[]): string {
 	return [ADDENDUM_HEAD, ...added].join("\n");
 }
 
+/**
+ * The one-shot that says deferred tools the conversation was told about are
+ * gone (their MCP server disconnected or was removed, a resume without it).
+ * The earlier listing or addendum stays in the history as sent, and so may
+ * the tool's declaration, so without this the model calls it and gets "Tool
+ * not found".
+ */
+export function deferredRemovedText(removed: readonly string[]): string {
+	return ["The following deferred tools are no longer available. tool_search cannot load them and calls to them fail; do not use them:", ...removed].join("\n");
+}
+
 /** The loader every deferred tool sits behind. */
 export const TOOL_SEARCH = "tool_search";
 
@@ -161,6 +214,73 @@ export function toolSearchLoads(branch: readonly SessionEntry[]): Map<string, st
 }
 const TOOL_SEARCH_NAMES: ReadonlySet<string> = new Set([TOOL_SEARCH]);
 
+/**
+ * The tools `entries` use: loaded by a `tool_search` result in them (`loads`,
+ * their `toolSearchLoads`), or called by an assistant message in them. A call
+ * the dispatcher failed as "Tool <name> not found" does not count: the tool
+ * was not loaded, and the miss steers the model to `tool_search` to load it.
+ */
+export function toolsInUse(entries: readonly SessionEntry[], loads: ToolSearchLoads = toolSearchLoads(entries)): Set<string> {
+	const inUse = new Set([...loads.values()].flat());
+	const missed = new Set<string>();
+	for (const entry of entries) {
+		const message = entry.type === "message" ? (entry.message as { role?: string; toolCallId?: unknown; isError?: unknown }) : undefined;
+		if (message?.role === "toolResult" && message.isError === true && typeof message.toolCallId === "string" && toolNotFoundName(resultText(message))) missed.add(message.toolCallId);
+	}
+	for (const entry of entries) {
+		const message = entry.type === "message" ? (entry.message as { role?: string; content?: unknown }) : undefined;
+		if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+		for (const block of message.content as Array<{ type?: string; id?: unknown; name?: unknown }>) {
+			if (block?.type === "toolCall" && typeof block.name === "string" && !(typeof block.id === "string" && missed.has(block.id))) inUse.add(block.name);
+		}
+	}
+	return inUse;
+}
+
+/** Why a deferred tool is callable without a fresh `tool_search` load. */
+export interface CallableReasons {
+	/** Loaded by a `tool_search` result in context, or called in context: its history names it. */
+	inUse: ReadonlySet<string>;
+	/** Announced callable by a `tool_addition` in the current epoch (the ledger's told facts). */
+	toldCallable: ReadonlySet<string>;
+	/** Declared eagerly by the recorded head the next request starts from: it stays declared, so it stays callable. */
+	declaredEager: ReadonlySet<string>;
+	/** Announced callable by the next request itself: loadable and untold inside an epoch, on a model that takes `tool_addition`. */
+	announcing: ReadonlySet<string>;
+}
+
+/**
+ * The deferred tools that are callable now, derived from the branch, the model
+ * and the registry (lifecycle-grid-hunt design.md section 6): every other
+ * deferred tool is inactive, whoever activated it. One function decides, so a
+ * resume, `/reload`, `/tree`, a compaction, a model switch and a late defer
+ * cannot disagree with what the wire declares and what the model was told.
+ */
+export function callableDeferredTools(deferred: Iterable<string>, reasons: CallableReasons): Set<string> {
+	const callable = new Set<string>();
+	for (const name of deferred) {
+		if (reasons.inUse.has(name) || reasons.toldCallable.has(name) || reasons.declaredEager.has(name) || reasons.announcing.has(name)) callable.add(name);
+	}
+	return callable;
+}
+
+/**
+ * pi's active set with exactly the `callable` deferred tools active (those
+ * pi has registered) and no `withheld` tool; every other tool as it was. The
+ * input itself when nothing changes.
+ */
+export function reconcileActive(
+	active: readonly string[],
+	deferred: ReadonlySet<string>,
+	callable: ReadonlySet<string>,
+	withheld: ReadonlySet<string>,
+	registered: ReadonlySet<string>,
+): readonly string[] {
+	const kept = active.filter((name) => !withheld.has(name) && (!deferred.has(name) || callable.has(name)));
+	const added = [...callable].filter((name) => registered.has(name) && !withheld.has(name) && !kept.includes(name));
+	return kept.length === active.length && added.length === 0 ? active : [...kept, ...added];
+}
+
 type WireTool = Record<string, unknown> & { name: string };
 type WireBlock = Record<string, unknown> & { type?: unknown };
 type WireMessage = { role?: unknown; content?: unknown };
@@ -383,20 +503,24 @@ export function responsesToolLoadCompat(model: ResponsesToolLoadModel | undefine
 type WireItem = Record<string, unknown>;
 
 /**
- * A Responses request whose `tools` array stays request 1's whatever
+ * A Responses request whose starting tools stay request 1's whatever
  * `tool_search` has loaded since: the OpenAI side of
  * {@link stabilizeDeferredTools}. pi 0.86 and later put a loaded tool into
  * `tools` for One Code (its forced system prompt collapses tool changes into
  * the head, findings §7), so every load re-cached the whole conversation (0
  * cached tokens on the request after a load on `openai-codex`, findings §45).
  *
- * A loaded registry tool leaves `tools` and enters the input right before the
+ * The starting tools are a top-level `tools` array (pi 1.0 to 1.3, and
+ * models pi does not flag) or, from pi 1.4.0, an `additional_tools` item at
+ * the head of the input (findings §78); this reads which from the payload.
+ * A loaded registry tool leaves that list and enters the input right before the
  * `function_call_output` of the `tool_search` call that loaded it, in pi-ai's
  * own native shape (`convertResponsesMessages` `appendSystemToolAdditions`):
- * an `additional_tools` developer item when the model supports one, else a
- * `tool_search_call` + `tool_search_output` pair whose tools carry
- * `defer_loading: true`. A tool the model called before that output, or whose
- * loading output is not on the wire, stays in `tools`.
+ * an `additional_tools` developer item when the request already declares in
+ * items or the model supports one, else a `tool_search_call` +
+ * `tool_search_output` pair whose tools carry `defer_loading: true`. A tool
+ * the model called before that output, or whose loading output is not on the
+ * wire, stays where pi declared it.
  *
  * Returns undefined (leave the payload alone) when nothing moves. Never
  * mutates its input.
@@ -407,9 +531,14 @@ export function stabilizeResponsesToolLoads(
 	loads: ToolSearchLoads,
 	compat: ToolLoadCompat,
 ): Record<string, unknown> | undefined {
-	const tools = payload.tools;
 	const input = payload.input;
-	if (!Array.isArray(tools) || !Array.isArray(input) || loads.size === 0) return undefined;
+	if (!Array.isArray(input) || loads.size === 0) return undefined;
+	// Where the request declares its starting tools: a top-level array (pi 1.0
+	// to 1.3, and models pi does not flag), or an `additional_tools` item at the
+	// head of the input (pi 1.4.0 and later, findings §78). Read from the bytes.
+	const headItem = leadingToolsItem(payload.tools, input);
+	const tools = headItem ? headItem.tools : payload.tools;
+	if (!Array.isArray(tools)) return undefined;
 
 	// Input index of each tool output and of each tool's first call. pi sends a
 	// call id as `<call_id>|<item_id>`; the wire's `call_id` is the first part.
@@ -438,18 +567,20 @@ export function stabilizeResponsesToolLoads(
 	}
 	if (movedAt.size === 0) return undefined;
 
+	// A request that declares in items takes another item, shaped like its
+	// head; the top-level shape takes what the model's compat supports.
 	const nextInput: unknown[] = [];
 	(input as WireItem[]).forEach((item, index) => {
 		const moved = movedAt.get(index);
-		if (moved) nextInput.push(...toolLoadItems(moved, String(item.call_id), compat));
-		nextInput.push(item);
+		if (moved) nextInput.push(...(headItem ? [toolsItemFor(moved, headItem)] : toolLoadItems(moved, String(item.call_id), compat)));
+		nextInput.push(headItem && index === 0 ? { ...headItem, tools: kept } : item);
 	});
-	return { ...payload, tools: kept, input: nextInput };
+	return headItem ? { ...payload, input: nextInput } : { ...payload, tools: kept, input: nextInput };
 }
 
 /** pi-ai's native items for tools added at one point of a Responses conversation. */
 function toolLoadItems(tools: WireItem[], loaderCallId: string, compat: ToolLoadCompat): WireItem[] {
-	if (compat.supportsAdditionalTools) return [{ type: "additional_tools", role: "developer", tools }];
+	if (compat.supportsAdditionalTools) return [toolsItemFor(tools)];
 	const names = tools.map((tool) => String(tool.name));
 	const callId = `pi_tool_load_${createHash("sha256").update(`${loaderCallId}:${names.join(",")}`).digest("hex").slice(0, 16)}`;
 	return [
@@ -511,6 +642,15 @@ export function withheldMissReminderText(name: string): string {
 	return `\`${name}\` failed with "Tool ${name} not found" because it was withdrawn for the current model — it is not a deferred tool you can load with tool_search. Do not retry it; continue without it.`;
 }
 
+/**
+ * A call to a tool the conversation still declares (the epoch's recorded
+ * tools stay declared, decisions/caching.md "record once") that this session
+ * no longer runs: a setting turned it off, or an extension stopped offering it.
+ */
+export function unavailableToolReminderText(name: string): string {
+	return `\`${name}\` failed with "Tool ${name} not found" because it is no longer available in this session, although it is still declared. Do not retry it; continue without it.`;
+}
+
 export interface SearchMatch {
 	name: string;
 	score: number;

package/extensions/lib/ledger/fold-memo.ts

@@ -0,0 +1,49 @@
+/**
+ * One fold per branch state: the extensions that read the ledger's fold
+ * (the ledger's `context` hook, its payload hook, tool-search, claude-context)
+ * share the last fold of each session instead of folding the same branch
+ * again. `foldBranch` is O(requests × list length), and tool-search folds at
+ * every `turn_start`, moments before the ledger's `context` hook folds the
+ * same branch for the request (in every child session too).
+ *
+ * The memo lives in process state (lib/process-state.ts), since each
+ * extension file evaluates its own copy of this module (findings §3), keyed
+ * by the session manager. A hit needs the same identity and the same entries
+ * (every entry the same object, in the same order): any appended entry, a
+ * different leaf or a rebuilt branch misses, so it never returns another
+ * branch's fold. The fold is a pure function of the two, and its readers
+ * never mutate it.
+ *
+ * Pure: no pi imports.
+ */
+import { processState } from "../process-state.ts";
+import { foldBranch, type LedgerFold } from "./fold.ts";
+import type { EntryLike, RequestIdentity } from "./records.ts";
+
+interface Memo {
+	/** A copy of the branch it folded: `getBranch()` may hand back a list that grows in place. */
+	entries: readonly EntryLike[];
+	identity: string;
+	fold: LedgerFold;
+}
+
+const memos = () => processState("ledger:fold-memo", () => new WeakMap<object, Memo>());
+
+/** Whether two branches hold the same entries, each the same object, in the same order: the key a memo of anything derived from a branch takes. */
+export const sameEntries = (a: readonly unknown[], b: readonly unknown[]) => a.length === b.length && a.every((entry, i) => entry === b[i]);
+
+/** `foldBranch(branch, identity)`, reused while `owner`'s branch and the identity stay the same. Without an owner it folds. */
+export function foldOnce(owner: object | undefined, branch: readonly EntryLike[], identity: RequestIdentity | undefined): LedgerFold {
+	if (!owner) return foldBranch(branch, identity);
+	const key = JSON.stringify(identity ?? null);
+	const memo = memos().get(owner);
+	if (memo && memo.identity === key && sameEntries(memo.entries, branch)) return memo.fold;
+	const fold = foldBranch(branch, identity);
+	memos().set(owner, { entries: [...branch], identity: key, fold });
+	return fold;
+}
+
+/** The fold of a session's current branch under `identity` (`sessionIdentity`, lib/anthropic-auth.ts). */
+export function foldSession(sessionManager: { getBranch(): unknown[] } | undefined, identity: RequestIdentity | undefined): LedgerFold {
+	return foldOnce(sessionManager, (sessionManager?.getBranch() ?? []) as EntryLike[], identity);
+}

package/extensions/lib/ledger/fold.ts

@@ -0,0 +1,265 @@
+/**
+ * The fold: everything the ledger knows, derived from the current branch's
+ * entries alone (design.md sections 3 to 5). Resume, `/reload`, `/fork` and
+ * `/tree` need no restore code because each folds a different branch.
+ *
+ * Rules: told facts are a union within the
+ * epoch and start empty at its start; pending items are those no request
+ * delivered; pi's `usage` entries (a cache warm) are skipped. An epoch starts
+ * at the first request, after a compaction entry or an `epoch` record, and at
+ * a request whose identity (api, provider, model, auth) differs.
+ *
+ * Delivered means the model saw it and the branch kept it. A request counts
+ * (its consumed pending ids and the told records written with it, and it
+ * becomes the base the next request extends) only when its own reply follows
+ * it: the first message after the request record, before any other request,
+ * epoch or compaction, is an assistant message that did not end in an error
+ * or an abort and that pi did not omit later (a `context_edit` with no
+ * replacement: a recoverable length stop, a failed attempt before a retry).
+ * A request with no reply (the turn in flight, a process that died
+ * mid-stream, a re-send that replaced it, a btw fork copied mid-stream)
+ * counts nothing, so its pending items are delivered again.
+ * A request that does not count takes back what it changed: the `epoch`
+ * record written right before it and an identity change it made, so a failed
+ * model hop leaves the epoch it left.
+ *
+ * The rebuilt request shares its elements with the branch's entries: clone
+ * before mutating (`spliceRequest` does).
+ *
+ * Pure: no pi imports.
+ */
+import { type Coverage, type EntryLike, type EpochCause, type PendingRecordData, readRecord, type RequestIdentity, type RequestRecordData, sameIdentity, type ToldFact } from "./records.ts";
+import { declaredToolNames, leadingToolsItem, loadedInList, type RecordedRequest } from "./wire.ts";
+
+export type { EpochCause };
+
+/** A recorded request as the fold rebuilds it: the wire list and head, the context messages it covered, and where it was routed. */
+export interface FoldedRequest extends RecordedRequest {
+	covers?: Coverage;
+	routing?: string;
+}
+
+export interface LedgerFold {
+	/** True when the next request opens an epoch: no request yet, a compaction or `epoch` record since, or a changed identity. */
+	opensEpoch: boolean;
+	/** Why, when `opensEpoch`. */
+	cause?: EpochCause;
+	/** The last request on the branch that counts (its reply followed it and stayed), rebuilt from its records. */
+	lastRequest: FoldedRequest | undefined;
+	/** Every element hash already stored on the branch. */
+	knownHashes: Set<string>;
+	/** Every tool the branch's counted requests declared, in the order of its first declaration: the order an epoch renders (ledger/wire.ts). */
+	toolOrder: string[];
+	/** Told facts in the current epoch: kind ("tools", "skills", `CALLABLE_TOOLS`) to names. */
+	told: Map<string, Set<string>>;
+	/** Modes told in the current epoch, by key: on or off as last told. */
+	modes: Map<string, boolean>;
+	/** Whole-text blocks told in the current epoch, by key: the content hash of the text last told. */
+	blocks: Map<string, string>;
+	/** Produced and not yet sent, latest per key, in branch order. */
+	pending: PendingRecordData[];
+}
+
+/** The told kind of the tools announced by a callable `tool_addition` (also folded under "tools"). */
+export const CALLABLE_TOOLS = "tools:callable";
+
+/** What an epoch has told the model, as the fold keeps it and a render reads it. */
+export interface ToldState {
+	told: Map<string, Set<string>>;
+	modes: Map<string, boolean>;
+	blocks: Map<string, string>;
+}
+
+/** Add `facts` to what the epoch told: a mode or block as last told, names as a union (callable tools also under `CALLABLE_TOOLS`), tools told gone taken out. */
+export function tellFacts(into: ToldState, facts: readonly ToldFact[]): void {
+	for (const fact of facts) {
+		if (fact.kind === "mode") into.modes.set(fact.key, fact.on);
+		else if (fact.kind === "block") into.blocks.set(fact.key, fact.hash);
+		else if (fact.kind === "tools" && fact.removed) {
+			for (const kind of ["tools", CALLABLE_TOOLS]) for (const name of fact.names) into.told.get(kind)?.delete(name);
+		} else {
+			const kinds = fact.kind === "tools" && fact.callable ? ["tools", CALLABLE_TOOLS] : [fact.kind];
+			for (const kind of kinds) {
+				const set = into.told.get(kind) ?? new Set<string>();
+				for (const name of fact.names) set.add(name);
+				into.told.set(kind, set);
+			}
+		}
+	}
+}
+
+/** What `facts` tell an epoch that starts empty. */
+export function toldOf(facts: readonly ToldFact[]): ToldState {
+	const state: ToldState = { told: new Map(), modes: new Map(), blocks: new Map() };
+	tellFacts(state, facts);
+	return state;
+}
+
+/** The request a record describes, rebuilt on its base; undefined when the branch lacks a body it needs. */
+function rebuild(data: RequestRecordData, base: RecordedRequest | undefined, blobs: ReadonlyMap<string, unknown>): FoldedRequest | undefined {
+	const kept = base?.list.length ?? 0;
+	if (data.keep > kept || !blobs.has(data.head) || !data.append.every((hash) => blobs.has(hash))) return undefined;
+	const head = blobs.get(data.head);
+	if (typeof head !== "object" || head === null || Array.isArray(head)) return undefined;
+	return {
+		identity: data.identity,
+		list: [...(base?.list.slice(0, data.keep) ?? []), ...data.append.map((hash) => blobs.get(hash))],
+		head: head as Record<string, unknown>,
+		hashes: [...(base?.hashes.slice(0, data.keep) ?? []), ...data.append],
+		headHash: data.head,
+		...(data.covers ? { covers: data.covers } : {}),
+		...(data.routing ? { routing: data.routing } : {}),
+	};
+}
+
+/**
+ * What a request that does not count takes back: the told state, the epoch
+ * cause and the identity from before it. The told state is held by reference,
+ * not copied: nothing tells into it while a checkpoint is live (an epoch or a
+ * changed identity replaces it, and told records riding a request wait in its
+ * `facts` until it counts, when its checkpoint is dropped).
+ */
+interface FoldCheckpoint {
+	told: ToldState;
+	resetSinceBase: EpochCause | undefined;
+	lastIdentity: RequestIdentity | undefined;
+}
+
+/** The ids of the entries pi omitted from the model's view: a `context_edit` with no replacement. */
+function omittedIds(branch: readonly EntryLike[]): Set<string> {
+	const ids = new Set<string>();
+	for (const entry of branch) if (entry.type === "context_edit" && entry.replacement === null && typeof entry.targetId === "string") ids.add(entry.targetId);
+	return ids;
+}
+
+/** The tools a request declares at its head: its head's declarations, then a leading Responses `additional_tools` item's (pi 1.4.0 and later). */
+function headToolNames(request: Pick<RecordedRequest, "head" | "list">): string[] {
+	const item = leadingToolsItem(request.head.tools, request.list);
+	return [...declaredToolNames(request.head), ...(item ? loadedInList([item]) : [])];
+}
+
+/** Fold the branch (root first, as `getBranch()` returns it). `identity` is the live request identity, for epoch detection. */
+export function foldBranch(branch: readonly EntryLike[], identity?: RequestIdentity): LedgerFold {
+	const blobs = new Map<string, unknown>();
+	let told = toldOf([]);
+	const produced: { item: PendingRecordData; index: number }[] = [];
+	const consumed = new Set<string>();
+	const omitted = omittedIds(branch);
+	/** The index of the last compaction on the branch: an older `untilCompaction` pending item is stale. */
+	let lastCompaction = -1;
+	let base: FoldedRequest | undefined;
+	const toolOrder = new Set<string>();
+	/** The head hash of the last counted request, and its first list element's (a leading tools item's), whose declarations `toolOrder` holds. */
+	let orderedHead: string | undefined;
+	/** A compaction or `epoch` record after the base: the next request renders everything again. */
+	let resetSinceBase: EpochCause | undefined;
+	let lastIdentity: RequestIdentity | undefined;
+	/** The state before the last `epoch` record, while nothing but its own request may follow it. */
+	let beforeEpoch: { index: number; checkpoint: FoldCheckpoint } | undefined;
+	/** The latest request and what rode it, until its reply settles it. */
+	let open: { request: FoldedRequest | undefined; consumed: string[]; facts: ToldFact[]; checkpoint: FoldCheckpoint } | undefined;
+
+	const tell = (facts: readonly ToldFact[]) => tellFacts(told, facts);
+	const checkpoint = (): FoldCheckpoint => ({ told, resetSinceBase, lastIdentity });
+	/** A new epoch starts with nothing told: a new state, so a checkpoint keeps the one it holds. */
+	const resetTold = () => {
+		told = toldOf([]);
+	};
+	/** Count what the open request carried and make it the base; a request without its reply takes back what it changed. */
+	const settle = (counts: boolean) => {
+		if (!open) return;
+		if (counts) {
+			for (const id of open.consumed) consumed.add(id);
+			tell(open.facts);
+			if (open.request) {
+				base = open.request;
+				resetSinceBase = undefined;
+				// Requests mostly share their head: the last counted one's adds no name.
+				const heading = `${open.request.headHash}:${open.request.hashes[0] ?? ""}`;
+				if (heading !== orderedHead) for (const name of headToolNames(open.request)) toolOrder.add(name);
+				orderedHead = heading;
+			}
+		} else {
+			({ told, resetSinceBase, lastIdentity } = open.checkpoint);
+		}
+		open = undefined;
+	};
+
+	branch.forEach((entry, index) => {
+		const attached = beforeEpoch?.index === index - 1 ? beforeEpoch : undefined;
+		beforeEpoch = undefined;
+		if (entry.type === "message") {
+			// A request's reply is the first message after its record: pi stores the
+			// prompt before the request and the tool results after the reply, so a
+			// user message first (a btw fork's side question, copied mid-stream) means
+			// no reply. pi drops an errored or aborted reply from the next request
+			// (transform-messages.js) and omits a recovered one.
+			const message = entry.message;
+			settle(message?.role === "assistant" && message.stopReason !== "error" && message.stopReason !== "aborted" && !omitted.has(entry.id));
+			return;
+		}
+		if (entry.type === "compaction") {
+			lastCompaction = index;
+			settle(false);
+			resetTold();
+			resetSinceBase = "compaction";
+			return;
+		}
+		const record = readRecord(entry);
+		if (!record) return;
+		switch (record.kind) {
+			case "epoch":
+				settle(false);
+				beforeEpoch = { index, checkpoint: checkpoint() };
+				resetTold();
+				resetSinceBase = record.data.cause;
+				return;
+			case "request": {
+				settle(false);
+				const data = record.data;
+				for (const [hash, body] of Object.entries(data.blobs)) if (!blobs.has(hash)) blobs.set(hash, body);
+				const before = attached?.checkpoint ?? checkpoint();
+				if (lastIdentity && !sameIdentity(lastIdentity, data.identity)) resetTold();
+				lastIdentity = data.identity;
+				open = { request: rebuild(data, base, blobs), consumed: data.consumed, facts: [], checkpoint: before };
+				return;
+			}
+			case "told":
+				if (open) open.facts.push(...record.data.facts);
+				else tell(record.data.facts);
+				return;
+			case "pending":
+				produced.push({ item: record.data, index });
+				return;
+		}
+	});
+	settle(false);
+
+	const latestByKey = new Map<string, number>();
+	for (const { item, index } of produced) if (item.key !== undefined) latestByKey.set(item.key, index);
+	const pending = produced
+		.filter(({ item, index }) => item.key === undefined || latestByKey.get(item.key) === index)
+		.filter(({ item, index }) => !consumed.has(item.id) && !(item.untilCompaction && index < lastCompaction))
+		.map(({ item }) => item);
+
+	const changed = (b: RequestIdentity, live: RequestIdentity): EpochCause | undefined =>
+		b.model !== live.model || b.api !== live.api || b.provider !== live.provider
+			? "model"
+			: b.auth !== live.auth
+				? "auth"
+				: b.effortMarkers !== live.effortMarkers
+					? "effort"
+					: undefined;
+	// A compaction with no settled request before it (the only request failed, a
+	// session recorded before the ledger) still opens the compaction's epoch.
+	const cause: EpochCause | undefined = resetSinceBase ?? (!base ? "first" : identity ? changed(base.identity, identity) : undefined);
+	return {
+		opensEpoch: cause !== undefined,
+		...(cause ? { cause } : {}),
+		lastRequest: base,
+		knownHashes: new Set(blobs.keys()),
+		toolOrder: [...toolOrder],
+		...told,
+		pending,
+	};
+}

package/extensions/lib/ledger/layout.ts

@@ -0,0 +1,72 @@
+/**
+ * The final layout pass over a request's list (findings §52). On Anthropic a
+ * system message with content must come after a user message and reach an
+ * assistant message, or the end, through system messages only; a request
+ * that breaks the rule is a 400, every time, so a session that sends one
+ * cannot continue. Several builders put system messages in a list (the
+ * stack's system message, `<total_tokens>` countdowns, `tool_addition`
+ * notices) and several append to a list built earlier (a side call's prompt
+ * after a captured request, a fork's task after its parent's, hook context
+ * after a prompt). Instead of each checking what comes after, this pass runs
+ * last and makes the layout valid by construction: a run of system messages
+ * that a user message follows moves down to just before the next assistant
+ * message, or to the end, ahead of the trailing directives pi-ai appends.
+ *
+ * Only elements from `from` on move (a request's recorded prefix must keep its
+ * bytes); the system run that ends the prefix counts as new, since what comes
+ * after it is.
+ *
+ * Pure: no pi imports.
+ */
+import { isObject } from "./records.ts";
+import { appendPoint } from "./wire.ts";
+
+const roleOf = (element: unknown) => (isObject(element) ? element.role : undefined);
+
+/** A system message that is not the directive-only form, which may sit anywhere. */
+function isContentSystem(element: unknown): boolean {
+	if (roleOf(element) !== "system" || !isObject(element)) return false;
+	const content = element.content;
+	return Array.isArray(content) || typeof content === "string" ? content.length > 0 : content !== undefined;
+}
+
+/** Whether the system run starting at `index` reaches a non-system element that is not an assistant message. */
+function strandedAt(list: readonly unknown[], index: number): boolean {
+	let next = index + 1;
+	while (next < list.length && roleOf(list[next]) === "system") next++;
+	return next < list.length && roleOf(list[next]) !== "assistant";
+}
+
+/** `list` with no stranded system message at or after `from`: the input itself when nothing moves. */
+export function settleSystemMessages<T>(list: readonly T[], api: string, from = 0): readonly T[] {
+	if (api !== "anthropic-messages") return list;
+	let start = Math.max(0, Math.min(from, list.length));
+	while (start > 0 && roleOf(list[start - 1]) === "system") start--;
+	if (!list.some((element, index) => index >= start && isContentSystem(element) && strandedAt(list, index))) return list;
+	const out = list.slice(0, start);
+	let held: T[] = [];
+	for (let i = start; i < list.length; i++) {
+		const element = list[i];
+		if (isContentSystem(element) && strandedAt(list, i)) {
+			held.push(element);
+			continue;
+		}
+		if (roleOf(element) === "assistant" && held.length > 0) {
+			out.push(...held);
+			held = [];
+		}
+		out.push(element);
+	}
+	if (held.length > 0) {
+		out.splice(Math.max(start, appendPoint(out, api)), 0, ...held);
+	}
+	return out;
+}
+
+/** `payload` with its list settled from `from` on; the payload itself when nothing moves. */
+export function settlePayload(payload: Record<string, unknown>, api: string, key: string, from = 0): Record<string, unknown> {
+	const list = payload[key];
+	if (!Array.isArray(list)) return payload;
+	const settled = settleSystemMessages(list, api, from);
+	return settled === list ? payload : { ...payload, [key]: settled };
+}