@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/engines/pi/harness.js

@@ -38,6 +38,13 @@ export function harnessSession(harness) {
  * so a mid-stream failure surfaces as a `failed` event.
  */
 const PROVIDER_MAX_RETRIES = 2;
+/**
+ * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
+ * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
+ * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
+ * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
+ */
+export const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDelayMs: 2000 };
 /**
  * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
  * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
@@ -69,6 +76,84 @@ const DEFAULT_THINKING_LEVEL = "medium";
  * (like L2's findings memo), not session state — the resolve stays derived from the session.
  */
 const warnedRestores = new Set();
+/** pi's ThinkingLevel scale as a checkable set — THE single source for fastagent (session entries
+ *  store plain strings; session-control's dispatch validation and capabilities derive from this).
+ *  The `satisfies Record<ThinkingLevel, …>` anchor makes it EXHAUSTIVE against pi's union: pi
+ *  adding a level turns this into a type error instead of a silent drift where `set_thinking`
+ *  rejects a value pi supports. */
+const ALL_THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
+/**
+ * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
+ * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
+ * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
+ * skipped over to an earlier record: the reporting surface and the execution surface must agree on
+ * which record is "the" override.
+ */
+export function lastOverrideEntries(entries) {
+    let model;
+    let modelSeen = false;
+    let thinkingLevel;
+    let thinkingSeen = false;
+    for (let i = entries.length - 1; i >= 0 && !(modelSeen && thinkingSeen); i--) {
+        const e = entries[i];
+        if (!modelSeen && e?.type === "model_change") {
+            modelSeen = true;
+            if (e.provider !== undefined && e.modelId !== undefined)
+                model = { provider: e.provider, modelId: e.modelId };
+        }
+        if (!thinkingSeen && e?.type === "thinking_level_change") {
+            thinkingSeen = true;
+            if (e.thinkingLevel !== undefined)
+                thinkingLevel = e.thinkingLevel;
+        }
+    }
+    return { model, thinkingLevel };
+}
+/**
+ * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
+ * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
+ * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
+ * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
+ * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
+ * back to the default with a deduped warn (fail visibly without bricking the session — the
+ * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ */
+export function resolveHarnessOverrides(entries, models, defaults, sessionId) {
+    let model = defaults.model;
+    let thinkingLevel = defaults.thinkingLevel;
+    const warnOnce = (key, message) => {
+        const emit = warnedRestores.has(key) ? log.debug : log.warn;
+        warnedRestores.add(key);
+        emit(message);
+    };
+    const recorded = lastOverrideEntries(entries);
+    if (recorded.model) {
+        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
+        if (found)
+            model = found;
+        else {
+            warnOnce(`${sessionId}\u0000model\u0000${recorded.model.provider}/${recorded.model.modelId}`, `[fastagent] session ${sessionId}: recorded model override ${recorded.model.provider}/${recorded.model.modelId} is not in this deployment's registry — using the configured default`);
+        }
+    }
+    if (recorded.thinkingLevel !== undefined) {
+        if (THINKING_LEVELS.has(recorded.thinkingLevel)) {
+            thinkingLevel = recorded.thinkingLevel;
+        }
+        else {
+            warnOnce(`${sessionId}\u0000thinking\u0000${recorded.thinkingLevel}`, `[fastagent] session ${sessionId}: recorded thinking level "${recorded.thinkingLevel}" is unknown — using the configured default`);
+        }
+    }
+    return { model, thinkingLevel };
+}
 export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     const anyDeferred = tools.some(isDeferredTool);
     const initial = tools.filter((t) => !isDeferredTool(t)).map((t) => t.name);
@@ -99,17 +184,20 @@ export function piHarnessFactory(options) {
         const { systemPrompt } = options;
         const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
         const skills = fresh ? fresh.skills : options.skills;
+        // Session overrides (set_model / set_thinking) win over the assembly defaults — same entry walk.
+        const overrides = resolveHarnessOverrides(entries, options.models, { model: options.model, thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL }, sessionId);
         const harness = new AgentHarness({
             env: options.env,
             session,
             models: options.models,
-            model: options.model,
-            thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+            model: overrides.model,
+            thinkingLevel: overrides.thinkingLevel,
             tools: options.tools,
             activeToolNames: resolveHarnessActiveToolNames(activated.length > 0 ? activated : null, options.tools ?? [], sessionId),
             systemPrompt: prompt,
             resources: skills ? { skills } : undefined,
             streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
+            retry: SUMMARIZATION_RETRY_POLICY,
         });
         harnessSessions.set(harness, session);
         return harness;

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

@@ -1,5 +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.
+ *
+ *   §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 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 {
@@ -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,5 +1,6 @@
 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 { TOOL_ACTIVATION_ENTRY, harnessSession } from "./harness.js";
 import { additiveActivation, turnContext } from "./tool-context.js";
@@ -95,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;
     }
@@ -120,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)) };
     }
@@ -130,6 +225,20 @@ 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
@@ -243,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",
@@ -255,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 {
@@ -262,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, tools: toolActivation(harness) }, () => 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 {
@@ -289,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 {
@@ -326,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;