@fastagent-sh/fastagent 0.17.1 → 0.18.0

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

@@ -0,0 +1,32 @@
+/**
+ * L0 over pi-coding-agent's `AgentSession`, in the `per-invoke` state locality
+ * ([conformance-levels.md](../../../docs/design/conformance-levels.md) §2, top-right cell): build a
+ * session per invoke over the SAME durable jsonl, run one turn, dispose.
+ *
+ * Why this exists next to {@link createPiAgentFromHarness}: pi 0.84 replaced `AgentHarness` with an
+ * unimplemented lane-based skeleton, and pi does not consume that class itself — its TUI, RPC and SDK
+ * all run on `AgentSession`. This is the executable proof that the SPEC's four Agent-side MUSTs hold
+ * on the class pi actually maintains (test/conformance-session.test.ts).
+ *
+ * SCOPE, deliberately narrow: the concurrency floor, the event stream, and cancellation. The
+ * observation plane (SessionObserver / RunControls / the rich `SessionEvent` vocabulary), the tool
+ * activation bridge, auto-compaction and session inheritance are NOT wired.
+ *
+ * WHICH L0 SERVES: {@link createPiAgentFromHarness}, still — this one is reachable only from its
+ * conformance test (deliberately absent from `src/pi.ts`), because a serving path needs the pieces
+ * above. Its one known debt is {@link toAgentEvent}: translating pi events straight to SPEC
+ * `AgentEvent`s is the second parallel translation `docs/design/session-control.md` §6 forbids. It
+ * retires the moment this L0 grows the observation plane — the rich `SessionEvent` layer comes back
+ * with it, and the harness L0 goes away.
+ */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type Agent } from "../../agent.ts";
+import { type Lease } from "./turn-kit.ts";
+/** Open-or-create the session behind `sessionId` and bind an `AgentSession` to it, per invoke. */
+export type PiAgentSessionFactory = (sessionId: string) => Promise<AgentSession>;
+export interface CreatePiAgentFromSessionOptions {
+    sessionFactory: PiAgentSessionFactory;
+    /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
+    lease?: Lease;
+}
+export declare function createPiAgentFromSession(options: CreatePiAgentFromSessionOptions): Agent;

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

@@ -0,0 +1,171 @@
+import { SESSION_BUSY_CODE } from "../../agent.js";
+import { cancellableStream } from "../../collect.js";
+import { log } from "../../log.js";
+import { EventQueue, errorToTerminal, inProcessLease, toPiPromptOptions, toTerminal } from "./turn-kit.js";
+/**
+ * SPEC events from pi's session stream. `auto_retry_start` has no harness counterpart: an
+ * `AgentSession` retries a failed assistant request itself, which the SPEC already has a word for.
+ */
+function toAgentEvent(event) {
+    switch (event.type) {
+        case "message_update": {
+            // An empty delta is not output: it moves no consumer's state, and treating it as output would
+            // spend the silent window that auto-retry is allowed to use (see runOnSession).
+            const ev = event.assistantMessageEvent;
+            if (ev.type === "text_delta")
+                return ev.delta === "" ? null : { type: "text", delta: ev.delta };
+            if (ev.type === "thinking_delta")
+                return ev.delta === "" ? null : { type: "thinking", delta: ev.delta };
+            return null;
+        }
+        case "tool_execution_start":
+            return { type: "tool_started", id: event.toolCallId, name: event.toolName, args: event.args };
+        case "tool_execution_end":
+            return { type: "tool_ended", id: event.toolCallId, isError: event.isError, content: event.result };
+        case "auto_retry_start":
+            return {
+                type: "retrying",
+                attempt: event.attempt,
+                maxAttempts: event.maxAttempts,
+                delayMs: event.delayMs,
+                reason: event.errorMessage,
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * The turn's outcome. `prompt()` resolves void and never throws for an engine-side failure (measured:
+ * a provider error and an abort both resolve normally), so the terminal comes from the assistant
+ * message the run ended on — the same read {@link toTerminal} performs on the harness path.
+ *
+ * That message is taken from the EVENT STREAM, not from `session.state.messages`. Session state is
+ * mutable mid-turn: compaction replaces the array, and overflow recovery splices the last assistant
+ * message out of it outright (`state.messages = messages.slice(0, -1)`). Any index into it is a
+ * turn boundary that the engine is free to invalidate, while a `message_end` payload is a fact that
+ * already happened. Auto-compaction runs its own model call outside the agent's event stream, so it
+ * cannot masquerade as the turn's answer here.
+ */
+const ENGINE_PRODUCED_NOTHING = {
+    // Unreachable on a settled run: pi ends every outcome, error and abort included, with an assistant
+    // message. Reaching it means the engine broke its own contract — name the engine, not the turn.
+    type: "failed",
+    details: "the engine settled the run without ending an assistant message",
+    retryable: false,
+};
+export function createPiAgentFromSession(options) {
+    const { sessionFactory, lease = inProcessLease() } = options;
+    /** Own the session's lifetime: one writer, built here, disposed here whatever the turn did. */
+    async function* turn(scope, prompt, hooks) {
+        const release = lease.tryAcquire(scope.session);
+        if (!release) {
+            yield {
+                type: "failed",
+                details: "session busy: a turn is already in flight for this session",
+                retryable: true,
+                code: SESSION_BUSY_CODE,
+            };
+            return;
+        }
+        try {
+            let session;
+            try {
+                session = await sessionFactory(scope.session);
+            }
+            catch (error) {
+                yield errorToTerminal(error); // setup failures are events, never throws (MUST 2)
+                return;
+            }
+            try {
+                yield* runOnSession(session, prompt, hooks);
+            }
+            finally {
+                try {
+                    session.dispose();
+                }
+                catch (error) {
+                    log.warn(`[fastagent] session dispose failed during cleanup: ${String(error)}`);
+                }
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    return { invoke: (scope, prompt) => cancellableStream((hooks) => turn(scope, prompt, hooks)) };
+}
+/** One turn on a session someone else owns: subscribe, prompt, stream, terminal. */
+async function* runOnSession(session, prompt, { onCancelReady, wasCancelled }) {
+    const abort = () => session.abort().catch(() => { });
+    onCancelReady(() => void abort());
+    const queue = new EventQueue();
+    let finalAssistant;
+    /** Whether any of THIS attempt's answer has been streamed — the only output a retry would duplicate. */
+    let streamedAnswer = false;
+    /** Set when a retry is refused because the answer already streamed — carries the error that ends it. */
+    let retriedAfterAnswer;
+    const unsub = session.subscribe((event) => {
+        if (retriedAfterAnswer !== undefined)
+            return; // the turn is decided; the retry's output is not ours
+        if (event.type === "message_end" && event.message.role === "assistant") {
+            finalAssistant = event.message;
+        }
+        // pi retries a failed assistant request by DISCARDING that attempt's assistant message and asking
+        // again. Everything the turn achieved before it survives - executed tools keep their persisted
+        // results, and the retry resumes from them - so the only thing a retry can duplicate is answer
+        // text this L0 already streamed, which SPEC deltas cannot retract. Refuse it exactly there:
+        // refusing on tool events instead would push the retry out to the CALLER, who can only re-run the
+        // whole prompt and execute the tool a second time.
+        if (event.type === "auto_retry_start" && streamedAnswer) {
+            retriedAfterAnswer = event.errorMessage;
+            // Not synchronously: pi emits this event BEFORE creating the controller that makes its backoff
+            // abortable, so an abort from inside the listener would find nothing to cancel and the turn
+            // would still pay the full delay and burn a provider call on an answer we must discard.
+            queueMicrotask(() => void abort());
+            return;
+        }
+        const projected = toAgentEvent(event);
+        if (!projected)
+            return;
+        if (projected.type === "text" || projected.type === "thinking")
+            streamedAnswer = true;
+        queue.push(projected);
+    });
+    try {
+        // Resolving prompt options 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. Hence the two guards, in
+        // this order and no earlier: its failure is a turn failure (MUST 2), and the latch has to be read
+        // after the LAST await before the call — the door armed above only stops a RUNNING session, so a
+        // consumer who walked away during the build or the resize would knock on an idle one and have
+        // the turn start anyway.
+        let options;
+        try {
+            options = await toPiPromptOptions(prompt);
+        }
+        catch (error) {
+            yield errorToTerminal(error);
+            return;
+        }
+        if (wasCancelled()) {
+            await abort();
+            return;
+        }
+        const run = session.prompt(prompt.text, options);
+        yield* queue.drainUntil(run);
+        try {
+            await run;
+            if (retriedAfterAnswer !== undefined) {
+                yield { type: "failed", details: retriedAfterAnswer, retryable: true };
+            }
+            else {
+                yield finalAssistant ? toTerminal(finalAssistant) : ENGINE_PRODUCED_NOTHING;
+            }
+        }
+        catch (error) {
+            yield errorToTerminal(error);
+        }
+    }
+    finally {
+        unsub();
+    }
+}

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

@@ -1,32 +1,20 @@
 /**
- * The turn mechanism (request-time): fan pi AgentHarness's two ports (subscribe event side-channel
- * + prompt final value) into SPEC's single event stream, under a single-writer-per-session lease.
+ * The harness L0: fan pi AgentHarness's two ports (subscribe event side-channel + prompt final
+ * value) into SPEC's single event stream, under a single-writer-per-session lease.
  *
- *   §1 Lease       — single-writer concurrency floor (injectable port + in-process default)
- *   §2 translate   — the single pi↔SPEC translation point (both directions)
- *   §3 EventQueue  — push→pull plumbing for pi's two-port shape
- *   §4 createPiAgentFromHarness — composes §1–§3 into Agent.invoke
+ * The half that does not care which pi class runs the turn — lease, terminals, event queue, prompt
+ * prep — is turn-kit.ts. What lives here is what only the harness has: its event vocabulary, translated ONCE
+ * into the rich `SessionEvent` layer, and the observation plane that layer feeds.
  *
  * Concurrency: at most one in-flight turn per session; a second invoke fails fast with
  * `failed{retryable}` ("session busy"), leaving dedupe/queueing/steering to the channel. Each
  * invoke builds a fresh harness bound to the session and discards it (stateless multi-session).
  */
 import type { AgentHarnessEvent } from "@earendil-works/pi-agent-core";
-import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { type Agent, type AgentEvent, type Prompt } from "../../agent.ts";
 import type { SessionEvent } from "../../session.ts";
 import { type PiHarnessFactory } from "./harness.ts";
-export type Release = () => void;
-export interface Lease {
-    /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */
-    tryAcquire(session: string): Release | null;
-}
-export declare function inProcessLease(): Lease;
-/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
-export declare function classifyRetryable(details: string, signal: {
-    status?: number;
-    code?: unknown;
-}): boolean;
+import { type Lease } from "./turn-kit.ts";
 /**
  * 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
@@ -58,15 +46,6 @@ export interface RunControls {
  *  modulation handles — it is the trusted hub seam, not a public fan-out point. Do not wire
  *  untrusted taps here; give third parties the read-only `events()` stream instead. */
 export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
-/**
- * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
- * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
- * entire failure class (violating SPEC MUST 1).
- */
-export declare function toTerminal(message: AssistantMessage): AgentEvent;
-export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
-    type: "failed";
-}>;
 export interface CreatePiAgentFromHarnessOptions {
     harnessFactory: PiHarnessFactory;
     /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */

package/dist/engines/pi/invoke.js

@@ -1,27 +1,11 @@
 import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
 import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
-import { abortFirstIterator } from "../../collect.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";
-export function inProcessLease() {
-    const busy = new Set();
-    return {
-        tryAcquire(session) {
-            if (busy.has(session))
-                return null;
-            busy.add(session);
-            let released = false;
-            return () => {
-                if (released)
-                    return;
-                released = true;
-                busy.delete(session);
-            };
-        },
-    };
-}
-// ── §2 translate: the single pi↔SPEC translation point ───────────────────────
+// ── 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
@@ -37,65 +21,6 @@ export function inProcessLease() {
 // 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).
-/** Clearly-transient network error codes (Node/undici), decisive on their own. */
-const RETRYABLE_CODES = new Set([
-    "ECONNRESET",
-    "ETIMEDOUT",
-    "ENETUNREACH",
-    "ENETDOWN",
-    "EAI_AGAIN",
-    "EPIPE",
-    "UND_ERR_CONNECT_TIMEOUT",
-    "UND_ERR_SOCKET",
-]);
-/** 429 (rate limit) and 5xx (server) are worth retrying; other statuses are decisive NON-retryable. */
-const statusIsRetryable = (status) => status === 429 || (status >= 500 && status < 600);
-/** Last-resort prose match, used only when no structured status/code is available. */
-const RETRYABLE_MESSAGE = /\b(429|5\d\d|timeout|timed out|rate.?limit|overloaded|ECONNRESET|ETIMEDOUT|ENETUNREACH|EAI_AGAIN|socket hang up)\b/i;
-/** A structured status/code decision, or `null` when the signal is absent/undecisive → fall to prose. */
-function retryableFromSignal(signal) {
-    if (typeof signal.status === "number")
-        return statusIsRetryable(signal.status);
-    const { code } = signal;
-    if (typeof code === "number")
-        return statusIsRetryable(code);
-    if (typeof code === "string") {
-        if (RETRYABLE_CODES.has(code))
-            return true;
-        if (/^\d{3}$/.test(code))
-            return statusIsRetryable(Number(code)); // a status carried as a string
-    }
-    return null; // no code, or an unknown one — not decisive on its own
-}
-/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
-export function classifyRetryable(details, signal) {
-    return retryableFromSignal(signal) ?? RETRYABLE_MESSAGE.test(details);
-}
-/** Pull a structured status/code off a thrown error (HTTP status or a network code, incl. its cause). */
-function errorSignal(error) {
-    if (!error || typeof error !== "object")
-        return {};
-    const e = error;
-    const status = typeof e.status === "number" ? e.status : typeof e.statusCode === "number" ? e.statusCode : undefined;
-    const causeCode = e.cause && typeof e.cause === "object" ? e.cause.code : undefined;
-    return { status, code: e.code ?? causeCode };
-}
-/**
- * Pull the structured error `code` pi records on a failed message's diagnostics. `diagnostics`
- * accumulates across attempts (`appendAssistantMessageDiagnostic`), so the terminal cause is the LAST
- * code-bearing entry — `findLast`, not `find`: an earlier attempt's transient 503 must not classify a
- * terminal 400/auth failure as retryable. (Reverse scan rather than `findLast` — the tsconfig lib is
- * ES2022.)
- */
-function messageSignal(message) {
-    const diagnostics = message.diagnostics ?? [];
-    for (let i = diagnostics.length - 1; i >= 0; i--) {
-        const code = diagnostics[i]?.error?.code;
-        if (code !== undefined)
-            return { code };
-    }
-    return {};
-}
 /**
  * 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
@@ -203,28 +128,6 @@ export function projectAgentEvent(se) {
             return null;
     }
 }
-/**
- * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
- * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
- * entire failure class (violating SPEC MUST 1).
- */
-export function toTerminal(message) {
-    if (message.stopReason === "aborted") {
-        // A deliberate stop (control-plane abort / harness abort), not an error — see {@link ABORTED_CODE}
-        // for the consumer contract (design §6).
-        const details = message.errorMessage ?? "run aborted";
-        return { type: "failed", details, retryable: false, code: ABORTED_CODE };
-    }
-    if (message.stopReason === "error") {
-        const details = message.errorMessage ?? `model stopped: ${message.stopReason}`;
-        return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
-    }
-    return { type: "completed" };
-}
-export function errorToTerminal(error) {
-    const details = error instanceof Error ? error.message : String(error);
-    return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
-}
 /** Bind the concrete pi-agent-core Session behind FastAgent's tool-runtime manager port. */
 function toolSessionManager(sessionId, harness) {
     const session = harnessSession(harness);
@@ -288,100 +191,16 @@ async function maybeCompact(harness, message) {
         await harness.compact();
     }
 }
-/**
- * Map prompt images to pi ImageContent, resizing each to model-friendly dimensions/size with pi's
- * Photon resizer (reused from pi-coding-agent, lazy-imported so the common no-image headless path never
- * loads the TUI module graph). A null resize (unresizable / Photon unavailable) keeps the original
- * bytes — the provider then applies its own limit.
- */
-async function toPiPromptOptions(prompt) {
-    if (!prompt.images || prompt.images.length === 0)
-        return undefined;
-    const { resizeImage } = await import("@earendil-works/pi-coding-agent");
-    const images = await Promise.all(prompt.images.map(async (img) => {
-        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType, {
-            maxWidth: 1568,
-            maxHeight: 1568,
-            maxBytes: 5 * 1024 * 1024,
-        }).catch(() => null);
-        return resized
-            ? { type: "image", data: resized.data, mimeType: resized.mimeType }
-            : { type: "image", data: img.data, mimeType: img.mimeType };
-    }));
-    return { images };
-}
-// ── §3 EventQueue: push→pull plumbing for pi's two-port shape ────────────────
-//
-// Single-consumer async queue; single-threaded JS means no await interleaves between push and
-// drain, so no locking. Engines that are natively async-iterable would not need it.
-class EventQueue {
-    buffer = [];
-    wake;
-    push(item) {
-        this.buffer.push(item);
-        const wake = this.wake;
-        this.wake = undefined;
-        wake?.();
-    }
-    /**
-     * Yield pushed events in order until `done` settles AND the buffer is drained. The terminal is
-     * produced separately (toTerminal); rejections of `done` are swallowed here (the caller awaits
-     * `run` itself) to avoid unhandled rejections.
-     */
-    async *drainUntil(done) {
-        let settled = false;
-        const onSettle = () => {
-            settled = true;
-            const wake = this.wake;
-            this.wake = undefined;
-            wake?.();
-        };
-        const finished = done.then(onSettle, onSettle);
-        while (true) {
-            while (this.buffer.length > 0) {
-                yield this.buffer.shift();
-            }
-            if (settled)
-                break;
-            await new Promise((resolve) => {
-                this.wake = resolve;
-            });
-        }
-        await finished;
-    }
-}
 /** "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;
-    function invoke(scope, prompt) {
-        // The cancellation DOOR (SPEC MUST 3), via the shared abort-first protocol (see
-        // abortFirstIterator): cancel aborts the engine work, which settles the run and releases a
-        // generator suspended on a quiet stream (a tool mid-execution). The local for-await pattern
-        // never hit the underlying deadlock (it breaks at a yield boundary); pull-driven consumers
-        // (the SSE handler's eager reads) do.
-        // The cancel intent is LATCHED: a consumer may cancel while the generator is still inside
-        // the harness build (the door not yet armed) — abortFirstIterator knocks exactly once, and a
-        // knock before prompt() starts would be a no-op on an idle harness (the LATER run would
-        // ignore it). So turn consults the latch right after arming and, when the consumer already
-        // walked away, never starts the model call at all.
-        let externalCancel;
-        let cancelled = false;
-        const gen = turn(scope, prompt, (cancel) => {
-            externalCancel = cancel;
-        }, () => cancelled);
-        const iterator = abortFirstIterator(gen, () => {
-            cancelled = true;
-            externalCancel?.();
-        });
-        return {
-            [Symbol.asyncIterator]() {
-                return iterator;
-            },
-        };
-    }
-    async function* turn(scope, prompt, onCancelReady, 
-    /** The consumer's cancel latch (see invoke's wrapper) — checked once at arming. */
-    wasCancelled) {
+    // 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).
@@ -480,7 +299,14 @@ export function createPiAgentFromHarness(options) {
         try {
             let harness;
             try {
-                harness = await harnessFactory(scope.session);
+                // 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.
@@ -497,21 +323,6 @@ export function createPiAgentFromHarness(options) {
             onCancelReady(() => {
                 void harness.abort().catch(() => { });
             });
-            // The consumer cancelled DURING the build (latched — the door above came too late to be
-            // knocked): never start the model call; settle as aborted and let the queued return()
-            // finish the generator. Same synchronous tick as the arming — a cancel from here on
-            // reaches the armed door instead.
-            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
-            }
             const queue = new EventQueue();
             const unsub = harness.subscribe((pe) => {
                 // Summarization retries also warn to server logs: the session `retry_scheduled` event only
@@ -529,8 +340,38 @@ export function createPiAgentFromHarness(options) {
             });
             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 opts = await toPiPromptOptions(prompt);
                 const run = turnContext.run({
                     cwd: options.cwd ?? process.cwd(),
                     sessionManager: toolSessionManager(scope.session, harness),

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

@@ -1,13 +1,16 @@
-/**
- * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId
- * lookup) AND auth (per-request credential resolution). fastagent builds one per opener and threads
- * it into the harness alongside the selected `model`; the two must come from the same collection so
- * the model's provider auth is in scope.
- */
 import { type Api, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type FastagentAuthOptions } from "./auth.ts";
 import { type InteractiveLoginKind } from "./login.ts";
+/** The DEFINITION-LOCAL custom-endpoint file, in pi's own models.json schema (see pi's docs/models.md):
+ *  declare a self-hosted / gateway endpoint as `{ providers: { <id>: { baseUrl, api, apiKey, models } } }`
+ *  and select it with a `<id>/<modelId>` model spec. Keys belong in the environment — `apiKey` supports
+ *  `"$ENV_VAR"` interpolation and `"!command"` — with the NAME listed in `deploy.secrets` so the value
+ *  travels to the host. Living in the agent dir is the whole point: it is part of the definition, so it
+ *  is baked into the deployed image. pi's MACHINE-GLOBAL `~/.pi/agent/models.json` stays unread — that
+ *  one is builder-machine state, and reading it would make an agent work locally and lose its model on
+ *  deploy. The NAME itself lives in the neutral paths.ts — `dev`'s watcher needs the same one, and a
+ *  second spelling would let the restart scope drift from what the worker loads. */
 export interface CreatePiModelsOptions extends FastagentAuthOptions {
     /** Credentials file path. Defaults to the global `~/.fastagent/.secrets/auth.json`; the directory opener passes
      *  the project-level `<root>/.secrets/auth.json`. */
@@ -26,15 +29,46 @@ export declare function createPiModels(options?: CreatePiModelsOptions): Models;
 /**
  * The `ModelRuntime`-shaped sibling of {@link createPiModels} — the SAME hub semantics (built-in
  * providers + fastagent's credential store at `authPath`) in the type pi's session services require
- * (`createAgentSessionServices({ modelRuntime })`). Builtins only (`modelsPath: null` — pi's
- * machine-global models.json is definition-foreign) and no availability network, so the model
- * surface equals serving's. No `providers` option: `ModelRuntime` registers providers by config
- * record, not `Provider` instance — accepting the option and dropping it would be a silent no-op;
- * add the mapping when a consumer actually needs it.
+ * (`createAgentSessionServices({ modelRuntime })`). Built-ins PLUS the agent's own
+ * {@link AGENT_MODELS_FILE} when `agentDir` is given (a dir-less caller gets built-ins only), and no
+ * availability network, so the model surface equals serving's.
+ *
+ * `ModelRuntime` also takes `Provider` INSTANCES via `registerNativeProvider` (pi 0.83); the
+ * declarative file is what this rung wires because it is data that travels with the definition.
  */
 export declare function createPiModelRuntime(options?: FastagentAuthOptions & {
     authPath?: string;
+    /** The agent dir, whose {@link AGENT_MODELS_FILE} declares custom endpoints. Omit for built-ins only. */
+    agentDir?: string;
+    /** Where the dynamic model-catalog cache goes; defaults to the agent's resolved state root. */
+    stateRoot?: string;
+    /** Extra providers for the ids the built-ins do not cover — the CODE-shaped sibling of models.json,
+     *  for what a file cannot express (minting a token per request, a test fake).
+     *
+     *  On an id COLLISION the file wins, not this: upstream installs a native provider as the BASE and
+     *  composes the models.json entry over it. Right way round — where a deployed agent's traffic goes
+     *  is a property of the definition, not of the program that embedded it — but it does mean a same-id
+     *  file entry silently replaces the endpoint injected here. Use a distinct id to keep both. */
+    providers?: Provider[];
 }): Promise<ModelRuntime>;
+/**
+ * How a model's credential will REACH a deployed agent — the question `deploy` asks, which
+ * {@link probeAuthSource} cannot answer: it flattens every models.json endpoint to the display label
+ * "configured API key", so a self-hosted endpoint looks credential-less to the deploy gate even when
+ * its key is sitting in an env var.
+ *
+ * - `envVar`: an environment variable backs it, BY NAME — the shape `deploy` already understands, so
+ *   the value carries as a host secret with no extra declaration from the author.
+ * - `inDefinition`: the definition itself carries it (a literal `apiKey`, or a `!command` run on the
+ *   host). Nothing for `deploy` to carry — and nothing to gate on either, which is the point: the
+ *   `fastagent login` remedy is meaningless for a provider login cannot serve.
+ *
+ * Neither set = a stored credential or nothing at all; the existing auth.json / gate paths decide.
+ */
+export declare function modelCredentialCarry(runtime: ModelRuntime, spec: string): {
+    envVar?: string;
+    inDefinition: boolean;
+};
 /** Per-provider auth status for the first-run model picker: usable now (with the source label), not
  *  configured, or configured-but-broken (expired token, refresh failure, corrupt store — kept as DATA
  *  so the picker can show it instead of silently dropping the provider). Non-ready states carry the