@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/engines/pi/invoke.js

@@ -1,459 +0,0 @@
-import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
-import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
-import { cancellableStream } from "../../collect.js";
-import { log } from "../../log.js";
-import { TOOL_ACTIVATION_ENTRY, harnessSession } from "./harness.js";
-import { EventQueue, errorToTerminal, inProcessLease, toPiPromptOptions, toTerminal } from "./turn-kit.js";
-import { additiveActivation, turnContext } from "./tool-context.js";
-// ── Event translation: the single pi↔SPEC translation point ─────────────────
-//
-// `retryable` = worth re-sending with the same session (SPEC §6: advisory, not a session-atomicity
-// guarantee). Classify from the STRUCTURED signal first, prose only as the last-resort ceiling. What
-// is actually available differs by path, and the two are NOT symmetric:
-//   - thrown error (errorToTerminal): an HTTP `.status`/`.statusCode` AND a network `.code` (incl.
-//     `.cause.code`) — this is where a numeric status genuinely drives the decision.
-//   - failed message (toTerminal): ONLY `diagnostics[].error.code`. pi's `DiagnosticErrorInfo` carries
-//     a `code` (a network code, or a status delivered as a code), with no separate HTTP-status field —
-//     so a message whose provider `code` is a string label (e.g. "rate_limit_exceeded") is not
-//     decisive here and falls to prose.
-// The prose fallback is bounded, not a cop-out: pi-ai already ran its own status-code-based client
-// retries (harness.ts PROVIDER_MAX_RETRIES) before surfacing, so an error that reaches this point has
-// already exhausted the cleanly-retryable cases. The regex is the narrow ceiling, not the classifier.
-// Upstream ask: a first-class `retryable`/`kind` on pi's terminal error would retire the prose path
-// entirely (mirrors the §11 "the deeper fix is upstream in pi" pattern).
-/**
- * In-stream event mapping — pi events are translated ONCE into the rich `SessionEvent` vocabulary;
- * the SPEC `AgentEvent` stream is a narrow {@link projectAgentEvent} of it (design §6: one
- * translation plus one projection, never two parallel translations). pi events with no session
- * vocabulary yet (turn_start, agent_start, …) are dropped.
- */
-export function toSessionEvent(pe, runId) {
-    const at = Date.now();
-    switch (pe.type) {
-        case "queue_update":
-            return {
-                type: "queue_changed",
-                timestamp: at,
-                runId,
-                data: { steering: pe.steer.length, followUp: pe.followUp.length },
-            };
-        case "message_start":
-            // Assistant streaming only — a user/toolResult message is not a live message boundary.
-            if (pe.message.role !== "assistant")
-                return null;
-            return { type: "message_started", timestamp: at, runId, data: {} };
-        case "message_update": {
-            const ev = pe.assistantMessageEvent;
-            if (ev.type === "text_delta") {
-                return { type: "message_delta", timestamp: at, runId, data: { channel: "text", delta: ev.delta } };
-            }
-            if (ev.type === "thinking_delta") {
-                return { type: "message_delta", timestamp: at, runId, data: { channel: "thinking", delta: ev.delta } };
-            }
-            return null;
-        }
-        case "message_end":
-            if (pe.message.role !== "assistant")
-                return null;
-            return { type: "message_finished", timestamp: at, runId, data: {} };
-        case "tool_execution_start":
-            return {
-                type: "tool_started",
-                timestamp: at,
-                runId,
-                data: { id: pe.toolCallId, name: pe.toolName, args: pe.args },
-            };
-        case "tool_execution_update":
-            return {
-                type: "tool_progress",
-                timestamp: at,
-                runId,
-                data: { id: pe.toolCallId, name: pe.toolName, partialResult: pe.partialResult },
-            };
-        case "tool_execution_end":
-            return {
-                type: "tool_finished",
-                timestamp: at,
-                runId,
-                data: { id: pe.toolCallId, isError: pe.isError, content: pe.result },
-            };
-        case "retry_scheduled": {
-            // Summarization retry backoff (auto-compaction / branch summary, pi ≥0.81.1) — without it,
-            // up to ~14s of backoff at the turn's tail reads as a hang. `retry_attempt_start`/
-            // `retry_finished` stay dropped: they carry no outcome, and the next event is the closure.
-            // Typed against the vocabulary (as is the second construction site, session-control's
-            // manual-compact callback) so a payload change breaks both at compile time.
-            const event = {
-                type: "retry_scheduled",
-                timestamp: at,
-                runId,
-                data: {
-                    operation: pe.operation,
-                    attempt: pe.attempt,
-                    maxAttempts: pe.maxAttempts,
-                    delayMs: pe.delayMs,
-                    error: pe.errorMessage,
-                },
-            };
-            return event;
-        }
-        default:
-            return null;
-    }
-}
-/** The SPEC projection of the rich stream. Events with no `AgentEvent` counterpart (progress,
- *  message boundaries, run boundaries) project to null — the invoke terminal is produced from the
- *  resolved message ({@link toTerminal}), not from `run_settled`. */
-export function projectAgentEvent(se) {
-    switch (se.type) {
-        case "message_delta": {
-            const d = se.data;
-            return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
-        }
-        case "tool_started": {
-            const d = se.data;
-            return { type: "tool_started", id: d.id, name: d.name, args: d.args };
-        }
-        case "tool_finished": {
-            const d = se.data;
-            return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
-        }
-        case "retry_scheduled": {
-            // `operation` (compaction | branch_summary) stays session-plane vocabulary — a turn renderer
-            // only needs "transient failure, retrying"; the engine detail lives in the control plane.
-            const d = se.data;
-            return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
-        }
-        default:
-            return null;
-    }
-}
-/** Bind the concrete pi-agent-core Session behind FastAgent's tool-runtime manager port. */
-function toolSessionManager(sessionId, harness) {
-    const session = harnessSession(harness);
-    if (!session)
-        return undefined;
-    return {
-        getSessionId: () => sessionId,
-        async getHeader() {
-            const metadata = await session.getMetadata();
-            return { id: sessionId, timestamp: metadata.createdAt };
-        },
-        getBranch: () => session.getBranch(),
-    };
-}
-/**
- * The turn's {@link ToolActivation} over the live harness. `activate` is additive and filters to the
- * registered names first — pi's `setActiveTools` THROWS on unknown names, and a loader must get a
- * usable "nothing new" answer, not an exception. pi persists the change in the session, so the
- * per-invoke restore (harness.ts) carries it into later turns.
- */
-function toolActivation(harness) {
-    // Serialize activations per turn: "who activated first" must be decided HERE, not by whether pi's
-    // setActiveTools happens to mutate before its first await — parallel tool calls in one batch race
-    // their activate() calls, and the addedToolNames load points must not double-stamp.
-    let chain = Promise.resolve([]);
-    return {
-        active: () => harness.getActiveTools().map((t) => t.name),
-        registered: () => harness.getTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
-        activate(names) {
-            const run = async () => {
-                const current = harness.getActiveTools().map((t) => t.name);
-                const added = additiveActivation(harness.getTools().map((t) => t.name), current, names);
-                if (added.length > 0) {
-                    await harness.setActiveTools([...current, ...added]);
-                    // Persist the DELTA in a dedicated entry — what the per-invoke resolve (harness.ts) reads.
-                    // pi's own active_tools_change record is a full snapshot and is deliberately ignored there.
-                    // Absent session (a harness built outside piHarnessFactory): in-turn activation still works,
-                    // it just isn't durable — the factory owns persistence.
-                    await harnessSession(harness)?.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
-                }
-                return added;
-            };
-            const result = chain.then(run, run); // run after the predecessor settles, success or failure
-            chain = result.catch(() => []); // the caller sees a rejection on `result`; the chain stays usable
-            return result;
-        },
-    };
-}
-/**
- * After a successful turn, compact the session if its context has grown past pi's threshold — a long
- * shared (group) or 1:1 conversation otherwise overflows the model's window. pi owns the mechanism
- * (`harness.compact()` writes a summary entry into the session, so the next reopen is compacted); the
- * bare harness does NOT auto-trigger it, so fastagent checks `shouldCompact` here and fires it. The
- * context size is the provider's own count from the turn's assistant message (`usage`).
- */
-async function maybeCompact(harness, message) {
-    const contextWindow = harness.getModel().contextWindow;
-    if (!contextWindow)
-        return;
-    if (shouldCompact(calculateContextTokens(message.usage), contextWindow, DEFAULT_COMPACTION_SETTINGS)) {
-        await harness.compact();
-    }
-}
-/** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
-export function createPiAgentFromHarness(options) {
-    const { harnessFactory, lease = inProcessLease(), observer } = options;
-    // The cancellation protocol (SPEC MUST 3) lives in cancellableStream. Both halves matter here:
-    // the DOOR settles a generator suspended on a quiet stream (a tool mid-execution) — the local
-    // for-await pattern never hit that deadlock, but pull-driven consumers (the SSE handler's eager
-    // reads) do — and the LATCH covers the window where the harness is still being built, where a
-    // knock would land on an idle harness and the LATER run would ignore it.
-    const invoke = (scope, prompt) => cancellableStream((hooks) => turn(scope, prompt, hooks));
-    async function* turn(scope, prompt, { onCancelReady, wasCancelled }) {
-        const release = lease.tryAcquire(scope.session);
-        if (!release) {
-            // Rejected BEFORE acceptance: no run exists, so the observer sees nothing (replay-safe).
-            yield {
-                type: "failed",
-                details: "session busy: a turn is already in flight for this session",
-                retryable: true,
-                code: SESSION_BUSY_CODE,
-            };
-            return;
-        }
-        // The run exists from here: one run_started, exactly one run_settled. Terminal points only
-        // RECORD the outcome; the settlement event is emitted in the outer finally, right before
-        // release() — so the observation plane's "running" window equals the lease window (state()
-        // must never say idle while a new invoke would still be rejected session_busy), and the
-        // post-terminal auto-compaction is naturally inside the run. A run with no recorded outcome
-        // was cancelled by the caller (SPEC: cancellation has no terminal event) → aborted.
-        const runId = crypto.randomUUID();
-        let outcome;
-        const observe = (event, run) => {
-            if (!event || !observer)
-                return;
-            try {
-                observer(scope.session, event, run);
-            }
-            catch (error) {
-                // The observation plane must never break the data plane; a broken hub is its own problem.
-                log.warn(`[fastagent] session observer threw (event ${event.type}): ${String(error)}`);
-            }
-        };
-        // run_started must be observed before the (awaited) harness build so no early event outruns
-        // registration — so the controls AWAIT the build instead of erroring on the assembling window:
-        // a dispatch that races the build simply queues on the freshly built harness. A setup failure
-        // rejects the gate (and the run settles failed); the guard keeps an undispatched rejection from
-        // becoming an unhandled-rejection crash.
-        let harnessReady;
-        let harnessFailed;
-        const harnessGate = new Promise((resolve, reject) => {
-            harnessReady = resolve;
-            harnessFailed = reject;
-        });
-        harnessGate.catch(() => { }); // observed via controls only when a dispatch actually happens
-        // Aborted classification has two attribution sources, either suffices: pi's own
-        // stopReason:"aborted" (toTerminal), and control-plane INTENT — needed because providers do
-        // not uniformly attribute an aborted stream (verified empirically: the faux path surfaces a
-        // plain error). Intent = "an abort() succeeded, OR one was still in flight when the terminal
-        // arrived" (the harness error often lands before abort() resolves). A rejected abort that
-        // RETURNED before the terminal counts as nothing — no rollback dance, no interleaving hazard.
-        // GUARANTEE BOUNDARY: an abort still in flight that ultimately rejects can classify a
-        // concurrent real error as aborted — narrow, and non-lossy: the settlement carries
-        // `error.message` either way.
-        let abortsInFlight = 0;
-        let abortSucceeded = false;
-        // Stale-controls guard: after settlement pi's steer()/followUp()/abort() would still resolve
-        // (they queue / no-op on the to-be-discarded harness) — a silent acceptance of a command that
-        // can never take effect. The flag flips at THREE points, earliest wins: (1) the moment the
-        // run's terminal is determined (the main window — before the consumer-paced `yield terminal`
-        // and auto-compaction), (2) the setup-failure path, (3) the outer finally as the backstop for
-        // caller cancellation. A post-settle call throws and the dispatcher maps it to
-        // `run_command_failed`.
-        let runSettled = false;
-        const settledError = () => new Error("run already settled; the command cannot take effect");
-        // The settled check and the harness call MUST share one synchronous block (no await between):
-        // pi enqueues/aborts synchronously at method entry, so check-then-call in the same tick truly
-        // closes the race — a check behind its own await boundary would only shrink it.
-        const controls = {
-            async steer(p) {
-                const opts = await toPiPromptOptions(p);
-                const harness = await harnessGate;
-                if (runSettled)
-                    throw settledError();
-                await harness.steer(p.text, opts);
-            },
-            async followUp(p) {
-                const opts = await toPiPromptOptions(p);
-                const harness = await harnessGate;
-                if (runSettled)
-                    throw settledError();
-                await harness.followUp(p.text, opts);
-            },
-            async abort() {
-                const harness = await harnessGate;
-                if (runSettled)
-                    throw settledError();
-                abortsInFlight++;
-                try {
-                    await harness.abort();
-                    abortSucceeded = true;
-                }
-                finally {
-                    abortsInFlight--;
-                }
-            },
-        };
-        observe({ type: "run_started", timestamp: Date.now(), runId, data: {} }, controls);
-        try {
-            let harness;
-            try {
-                // Scope's lineage extension flows to the store's CREATE path only — an existing session
-                // opens exactly as before, whatever the scope names (inheritance is one-time by construction).
-                harness = await harnessFactory(scope.session, scope.parentSession === undefined
-                    ? undefined
-                    : {
-                        parentSession: scope.parentSession,
-                        ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
-                    });
-            }
-            catch (error) {
-                // Setup failures (session open / auth / …) MUST surface as a failed event, never a throw.
-                harnessFailed(error); // a pending dispatch learns the run cannot take commands
-                const terminal = errorToTerminal(error);
-                outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
-                runSettled = true; // commands can no longer take effect — reject stale controls from here on
-                yield terminal;
-                return; // → outer finally emits the settlement
-            }
-            harnessReady(harness);
-            // Arm the cancellation door (see invoke's wrapper): aborting the harness settles the run,
-            // releasing any await the generator is parked on so a queued return() can reach the finally.
-            onCancelReady(() => {
-                void harness.abort().catch(() => { });
-            });
-            const queue = new EventQueue();
-            const unsub = harness.subscribe((pe) => {
-                // Summarization retries also warn to server logs: the session `retry_scheduled` event only
-                // reaches attached observers, and an operator tailing logs must see the backoff too.
-                if (pe.type === "retry_scheduled") {
-                    log.warn(`[fastagent] ${pe.operation} retry ${pe.attempt}/${pe.maxAttempts} in ${pe.delayMs}ms (session ${scope.session}): ${pe.errorMessage}`);
-                }
-                const rich = toSessionEvent(pe, runId);
-                if (!rich)
-                    return;
-                observe(rich);
-                const event = projectAgentEvent(rich);
-                if (event)
-                    queue.push(event);
-            });
-            let completed; // the assistant message of a cleanly completed turn
-            try {
-                // Preparing the prompt lazy-loads the image pipeline and re-encodes every attachment, so it
-                // both takes time and can throw BEFORE any engine work exists to fail — and a throw here
-                // would escape the generator and break iteration for the caller, which MUST 2 forbids. It
-                // settles the run the same way a setup failure does.
-                let opts;
-                try {
-                    opts = await toPiPromptOptions(prompt);
-                }
-                catch (error) {
-                    const terminal = errorToTerminal(error);
-                    outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
-                    runSettled = true;
-                    yield terminal;
-                    return; // → outer finally emits the settlement
-                }
-                // The consumer walked away while the harness was built or the prompt prepared (latched — the
-                // door armed above only stops a RUNNING harness, so a knock in that window is a no-op the
-                // LATER run would ignore): never start the model call. Read AFTER the last await before it,
-                // so both windows are covered; settle as aborted and let the queued return() finish the
-                // generator.
-                if (wasCancelled()) {
-                    outcome = { status: "aborted" };
-                    runSettled = true;
-                    try {
-                        await harness.abort(); // teardown — fresh-harness discipline
-                    }
-                    catch (error) {
-                        log.warn(`[fastagent] harness abort failed during cleanup: ${String(error)}`);
-                    }
-                    return; // → outer finally emits the settlement
-                }
-                // Bind current cwd/session/activation capabilities for every FastAgent-defined tool.
-                const run = turnContext.run({
-                    cwd: options.cwd ?? process.cwd(),
-                    sessionManager: toolSessionManager(scope.session, harness),
-                    tools: toolActivation(harness),
-                }, () => harness.prompt(prompt.text, opts));
-                yield* queue.drainUntil(run);
-                let terminal;
-                try {
-                    const message = await run;
-                    terminal = toTerminal(message);
-                    if (terminal.type === "completed")
-                        completed = message;
-                }
-                catch (error) {
-                    terminal = errorToTerminal(error);
-                }
-                if ((abortSucceeded || abortsInFlight > 0) && terminal.type === "failed") {
-                    terminal = { type: "failed", details: terminal.details, retryable: false, code: ABORTED_CODE };
-                }
-                if (terminal.type === "completed")
-                    outcome = { status: "completed" };
-                else if (terminal.type === "failed") {
-                    outcome =
-                        terminal.code === ABORTED_CODE
-                            ? // Carry the detail: an independent real error that raced an accepted abort must stay
-                                // diagnosable in the settlement (audit consumers read run_settled, not the invoke
-                                // stream) — aborted classifies the run, the message preserves what actually stopped it.
-                                { status: "aborted", error: { message: terminal.details, retryable: false } }
-                            : {
-                                status: "failed",
-                                error: { code: terminal.code, message: terminal.details, retryable: terminal.retryable },
-                            };
-                }
-                // Commands become ineffective the moment the run resolved — NOT at the outer finally, which
-                // sits behind `yield terminal` (a consumer-paced suspension) and auto-compaction. Flipping
-                // here closes the silent-drop window for steer/follow_up dispatched in that gap; the
-                // outer-finally flip remains as the backstop for caller cancellation.
-                runSettled = true;
-                yield terminal;
-            }
-            finally {
-                // After a successful turn, keep the session under the model's context window (a long shared group
-                // or 1:1 conversation would otherwise overflow). Runs HERE — before teardown (it uses the harness)
-                // and BEFORE the lease release below, and is awaited via the generator's return(), so the next
-                // turn for this session waits and never reopens mid-compaction. That await rides the consumer's
-                // iteration: a STREAMING consumer (e.g. telegram) already sent the reply on the terminal before
-                // returning, so compaction — rare, only over threshold — does not delay it; a `collect`-style
-                // consumer returns the reply FROM the loop, so it waits for the (occasional) compaction. Non-fatal:
-                // a failed compaction leaves the (still-valid) session for the next turn to retry.
-                if (completed) {
-                    try {
-                        await maybeCompact(harness, completed);
-                    }
-                    catch (error) {
-                        log.warn(`[fastagent] auto-compaction failed during cleanup: ${String(error)}`);
-                    }
-                }
-                // Cleanup MUST NOT throw after the terminal was yielded — that would make an already-closed
-                // event stream throw on iteration (violating SPEC MUST 2 / MUST 3). Contain it, but surface it
-                // (a cleanup failure is abnormal).
-                try {
-                    unsub();
-                }
-                catch (error) {
-                    log.warn(`[fastagent] harness unsubscribe failed during cleanup: ${String(error)}`);
-                }
-                try {
-                    await harness.abort();
-                }
-                catch (error) {
-                    log.warn(`[fastagent] harness abort failed during cleanup: ${String(error)}`);
-                }
-            }
-        }
-        finally {
-            // Exactly-one settlement, after ALL run work (incl. auto-compaction) and immediately before
-            // the lease releases — see the outcome note above. The stale-controls flag flips FIRST so a
-            // dispatch racing this settlement is rejected instead of silently accepted.
-            runSettled = true;
-            observe({ type: "run_settled", timestamp: Date.now(), runId, data: outcome ?? { status: "aborted" } });
-            release(); // after cleanup, so the next invoke for this session can enter
-        }
-    }
-    return { invoke };
-}

package/dist/engines/pi/read-image.d.ts

@@ -1,4 +0,0 @@
-import type { ReadImageProcessor } from "@earendil-works/pi-agent-core";
-/** The `read` tool's image processor. Matches pi-coding-agent's messages verbatim: they reach the model
- *  as tool output, so a reworded one is a different prompt, not a different implementation detail. */
-export declare const readImageProcessor: ReadImageProcessor;

package/dist/engines/pi/read-image.js

@@ -1,62 +0,0 @@
-/**
- * The image pipeline pi's `read` tool needs: normalize an unsupported format to PNG, resize below the
- * inline limit, and hand back the hints that tell the model what it is looking at.
- *
- * pi-agent-core's `createReadTool` takes this as an INJECTED processor and does nothing without one —
- * unlike pi-coding-agent's, which wires its private `processImage` internally. That function is not
- * exported (nor reachable: the package's `exports` map has no deep paths), so this rebuilds it from the
- * two halves that ARE public, `convertToPng` and `resizeImage`/`formatDimensionNote`.
- *
- * It is upstream logic restated, which is a real cost — without it `read` on a screenshot sends the raw
- * bytes (measured: 7.48 MB of base64 where pi-coding-agent sends 3.48 MB, and no dimension note for the
- * model's coordinate math), and a bmp is dropped entirely while the tool's own description still
- * advertises it. test/tools-parity.test.ts compares this against pi-coding-agent's real `read` on both
- * paths, so upstream changing the pipeline surfaces as a failing test rather than as drift.
- */
-import { convertToPng, formatDimensionNote, resizeImage } from "@earendil-works/pi-coding-agent";
-/** Formats a provider takes inline as-is; everything else has to become a PNG first. */
-const INLINE_MIME = {
-    "image/png": "image/png",
-    "image/jpeg": "image/jpeg",
-    "image/jpg": "image/jpeg",
-    "image/gif": "image/gif",
-    "image/webp": "image/webp",
-};
-/** The `read` tool's image processor. Matches pi-coding-agent's messages verbatim: they reach the model
- *  as tool output, so a reworded one is a different prompt, not a different implementation detail. */
-export const readImageProcessor = async (bytes, mimeType, options) => {
-    const base = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-    const inline = INLINE_MIME[base];
-    let normalized;
-    if (inline) {
-        normalized = { bytes, mimeType: inline };
-    }
-    else {
-        const png = await convertToPng(Buffer.from(bytes).toString("base64"), base);
-        if (!png)
-            return { ok: false, message: "[Image omitted: could not be converted to a supported inline image format.]" };
-        normalized = { bytes: Buffer.from(png.data, "base64"), mimeType: png.mimeType, convertedFrom: base };
-    }
-    const hints = [];
-    const converted = (to) => normalized.convertedFrom && normalized.convertedFrom !== to
-        ? `[Image converted from ${normalized.convertedFrom} to ${to}.]`
-        : undefined;
-    if (!options.autoResizeImages) {
-        const hint = converted(normalized.mimeType);
-        if (hint)
-            hints.push(hint);
-        return { ok: true, data: Buffer.from(normalized.bytes).toString("base64"), mimeType: normalized.mimeType, hints };
-    }
-    const resized = await resizeImage(normalized.bytes, normalized.mimeType);
-    if (!resized)
-        return { ok: false, message: "[Image omitted: could not be resized below the inline image size limit.]" };
-    const hint = converted(resized.mimeType);
-    if (hint)
-        hints.push(hint);
-    // The scale factor the model needs to map coordinates back onto the original — dropping it is what
-    // makes a resized screenshot unusable for anything positional.
-    const note = formatDimensionNote(resized);
-    if (note)
-        hints.push(note);
-    return { ok: true, data: resized.data, mimeType: resized.mimeType, hints };
-};

package/dist/engines/pi/sessions.d.ts

@@ -1,60 +0,0 @@
-import type { Session, SessionTreeEntry } from "@earendil-works/pi-agent-core";
-/**
- * Where a NEW session starts from, when it names a parent (participant-model.md §5: "a thread starts
- * from what the room knew"). Read only on the create path — an EXISTING session ignores it entirely,
- * which is what makes inheritance one-time by construction: no marker to persist, no decision to
- * retry per turn; the session existing IS the record that the decision was taken.
- */
-export interface SessionInheritance {
-    /** The session to fork from. Missing or unreadable → the new session starts empty, with a warn —
-     *  context is not the ask, and losing it must not cost the turn. */
-    parentSession: string;
-    /** Opaque markers that MAY locate the branch point on the parent's active path (searched in
-     *  message content, first hit wins, most recent occurrence). No match → the parent's present. */
-    branchHints?: string[];
-}
-/** What fastagent needs from a session backend: open-or-create by opaque id. */
-export interface PiSessionStore {
-    openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<Session>;
-}
-/**
- * OPEN-EXISTING sibling of {@link PiSessionStore} (session-control.ts): an unknown session answers
- * `undefined`, never creates one — sessions are the data plane's monopoly. Two consumers:
- * - the OBSERVATION plane (`state()`/`entries()`), strictly read-only (design §16 invariant 4);
- * - the control plane's BOUNDARY writers (`set_model`/`set_thinking` append override records to the
- *   returned handle; `navigate` moves its leaf) after an existence check, under the run lease.
- * `openIfExists` skips the open-time crash reconciliation (that appends repair entries — a write
- * the observation plane must not perform). The boundary writers are safe WITHOUT it for two
- * different reasons: an override record is not a message, so it cannot create or pair with a
- * dangling tool_use; a `navigate` writes no message either, but it CAN expose one — parking the
- * leaf on an assistant entry whose tool results are now off-path is the dangling-pair state
- * {@link reconcileInterruptedToolCalls} exists for. That is repaired at the next `openOrCreate`,
- * which repairs AT THE LEAF — exactly where a move puts it.
- *
- * Writing MESSAGE-class records through this handle would bypass that repair: use `openOrCreate`
- * for anything that enters the transcript.
- */
-export interface PiSessionReader {
-    openIfExists(sessionId: string): Promise<Session | undefined>;
-}
-/**
- * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
- * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
- * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
- * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
- * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
- * recorded before a compaction is a preference, and it still governs the session after one.
- */
-export declare function activePathEntries(session: Session): Promise<SessionTreeEntry[]>;
-/** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
-export declare function inMemorySessionStore(): PiSessionStore & PiSessionReader;
-/**
- * Disk-backed store (pi JsonlSessionRepo under `dir`): restart the process, conversations continue.
- * `cwd` is recorded in session metadata; defaults to process.cwd().
- */
-export declare function jsonlSessionStore(options: {
-    dir: string;
-    cwd?: string;
-    /** Inheritance guard override (tests): parent journals above this are not forked. Default 32 MiB. */
-    forkMaxBytes?: number;
-}): PiSessionStore & PiSessionReader;