@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/engines/pi/retry-event.js

@@ -0,0 +1,15 @@
+/** Manual compaction retries are session-scoped; retries inside an invoke carry its runId. */
+export function toRetryScheduledEvent(event, runId) {
+    return {
+        type: "retry_scheduled",
+        timestamp: Date.now(),
+        ...(runId === undefined ? {} : { runId }),
+        data: {
+            operation: event.type === "auto_retry_start" ? "assistant" : "compaction",
+            attempt: event.attempt,
+            maxAttempts: event.maxAttempts,
+            delayMs: event.delayMs,
+            error: event.errorMessage,
+        },
+    };
+}

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

@@ -1,10 +1,9 @@
 /**
  * The shared definition-aware session builder: open a directory's assembled agent as a resident pi
- * `AgentSessionRuntime`. Extracted from chat.ts (session-control Phase 0) as the proof of the
- * assembly seam — independently instantiable, running the SAME agent that `dev`/`start` serve. The
- * TUI (chat.ts) is its one consumer: the session control plane (Phases 1–3) was built on the invoke
- * pipeline instead of this resident runtime, so control-plane observation covers invoke-driven runs
- * and deliberately not chat sessions (design §10/§15).
+ * `AgentSessionRuntime`, running the SAME agent that `dev`/`start` serve. The TUI (chat.ts) is its
+ * one consumer: the session control plane was built on the invoke pipeline instead of this resident
+ * runtime, so control-plane observation covers invoke-driven runs and deliberately not chat sessions
+ * (docs/design/session-control.md §10, §15).
  *
  * FIDELITY: pi's vanilla discovery (AGENTS.md walk to repo root, machine-global skills/extensions)
  * is suppressed; fastagent's assembly is INJECTED into pi's session:
@@ -28,16 +27,15 @@
  * workspace.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { SessionManager, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
-import { definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
+import { SessionManager, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { bindPiSession, definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
 import { resolveModel } from "./config.js";
 import { assembleSystemPrompt, piBasePrompt } from "./create.js";
 import { canonicalPath, loadAgentDefinition, loadExtensionPaths } from "./definition.js";
-import { createPiModelRuntime, probeAuthSource } from "./models.js";
-import { log, reportModuleLoadFailures } from "../../log.js";
-import { agentSessionManager, sessionToolActivation, turnContext, } from "./tool-context.js";
+import { createPiModelRuntime } from "./models.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "./report.js";
 import { resolveAgentAssembly } from "./open.js";
 /**
@@ -51,14 +49,9 @@ sessionManager) {
     async function resolveAssembly(cwd) {
         // The shared front half — the SAME placement/config/model-spec/tool/auth resolution the serving
         // opener uses (open.ts); those inputs cannot drift between the two consumption shapes.
-        // (Definition→prompt assembly is NOT shared: serving re-reads live per invoke, this runtime is a
-        // startup snapshot and pi appends skills/env itself — see the header.) `tools` arrives with
-        // search_tools applied; deferral is EMULATED below like serving
-        // (what you iterate is what you serve): the initial active set excludes deferred tools (applied
-        // on the session in createRuntime — pi's session starts all-active), and the activation bridge
-        // above rides the same turn context, so the SAME search_tools works against pi's AgentSession
-        // instead of the served one.
-        const { config, modelSpec, agentDir, authPath, stateRoot, tools, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
+        // Serving re-reads the definition per invoke; chat keeps a startup snapshot. Both pass identity
+        // and project context to Pi, which appends skills/cwd. `tools` already includes search_tools.
+        const { config, modelSpec, agentDir, authPath, stateRoot, tools, toolCollisions, toolFailures } = await resolveAgentAssembly(cwd, options);
         reportToolCollisions(toolCollisions);
         reportModuleLoadFailures(toolFailures);
         // ONE hub owns model resolution AND per-request auth; see models.ts.
@@ -71,33 +64,6 @@ sessionManager) {
         // Assembly-time, like serving's: this whole function is memoized, so the scan and its warnings
         // happen once per runtime rather than per session rebuild (/new, /resume, fork).
         const extensionPaths = await loadExtensionPaths(agentDir, { cwd, env });
-        // fastagent mounts pi's complete coding set itself; `noTools: "builtin"` below keeps the runtime
-        // from adding duplicate copies.
-        // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts
-        // it). Each execute runs inside the turn context with the CURRENT session's activation bridge — the
-        // assembly is memoized across /new//resume/fork rebuilds while the session changes, so the bridge
-        // resolves through sessionRef at call time, exactly like the serving path resolves its session.
-        const customToolDefs = tools.map((t) => ({
-            name: t.name,
-            label: t.name,
-            description: t.description ?? "",
-            parameters: t.parameters,
-            // Propagate the execution mode — an activating tool (the builtin loader) declares "sequential"
-            // so pi serializes its batch; without this, pi's outer active-set diff double-stamps parallels.
-            executionMode: t.executionMode,
-            execute: (id, params, signal) => {
-                const bound = sessionRef.current;
-                // Unreachable by construction (createRuntime sets sessionRef before any turn can run a tool).
-                // Throw rather than silently run outside the turn context — that would disguise a broken
-                // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
-                if (!bound)
-                    throw new Error("tool executed before its session was built (lifecycle invariant broken)");
-                return turnContext.run({ cwd, sessionManager: bound.sessionManager, tools: bound.activation }, 
-                // Lower-level MountedTools may consume the fifth-argument env. Directory coding tools are
-                // cwd-bound and ignore it; authored tools read FastAgent's turnContext instead.
-                () => t.execute(id, params, signal, undefined, { env }));
-            },
-        }));
         // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
         // them here would duplicate them).
         const systemPrompt = assembleSystemPrompt({
@@ -107,14 +73,11 @@ sessionManager) {
         return {
             modelRuntime,
             modelSpec,
-            authPath,
             // Serving honors config.thinkingLevel (config → L2); the resident session must too (fidelity).
             thinkingLevel: config.thinkingLevel,
             definition,
             extensionPaths,
-            customTools: tools,
-            customToolDefs,
-            deferredToolNames,
+            tools,
             systemPrompt,
         };
     }
@@ -124,15 +87,6 @@ sessionManager) {
     // load edits. And keep it workspace-scoped — `.env` is process-global, so a switch to another cwd
     // would leak env or require mutating global env at runtime.
     const rootCwd = canonicalPath(dir);
-    // The CURRENT pi session + its activation bridge, BOUND TOGETHER — rebuilt on /new//resume/fork
-    // while the memoized assembly (and its tool execute closures) stays. The bridge shares the
-    // session's lifetime because a tool call has to see what the previous one activated. Note on
-    // parallel batches: pi wraps SDK customTools in its own before/after active-set diff, so an
-    // activating tool must carry `executionMode: "sequential"` (the builtin loader does) — pi then runs
-    // the whole batch serially and the outer diff sees correct snapshots.
-    // NO activation record here: pi's chat session has nowhere to put one (see sessionToolActivation's
-    // `onActivated`), which is the documented divergence from serving — a resumed chat re-discovers.
-    const sessionRef = {};
     let assembly;
     const assemblyFor = (cwd) => {
         // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would
@@ -144,12 +98,8 @@ sessionManager) {
         assembly ??= resolveAssembly(rootCwd);
         return assembly;
     };
-    // The credential hint belongs to the RUNTIME, not to each session it builds: model resolution
-    // moved into createRuntime (extensions must load first), and repeating this on every /new,
-    // /resume and fork would nag about a setting that did not change.
-    let credentialHintShown = false;
     const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { modelRuntime, modelSpec, authPath, thinkingLevel, definition, extensionPaths, customToolDefs, deferredToolNames, systemPrompt, } = await assemblyFor(cwd);
+        const { modelRuntime, modelSpec, thinkingLevel, definition, extensionPaths, tools, systemPrompt } = await assemblyFor(cwd);
         // Per session, NOT memoized with the assembly: pi replaces the session on /new, /resume and
         // fork, and its extension contract is that the replacement gets freshly loaded extensions
         // rather than the previous session's objects. The expensive halves (model hub, auth) are shared
@@ -172,62 +122,25 @@ sessionManager) {
         // AFTER the services, because an extension may be what defines the model. `registerProvider()`
         // is pi's documented way for one to add providers, and extensions do not execute until the
         // services are built — resolving first fails a definition whose configured model comes from its
-        // own extension with a bare "unknown model", after warning about credentials for a provider
-        // that does not exist yet.
-        //
-        // MIGRATION HINT (deliberate breaking change): chat historically used pi's own `~/.pi` auth; it
-        // now reads the agent's credential file like every other command. Probe the RESOLVED model's
-        // provider through the normal resolution path (stored credential OR env var — an env-authed
-        // user is fine and must not be warned): only when that provider has no usable auth AND pi's old
-        // file exists does the bare provider error get its cause named.
-        if (!credentialHintShown &&
-            (await probeAuthSource(modelRuntime, modelSpec)) === undefined &&
-            existsSync(join(getAgentDir(), "auth.json"))) {
-            credentialHintShown = true;
-            log.warn(`[fastagent] no credentials for ${modelSpec} in ${authPath} — this runtime no longer reads ` +
-                `pi's ~/.pi auth; run \`fastagent login\` (or /login in the TUI) to store credentials for this agent`);
-        }
+        // own extension with a bare "unknown model".
         const model = resolveModel(modelRuntime, modelSpec);
-        const result = await createAgentSessionFromServices({
+        // The same bind serving performs, minus the activation record: pi's chat session has nowhere to
+        // put one, which is the documented divergence — a resumed chat re-discovers via search_tools.
+        // NOT bound to the host here: InteractiveMode.bindCurrentSessionExtensions() calls
+        // session.bindExtensions() with the TUI's uiContext, abort handler and command actions — binding
+        // here too would emit session_start twice per chat, so an extension opening a resource on start
+        // would open two.
+        const result = await bindPiSession({
             services,
             sessionManager,
             sessionStartEvent,
             model,
             thinkingLevel,
-            // NO `tools` allowlist. It would freeze the tool set at build time, and pi lets an extension
-            // register from `session_start`, a command, or any handler — those names would not be in a
-            // startup snapshot, so `refreshTools()` would filter them straight back out and the extension
-            // would look like it did nothing. `noTools: "builtin"` gets the same guarantee the allowlist
-            // was really there for (the machine's `defaultTools` setting cannot add pi's own copies on top
-            // of ours) without freezing anything.
-            noTools: "builtin",
-            customTools: customToolDefs,
+            tools,
+            // A tool must see one spelling of the workspace, including when opened through a symlink.
+            cwd: rootCwd,
+            recordActivations: false,
         });
-        sessionRef.current = {
-            session: result.session,
-            sessionManager: agentSessionManager(result.session, result.session.sessionManager.getSessionId()),
-            activation: sessionToolActivation(result.session),
-        };
-        // NOT bound here: the HOST does it. InteractiveMode.bindCurrentSessionExtensions() calls
-        // session.bindExtensions() with the TUI's uiContext, abort handler and command actions — binding
-        // here too would emit session_start twice per chat, so an extension opening a resource on start
-        // would open two.
-        // Deferral emulation: pi starts THIS agent's tools active — every coding tool it mounted, plus
-        // every custom and extension tool. So narrow by SUBTRACTING the deferred names from whatever is
-        // active, rather than stating a set: an exact-set-equality gate would silently stop narrowing the
-        // day pi activates one more.
-        //
-        // Applied on EVERY build including /resume: pi's chat session does not record activations (its
-        // SessionContext has no activeToolNames), so "restore prior activations" is not implementable
-        // here — deferral stays consistently ON and a resumed conversation re-discovers via search_tools
-        // (a documented divergence from serving, where activations persist in the session). The deferred
-        // SET comes from the shared assembly (one definition of "deferred"), never recomputed here.
-        if (deferredToolNames.length > 0) {
-            const active = result.session.getActiveToolNames();
-            if (deferredToolNames.some((n) => active.includes(n))) {
-                result.session.setActiveToolsByName(active.filter((n) => !deferredToolNames.includes(n)));
-            }
-        }
         return { ...result, services, diagnostics: services.diagnostics };
     };
     const runtime = await createAgentSessionRuntime(createRuntime, {

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

@@ -12,22 +12,17 @@
  * Writes take the same lease as runs. Without boundary wiring they reject before acceptance with
  * `unsupported_capability` — a client gating on `capabilities()` never sends them.
  */
-import { type ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
 import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
 import type { SessionObserver, Lease } from "./turn-kit.ts";
 import type { AnyModel } from "./models.ts";
 import type { PiAgentSessionFactory } from "./invoke-session.ts";
 import type { PiSessionRecordStore } from "./session-store.ts";
-/** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
- *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
- *  has its buffer FROZEN at the cap (memory bounded — the actual goal: ≈10k small events ≈ a few
- *  MB worst case per stuck connection) and its subscription marked closed. The close is observed
- *  via pulls — which a stalled connection by definition does not make — so a consumer that RESUMES
- *  pulling first drains the frozen backlog, then gets done (no buffered event dropped), while a
- *  permanently stalled one holds the frozen buffer until its TCP connection dies. Recovery either
- *  way is the standard reconnect+backfill, semantically lossless. */
+/** Per-subscriber backlog limits: event count and UTF-8 JSON bytes. Overflow freezes the accepted
+ *  prefix; the reader drains it before seeing done, then reconnects and backfills via entries(). */
 export declare const SUBSCRIBER_BUFFER_CAP = 10000;
+export declare const SUBSCRIBER_BUFFER_BYTES: number;
 /** What the plane's writes (`update` / `compact` / `fork` / `delete`) need — the SAME instances the
  *  agent assembly uses: the lease (a write must not race a run), the model registry (validation +
  *  allowedModels), and the session factory (compaction is a model call). Writes go through the
@@ -49,15 +44,12 @@ export interface PiBoundaryWiring {
 export interface CreatePiSessionControlOptions {
     /** Read-only access to the durable session records (the same root the agent writes). */
     sessions: PiSessionRecordStore;
-    /** Boundary-mutation wiring, as a LAZY thunk: the hub's observer must exist before the agent
-     *  assembly that produces these parts, so the hub asks for them at dispatch time instead
-     *  (assembly completes before any dispatch can arrive). Absent / undefined → boundary commands
-     *  are gated off in `capabilities()` and rejected `unsupported_capability`. */
-    boundary?: () => PiBoundaryWiring | undefined;
-    /** The definition's names, as a LAZY thunk for the same reason {@link boundary} is one (the hub
-     *  exists before the assembly that can read a definition) — and async because the definition is
-     *  live: this must re-read it, not close over a boot snapshot, or `commands()` would advertise a
-     *  list the next turn no longer runs.
+    /** Boundary-mutation wiring — the assembly's own parts. Absent → boundary commands are gated off
+     *  in `capabilities()` and rejected `unsupported_capability`. */
+    boundary?: PiBoundaryWiring;
+    /** The definition's names, as an async thunk because the definition is live: this must re-read it,
+     *  not close over a boot snapshot, or `commands()` would advertise a list the next turn no longer
+     *  runs.
      *
      *  OPTIONAL because absence is a TRUE answer for the assembly that omits it: a hub over an L1
      *  agent (`createPiAgent({ model, instructions, tools })`) has no definition and therefore no

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

@@ -1,25 +1,28 @@
-/**
- * The pi implementation of the session control plane. `createPiSessionControl` returns the neutral
- * `SessionControl` plus the {@link SessionObserver} to plug into the invoke pipeline
- * (`createPiAgent({ observer })`).
- *
- * It holds no durable state of its own: live truth comes from the event stream (plus the
- * {@link RunControls} a `run_started` carries), durable truth from {@link PiSessionRecordStore} —
- * which is also what performs every write, so how a record takes a property is not knowledge this
- * file has. What it owns is the vocabulary: capability gating, the lease, error codes, and the
- * events its own writes emit.
- *
- * Writes take the same lease as runs. Without boundary wiring they reject before acceptance with
- * `unsupported_capability` — a client gating on `capabilities()` never sends them.
- */
-import { prepareCompaction } from "@earendil-works/pi-agent-core";
+import { findCutPoint, getLatestCompactionEntry, sessionEntryToContextMessages, } from "@earendil-works/pi-coding-agent";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, isAddressableSession, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, PARTIAL_UPDATE_CODE, UPDATE_FIELDS, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
 import { listModels } from "./config.js";
 import { forkProvenance, isNavigable, publishedLeaf } from "./session-markers.js";
+import { toRetryScheduledEvent } from "./retry-event.js";
 import { THINKING_LEVELS, activePath, resolveSessionSettings } from "./session-settings.js";
 import { log } from "../../log.js";
+/** Admission uses coding-agent's cut point and context rules, including a split-turn prefix.
+ *  Its prepareCompaction is private; agent-core's namesake uses a different journal format. */
+function hasCompactableHistory(path, keepRecentTokens) {
+    if (path.at(-1)?.type === "compaction")
+        return false;
+    const previous = getLatestCompactionEntry(path);
+    let start = 0;
+    if (previous) {
+        const kept = path.findIndex((entry) => entry.id === previous.firstKeptEntryId);
+        start = kept >= 0 ? kept : path.indexOf(previous) + 1;
+    }
+    const { firstKeptEntryIndex } = findCutPoint(path, start, path.length, keepRecentTokens);
+    return path
+        .slice(start, firstKeptEntryIndex)
+        .some((entry) => entry.type !== "compaction" && sessionEntryToContextMessages(entry).length > 0);
+}
 // ── Entry normalization (durable plane) ──────────────────────────────────────
 /** Concatenated plain text of a message's content blocks (the L0 rendering payload). A custom
  *  AgentMessage role may carry no `content` at all — that reads as empty, not a crash. */
@@ -76,16 +79,11 @@ function toSessionEntry(entry, parentId) {
     return { ...base, kind: entry.type, data: {} };
 }
 // ── Live fan-out (events plane) ──────────────────────────────────────────────
-/** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
- *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
- *  has its buffer FROZEN at the cap (memory bounded — the actual goal: ≈10k small events ≈ a few
- *  MB worst case per stuck connection) and its subscription marked closed. The close is observed
- *  via pulls — which a stalled connection by definition does not make — so a consumer that RESUMES
- *  pulling first drains the frozen backlog, then gets done (no buffered event dropped), while a
- *  permanently stalled one holds the frozen buffer until its TCP connection dies. Recovery either
- *  way is the standard reconnect+backfill, semantically lossless. */
+/** Per-subscriber backlog limits: event count and UTF-8 JSON bytes. Overflow freezes the accepted
+ *  prefix; the reader drains it before seeing done, then reconnects and backfills via entries(). */
 export const SUBSCRIBER_BUFFER_CAP = 10_000;
-/** One subscriber's push→pull queue, capped at {@link SUBSCRIBER_BUFFER_CAP}. `close()` settles a
+export const SUBSCRIBER_BUFFER_BYTES = 8 * 1024 * 1024;
+/** One subscriber's bounded push→pull queue. `close()` settles a
  *  pending pull — an async generator suspended on a quiet stream cannot be ended by `return()`
  *  alone (it queues behind the never-settling await), so teardown needs this explicit door. */
 class Subscriber {
@@ -96,7 +94,9 @@ class Subscriber {
     constructor(session) {
         this.session = session;
     }
+    // Serialized snapshots cannot grow when a producer later mutates its event or tool result.
     buffer = [];
+    bufferedBytes = 0;
     // A QUEUE of waiters, not a single slot: concurrent next() calls are contract-legal (any wrapper
     // may poll twice), and a single `wake` field would let the second await overwrite the first's
     // resolver — hanging the first next() forever. Every wake flushes all waiters; each re-checks the
@@ -112,12 +112,15 @@ class Subscriber {
     push(event) {
         if (this.closed)
             return;
-        if (this.buffer.length >= SUBSCRIBER_BUFFER_CAP) {
-            log.warn(`[fastagent] session-control subscriber for session "${this.session}" is ${SUBSCRIBER_BUFFER_CAP} events behind — no further events buffered; its stream ends after draining the backlog (or at connection death), then the client resyncs via entries()`);
+        const json = JSON.stringify(event);
+        const bytes = Buffer.byteLength(json);
+        if (this.buffer.length >= SUBSCRIBER_BUFFER_CAP || this.bufferedBytes + bytes > SUBSCRIBER_BUFFER_BYTES) {
+            log.warn(`[fastagent] session-control subscriber for session "${this.session}" exceeded its buffer limit (${SUBSCRIBER_BUFFER_CAP} events / ${SUBSCRIBER_BUFFER_BYTES} bytes; ${this.bufferedBytes} bytes queued, ${bytes} incoming); its stream ends after draining the backlog, then the client resyncs via entries()`);
             this.close();
             return;
         }
-        this.buffer.push(event);
+        this.buffer.push({ json, bytes });
+        this.bufferedBytes += bytes;
         this.flush();
     }
     close() {
@@ -126,8 +129,11 @@ class Subscriber {
     }
     async next() {
         while (true) {
-            if (this.buffer.length > 0)
-                return { done: false, value: this.buffer.shift() };
+            const item = this.buffer.shift();
+            if (item) {
+                this.bufferedBytes -= item.bytes;
+                return { done: false, value: JSON.parse(item.json) };
+            }
             if (this.closed)
                 return { done: true, value: undefined };
             await new Promise((resolve) => {
@@ -195,7 +201,7 @@ export function createPiSessionControl(options) {
             return (await options.commands?.()) ?? [];
         },
         capabilities: () => {
-            const b = boundary?.();
+            const b = boundary;
             return {
                 steering: true,
                 followUp: true,
@@ -227,7 +233,7 @@ export function createPiSessionControl(options) {
             // channel to explain itself. The fault is not swallowed — it surfaces where codes exist: the
             // next invoke fails (binding a session walks the same chain) and a boundary dispatch answers
             // `boundary_command_failed`. Here it is a server-side warn.
-            const b = boundary?.();
+            const b = boundary;
             let settings;
             if (opened && b) {
                 try {
@@ -455,7 +461,7 @@ export function createPiSessionControl(options) {
         const fields = named.filter((f) => patch[f] !== undefined);
         if (fields.length === 0)
             return { ok: true }; // an empty patch asks for nothing, and gets it
-        const b = boundary?.();
+        const b = boundary;
         if (!b)
             return unsupported(`update(${fields.join(", ")})`);
         // PAYLOAD validation first — before the session is even opened, and long before the lease: an
@@ -598,7 +604,7 @@ export function createPiSessionControl(options) {
      * finished{error} dressed as a failure — pi reports it as a throw from compact(), too late.
      */
     const compactOf = async (session, instructions) => {
-        const b = boundary?.();
+        const b = boundary;
         if (!b)
             return unsupported("compact()");
         const existing = await sessions.openIfExists(session);
@@ -628,14 +634,7 @@ export function createPiSessionControl(options) {
             // either reject a compaction pi would have run, or admit one it refuses — and its refusal
             // arrives too late to be a pre-acceptance answer.
             const path = bound.sessionManager.getBranch();
-            const prep = prepareCompaction(path, bound.settingsManager.getCompactionSettings());
-            if (!prep.ok)
-                throw prep.error;
-            // Empty is the same answer as absent: pi ships two prepareCompaction implementations
-            // (agent-core answers with a Result, coding-agent with undefined) and they disagree on which
-            // one an unsummarizable session gets. What they agree on is the CONTENT — no messages to
-            // summarize — so that is what the gate reads.
-            if (!prep.value || prep.value.messagesToSummarize.length === 0) {
+            if (!hasCompactableHistory(path, bound.settingsManager.getCompactionSettings().keepRecentTokens)) {
                 teardown();
                 release();
                 // A no-op, not a failure — its OWN code (the NO_ACTIVE_RUN pattern): a client must
@@ -656,37 +655,13 @@ export function createPiSessionControl(options) {
             release();
             return failed(error);
         }
-        // The door is the session's own compaction abort — a real one, unlike a summarization call with
-        // no signal: `abort` must reach the model call (run/compaction symmetry).
-        //
-        // pi builds the controller that makes it abortable AFTER an internal await, so an abort arriving
-        // in that window would find nothing to cancel and the compaction would run to completion — the
-        // client's cancel silently doing nothing. The intent is latched and re-applied until it takes
-        // (`isCompacting` reports when it has).
-        //
-        // The retry is DEFENSIVE: the window is one await wide, and the test below lands after it, so
-        // this loop is not what makes that test pass. It is here because the window is on the code path,
-        // not because it has been observed.
+        // Pi creates the abort controller after an await and emits compaction_start immediately after.
+        // Retain early cancellation until that event; there is no time limit on session startup.
         let aborted = false;
-        let running = true; // cleared when the compaction settles, however it settles
-        const applyAbort = async () => {
-            // WAIT for the controller rather than requiring it: an abort that arrives before pi builds one
-            // sees isCompacting false, and a loop that only runs WHILE compacting would exit immediately —
-            // leaving the intent unapplied in exactly the window it exists for.
-            for (let attempt = 0; attempt < 200 && running; attempt++) {
-                if (bound.isCompacting) {
-                    bound.abortCompaction();
-                    if (!bound.isCompacting)
-                        return; // it took
-                }
-                await new Promise((resolve) => setTimeout(resolve, 1));
-            }
-        };
         compacting.set(session, {
             abort: () => {
                 aborted = true;
                 bound.abortCompaction();
-                void applyAbort();
             },
         });
         emitOwn(session, { type: "compaction_started", timestamp: Date.now(), data: {} });
@@ -696,20 +671,12 @@ export function createPiSessionControl(options) {
             // backoff so a long gap is diagnosable (not confusable with a hang): as a session event for
             // attached observers, as a warn for server logs.
             const unsub = bound.subscribe((event) => {
+                if (event.type === "compaction_start" && event.reason === "manual" && aborted)
+                    bound.abortCompaction();
                 if (event.type !== "summarization_retry_scheduled")
                     return;
                 log.warn(`[fastagent] compaction retry ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms (session ${session}): ${event.errorMessage}`);
-                emitOwn(session, {
-                    type: "retry_scheduled",
-                    timestamp: Date.now(),
-                    data: {
-                        operation: "compaction",
-                        attempt: event.attempt,
-                        maxAttempts: event.maxAttempts,
-                        delayMs: event.delayMs,
-                        error: event.errorMessage,
-                    },
-                });
+                emitOwn(session, toRetryScheduledEvent(event));
             });
             try {
                 const done = await bound.compact(instructions);
@@ -721,7 +688,6 @@ export function createPiSessionControl(options) {
                 // failure still reads as aborted).
                 outcome = aborted ? { aborted: true } : { error: String(error) };
             }
-            running = false;
             unsub();
             teardown();
             // Release BEFORE emitting finished: a watcher seeing finished may act next — "finished ⇒ the
@@ -744,7 +710,7 @@ export function createPiSessionControl(options) {
         /** WHICH fork this is: source + branch point. Two forks of one session at different entries are
          *  different requests, so a retry of one must not be answered by the other. */
         const provenance = `${from}@${at}`;
-        const b = boundary?.();
+        const b = boundary;
         if (!b)
             return unsupported("fork()");
         // An id no client could then open: the empty string, `.` and `..` are not URL path segments
@@ -807,7 +773,7 @@ export function createPiSessionControl(options) {
         return { ok: true };
     };
     const deleteOf = async (session) => {
-        const b = boundary?.();
+        const b = boundary;
         if (!b)
             return unsupported("delete()");
         const existing = await sessions.openIfExists(session);

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

@@ -35,7 +35,7 @@ export interface SessionSettings {
     thinkingLevel: ThinkingLevel;
     /** What `update({ thinkingLevel })` accepts for this session. */
     availableThinkingLevels: string[];
-    /** Recorded but not honored — only the execution path reports it (as a warn). */
+    /** Recorded overrides that could not be applied. */
     dropped?: {
         model?: string;
         thinkingLevel?: {

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

@@ -49,7 +49,7 @@ export function resolveSessionSettings(entries, models, defaults) {
             dropped.model = `${recorded.model.provider}/${recorded.model.modelId}`;
     }
     const availableThinkingLevels = getSupportedThinkingLevels(model);
-    let thinkingLevel = defaults.thinkingLevel;
+    let thinkingLevel = clampThinkingLevel(model, defaults.thinkingLevel);
     if (recorded.thinkingLevel !== undefined) {
         const level = recorded.thinkingLevel;
         if (!THINKING_LEVELS.has(level)) {

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

@@ -85,10 +85,10 @@ interface AppliedProperties {
  * 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.
+ * Injective within this encoding — which is only sufficient because this store's records live in
+ * their own directory. A name this store did not write draws from the same character set and can
+ * still decode: a file called `s42` is also this encoding of `42`, so one directory would make some
+ * names ambiguous no matter how this side spells them.
  *
  * Readability is deliberate: `-1001234567890` becomes `s-1001234567890`, so an operator can still
  * tell which room a file belongs to.
@@ -110,24 +110,19 @@ export declare function callerSessionId(recordId: string): string | undefined;
  * 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.
+ * Records live in a subdirectory of their own, because a name this store did not write can still
+ * decode to a Caller id: a file called `s42` beside them is also this encoding of `42`, so a shared
+ * directory would answer `42` with a record it does not own. Only this directory is scanned, which
+ * makes this encoding's own injectivity sufficient — a record written before this store existed
+ * lies outside it and is never read.
  *
  * 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.
+ * conversation forks into two records. 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;