@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/engines/pi/definition.js

@@ -14,10 +14,11 @@
  * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
  */
 import { realpathSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { loadSkills } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { log } from "../../log.js";
 import { assertInsideAgentDir } from "../../paths.js";
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export async function loadAgentDefinition(agentDir, options = {}) {
@@ -45,6 +46,119 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     const { skills, diagnostics, collisions } = await readSkills(e, root);
     return { contextFiles, persona, skills, diagnostics, collisions, dir: root };
 }
+/**
+ * Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none.
+ *
+ * Paths, not loaded objects — unlike skills (data: content inline, serializable), an extension is
+ * CODE that pi loads with jiti and binds to its own eventBus/runtime, so loading it here would
+ * reimplement pi's loader. The engine binding hands these to pi as `additionalExtensionPaths`, which
+ * survives `noExtensions: true` — that flag suppresses MACHINE-GLOBAL discovery (`~/.pi`), and the
+ * definition's own extensions were only ever collateral to it. FILES, not the directory: pi's paths
+ * are module specifiers, and a directory fails as `Cannot find module` into a
+ * `LoadExtensionsResult.errors` entry nothing reads.
+ *
+ * SEPARATE from {@link loadAgentDefinition} on purpose. Prompt and skills are re-read every invoke
+ * ("the directory is the agent, LIVE"); scanning for extension entry points is not, since the set
+ * cannot change without a restart. Called once per assembly, like `tools/`.
+ *
+ * Discovery runs on BOTH paths; loading does not. `chat` hands these to pi and runs them fully.
+ * Serving only announces them — pi's extension runtime is shared across sessions, and serving has
+ * concurrent turns for unrelated conversations (see `PiAgentSessionFactoryOptions.extensionPaths`).
+ * The refusals below are therefore about what the ARTIFACT may contain, and hold for both.
+ *
+ * Discovery follows pi's own rules, so an extension that works in pi works here:
+ *
+ * 1. a direct `*.ts` / `*.js` file;
+ * 2. a subdirectory with `index.ts` / `index.js`.
+ *
+ * pi has a third rule — a subdirectory whose `package.json` declares a `pi` field — which is NOT
+ * implemented here. That shape is reported rather than skipped: a definition whose extension silently
+ * fails to load is the failure mode this whole path exists to remove.
+ *
+ * Containment matches skills/tools/channels/schedules (the fifth of five surfaces): a symlinked
+ * `extensions/` escaping the agent dir is refused, and — like `loadModuleDir`, whose `entry.isFile()`
+ * excludes them — a symlinked ENTRY is not loaded either. pi's own discovery does follow those, but
+ * an extension reached through a link out of the definition is code the artifact does not carry: it
+ * resolves on the authoring machine and is missing in the container. Refused loudly, never silently.
+ *
+ * Absent is normal and silent; a FILE at that path is not — that is an author who meant something.
+ */
+export async function loadExtensionPaths(agentDir, options = {}) {
+    const cwd = options.cwd ?? agentDir;
+    const e = options.env ?? new NodeExecutionEnv({ cwd });
+    const rootResult = await e.absolutePath(agentDir);
+    if (!rootResult.ok)
+        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
+    const root = rootResult.value;
+    await assertInsideAgentDir(root, "extensions");
+    const dir = join(root, "extensions");
+    const listed = await e.listDir(dir);
+    if (!listed.ok) {
+        if (listed.error.code === "not_found")
+            return [];
+        throw new Error(`cannot read ${dir}: ${listed.error.message}`);
+    }
+    const paths = [];
+    for (const entry of listed.value) {
+        if (entry.kind === "symlink") {
+            // EVERY symlink here is announced, without guessing whether it meant to be an extension. The
+            // two mistakes are not equal: a needless line about a symlinked README costs a glance, while
+            // staying quiet about a symlinked extension loses a feature silently and only shows up in the
+            // container. A name-based guess also cannot see through the link — `audit.ext -> some/dir` is
+            // a directory candidate to pi and a mystery here — so the warning says what it knows and
+            // tells the author when to ignore it.
+            warnSymlinkRefused(entry.path);
+            continue;
+        }
+        if (entry.name.endsWith(".ts") || entry.name.endsWith(".js")) {
+            if (entry.kind === "file")
+                paths.push(entry.path);
+            continue;
+        }
+        if (entry.kind === "file")
+            continue; // a README, a .json — not an extension, not a problem
+        const index = await firstRealFile(e, [join(entry.path, "index.ts"), join(entry.path, "index.js")]);
+        if (index.path) {
+            paths.push(index.path);
+        }
+        else if (!index.refused) {
+            // Silent when the index WAS found and refused for being a symlink: that warning already named
+            // the real problem, and "expected index.ts" on top of it describes a directory that has one.
+            log.warn(`[fastagent] ${entry.path} is not a loadable extension: expected index.ts or index.js ` +
+                `(pi's package.json "pi" manifest form is not supported here) — it will not be loaded`);
+        }
+    }
+    return paths.sort();
+}
+/**
+ * The first candidate that is a REAL file. `exists` would follow a symlink, which is how a
+ * subdirectory's `index.ts` could otherwise point outside the definition and slip past the rule the
+ * top-level entries already follow.
+ */
+/** The first real file among the candidates, and whether one was found but REFUSED as a symlink. */
+async function firstRealFile(e, candidates) {
+    let refused = false;
+    for (const candidate of candidates) {
+        const info = await e.fileInfo(candidate);
+        if (!info.ok) {
+            if (info.error.code === "not_found")
+                continue;
+            throw new Error(`cannot read ${candidate}: ${info.error.message}`);
+        }
+        if (info.value.kind === "file")
+            return { path: candidate, refused };
+        if (info.value.kind === "symlink") {
+            warnSymlinkRefused(candidate);
+            refused = true;
+        }
+    }
+    return { refused };
+}
+function warnSymlinkRefused(path) {
+    log.warn(`[fastagent] ${path} is a symlink and will not be loaded: an extension must be a real file inside ` +
+        `the definition so it travels with the artifact — move it in. (If it is not an extension, ` +
+        `keep it outside extensions/ to silence this.)`);
+}
 /** The skills half, shared by the full load and {@link loadAgentSkills}. `root` is already resolved. */
 async function readSkills(e, root) {
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
@@ -81,16 +195,6 @@ export async function loadAgentSkills(agentDir, options = {}) {
     // (the findings memo) on it, and "./agent" vs an absolute path must not become two definitions.
     return { ...(await readSkills(e, rootResult.value)), dir: rootResult.value };
 }
-/**
- * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
- * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
- * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
- * does not act on where a user's paths point.
- */
-export function isUnderDir(targetPath, baseDir) {
-    const rel = relative(baseDir, targetPath);
-    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-}
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export function canonicalPath(p) {

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

@@ -0,0 +1,35 @@
+/**
+ * THE L0: pi's `AgentSession`, one per invoke, over the same durable record —
+ * [conformance-levels.md](../../../docs/design/conformance-levels.md) §2's `per-invoke` posture.
+ * Build a session, run one turn, dispose; continuity lives in the record, never in this process.
+ *
+ * Why this class: 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`. Being the
+ * sole consumer of a surface nobody dogfoods is a position, not an architecture.
+ *
+ * Events are translated ONCE, into the rich `SessionEvent` vocabulary the observation plane speaks;
+ * the SPEC stream is a projection of that (`docs/design/session-control.md` §6 — one translation
+ * plus one projection, never two parallel ones).
+ *
+ * Two disciplines this file exists to hold:
+ * - the turn's outcome comes from the EVENT STREAM, never from an index into session state, which
+ *   compaction and overflow recovery both rewrite mid-turn;
+ * - `run_started` is published BEFORE the session is bound, so a dispatch racing the build queues on
+ *   the run's controls instead of finding no run.
+ */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { SessionInheritance } from "./session-inheritance.ts";
+import { type Agent } from "../../agent.ts";
+import { type Lease, type SessionObserver } from "./turn-kit.ts";
+/** Open-or-create the session behind `sessionId` and bind an `AgentSession` to it, per invoke.
+ *  `inherit` reaches the CREATE path only — an existing session ignores it. */
+export type PiAgentSessionFactory = (sessionId: string, inherit?: SessionInheritance) => Promise<AgentSession>;
+export interface CreatePiAgentFromSessionOptions {
+    sessionFactory: PiAgentSessionFactory;
+    /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
+    lease?: Lease;
+    /** Observation-plane tap: every rich event of every run, plus the run's live {@link RunControls}
+     *  on `run_started`. Optional; the SPEC stream is identical with or without it. */
+    observer?: SessionObserver;
+}
+export declare function createPiAgentFromSession(options: CreatePiAgentFromSessionOptions): Agent;

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

@@ -0,0 +1,357 @@
+import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { cancellableStream } from "../../collect.js";
+import { log } from "../../log.js";
+import { EventQueue, errorToTerminal, inProcessLease, projectAgentEvent, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
+/**
+ * pi session events into the rich `SessionEvent` vocabulary — the SINGLE translation point. Events
+ * with no vocabulary yet (agent_start, turn_start, entry_appended, …) are dropped.
+ *
+ * `auto_retry_start` reports as a `retry_scheduled` with `operation: "assistant"`: pi retries a
+ * failed ANSWER request itself, which the summarization-only cases of that vocabulary predate.
+ */
+function toSessionEvent(event, runId) {
+    const at = Date.now();
+    switch (event.type) {
+        case "message_start":
+            // Assistant streaming only — a user/toolResult message is not a live message boundary.
+            if (event.message.role !== "assistant")
+                return null;
+            return { type: "message_started", timestamp: at, runId, data: {} };
+        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: "message_delta", timestamp: at, runId, data: { channel: "text", delta: ev.delta } };
+            }
+            if (ev.type === "thinking_delta") {
+                return ev.delta === ""
+                    ? null
+                    : { type: "message_delta", timestamp: at, runId, data: { channel: "thinking", delta: ev.delta } };
+            }
+            return null;
+        }
+        case "message_end":
+            if (event.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: event.toolCallId, name: event.toolName, args: event.args },
+            };
+        case "tool_execution_update":
+            return {
+                type: "tool_progress",
+                timestamp: at,
+                runId,
+                data: { id: event.toolCallId, name: event.toolName, partialResult: event.partialResult },
+            };
+        case "tool_execution_end":
+            return {
+                type: "tool_finished",
+                timestamp: at,
+                runId,
+                data: { id: event.toolCallId, isError: event.isError, content: event.result },
+            };
+        case "queue_update":
+            return {
+                type: "queue_changed",
+                timestamp: at,
+                runId,
+                data: { steering: event.steering.length, followUp: event.followUp.length },
+            };
+        case "auto_retry_start": {
+            const retry = {
+                type: "retry_scheduled",
+                timestamp: at,
+                runId,
+                data: {
+                    operation: "assistant",
+                    attempt: event.attempt,
+                    maxAttempts: event.maxAttempts,
+                    delayMs: event.delayMs,
+                    error: event.errorMessage,
+                },
+            };
+            return retry;
+        }
+        case "summarization_retry_scheduled": {
+            const retry = {
+                type: "retry_scheduled",
+                timestamp: at,
+                runId,
+                data: {
+                    operation: "compaction",
+                    attempt: event.attempt,
+                    maxAttempts: event.maxAttempts,
+                    delayMs: event.delayMs,
+                    error: event.errorMessage,
+                },
+            };
+            return retry;
+        }
+        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.
+ *
+ * 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(), observer } = options;
+    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: exactly one run_started, exactly one run_settled. The settlement is
+        // emitted in the outer finally, immediately before the lease releases, so the observation
+        // plane's "running" window equals the lease window — state() must never read idle while a new
+        // invoke would still be rejected session_busy. A run with no recorded outcome was cancelled by
+        // the caller (SPEC: cancellation has no terminal event), which settles as 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 is published BEFORE the session is built, so no early event can outrun the
+        // registration — which means the controls have to await the build rather than reject during it:
+        // a dispatch that races it simply queues on the freshly bound session. A build failure rejects
+        // the gate, so a pending dispatch learns why instead of hanging.
+        let sessionReady;
+        let sessionFailed;
+        const bound = new Promise((resolve, reject) => {
+            sessionReady = resolve;
+            sessionFailed = reject;
+        });
+        bound.catch(() => { }); // observed through the controls only when a dispatch actually happens
+        // Stale-controls guard: after settlement pi's steer()/followUp()/abort() would still resolve
+        // (they queue onto a session about to be disposed), which is a silent acceptance of a command
+        // that can never take effect. The check and the engine call share one synchronous block — pi
+        // enqueues at method entry, so a check behind its own await would only shrink the race.
+        let settled = false;
+        const settledError = () => new Error("run already settled; the command cannot take effect");
+        // Aborted classification has two sources, either sufficient: pi's own stopReason "aborted", and
+        // control-plane INTENT — providers do not uniformly attribute an aborted stream, so an abort
+        // that was still in flight when the terminal arrived counts too.
+        let abortsInFlight = 0;
+        let abortSucceeded = false;
+        const controls = {
+            async steer(p) {
+                const opts = await toPiPromptOptions(p);
+                const session = await bound;
+                if (settled)
+                    throw settledError();
+                await session.steer(p.text, opts?.images);
+            },
+            async followUp(p) {
+                const opts = await toPiPromptOptions(p);
+                const session = await bound;
+                if (settled)
+                    throw settledError();
+                await session.followUp(p.text, opts?.images);
+            },
+            async abort() {
+                const session = await bound;
+                if (settled)
+                    throw settledError();
+                abortsInFlight++;
+                try {
+                    await session.abort();
+                    abortSucceeded = true;
+                }
+                finally {
+                    abortsInFlight--;
+                }
+            },
+        };
+        observe({ type: "run_started", timestamp: Date.now(), runId, data: {} }, controls);
+        try {
+            let session;
+            try {
+                // The scope's lineage reaches the store's CREATE path only — an existing session opens
+                // exactly as before, whatever the scope names.
+                session = await sessionFactory(scope.session, scope.parentSession === undefined
+                    ? undefined
+                    : {
+                        parentSession: scope.parentSession,
+                        ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
+                    });
+                sessionReady(session);
+            }
+            catch (error) {
+                // Setup failures (session open, auth, a broken definition) are EVENTS, never throws
+                // (MUST 2) — and they settle the run as failed: an unrecorded outcome means the caller
+                // cancelled, which this is not.
+                sessionFailed(error); // a pending dispatch learns the run cannot take commands
+                const terminal = errorToTerminal(error);
+                outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
+                settled = true;
+                yield terminal;
+                return;
+            }
+            try {
+                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 duplicates. */
+                let streamedAnswer = false;
+                /** Set when a retry is refused because the answer already streamed — carries the ending error. */
+                let retriedAfterAnswer;
+                const unsub = session.subscribe((event) => {
+                    if (retriedAfterAnswer !== undefined)
+                        return; // 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 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 delay and burn a provider call on a discarded answer.
+                        queueMicrotask(() => void abort());
+                        return;
+                    }
+                    const rich = toSessionEvent(event, runId);
+                    if (!rich)
+                        return;
+                    observe(rich);
+                    const projected = projectAgentEvent(rich);
+                    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 promptOptions;
+                    try {
+                        promptOptions = await toPiPromptOptions(prompt);
+                    }
+                    catch (error) {
+                        const terminal = errorToTerminal(error);
+                        outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
+                        settled = true;
+                        yield terminal;
+                        return;
+                    }
+                    if (wasCancelled()) {
+                        settled = true;
+                        await abort();
+                        return; // cancelled: the outer finally settles it as aborted
+                    }
+                    const run = session.prompt(prompt.text, promptOptions);
+                    yield* queue.drainUntil(run);
+                    let terminal;
+                    try {
+                        await run;
+                        terminal =
+                            retriedAfterAnswer !== undefined
+                                ? { type: "failed", details: retriedAfterAnswer, retryable: true }
+                                : finalAssistant
+                                    ? toTerminal(finalAssistant)
+                                    : ENGINE_PRODUCED_NOTHING;
+                    }
+                    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 === "failed") {
+                        outcome =
+                            terminal.code === ABORTED_CODE
+                                ? // Carry the detail: an independent error that raced an accepted abort must stay
+                                    // diagnosable in the settlement, which is what audit consumers read.
+                                    { status: "aborted", error: { message: terminal.details, retryable: false } }
+                                : {
+                                    status: "failed",
+                                    error: { code: terminal.code, message: terminal.details, retryable: terminal.retryable },
+                                };
+                    }
+                    else {
+                        outcome = { status: "completed" };
+                    }
+                    // Commands become ineffective the moment the run resolved — not at the outer finally,
+                    // which sits behind a consumer-paced `yield`.
+                    settled = true;
+                    yield terminal;
+                }
+                finally {
+                    settled = true;
+                    unsub();
+                }
+            }
+            finally {
+                // NO session_shutdown here, deliberately. A per-invoke session makes one look right, but the
+                // extension INSTANCE it would tear down is not per-invoke: extensions belong to the agent's
+                // assembly and every turn shares one. Emitting a shutdown per turn had a finished
+                // turn clearing a timer a concurrent turn had just opened (measured, and pinned in
+                // definition-extensions.test.ts). The lifecycle has to match the instance, not the session
+                // wrapper: one agent, one instance, no per-turn teardown. Extensions that need per-turn
+                // cleanup do it in the tool or handler that opened the resource.
+                try {
+                    session.dispose();
+                }
+                catch (error) {
+                    log.warn(`[fastagent] session dispose failed during cleanup: ${String(error)}`);
+                }
+            }
+        }
+        finally {
+            settled = true;
+            observe({ type: "run_settled", timestamp: Date.now(), runId, data: outcome ?? { status: "aborted" } });
+            release(); // after the settlement, so the next invoke for this session cannot outrun it
+        }
+    }
+    return { invoke: (scope, prompt) => cancellableStream((hooks) => turn(scope, prompt, hooks)) };
+}

package/dist/engines/pi/login.js

@@ -18,13 +18,16 @@ function anySignal(...signals) {
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Map pi-ai's `AuthInteraction` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
- * resolves, cancelling a prompt the provider left pending (a manual-code paste racing a callback
- * server it just won) so the one-shot CLI exits instead of hanging on stdin.
+ * Map pi-ai's `ProviderAuthInteraction` onto the injected {@link LoginIO}. `doneSignal` fires when
+ * the flow resolves, cancelling a prompt the provider left pending (a manual-code paste racing a
+ * callback server it just won) so the one-shot CLI exits instead of hanging on stdin.
+ *
+ * The signal is REQUIRED by that type (pi normalizes it before calling a provider), so a caller that
+ * passes none gets one that never fires — the same "no cancellation" the optional field meant.
  */
 function authCallbacks(io, userSignal, doneSignal) {
     return {
-        signal: userSignal,
+        signal: userSignal ?? new AbortController().signal,
         prompt: async (p) => {
             if (p.type === "select") {
                 const v = await io.select(p.message, p.options.map((o) => ({ value: o.id, label: o.label, hint: o.description })));

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

@@ -1,13 +1,17 @@
-/**
- * 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 { ThinkingLevel } from "@earendil-works/pi-agent-core";
 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`. */
@@ -23,18 +27,62 @@ export interface CreatePiModelsOptions extends FastagentAuthOptions {
  * is upstream-owned).
  */
 export declare function createPiModels(options?: CreatePiModelsOptions): Models;
+/**
+ * pi's Model with the API-shape generic erased — fastagent only passes models through to the engine,
+ * so the generic carries no information. One alias keeps the `any` auditable.
+ */
+export type AnyModel = Model<any>;
+/**
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the engine, whose fallback is "off": an author vibes
+ * at "medium" in pi and must get "medium" when served (fidelity), and pinning the value here means
+ * an upstream default change in either place cannot silently alter deployments. Models that do not
+ * support a level are clamped by pi per model.
+ */
+export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
 /**
  * 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