@fastagent-sh/fastagent 0.24.4 → 0.25.0

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

@@ -1,908 +0,0 @@
-// The L0 rendering payload reads message text the way the engine does — ONE reading, joined without a
-// separator because this payload is a transcript, not a preview line.
-import { contentText } from "@earendil-works/pi-ai";
-import * as Deferred from "effect/Deferred";
-import * as Effect from "effect/Effect";
-import * as Queue from "effect/Queue";
-import { PortFailure, port, portAbort, portCleanup, portError, portJoin } from "../../effect-port.js";
-import { acquireSession, acquireSessionLease } from "./session-effects.js";
-import { calculateContextTokens, estimateTokens, getLastAssistantUsage, } from "@earendil-works/pi-coding-agent";
-import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
-import { MISSING_MODEL_CODE, 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 { forkProvenance, isConversationMessage, isNavigable, publishedLeaf } from "./session-markers.js";
-import { entryImages, imageAt } from "./entry-images.js";
-import { answerOutcome, answerThinking, endsRun, } from "./turn-kit.js";
-import { startCompaction } from "./agent-session-factory.js";
-import { toRetryScheduledEvent } from "./retry-event.js";
-import { MissingModel, THINKING_LEVELS, activePath, describeModels, resolveSessionSettings, } from "./session-settings.js";
-import { log } from "../../log.js";
-// ── Usage (read from the record) ─────────────────────────────────────────────
-/**
- * What the newest answer cost and how full the context is, from the record rather than a live session (a served
- * session exists only during its run). The numbers are the provider's own, on the newest assistant pi counts as
- * carrying usage (`getLastAssistantUsage`). The context size adds pi's estimate of what followed that answer, which
- * after a finished turn is nothing: then it is exactly pi's `getContextUsage()`.
- *
- * `contextTokens` is omitted, never guessed, once a compaction or a context edit follows that answer: the provider's
- * count no longer describes the context (pi's own rule). pi then estimates from characters; this reports unknown
- * until the next response.
- */
-function sessionUsage(path, record, contextWindow) {
-    const usage = getLastAssistantUsage(path);
-    if (!usage)
-        return undefined;
-    let at = path.length - 1;
-    while (at >= 0) {
-        const entry = path[at];
-        if (entry?.type === "message" && entry.message.usage === usage)
-            break;
-        at--;
-    }
-    const answer = path[at];
-    const stale = path.slice(at + 1).some((entry) => entry.type === "compaction" || entry.type === "context_edit");
-    let contextTokens;
-    if (answer && !stale) {
-        let trailing = 0;
-        let after = false;
-        for (const { sourceEntry, messages } of record.buildSessionProjection().entries) {
-            if (after)
-                for (const message of messages)
-                    trailing += estimateTokens(message);
-            if (sourceEntry.id === answer.id)
-                after = true;
-        }
-        contextTokens = calculateContextTokens(usage) + trailing;
-    }
-    return {
-        inputTokens: usage.input,
-        outputTokens: usage.output,
-        cacheReadTokens: usage.cacheRead,
-        cacheWriteTokens: usage.cacheWrite,
-        cost: usage.cost.total,
-        ...(contextTokens !== undefined ? { contextTokens } : {}),
-        ...(contextWindow !== undefined && contextWindow > 0 ? { contextWindow } : {}),
-    };
-}
-// ── Entry normalization (durable plane) ──────────────────────────────────────
-/**
- * pi `PiSessionEntry` → neutral {@link SessionEntry}. Message entries map onto the guaranteed
- * kind vocabulary (user/assistant/tool) with a minimal render payload; every other engine record
- * keeps its pi type as an open-set kind with an EMPTY payload — present so `parentId` chains and
- * cursors stay intact, skippable by contract, and no pi message class leaks through the adapter.
- * One exception: `context_edit` carries `{ targetId, omitted }`, never the replacement content.
- */
-function toSessionEntry(entry, parentId) {
-    const base = {
-        id: entry.id,
-        parentId,
-        timestamp: Date.parse(entry.timestamp),
-    };
-    if (entry.type === "message") {
-        const m = entry.message;
-        if (m.role === "user") {
-            return { ...base, kind: "user", data: { text: contentText(m.content, ""), ...entryImages(entry.id, m) } };
-        }
-        if (m.role === "assistant") {
-            // `args` is what `tool_started` carries live (pi emits the call's recorded `arguments` there), so a reopened
-            // conversation shows the same call a watcher saw.
-            const toolCalls = m.content
-                .filter((b) => b.type === "toolCall")
-                .map((b) => ({ id: b.id ?? "", name: b.name ?? "", args: b.arguments ?? {} }));
-            const data = { text: contentText(m.content, "") };
-            if (toolCalls.length > 0)
-                data.toolCalls = toolCalls;
-            // The same text the live `message_delta { channel: "thinking" }` added up to (turn-kit.ts answerThinking).
-            const thinking = answerThinking(m);
-            if (thinking !== undefined)
-                data.thinking = thinking;
-            const outcome = answerOutcome(m);
-            if (outcome)
-                data.outcome = outcome;
-            return { ...base, kind: "assistant", data };
-        }
-        if (m.role === "toolResult") {
-            return {
-                ...base,
-                kind: "tool",
-                data: {
-                    toolCallId: m.toolCallId,
-                    toolName: m.toolName,
-                    isError: m.isError ?? false,
-                    text: contentText(m.content, ""),
-                    ...entryImages(entry.id, m),
-                    // Same flag as the live `tool_finished` (turn-kit.ts asksToEndRun).
-                    ...(endsRun(m) ? { terminate: true } : {}),
-                },
-            };
-        }
-        // Not a conversation turn (`isConversationMessage`): the engine's own `system` bookkeeping, or a custom
-        // AgentMessage role a channel/extension defined. Open-set kind with an EMPTY payload, skippable by contract —
-        // which is also what keeps the assembled prompt out of everything this plane publishes.
-        return { ...base, kind: `message:${m.role}`, data: {} };
-    }
-    // Which transcript entry the model no longer sees as written: `omitted` when it left the model context (pi's own
-    // abandoned retry and overflow attempts, or an extension's edit), otherwise its content was replaced. The target
-    // stays in the transcript either way, and the edit applies only on a path that contains it.
-    if (entry.type === "context_edit") {
-        return { ...base, kind: entry.type, data: { targetId: entry.targetId, omitted: entry.replacement === null } };
-    }
-    return { ...base, kind: entry.type, data: {} };
-}
-// ── Live fan-out (events plane) ──────────────────────────────────────────────
-/** 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;
-export const SUBSCRIBER_BUFFER_BYTES = 8 * 1024 * 1024;
-/**
- * One subscriber's bounded push→pull queue.
- *
- * The mechanics are Effect's, because both halves are things this class hand-rolled and got wrong
- * once each. `Queue.end` stops accepting offers, lets the reader drain what WAS accepted, and only
- * then reports done — which is both the overflow policy above and the door teardown needs (an async
- * generator suspended on a quiet stream cannot be ended by `return()` alone: that queues behind the
- * never-settling await). And a queue has a SET of takers, so two concurrent `next()` calls — legal,
- * any wrapper may poll twice — cannot overwrite each other's resolver.
- *
- * What stays here is the arithmetic Queue has no opinion on: the two backlog limits, and the JSON
- * snapshot (taken at push, so a producer that later mutates its event or tool result cannot grow a
- * queued one). Cost of the swap: one fiber per delivered event instead of an array shift, on a
- * stream that carries per-token deltas — cheap next to a model call, and paid only while someone is
- * attached.
- */
-class Subscriber {
-    /** For the overflow diagnostic only — a warn without the session is not actionable on a
-     *  multi-session serve. (Explicit assignment: TS parameter properties break Node's strip-only
-     *  type erasure, which the CLI runs under.) */
-    session;
-    constructor(session) {
-        this.session = session;
-    }
-    queue = Effect.runSync(Queue.unbounded());
-    buffered = 0;
-    bufferedBytes = 0;
-    ended = false;
-    push(event) {
-        if (this.ended)
-            return;
-        const json = JSON.stringify(event);
-        const bytes = Buffer.byteLength(json);
-        if (this.buffered >= 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;
-        }
-        Queue.offerUnsafe(this.queue, { json, bytes });
-        this.buffered++;
-        this.bufferedBytes += bytes;
-    }
-    close() {
-        this.ended = true;
-        Queue.endUnsafe(this.queue);
-    }
-    next() {
-        return Effect.runPromise(Queue.take(this.queue).pipe(Effect.map((item) => {
-            this.buffered--;
-            this.bufferedBytes -= item.bytes;
-            return { done: false, value: JSON.parse(item.json) };
-        }), Effect.catchTag("Done", () => Effect.succeed({ done: true, value: undefined }))));
-    }
-}
-/**
- * Build the observation hub. Wire `observer` into the SAME agent assembly that serves the sessions:
- *
- * ```ts
- * const { control, observer } = createPiSessionControl({ sessions });
- * const agent = createPiAgent({ ..., sessions, observer });
- * ```
- */
-export function createPiSessionControl(options) {
-    const { sessions, boundary } = options;
-    /** Live run state per session — derived purely from run_started/run_settled and the controls
-     *  registered with run_started. */
-    const active = new Map();
-    const subscribers = new Map();
-    /** Sessions with a manual compaction in flight — reported as `status: "compacting"`, keyed to
-     *  the summarization's AbortController so `abort` has a door into it (run/compaction symmetry:
-     *  both are model calls a client must be able to stop). Set at ADMISSION, cleared by the
-     *  detached task before `compaction_finished`. */
-    const compacting = new Map();
-    /** Fan an event out to this session's subscribers — shared by the observer (run events) and the
-     *  boundary mutations (session-level events, no runId). */
-    const fanOut = (session, event) => {
-        const subs = subscribers.get(session);
-        if (subs)
-            for (const sub of [...subs])
-                sub.push(event);
-    };
-    /** Emit a HUB-generated event: subscribers first, then the external tap — the boundary-event
-     *  half of a full-vocabulary tap (run events reach it through the observer composition). */
-    const emitOwn = (session, event) => {
-        fanOut(session, event);
-        try {
-            options.tap?.(session, event);
-        }
-        catch (error) {
-            // Same discipline as the data plane's observer guard: a broken tap is its own problem.
-            log.warn(`[fastagent] session-control tap threw (event ${event.type}): ${String(error)}`);
-        }
-    };
-    const observer = (session, event, run) => {
-        if (event.type === "run_started" && event.runId) {
-            active.set(session, { runId: event.runId, controls: run, pending: { steering: [], followUp: [] } });
-        }
-        else if (event.type === "run_settled") {
-            active.delete(session);
-        }
-        else if (event.type === "queue_changed") {
-            const entry = active.get(session);
-            if (entry)
-                entry.pending = event.data;
-        }
-        fanOut(session, event);
-        if (event.type === "run_settled")
-            publishUsage(session);
-    };
-    /**
-     * Report `usage` as the record now reads it: after a run (a new answer) and after a compaction (the context it
-     * described is gone). Read after the fact, so it follows the event that caused it.
-     */
-    const publishUsage = (session) => {
-        // Every serve runs a hub, most with nobody attached (a chat channel): reading the whole record each turn for an
-        // empty audience would cost a full parse per turn, growing with the conversation.
-        if (!subscribers.get(session)?.size && !options.tap)
-            return;
-        reads.state(session).then(({ usage }) => {
-            if (usage)
-                emitOwn(session, { type: "state_changed", timestamp: Date.now(), data: { usage } });
-        }, (error) => log.warn(`[fastagent] session ${session}: usage not published: ${String(error)}`));
-    };
-    // The reads, plus the two sessionless declarations. Bound onto a handle below.
-    const reads = {
-        async commands() {
-            return (await options.commands?.()) ?? [];
-        },
-        capabilities: () => {
-            const b = boundary;
-            return {
-                steering: true,
-                followUp: true,
-                compaction: !!b,
-                // Every write — a property, a copied record, a removed one — needs the boundary wiring for
-                // its LEASE, so they answer the same question: a write that races a run would hang the next
-                // turn off a stale branch, or pull the record out from under it.
-                fork: !!b,
-                delete: !!b,
-                // The CONTRACT's list, not a copy of it: a field added to SessionUpdate is advertised
-                // without anyone remembering to, and one removed cannot linger here.
-                updatable: b ? [...UPDATE_FIELDS] : [],
-                // The registry is a deployment fact (any session may be pointed at any of it). Each model carries the levels
-                // a session on it accepts, so a picker can offer them before the session runs on that model;
-                // `state().availableThinkingLevels` answers for the model the session is on.
-                ...(b ? { allowedModels: describeModels(b.models.getModels()) } : {}),
-                toolProgress: true, // tool_progress IS delivered (replace-semantics snapshots)
-                usage: true, // state().usage, and state_changed{usage} after each run and compaction
-            };
-        },
-        async state(session) {
-            const run = active.get(session);
-            const opened = await sessions.openIfExists(session);
-            const leafEntryId = opened ? publishedLeaf(opened) : undefined;
-            // What will RUN, not the raw record: a client steering a session needs the pair that executes.
-            // Without a boundary there is no model to resolve against, and the fields are absent.
-            // OBSERVATION IS TOTAL: an unreadable entry chain leaves the pair absent too (the same shape a
-            // control-less deployment answers with) rather than rejecting a read that has no error-code
-            // 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;
-            let settings;
-            let usage;
-            if (!opened) {
-                // An id with no record is an empty conversation at the defaults: its first turn would run on these.
-                if (b)
-                    settings = resolveSessionSettings([], b.models, b.defaults);
-            }
-            else {
-                try {
-                    const path = activePath(opened);
-                    if (b)
-                        settings = resolveSessionSettings(path, b.models, b.defaults);
-                    const selected = settings?.model;
-                    const latest = selected?.api === "pi-virtual"
-                        ? opened
-                            .buildSessionContext()
-                            .messages.filter((message) => message.role === "assistant" &&
-                            message.stopReason !== "error" &&
-                            message.stopReason !== "aborted")
-                            .at(-1)
-                        : undefined;
-                    const physical = latest?.role === "assistant" ? b?.models.getModel(latest.provider, latest.model) : undefined;
-                    usage = sessionUsage(path, opened, (physical ?? selected)?.contextWindow);
-                }
-                catch (error) {
-                    log.warn(`[fastagent] session ${session}: state unreadable (entry chain): ${String(error)}`);
-                }
-            }
-            const name = opened?.getSessionName();
-            return {
-                status: run ? "running" : compacting.has(session) ? "compacting" : "idle",
-                ...(name ? { name } : {}),
-                ...(run ? { activeRunId: run.runId } : {}),
-                ...(settings
-                    ? {
-                        model: `${settings.model.provider}/${settings.model.id}`,
-                        thinkingLevel: settings.thinkingLevel,
-                        availableThinkingLevels: settings.availableThinkingLevels,
-                    }
-                    : {}),
-                pending: run
-                    ? { steering: [...run.pending.steering], followUp: [...run.pending.followUp] }
-                    : { steering: [], followUp: [] },
-                ...(usage ? { usage } : {}),
-                ...(leafEntryId ? { leafEntryId } : {}),
-            };
-        },
-        async entries(session, opts) {
-            const opened = await sessions.openIfExists(session);
-            if (!opened)
-                return { entries: [] };
-            // LEAF FIRST, then the journal: `getEntries()` hands back a SNAPSHOT, so reading it first
-            // would race any concurrent append into a leaf the snapshot cannot contain — a live turn
-            // reading as a dangling head. This order makes the journal a superset of the leaf's chain,
-            // which is what lets the published head be trusted as one of the published entries.
-            const leafEntryId = publishedLeaf(opened);
-            const journal = opened.getEntries();
-            // The published tree must be SELF-CONTAINED: a `parentId` pointing at an entry this plane does
-            // not publish (a label, one of our markers) would break the walk a client does from
-            // `leafEntryId` upward — it would stop at an id it cannot look up and report a short path.
-            // So a skipped entry is spliced out: its children point at the nearest published ancestor.
-            const byId = new Map(journal.map((e) => [e.id, e]));
-            const publishedParent = (entry) => {
-                let parent = entry.parentId ?? undefined;
-                while (parent) {
-                    const found = byId.get(parent);
-                    // A gap in the chain is left as a gap — `state()` reports it and the next invoke fails on
-                    // it (design §7); inventing a parent here would hide a corrupt journal.
-                    if (!found)
-                        return parent;
-                    if (isNavigable(found))
-                        return parent;
-                    parent = found.parentId ?? undefined;
-                }
-                return undefined;
-            };
-            const all = journal.filter(isNavigable).map((e) => toSessionEntry(e, publishedParent(e)));
-            let entries = all;
-            if (opts?.since !== undefined) {
-                const idx = all.findIndex((e) => e.id === opts.since);
-                // Unknown cursor → full backfill (correct, merely larger): the client's cursor may predate
-                // a repository the session was rebuilt into; silently skipping records would lose history.
-                if (idx >= 0)
-                    entries = all.slice(idx + 1);
-            }
-            return { entries, ...(leafEntryId ? { leafEntryId } : {}) };
-        },
-        async image(session, ref) {
-            // ponytail: opens (parses) the whole record per image; an index when long image-heavy sessions make it show.
-            const opened = await sessions.openIfExists(session);
-            return opened ? imageAt(opened, ref) : undefined;
-        },
-        events(session) {
-            // ONE CALL IS ONE SUBSCRIPTION, and `ready` is its boundary: the moment after which nothing emitted for this
-            // session can be missed (session.ts, SessionEventStream). A second iteration of the same stream would be a
-            // second subscription inheriting the first one's readiness — a guarantee it never earned — so it is refused
-            // rather than documented. Matching the remote client, which opens one connection per stream.
-            //
-            // Registration happens on the FIRST next(), not at iterator creation: subscription semantics = you are
-            // subscribed while you iterate; an iterator obtained but never driven must not buffer. Teardown goes through
-            // Subscriber.close() so a `return()` on a QUIET stream resolves promptly instead of queueing behind a
-            // never-settling pull — without it every attach/detach against an idle session would leak a permanently
-            // registered subscriber.
-            let registered;
-            let unestablished;
-            const ready = new Promise((resolve, reject) => {
-                registered = resolve;
-                unestablished = reject;
-            });
-            // An awaiter gets the rejection; a consumer that only iterates would otherwise take an unhandled one for a
-            // cancellation it performed itself.
-            ready.catch(() => { });
-            let iterated = false;
-            return {
-                ready,
-                [Symbol.asyncIterator]() {
-                    if (iterated) {
-                        throw new Error("session events: this stream is one subscription — call events() again for another");
-                    }
-                    iterated = true;
-                    let sub;
-                    // `finished` is its own state: `sub === undefined` alone would conflate "not yet
-                    // registered" with "terminated", and a post-done next() would silently REGISTER A FRESH
-                    // subscription — the exact ghost-subscriber leak this class exists to prevent, reachable
-                    // by any wrapper that polls one extra time. done is terminal, per the iterator protocol.
-                    let finished = false;
-                    const cleanup = () => {
-                        finished = true;
-                        if (!sub) {
-                            // Cancelled before it registered: `ready` has a promise it cannot keep, and hanging on it is the one
-                            // outcome a caller cannot diagnose. The remote client answers the same way.
-                            unestablished(new Error("session events: cancelled before the subscription was established"));
-                            return;
-                        }
-                        sub.close();
-                        const set = subscribers.get(session);
-                        if (set) {
-                            set.delete(sub);
-                            if (set.size === 0)
-                                subscribers.delete(session);
-                        }
-                        sub = undefined;
-                    };
-                    return {
-                        async next() {
-                            if (finished)
-                                return { done: true, value: undefined };
-                            if (!sub) {
-                                sub = new Subscriber(session);
-                                let set = subscribers.get(session);
-                                if (!set) {
-                                    set = new Set();
-                                    subscribers.set(session, set);
-                                }
-                                set.add(sub);
-                                registered();
-                            }
-                            const result = await sub.next();
-                            if (result.done)
-                                cleanup();
-                            return result;
-                        },
-                        async return(value) {
-                            cleanup();
-                            return { done: true, value: value };
-                        },
-                    };
-                },
-            };
-        },
-    };
-    /** No boundary wiring — the write path does not exist in this deployment. A capability-gating
-     *  client never lands here; one that does gets the same answer every gate publishes. */
-    const unsupported = (what) => ({
-        ok: false,
-        error: {
-            code: UNSUPPORTED_CAPABILITY_CODE,
-            message: `${what} is not supported by this runtime (no boundary wiring)`,
-            retryable: false,
-        },
-    });
-    const noSuchSession = (session) => ({
-        ok: false,
-        error: { code: NO_SUCH_SESSION_CODE, message: `session "${session}" does not exist`, retryable: false },
-    });
-    /**
-     * The refusal for an id no client could then open: the empty string, `.` and `..` are not URL path segments
-     * (isAddressableSession), so minting one would put a row in list() that nothing can address — listed, unopenable by
-     * the client that just listed it. Both writes that create a record (fork's `into`, and an update to an id with no
-     * record) refuse it.
-     */
-    const unaddressable = (session) => invalid(`${JSON.stringify(session)} cannot be a session id — the control plane could not address it`);
-    const nothingToCompact = () => ({
-        ok: false,
-        error: {
-            code: NOTHING_TO_COMPACT_CODE,
-            message: "nothing to compact — the session has no compactable history yet; retry after more turns",
-            retryable: false,
-        },
-    });
-    const invalid = (message) => ({
-        ok: false,
-        error: { code: INVALID_COMMAND_CODE, message, retryable: false },
-    });
-    const busy = () => ({
-        ok: false,
-        error: {
-            code: SESSION_BUSY_CODE,
-            message: "session busy: a run (or another write) is in flight — retry at idle",
-            retryable: true,
-        },
-    });
-    const failed = (error) => ({
-        ok: false,
-        // A command that binds the session (compaction is a model call) on a session with no model: the same code the
-        // invoke answers, since the same fix (`update({ model })`) applies.
-        error: error instanceof MissingModel
-            ? { code: MISSING_MODEL_CODE, message: error.message, retryable: false }
-            : { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(error), retryable: true },
-    });
-    const runBoundary = (command) => Effect.runPromise(Effect.scoped(command).pipe(Effect.catchTag("SessionBusy", () => Effect.succeed(busy())), Effect.catchCause((cause) => Effect.succeed(failed(portError(cause))))));
-    /** steer / follow_up / abort — the run actions. They reach the LIVE run through the controls
-     *  registered with `run_started`; nothing durable is written. */
-    const runAction = (session, action) => Effect.runPromise(Effect.gen(function* () {
-        // pi dequeues a queued prompt by matching its text when it enters the conversation, and skips an empty one
-        // (`_handleAgentEvent`): an image-only prompt would sit in `pending` for the whole run and then read as dropped.
-        if ((action.type === "steer" || action.type === "follow_up") && action.prompt.text === "")
-            return invalid(`${action.type} needs non-empty text: a queued prompt is reported by its text`);
-        const run = active.get(session);
-        if (!run) {
-            // Run/compaction symmetry: an in-flight compaction is a model call too, and `abort` is its
-            // only door — interrupting it converges through the detached task's catch into
-            // `compaction_finished{aborted}` with the lease released; answering no_active_run against a
-            // state() that says "compacting" would be a lie.
-            const comp = action.type === "abort" ? compacting.get(session) : undefined;
-            if (comp) {
-                comp.abort();
-                return { ok: true }; // no runId — the outcome travels as compaction_finished{aborted}
-            }
-            // Rejected BEFORE acceptance: no run exists, nothing happened. retryable: false — the same
-            // call fails again; call it after state() shows an active run.
-            return {
-                ok: false,
-                error: {
-                    code: NO_ACTIVE_RUN_CODE,
-                    message: `no active run for this session — ${action.type} modulates a run an invoke is driving`,
-                    retryable: false,
-                },
-            };
-        }
-        if (!run.controls) {
-            // A run EXISTS (state() rightly reports running) but was registered observation-only (the
-            // observer seam allows run_started without controls). That is a CAPABILITY problem, not a run
-            // problem — permanent for this wiring, so neither no_active_run (would poll forever) nor
-            // run_command_failed (transient) fits.
-            return {
-                ok: false,
-                error: {
-                    code: UNSUPPORTED_CAPABILITY_CODE,
-                    message: `the active run registered without modulation controls (observation-only) — ${action.type} cannot reach it`,
-                    retryable: false,
-                },
-            };
-        }
-        const controls = run.controls;
-        if (action.type === "abort") {
-            yield* port(() => controls.abort());
-            return { ok: true, runId: run.runId };
-        }
-        const disposition = yield* port(() => action.type === "steer" ? controls.steer(action.prompt) : controls.followUp(action.prompt));
-        return { ok: true, runId: run.runId, disposition };
-    }).pipe(Effect.catchCause((cause) => Effect.succeed({
-        ok: false,
-        error: { code: RUN_COMMAND_FAILED_CODE, message: String(portError(cause)), retryable: false },
-    }))));
-    /**
-     * {@link Session.update} — validate the whole patch, take the lease once, hand the writes to the
-     * store, report what landed.
-     *
-     * Everything before the lease is validation, which is what makes a rejected patch leave nothing
-     * behind. What a value MEANS is decided here (a model spec against the registry, a level against
-     * the model it lands on); how a record takes it is the store's.
-     */
-    const updateOf = (session, patch) => runBoundary(Effect.gen(function* () {
-        // Keys, not values: a field this runtime does not know must not be silently skipped — that is a
-        // client typo, or a newer client talking to an older serve, and both need to hear about it.
-        const named = Object.keys(patch);
-        const unknown = named.filter((f) => !UPDATE_FIELDS.includes(f));
-        if (unknown.length > 0) {
-            return unsupported(`update field(s) ${unknown.join(", ")} — capabilities().updatable lists what this serve sets`);
-        }
-        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;
-        if (!b)
-            return unsupported(`update(${fields.join(", ")})`);
-        // PAYLOAD validation first — before the session is even opened, and long before the lease: an
-        // invalid value must not briefly block a run.
-        let model;
-        if (patch.model !== undefined) {
-            const slash = patch.model.indexOf("/");
-            model = slash > 0 ? b.models.getModel(patch.model.slice(0, slash), patch.model.slice(slash + 1)) : undefined;
-            if (!model) {
-                return invalid(`unknown model "${patch.model}" — capabilities().allowedModels lists the accepted models`);
-            }
-        }
-        if (patch.thinkingLevel !== undefined && !THINKING_LEVELS.has(patch.thinkingLevel)) {
-            return invalid(`unknown thinking level "${patch.thinkingLevel}" — state().availableThinkingLevels lists what this session accepts`);
-        }
-        // A name is the client's own label; the only thing that cannot be one is nothing.
-        if (patch.name !== undefined && patch.name.trim() === "")
-            return invalid("a session name cannot be empty");
-        // An id with no record takes properties too: its first turn is the "next turn" they apply to, so the write
-        // creates its record (below, under the lease). (Read-only handle — the WRITE one is opened under the lease,
-        // and this one is discarded.)
-        const existing = yield* port(() => sessions.openIfExists(session));
-        if (!existing && !isAddressableSession(session))
-            return unaddressable(session);
-        if (patch.leafEntryId !== undefined) {
-            // A target that cannot BE a leaf is a permanent payload error, not a session error — the same
-            // disposition as an unknown model spec. Same predicate `entries()` publishes by, so
-            // "everything published is a position" holds by construction rather than by two literals
-            // agreeing.
-            const entry = existing?.getEntry(patch.leafEntryId);
-            if (!entry || !isNavigable(entry)) {
-                return invalid(entry
-                    ? `entry "${patch.leafEntryId}" is not a position — entries() publishes every id you can move to, and this is not one of them`
-                    : `entry "${patch.leafEntryId}" does not exist in session "${session}" — entries() lists the positions`);
-            }
-        }
-        if (patch.thinkingLevel !== undefined) {
-            // The same set `state()` showed the client. Reject here rather than record a level the run
-            // would not use. The read is guarded because this must never REJECT — the contract promises a
-            // SessionResult, so an unreadable chain has to arrive as a code.
-            let resolved;
-            try {
-                // Against the path this patch LANDS on: a leaf move is written first, and the branch it
-                // moves to can carry a model override of its own — validating on the path being left would
-                // reject a level the destination supports, and accept one it does not.
-                const path = existing ? activePath(existing, patch.leafEntryId) : [];
-                resolved = resolveSessionSettings(path, b.models, b.defaults);
-            }
-            catch (error) {
-                return failed(error);
-            }
-            // An explicit model in the same patch wins over the one that path resolves to: it is applied
-            // after the move, so it is what the session ends up running. With neither (no model recorded, no
-            // default), any level of the vocabulary is recorded, and clamped once the session has a model, like a
-            // recorded level after a model change.
-            const target = model ?? resolved?.model;
-            if (target) {
-                const levels = getSupportedThinkingLevels(target);
-                if (!levels.includes(patch.thinkingLevel)) {
-                    return invalid(`thinking level "${patch.thinkingLevel}" is not supported by ${target.provider}/${target.id} (allowed: ${levels.join(", ")})`);
-                }
-            }
-        }
-        // Release before publishing state_changed: an observer may immediately issue another command.
-        const applied = yield* Effect.scoped(Effect.gen(function* () {
-            yield* acquireSessionLease(b.lease, session);
-            // portJoin, not port: the lease is held for the duration of this write, so an interrupted
-            // fiber must not release it while the store is still writing (effect-port.ts, rule 1).
-            // A never-run session's record is created through the data plane's own path, under the same lease an
-            // invoke creating it takes; one that invoke created meanwhile is simply opened.
-            if (!existing)
-                yield* portJoin(() => sessions.openOrCreate(session));
-            return yield* portJoin(() => sessions.applyProperties(session, {
-                ...(patch.name !== undefined ? { name: patch.name } : {}),
-                ...(model ? { model: { provider: model.provider, id: model.id } } : {}),
-                ...(patch.thinkingLevel !== undefined ? { thinkingLevel: patch.thinkingLevel } : {}),
-                ...(patch.leafEntryId !== undefined ? { leafEntryId: patch.leafEntryId } : {}),
-            }));
-        }));
-        if (!applied)
-            return noSuchSession(session); // deleted in the window between the read and the lease
-        if (applied.landed.length > 0) {
-            // ONE event for the patch, built from what the RECORD holds. The settings pair rides along
-            // whenever anything but the name changed: model and thinking level are one setting, and a
-            // moved leaf can drop an override that used to apply.
-            let settings;
-            if (applied.path) {
-                try {
-                    settings = resolveSessionSettings(applied.path, b.models, b.defaults);
-                }
-                catch (error) {
-                    // Already durable, so an unresolvable pair must NOT read as "nothing took effect": report
-                    // the position without it and let the next invoke — which walks the same path — be where
-                    // the fault surfaces.
-                    log.warn(`[fastagent] session ${session}: updated, settings unresolvable: ${String(error)}`);
-                }
-            }
-            // A moved head reads a different newest answer, and another model has another window: the event carries
-            // the usage the session now has, and carries none when it has none. Read back through `state()`, the one
-            // derivation; a read failure only costs the field, since the write has already landed.
-            const usage = applied.landed.some((f) => f === "leafEntryId" || f === "model")
-                ? yield* port(() => reads.state(session)).pipe(Effect.map((state) => state.usage), Effect.catchCause((cause) => Effect.sync(() => {
-                    log.warn(`[fastagent] session ${session}: updated, usage unreadable: ${String(portError(cause))}`);
-                    return undefined;
-                })))
-                : undefined;
-            emitOwn(session, {
-                type: "state_changed",
-                timestamp: Date.now(),
-                data: {
-                    ...(applied.landed.includes("leafEntryId") ? { leafEntryId: applied.leafEntryId } : {}),
-                    ...(settings && applied.landed.some((f) => f !== "name")
-                        ? { model: `${settings.model.provider}/${settings.model.id}`, thinkingLevel: settings.thinkingLevel }
-                        : {}),
-                    ...(applied.landed.includes("name") && applied.name ? { name: applied.name } : {}),
-                    ...(usage ? { usage } : {}),
-                },
-            });
-        }
-        if (applied.failure !== undefined) {
-            // `boundary_command_failed` means nothing durable landed. When something did, the client needs
-            // a different sentence — and the fields, so it knows what its retry would repeat.
-            return applied.landed.length === 0
-                ? failed(applied.failure)
-                : {
-                    ok: false,
-                    error: {
-                        code: PARTIAL_UPDATE_CODE,
-                        message: `applied ${applied.landed.join(", ")}, then failed: ${String(applied.failure)} — read state() before retrying`,
-                        retryable: false,
-                    },
-                };
-        }
-        return { ok: true };
-    }));
-    /** Admission waits for binding and pi's own admission (its cut point), not the model call.
-     *  Its execution scope survives the control response; completion is published only after releasing the shared
-     *  lease. */
-    const compactOf = (session, instructions) => {
-        const admitted = Deferred.makeUnsafe();
-        let accepted = false;
-        let aborted = false;
-        const work = Effect.scoped(Effect.gen(function* () {
-            const b = boundary;
-            if (!b)
-                return unsupported("compact()");
-            const existing = yield* port(() => sessions.openIfExists(session));
-            if (!existing)
-                return noSuchSession(session);
-            // A record with no conversation in it (the list's `messageCount: 0`, e.g. one `update()` created before a first
-            // turn) has nothing to compact on any branch. Said before binding, because binding is a write: pi records the
-            // model and thinking level on a session that has no messages, so asking pi would add two entries and then
-            // refuse. Whether a record WITH messages has a cut point stays pi's decision (below).
-            if (!existing.getEntries().some(isConversationMessage))
-                return nothingToCompact();
-            yield* acquireSessionLease(b.lease, session);
-            const bound = yield* acquireSession(b.sessionFactory, session);
-            yield* Effect.acquireRelease(Effect.try({
-                try: () => bound.subscribe((event) => {
-                    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, toRetryScheduledEvent(event));
-                }),
-                catch: (error) => new PortFailure(error),
-            }), (unsubscribe) => portCleanup("unsubscribe", unsubscribe));
-            // Admission is pi's own decision, observed rather than predicted: a prediction has to track pi's private
-            // cut-point rules release by release. It settles before the model call.
-            const compaction = startCompaction(bound, instructions, () => {
-                accepted = true;
-                compacting.set(session, {
-                    abort: () => {
-                        aborted = true;
-                        bound.abortCompaction();
-                    },
-                });
-                emitOwn(session, { type: "compaction_started", timestamp: Date.now(), data: {} });
-                Deferred.doneUnsafe(admitted, Effect.succeed({ ok: true }));
-            });
-            const admission = yield* portAbort("compact admission", () => compaction.admission, () => bound.abortCompaction());
-            if (admission === "nothing_to_compact")
-                return nothingToCompact();
-            // Any other error pi raises before admission. A served session has no known trigger: it always binds a
-            // model, and pi swallows a credential failure here and meets it at the model call (compaction_finished).
-            // NOT retryable all the same: it is pi's decision on this session, not a transport or lease fault that
-            // clears on its own, so repeating the call would meet it again.
-            if (admission !== "admitted") {
-                return {
-                    ok: false,
-                    error: { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(admission.refused), retryable: false },
-                };
-            }
-            const done = yield* portAbort("compact", () => compaction.done, () => bound.abortCompaction());
-            return { summary: done.summary };
-        })).pipe(Effect.catchTag("SessionBusy", () => Effect.succeed(busy())), Effect.catchCause((cause) => Effect.succeed(failed(portError(cause)))), Effect.tap((result) => Effect.sync(() => {
-            if (accepted) {
-                compacting.delete(session);
-                emitOwn(session, {
-                    type: "compaction_finished",
-                    timestamp: Date.now(),
-                    data: "summary" in result ? result : aborted ? { aborted: true } : { error: result.error.message },
-                });
-                if ("summary" in result)
-                    publishUsage(session);
-            }
-            Deferred.doneUnsafe(admitted, Effect.succeed("summary" in result ? { ok: true } : result));
-        })));
-        // The admitted operation, rather than the request waiting on this Deferred, owns the scope.
-        Effect.runFork(work);
-        return Effect.runPromise(Deferred.await(admitted));
-    };
-    /**
-     * Copy a history into a new session. IDEMPOTENT by construction: `into` is the caller's id, so a
-     * repeat of a fork that already landed answers `ok: true` and writes nothing — a client retrying a
-     * request whose response it never saw does not get a second record. Provenance is what makes that
-     * safe rather than merely quiet: the same `into` naming a session that came from somewhere else is
-     * a rejection, not an overwrite.
-     */
-    const forkOf = (options) => runBoundary(Effect.gen(function* () {
-        const { from, at, into } = 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;
-        if (!b)
-            return unsupported("fork()");
-        if (!isAddressableSession(into))
-            return unaddressable(into);
-        const source = yield* port(() => sessions.openIfExists(from));
-        if (!source)
-            return noSuchSession(from);
-        // The entry predicate is the one `entries()` publishes by, so "everything published is forkable"
-        // holds by construction — the same argument the leaf move makes.
-        const entry = source.getEntry(at);
-        if (!entry || !isNavigable(entry)) {
-            return invalid(`entry "${at}" is not a forkable position in session "${from}" — entries() lists the ids`);
-        }
-        const existingTarget = yield* port(() => sessions.openIfExists(into));
-        if (existingTarget) {
-            // Already forked from HERE: the request already happened, so answering ok is the truth rather
-            // than a convenience. Anything else under that id is a different history, and saying yes would
-            // be the id lying about what it holds.
-            return forkProvenance(existingTarget) === provenance
-                ? { ok: true }
-                : invalid(`session "${into}" already exists with a different history — fork mints nothing over it`);
-        }
-        // BOTH ends. The source lease keeps the copy from reading a history a run is mid-write on; the
-        // destination lease closes the window the existence check above leaves open — an invoke creating
-        // `into`, or a second fork from a DIFFERENT source (whose source lease is another key entirely),
-        // otherwise lands between that check and this write. tryAcquire never blocks, so taking two
-        // cannot deadlock.
-        yield* acquireSessionLease(b.lease, from);
-        yield* acquireSessionLease(b.lease, into);
-        // Recheck under both leases: another creator may have taken the target since validation.
-        const raced = yield* port(() => sessions.openIfExists(into));
-        if (raced) {
-            return forkProvenance(raced) === provenance
-                ? { ok: true }
-                : invalid(`session "${into}" already exists with a different history — fork mints nothing over it`);
-        }
-        // portJoin: both leases are held for this write and must outlive it (effect-port.ts, rule 1).
-        yield* portJoin(() => sessions.fork(from, at, into, provenance));
-        return { ok: true };
-    }));
-    const deleteOf = (session) => runBoundary(Effect.gen(function* () {
-        const b = boundary;
-        if (!b)
-            return unsupported("delete()");
-        const existing = yield* port(() => sessions.openIfExists(session));
-        if (!existing)
-            return noSuchSession(session);
-        const removed = yield* Effect.scoped(Effect.gen(function* () {
-            yield* acquireSessionLease(b.lease, session);
-            // portJoin: the lease must outlive the removal (effect-port.ts, rule 1).
-            return yield* portJoin(() => sessions.delete(session));
-        }));
-        if (!removed)
-            return noSuchSession(session);
-        // The session is gone, so its live streams have nothing left to report: end them rather than
-        // hold connections open on a record that no longer exists. A client's reconnect then reads an
-        // empty `state()`, which is the truth.
-        for (const sub of [...(subscribers.get(session) ?? [])])
-            sub.close();
-        subscribers.delete(session);
-        return { ok: true };
-    }));
-    const control = {
-        capabilities: reads.capabilities,
-        commands: reads.commands,
-        sessions: {
-            // The one read that may REJECT (design §13): `[]` is what a deployment with no sessions
-            // answers, so a store that cannot be read must not borrow that shape. The transport turns the
-            // throw into a coded non-2xx; nothing here swallows it.
-            list: () => sessions.list(),
-            fork: forkOf,
-            // A PURE BINDING: an id and the closures above it. Nothing is checked here — the calls answer
-            // that, each in its own vocabulary — and nothing is cached, so two handles for one id are
-            // interchangeable.
-            get: (session) => ({
-                id: session,
-                state: () => reads.state(session),
-                entries: (options) => reads.entries(session, options),
-                image: (ref) => reads.image(session, ref),
-                events: () => reads.events(session),
-                update: (patch) => updateOf(session, patch),
-                steer: (prompt) => runAction(session, { type: "steer", prompt }),
-                followUp: (prompt) => runAction(session, { type: "follow_up", prompt }),
-                abort: () => runAction(session, { type: "abort" }),
-                compact: (options) => compactOf(session, options?.instructions),
-                delete: () => deleteOf(session),
-            }),
-        },
-    };
-    return { control, observer };
-}