@fastagent-sh/fastagent 0.13.0 → 0.15.0

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

@@ -1,6 +1,21 @@
+/**
+ * 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.
+ *
+ *   §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
+ *
+ * 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 } from "../../agent.ts";
-import type { PiHarnessFactory } from "./harness.ts";
+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. */
@@ -12,17 +27,55 @@ export declare function classifyRetryable(details: string, signal: {
     status?: number;
     code?: unknown;
 }): boolean;
+/**
+ * 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 declare function toSessionEvent(pe: AgentHarnessEvent, runId: string): SessionEvent | 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 declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
+/** Live modulation handles for one active run — what the control plane's `dispatch` routes to.
+ *  Built inside the invoke closure (it owns the harness); registered with the observer at
+ *  run_started, gone after run_settled. RACE WINDOW (all three commands, symmetric): the run may
+ *  resolve between the settled-check and the engine call landing — an accepted `abort` can still
+ *  settle `completed`, and an accepted `steer`/`followUp` can settle without the prompt ever being
+ *  consumed. Acceptance is not outcome; the settlement is the truth. */
+export interface RunControls {
+    steer(prompt: Prompt): Promise<void>;
+    followUp(prompt: Prompt): Promise<void>;
+    abort(): Promise<void>;
+}
+/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. `run`
+ *  carries the live {@link RunControls}, attached to the `run_started` event only. A hub
+ *  (session-control.ts) implements this to serve `events()`/`state()`/`dispatch`; absent = zero
+ *  overhead. Scope: RUN events only — the hub's own boundary-mutation events (`state_changed`,
+ *  `compaction_*`) originate in the hub and reach full-vocabulary taps via the hub's `tap` option,
+ *  not this seam. TRUST BOUNDARY: since Phase 2a this seam hands every wired observer the run's
+ *  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): 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. */
     lease?: Lease;
+    /** Observation-plane tap (see {@link SessionObserver}). Optional; invoke behavior is identical
+     *  with or without it — the SPEC stream is a projection of what the observer sees. */
+    observer?: SessionObserver;
+    /** Working directory exposed to FastAgent-defined tools. Defaults to process.cwd(). */
+    cwd?: string;
 }
 /** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
 export declare function createPiAgentFromHarness(options: CreatePiAgentFromHarnessOptions): Agent;

package/dist/engines/pi/invoke.js

@@ -1,7 +1,9 @@
 import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
-import { SESSION_BUSY_CODE } from "../../agent.js";
+import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { abortFirstIterator } from "../../collect.js";
 import { log } from "../../log.js";
-import { turnContext } from "./tool-context.js";
+import { TOOL_ACTIVATION_ENTRY, harnessSession } from "./harness.js";
+import { additiveActivation, turnContext } from "./tool-context.js";
 export function inProcessLease() {
     const busy = new Set();
     return {
@@ -94,21 +96,109 @@ function messageSignal(message) {
     }
     return {};
 }
-/** In-stream event mapping. Non text/tool_* pi events (turn_start, message_start, …) are dropped. */
-function toAgentEvent(pe) {
+/**
+ * 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: "text", delta: ev.delta };
-            if (ev.type === "thinking_delta")
-                return { type: "thinking", delta: ev.delta };
+            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", id: pe.toolCallId, name: pe.toolName, args: pe.args };
+            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_ended", id: pe.toolCallId, isError: pe.isError, content: pe.result };
+            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;
     }
@@ -119,7 +209,13 @@ function toAgentEvent(pe) {
  * entire failure class (violating SPEC MUST 1).
  */
 export function toTerminal(message) {
-    if (message.stopReason === "error" || message.stopReason === "aborted") {
+    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)) };
     }
@@ -129,6 +225,54 @@ 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);
+    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
@@ -208,10 +352,39 @@ class EventQueue {
 }
 /** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
 export function createPiAgentFromHarness(options) {
-    const { harnessFactory, lease = inProcessLease() } = options;
-    async function* invoke(scope, prompt) {
+    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) {
         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",
@@ -220,6 +393,90 @@ export function createPiAgentFromHarness(options) {
             };
             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 {
@@ -227,22 +484,58 @@ export function createPiAgentFromHarness(options) {
             }
             catch (error) {
                 // Setup failures (session open / auth / …) MUST surface as a failed event, never a throw.
-                yield errorToTerminal(error);
-                return;
+                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(() => { });
+            });
+            // 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) => {
-                const event = toAgentEvent(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 {
-                // Run the turn inside the session context so a tool's `execute` can read which session it is in
-                // (turnContext / ToolContext.session). prompt() starts the async work synchronously here, so the
-                // store propagates to the tool calls awaited within it.
+                // Bind current cwd/session/activation capabilities for every FastAgent-defined tool.
                 const opts = await toPiPromptOptions(prompt);
-                const run = turnContext.run({ session: scope.session }, () => harness.prompt(prompt.text, opts));
+                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 {
@@ -254,6 +547,28 @@ export function createPiAgentFromHarness(options) {
                 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 {
@@ -291,6 +606,11 @@ export function createPiAgentFromHarness(options) {
             }
         }
         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
         }
     }

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

@@ -33,6 +33,17 @@ export interface LoginIO {
     openUrl(url: string): void;
 }
 export type LoginMethod = "oauth" | "api_key";
+/** The user backed out of a prompt/menu — a decision, not a failure. Callers (the first-run picker,
+ *  the login command) match on this to report neutrally instead of as a login "failure". */
+export declare class LoginCancelled extends Error {
+}
+/** What `loginFlow` can offer a provider interactively: an OAuth flow, an API-key ENTRY prompt, or
+ *  nothing ("none" — the key must come from the provider's env var). */
+export type InteractiveLoginKind = LoginMethod | "none";
+/** The provider's {@link InteractiveLoginKind}. OAuth wins when both exist (methodForProvider still
+ *  asks at login time); the first-run picker annotates with this so the hint predicts what picking
+ *  actually does — a browser login ("oauth"), a key prompt ("api_key"), or neither. */
+export declare function interactiveLoginKind(p: Provider): InteractiveLoginKind;
 export interface LoginResult {
     provider: string;
     method: LoginMethod;

package/dist/engines/pi/login.js

@@ -1,12 +1,24 @@
 import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./auth.js";
+/** The user backed out of a prompt/menu — a decision, not a failure. Callers (the first-run picker,
+ *  the login command) match on this to report neutrally instead of as a login "failure". */
+export class LoginCancelled extends Error {
+}
+/** The provider's {@link InteractiveLoginKind}. OAuth wins when both exist (methodForProvider still
+ *  asks at login time); the first-run picker annotates with this so the hint predicts what picking
+ *  actually does — a browser login ("oauth"), a key prompt ("api_key"), or neither. */
+export function interactiveLoginKind(p) {
+    if (p.auth.oauth)
+        return "oauth";
+    return p.auth.apiKey?.login ? "api_key" : "none";
+}
 /** Combine present abort signals into one (no-op when none/one). */
 function anySignal(...signals) {
     const present = signals.filter((s) => s !== undefined);
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Map pi-ai's `AuthLoginCallbacks` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
+ * 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.
  */
@@ -17,13 +29,13 @@ function authCallbacks(io, userSignal, doneSignal) {
             if (p.type === "select") {
                 const v = await io.select(p.message, p.options.map((o) => ({ value: o.id, label: o.label, hint: o.description })));
                 if (v === undefined)
-                    throw new Error("cancelled");
+                    throw new LoginCancelled("cancelled");
                 return v;
             }
             const signal = anySignal(p.signal, userSignal, doneSignal);
             const v = await io.prompt(p.message, { hidden: p.type === "secret", signal });
             if (v === undefined)
-                throw new Error("cancelled");
+                throw new LoginCancelled("cancelled");
             return v;
         },
         notify: (e) => {
@@ -53,7 +65,7 @@ async function selectMethod(io) {
         { value: "api_key", label: "Use an API key" },
     ]);
     if (v !== "oauth" && v !== "api_key")
-        throw new Error("no authentication method selected");
+        throw new LoginCancelled("no authentication method selected");
     return v;
 }
 /** Given a provider arg, pick the method it supports (asking only when it offers both). */
@@ -80,7 +92,7 @@ async function selectProvider(io, providers, method, store) {
     }));
     const id = await io.select("Select a provider", options);
     if (!id)
-        throw new Error("no provider selected");
+        throw new LoginCancelled("no provider selected");
     return id;
 }
 /**