@fastagent-sh/fastagent 0.18.0 → 0.20.0

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

@@ -1,35 +1,100 @@
-import { SESSION_BUSY_CODE } from "../../agent.js";
+import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
 import { cancellableStream } from "../../collect.js";
 import { log } from "../../log.js";
-import { EventQueue, errorToTerminal, inProcessLease, toPiPromptOptions, toTerminal } from "./turn-kit.js";
+import { EventQueue, errorToTerminal, inProcessLease, projectAgentEvent, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
 /**
- * SPEC events from pi's session stream. `auto_retry_start` has no harness counterpart: an
- * `AgentSession` retries a failed assistant request itself, which the SPEC already has a word for.
+ * 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 toAgentEvent(event) {
+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: "text", delta: ev.delta };
-            if (ev.type === "thinking_delta")
-                return ev.delta === "" ? null : { type: "thinking", delta: ev.delta };
+            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", id: event.toolCallId, name: event.toolName, args: event.args };
+            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_ended", id: event.toolCallId, isError: event.isError, content: event.result };
-        case "auto_retry_start":
             return {
-                type: "retrying",
-                attempt: event.attempt,
-                maxAttempts: event.maxAttempts,
-                delayMs: event.delayMs,
-                reason: event.errorMessage,
+                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;
     }
@@ -37,7 +102,7 @@ function toAgentEvent(event) {
 /**
  * The turn's outcome. `prompt()` resolves void and never throws for an engine-side failure (measured:
  * a provider error and an abort both resolve normally), so the terminal comes from the assistant
- * message the run ended on — the same read {@link toTerminal} performs on the harness path.
+ * 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
@@ -54,11 +119,11 @@ const ENGINE_PRODUCED_NOTHING = {
     retryable: false,
 };
 export function createPiAgentFromSession(options) {
-    const { sessionFactory, lease = inProcessLease() } = options;
-    /** Own the session's lifetime: one writer, built here, disposed here whatever the turn did. */
-    async function* turn(scope, prompt, hooks) {
+    const { 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",
@@ -67,19 +132,213 @@ export function createPiAgentFromSession(options) {
             };
             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 {
-                session = await sessionFactory(scope.session);
+                // 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) {
-                yield errorToTerminal(error); // setup failures are events, never throws (MUST 2)
+                // 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 {
-                yield* runOnSession(session, prompt, hooks);
+                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();
                 }
@@ -89,83 +348,10 @@ export function createPiAgentFromSession(options) {
             }
         }
         finally {
-            release();
+            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)) };
 }
-/** One turn on a session someone else owns: subscribe, prompt, stream, terminal. */
-async function* runOnSession(session, prompt, { onCancelReady, wasCancelled }) {
-    const abort = () => session.abort().catch(() => { });
-    onCancelReady(() => void abort());
-    const queue = new EventQueue();
-    let finalAssistant;
-    /** Whether any of THIS attempt's answer has been streamed — the only output a retry would duplicate. */
-    let streamedAnswer = false;
-    /** Set when a retry is refused because the answer already streamed — carries the error that ends it. */
-    let retriedAfterAnswer;
-    const unsub = session.subscribe((event) => {
-        if (retriedAfterAnswer !== undefined)
-            return; // the turn is decided; the retry's output is not ours
-        if (event.type === "message_end" && event.message.role === "assistant") {
-            finalAssistant = event.message;
-        }
-        // pi retries a failed assistant request by DISCARDING that attempt's assistant message and asking
-        // again. Everything the turn achieved before it survives - executed tools keep their persisted
-        // results, and the retry resumes from them - so the only thing a retry can duplicate is answer
-        // text this L0 already streamed, which SPEC deltas cannot retract. Refuse it exactly there:
-        // refusing on tool events instead would push the retry out to the CALLER, who can only re-run the
-        // whole prompt and execute the tool a second time.
-        if (event.type === "auto_retry_start" && streamedAnswer) {
-            retriedAfterAnswer = event.errorMessage;
-            // Not synchronously: pi emits this event BEFORE creating the controller that makes its backoff
-            // abortable, so an abort from inside the listener would find nothing to cancel and the turn
-            // would still pay the full delay and burn a provider call on an answer we must discard.
-            queueMicrotask(() => void abort());
-            return;
-        }
-        const projected = toAgentEvent(event);
-        if (!projected)
-            return;
-        if (projected.type === "text" || projected.type === "thinking")
-            streamedAnswer = true;
-        queue.push(projected);
-    });
-    try {
-        // Resolving prompt options lazy-loads the image pipeline and re-encodes every attachment, so it
-        // both takes time and can throw before any engine work exists to fail. Hence the two guards, in
-        // this order and no earlier: its failure is a turn failure (MUST 2), and the latch has to be read
-        // after the LAST await before the call — the door armed above only stops a RUNNING session, so a
-        // consumer who walked away during the build or the resize would knock on an idle one and have
-        // the turn start anyway.
-        let options;
-        try {
-            options = await toPiPromptOptions(prompt);
-        }
-        catch (error) {
-            yield errorToTerminal(error);
-            return;
-        }
-        if (wasCancelled()) {
-            await abort();
-            return;
-        }
-        const run = session.prompt(prompt.text, options);
-        yield* queue.drainUntil(run);
-        try {
-            await run;
-            if (retriedAfterAnswer !== undefined) {
-                yield { type: "failed", details: retriedAfterAnswer, retryable: true };
-            }
-            else {
-                yield finalAssistant ? toTerminal(finalAssistant) : ENGINE_PRODUCED_NOTHING;
-            }
-        }
-        catch (error) {
-            yield errorToTerminal(error);
-        }
-    }
-    finally {
-        unsub();
-    }
-}

package/dist/engines/pi/login.js

@@ -18,15 +18,30 @@ 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") {
+                // This branch is UNCANCELLABLE: `LoginIO.select` takes no signal, so all three the line
+                // below composes — the provider's own, the caller's `loginFlow({ signal })`, and the
+                // pending-prompt backstop — are dropped here.
+                //
+                // It costs nothing against pi 0.84's providers, where every `select` is the FIRST call of
+                // `login()` (bedrock, vertex, openai-codex, radius — all of them asking which login method
+                // to use). Nothing is racing it: no callback server is up yet, and `doneSignal` fires when
+                // `auth.login()` RETURNS, which it cannot do while blocked on this await.
+                //
+                // That is a property of the providers, not a guarantee, and nothing here holds it. A
+                // provider that ever issues a `select` after starting its callback server shows up as the
+                // CLI parked on stdin — widen `LoginIO.select` with a signal then.
                 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 LoginCancelled("cancelled");
@@ -91,9 +106,14 @@ async function selectProvider(io, providers, method, store) {
         return { value: p.id, label: auth?.name ?? p.name, hint: cred ? `configured (${cred.type})` : undefined };
     }));
     const id = await io.select("Select a provider", options);
-    if (!id)
+    // Answers the PROVIDER, not its id: the caller needs the object, and resolving it here means the
+    // one place that can fail to is the one that just offered the list. Cancel and an id that was
+    // never offered are the same answer — nothing was chosen — and `find` gives both, since a
+    // provider id is always a string and `undefined` matches none of them.
+    const chosen = candidates.find((p) => p.id === id);
+    if (!chosen)
         throw new LoginCancelled("no provider selected");
-    return id;
+    return chosen;
 }
 /**
  * Resolve method + provider (asking only what is not given), run the login flow, and persist. A no-op
@@ -103,26 +123,25 @@ export async function loginFlow(io, options = {}) {
     const store = options.store ?? fastagentCredentialStore(options.authPath ?? GLOBAL_AUTH_PATH);
     const providers = options.providers ?? builtinProviders();
     let method;
-    let providerId;
+    let provider;
     if (options.provider) {
-        providerId = options.provider;
-        const p = providers.find((x) => x.id === providerId);
-        if (!p)
-            throw new Error(`unknown provider "${providerId}"`);
-        method = options.method ?? (await methodForProvider(io, p));
+        const named = providers.find((x) => x.id === options.provider);
+        if (!named)
+            throw new Error(`unknown provider "${options.provider}"`);
+        provider = named;
+        method = options.method ?? (await methodForProvider(io, provider));
     }
     else {
         method = options.method ?? (await selectMethod(io));
-        providerId = await selectProvider(io, providers, method, store);
+        provider = await selectProvider(io, providers, method, store);
     }
     // Preflight: a no-op modify runs the refuse-corrupt / writability check BEFORE the flow.
-    await store.modify(providerId, async () => undefined);
-    const provider = providers.find((p) => p.id === providerId);
-    if (!provider)
-        throw new Error(`unknown provider "${providerId}"`);
+    await store.modify(provider.id, async () => undefined);
+    // Reachable even though both branches above resolved a provider: an explicit `method` bypasses
+    // methodForProvider, so `{ provider: "openai-codex", method: "api_key" }` arrives here.
     const auth = method === "oauth" ? provider.auth.oauth : provider.auth.apiKey;
     if (!auth?.login)
-        throw new Error(`provider "${providerId}" has no ${method} login`);
+        throw new Error(`provider "${provider.id}" has no ${method} login`);
     // `done` cancels any prompt left pending when login resolves (manual-code race backstop).
     const done = new AbortController();
     let credential;
@@ -132,6 +151,6 @@ export async function loginFlow(io, options = {}) {
     finally {
         done.abort();
     }
-    await store.modify(providerId, async () => credential);
-    return { provider: providerId, method };
+    await store.modify(provider.id, async () => credential);
+    return { provider: provider.id, method };
 }

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

@@ -1,3 +1,4 @@
+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";
@@ -26,6 +27,19 @@ 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

package/dist/engines/pi/models.js

@@ -1,7 +1,7 @@
 /**
  * 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
+ * it into the engine alongside the selected `model`; the two must come from the same collection so
  * the model's provider auth is in scope.
  */
 import { join } from "node:path";
@@ -28,6 +28,14 @@ export function createPiModels(options = {}) {
         models.setProvider(provider);
     return models;
 }
+/**
+ * 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 const DEFAULT_THINKING_LEVEL = "medium";
 /**
  * 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

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

@@ -1,12 +1,11 @@
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import type { SessionControl } from "../../session.ts";
-import type { SessionObserver } from "./invoke.ts";
-import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
+import type { SessionObserver } from "./turn-kit.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type LoadedDefinition } from "./definition.ts";
-import type { ToolCollision } from "./tool.ts";
-import type { MountedTool } from "./tool.ts";
+import { type PiSessionRecordStore } from "./session-store.ts";
+import type { ToolCollision, MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {
     /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;
@@ -44,7 +43,7 @@ export interface CreatePiAgentFromDirOptions {
 }
 /**
  * The agent assembly FRONT HALF — everything that is independent of how pi consumes the
- * definition (transient harness for serving vs resident AgentSession for chat / session control):
+ * definition (a per-invoke session for serving vs a resident one for chat):
  * placement resolution → config → model spec → the full tool surface ({@link resolveAgentTools} — the
  * ONE place it is computed) → state root → auth path. Both {@link createPiAgentFromDir} and the
  * session builder (session-builder.ts) consume this, so THESE inputs cannot drift between the two
@@ -65,7 +64,7 @@ export interface AgentAssembly {
     stateRoot: string;
     /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <agentDir>/.secrets/auth.json). */
     authPath: string;
-    /** The full mounted tool surface (config.tools + discovered tools/, search_tools applied). */
+    /** The full mounted tool surface (all coding tools + config.tools + discovered tools/, search_tools applied). */
     tools: MountedTool[];
     toolNames: string[];
     deferredToolNames: string[];
@@ -99,10 +98,13 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     sessionsDir: string;
     /** Absolute credentials file in use (for the startup report). */
     authPath: string;
-    /** The session store in use — also a {@link PiSessionReader}. */
-    sessions: PiSessionStore & PiSessionReader;
+    /** The session store in use. */
+    sessions: PiSessionRecordStore;
     /** The observation plane over this agent's sessions; present iff `options.sessionControl`. */
     sessionControl?: SessionControl;
+    /** Whether the agent schedules its own follow-up turns — read from the config, so a caller
+     *  assembling a service does not have to reach back into it (MountableAgent). */
+    selfSchedule: boolean;
     /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
      *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */
     toolNames: string[];