@fastagent-sh/fastagent 0.23.0 → 0.24.1

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

@@ -10,12 +10,12 @@ import { calculateContextTokens, estimateTokens, getLastAssistantUsage, } from "
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, isAddressableSession, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, PARTIAL_UPDATE_CODE, UPDATE_FIELDS, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
-import { listModels } from "./config.js";
-import { forkProvenance, isNavigable, publishedLeaf } from "./session-markers.js";
+import { forkProvenance, isConversationMessage, isNavigable, publishedLeaf } from "./session-markers.js";
 import { entryImages, imageAt } from "./entry-images.js";
+import { answerOutcome } from "./turn-kit.js";
 import { startCompaction } from "./agent-session-factory.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
-import { THINKING_LEVELS, activePath, resolveSessionSettings } from "./session-settings.js";
+import { THINKING_LEVELS, activePath, describeModels, resolveSessionSettings } from "./session-settings.js";
 import { log } from "../../log.js";
 // ── Usage (read from the record) ─────────────────────────────────────────────
 /**
@@ -92,6 +92,9 @@ function toSessionEntry(entry, parentId) {
             const data = { text: contentText(m.content, "") };
             if (toolCalls.length > 0)
                 data.toolCalls = toolCalls;
+            const outcome = answerOutcome(m);
+            if (outcome)
+                data.outcome = outcome;
             return { ...base, kind: "assistant", data };
         }
         if (m.role === "toolResult") {
@@ -267,10 +270,10 @@ export function createPiSessionControl(options) {
                 // The CONTRACT's list, not a copy of it: a field added to SessionUpdate is advertised
                 // without anyone remembering to, and one removed cannot linger here.
                 updatable: b ? [...UPDATE_FIELDS] : [],
-                // The registry is a deployment fact (any session may be pointed at any of it). Thinking
-                // LEVELS are a property of the model a session is running, so they ride
-                // `state().availableThinkingLevels` — a list here could only answer for one model.
-                ...(b ? { allowedModels: listModels(b.models) } : {}),
+                // The registry is a deployment fact (any session may be pointed at any of it). Each model carries the levels
+                // a session on it accepts, so a picker can offer them before the session runs on that model;
+                // `state().availableThinkingLevels` answers for the model the session is on.
+                ...(b ? { allowedModels: describeModels(b.models.getModels()) } : {}),
                 toolProgress: true, // tool_progress IS delivered (replace-semantics snapshots)
                 usage: true, // state().usage, and state_changed{usage} after each run and compaction
             };
@@ -289,12 +292,27 @@ export function createPiSessionControl(options) {
             const b = boundary;
             let settings;
             let usage;
-            if (opened) {
+            if (!opened) {
+                // An id with no record is an empty conversation at the defaults: its first turn would run on these.
+                if (b)
+                    settings = resolveSessionSettings([], b.models, b.defaults);
+            }
+            else {
                 try {
                     const path = activePath(opened);
                     if (b)
                         settings = resolveSessionSettings(path, b.models, b.defaults);
-                    usage = sessionUsage(path, opened, settings?.model.contextWindow);
+                    const selected = settings?.model;
+                    const latest = selected?.api === "pi-virtual"
+                        ? opened
+                            .buildSessionContext()
+                            .messages.filter((message) => message.role === "assistant" &&
+                            message.stopReason !== "error" &&
+                            message.stopReason !== "aborted")
+                            .at(-1)
+                        : undefined;
+                    const physical = latest?.role === "assistant" ? b?.models.getModel(latest.provider, latest.model) : undefined;
+                    usage = sessionUsage(path, opened, (physical ?? selected)?.contextWindow);
                 }
                 catch (error) {
                     log.warn(`[fastagent] session ${session}: state unreadable (entry chain): ${String(error)}`);
@@ -457,6 +475,21 @@ export function createPiSessionControl(options) {
         ok: false,
         error: { code: NO_SUCH_SESSION_CODE, message: `session "${session}" does not exist`, retryable: false },
     });
+    /**
+     * The refusal for an id no client could then open: the empty string, `.` and `..` are not URL path segments
+     * (isAddressableSession), so minting one would put a row in list() that nothing can address — listed, unopenable by
+     * the client that just listed it. Both writes that create a record (fork's `into`, and an update to an id with no
+     * record) refuse it.
+     */
+    const unaddressable = (session) => invalid(`${JSON.stringify(session)} cannot be a session id — the control plane could not address it`);
+    const nothingToCompact = () => ({
+        ok: false,
+        error: {
+            code: NOTHING_TO_COMPACT_CODE,
+            message: "nothing to compact — the session has no compactable history yet; retry after more turns",
+            retryable: false,
+        },
+    });
     const invalid = (message) => ({
         ok: false,
         error: { code: INVALID_COMMAND_CODE, message, retryable: false },
@@ -518,12 +551,12 @@ export function createPiSessionControl(options) {
             };
         }
         const controls = run.controls;
-        yield* port(() => action.type === "steer"
-            ? controls.steer(action.prompt)
-            : action.type === "follow_up"
-                ? controls.followUp(action.prompt)
-                : controls.abort());
-        return { ok: true, runId: run.runId };
+        if (action.type === "abort") {
+            yield* port(() => controls.abort());
+            return { ok: true, runId: run.runId };
+        }
+        const disposition = yield* port(() => action.type === "steer" ? controls.steer(action.prompt) : controls.followUp(action.prompt));
+        return { ok: true, runId: run.runId, disposition };
     }).pipe(Effect.catchCause((cause) => Effect.succeed({
         ok: false,
         error: { code: RUN_COMMAND_FAILED_CODE, message: String(portError(cause)), retryable: false },
@@ -557,7 +590,7 @@ export function createPiSessionControl(options) {
             const slash = patch.model.indexOf("/");
             model = slash > 0 ? b.models.getModel(patch.model.slice(0, slash), patch.model.slice(slash + 1)) : undefined;
             if (!model) {
-                return invalid(`unknown model "${patch.model}" — capabilities().allowedModels lists the accepted specs`);
+                return invalid(`unknown model "${patch.model}" — capabilities().allowedModels lists the accepted models`);
             }
         }
         if (patch.thinkingLevel !== undefined && !THINKING_LEVELS.has(patch.thinkingLevel)) {
@@ -566,18 +599,18 @@ export function createPiSessionControl(options) {
         // A name is the client's own label; the only thing that cannot be one is nothing.
         if (patch.name !== undefined && patch.name.trim() === "")
             return invalid("a session name cannot be empty");
-        // Sessions are created by invoke or copied by fork, never minted by an update: an unknown id is
-        // rejected, not turned into a ghost record. (Read-only handle — the WRITE one is opened under
-        // the lease below, and this one is discarded.)
+        // An id with no record takes properties too: its first turn is the "next turn" they apply to, so the write
+        // creates its record (below, under the lease). (Read-only handle — the WRITE one is opened under the lease,
+        // and this one is discarded.)
         const existing = yield* port(() => sessions.openIfExists(session));
-        if (!existing)
-            return noSuchSession(session);
+        if (!existing && !isAddressableSession(session))
+            return unaddressable(session);
         if (patch.leafEntryId !== undefined) {
             // A target that cannot BE a leaf is a permanent payload error, not a session error — the same
             // disposition as an unknown model spec. Same predicate `entries()` publishes by, so
             // "everything published is a position" holds by construction rather than by two literals
             // agreeing.
-            const entry = existing.getEntry(patch.leafEntryId);
+            const entry = existing?.getEntry(patch.leafEntryId);
             if (!entry || !isNavigable(entry)) {
                 return invalid(entry
                     ? `entry "${patch.leafEntryId}" is not a position — entries() publishes every id you can move to, and this is not one of them`
@@ -593,7 +626,8 @@ export function createPiSessionControl(options) {
                 // Against the path this patch LANDS on: a leaf move is written first, and the branch it
                 // moves to can carry a model override of its own — validating on the path being left would
                 // reject a level the destination supports, and accept one it does not.
-                resolved = resolveSessionSettings(activePath(existing, patch.leafEntryId), b.models, b.defaults);
+                const path = existing ? activePath(existing, patch.leafEntryId) : [];
+                resolved = resolveSessionSettings(path, b.models, b.defaults);
             }
             catch (error) {
                 return failed(error);
@@ -611,6 +645,10 @@ export function createPiSessionControl(options) {
             yield* acquireSessionLease(b.lease, session);
             // portJoin, not port: the lease is held for the duration of this write, so an interrupted
             // fiber must not release it while the store is still writing (effect-port.ts, rule 1).
+            // A never-run session's record is created through the data plane's own path, under the same lease an
+            // invoke creating it takes; one that invoke created meanwhile is simply opened.
+            if (!existing)
+                yield* portJoin(() => sessions.openOrCreate(session));
             return yield* portJoin(() => sessions.applyProperties(session, {
                 ...(patch.name !== undefined ? { name: patch.name } : {}),
                 ...(model ? { model: { provider: model.provider, id: model.id } } : {}),
@@ -619,7 +657,7 @@ export function createPiSessionControl(options) {
             }));
         }));
         if (!applied)
-            return noSuchSession(session); // vanished in the window: same condition, same code
+            return noSuchSession(session); // deleted in the window between the read and the lease
         if (applied.landed.length > 0) {
             // ONE event for the patch, built from what the RECORD holds. The settings pair rides along
             // whenever anything but the name changed: model and thinking level are one setting, and a
@@ -688,6 +726,12 @@ export function createPiSessionControl(options) {
             const existing = yield* port(() => sessions.openIfExists(session));
             if (!existing)
                 return noSuchSession(session);
+            // A record with no conversation in it (the list's `messageCount: 0`, e.g. one `update()` created before a first
+            // turn) has nothing to compact on any branch. Said before binding, because binding is a write: pi records the
+            // model and thinking level on a session that has no messages, so asking pi would add two entries and then
+            // refuse. Whether a record WITH messages has a cut point stays pi's decision (below).
+            if (!existing.getEntries().some(isConversationMessage))
+                return nothingToCompact();
             yield* acquireSessionLease(b.lease, session);
             const bound = yield* acquireSession(b.sessionFactory, session);
             yield* Effect.acquireRelease(Effect.try({
@@ -713,16 +757,8 @@ export function createPiSessionControl(options) {
                 Deferred.doneUnsafe(admitted, Effect.succeed({ ok: true }));
             });
             const admission = yield* portAbort("compact admission", () => compaction.admission, () => bound.abortCompaction());
-            if (admission === "nothing_to_compact") {
-                return {
-                    ok: false,
-                    error: {
-                        code: NOTHING_TO_COMPACT_CODE,
-                        message: "nothing to compact — the session has no compactable history yet; retry after more turns",
-                        retryable: false,
-                    },
-                };
-            }
+            if (admission === "nothing_to_compact")
+                return nothingToCompact();
             // Any other error pi raises before admission. A served session has no known trigger: it always binds a
             // model, and pi swallows a credential failure here and meets it at the model call (compaction_finished).
             // NOT retryable all the same: it is pi's decision on this session, not a transport or lease fault that
@@ -767,12 +803,8 @@ export function createPiSessionControl(options) {
         const b = boundary;
         if (!b)
             return unsupported("fork()");
-        // An id no client could then open: the empty string, `.` and `..` are not URL path segments
-        // (isAddressableSession), so minting one would put a row in list() that nothing can address —
-        // listed, unopenable by the client that just listed it.
-        if (!isAddressableSession(into)) {
-            return invalid(`${JSON.stringify(into)} cannot be a session id — the control plane could not address it`);
-        }
+        if (!isAddressableSession(into))
+            return unaddressable(into);
         const source = yield* port(() => sessions.openIfExists(from));
         if (!source)
             return noSuchSession(from);

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

@@ -2,8 +2,17 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
 import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ModelDescriptor } from "../../session.ts";
 import type { AnyModel } from "./models.ts";
 export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
+/**
+ * Models as a client's picker shows them, ordered by spec: the ONE description both listings give
+ * (`capabilities().allowedModels` and `availableModelsFromDir`). Its levels come from the function
+ * `resolveSessionSettings` reads, so a picker offers what `state()` will then report. A model that declares no name or
+ * context window (an extension's virtual model may not: pi reads the window as 0) leaves the field out rather than
+ * inventing one.
+ */
+export declare function describeModels(models: readonly AnyModel[]): ModelDescriptor[];
 /** The shape both override consumers walk — a session entry, structurally. */
 export interface OverrideEntryLike {
     type: string;

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

@@ -10,6 +10,23 @@ const ALL_THINKING_LEVELS = {
     max: true,
 };
 export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
+/**
+ * Models as a client's picker shows them, ordered by spec: the ONE description both listings give
+ * (`capabilities().allowedModels` and `availableModelsFromDir`). Its levels come from the function
+ * `resolveSessionSettings` reads, so a picker offers what `state()` will then report. A model that declares no name or
+ * context window (an extension's virtual model may not: pi reads the window as 0) leaves the field out rather than
+ * inventing one.
+ */
+export function describeModels(models) {
+    return models
+        .map((model) => ({
+        spec: `${model.provider}/${model.id}`,
+        ...(model.name ? { name: model.name } : {}),
+        thinkingLevels: getSupportedThinkingLevels(model),
+        ...(model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}),
+    }))
+        .sort((a, b) => (a.spec < b.spec ? -1 : a.spec > b.spec ? 1 : 0));
+}
 /**
  * The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through to an earlier
  * record.

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

@@ -6,8 +6,8 @@ import { type SessionInheritance } from "./session-inheritance.ts";
 export interface PiSessionRecordStore {
     openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<SessionManager>;
     /**
-     * OPEN-EXISTING sibling: an unknown session answers undefined, never creates one — sessions are the data plane's
-     * monopoly.
+     * OPEN-EXISTING sibling: an unknown session answers undefined, never creates one. The reads and every write that
+     * needs history go through it; creating is `openOrCreate`'s.
      */
     openIfExists(sessionId: string): Promise<SessionManager | undefined>;
     /** Write session properties, in the order pi's leaf pointer requires, and report what LANDED. */

package/dist/engines/pi/tool-context.d.ts

@@ -17,14 +17,12 @@ export declare function agentSessionManager(session: AgentSession, sessionId: st
  * activate deferred tools mid-turn without tool.ts importing the engine. pi anchors the addition in the transcript
  * (a system message carrying `toolsAdded`, written after the batch of tool results the activating call belongs to),
  * so providers with native deferred loading keep their
- * prompt-cache prefix; that message describes the run that wrote it, so what carries an activation into LATER turns
- * is fastagent's own `fastagent:tool-activation` entry, replayed by the per-invoke restore
- * (agent-session-factory.ts).
+ * prompt-cache prefix. The same transcript declarations restore the loadout on the next binding.
  */
 export interface ToolActivation {
     /** Names of the currently ACTIVE tools. */
     active(): string[];
-    /** Every registered tool (active or not) — the discovery corpus for a loader like `search_tools`. */
+    /** Every registered tool (active or not). */
     registered(): Array<{
         name: string;
         description: string;
@@ -37,7 +35,7 @@ export interface ToolActivation {
     activate(names: string[]): string[];
 }
 /** The activation bridge over a live pi session — the ONE implementation, for both consumers. */
-export declare function sessionToolActivation(session: AgentSession, onActivated?: (added: string[]) => void): ToolActivation;
+export declare function sessionToolActivation(session: AgentSession): ToolActivation;
 export interface TurnContext {
     /** Working directory for this execution. */
     cwd?: string;

package/dist/engines/pi/tool-context.js

@@ -16,28 +16,16 @@ export function agentSessionManager(session, sessionId) {
     };
 }
 /** The activation bridge over a live pi session — the ONE implementation, for both consumers. */
-export function sessionToolActivation(session, onActivated) {
+export function sessionToolActivation(session) {
     return {
         active: () => session.getActiveToolNames(),
         registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
         activate(names) {
             const current = session.getActiveToolNames();
-            const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
-            if (added.length === 0)
-                return added;
-            session.setActiveToolsByName([...current, ...added]);
-            onActivated?.(added);
-            return added;
+            session.setActiveToolsByName([...current, ...names]);
+            const before = new Set(current);
+            return session.getActiveToolNames().filter((name) => !before.has(name));
         },
     };
 }
 export const turnContext = new AsyncLocalStorage();
-/**
- * dedupe → keep registered names only (pi's setters THROW on unknown) → exclude already-active → the names to actually
- * add (empty = nothing to set).
- */
-function additiveActivation(registered, current, names) {
-    const known = new Set(registered);
-    const active = new Set(current);
-    return [...new Set(names)].filter((name) => known.has(name) && !active.has(name));
-}

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

@@ -1,5 +1,5 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionToolContext, ToolAnnotations, ToolDefinition, ToolExposure, ToolNamespace } from "@earendil-works/pi-coding-agent";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
 import { type DeclaredSecret } from "../../declared-secrets.ts";
@@ -11,10 +11,23 @@ export interface ToolContext {
     signal?: AbortSignal;
     sessionManager?: ReadonlySessionManager;
     /**
-     * Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred} tools with it —
-     * the built-in `search_tools` is one consumer).
+     * Tool activation for the current turn; Pi records changes in the transcript.
      */
     tools?: ToolActivation;
+    /**
+     * Run another mounted tool through pi's own pipeline: argument validation, the definition's `tool_call` and
+     * `tool_result` hooks, cancellation (this call's signal by default). It reaches the active `direct` tools and every
+     * `codemode` or `deferred` one. A tool failure comes back as `isError: true`, never as a rejection. The nested call
+     * is observed with `parentToolCallId` and does not enter the transcript. Undefined without a session
+     * (`fastagent tool`).
+     */
+    executeTool?: ExtensionToolContext["executeTool"];
+    /**
+     * Report progress while this call runs: a snapshot of everything so far (each call replaces the last), wrapped the
+     * way a return value is. Its last line is the call's status (`tool_progress` on the invoke stream); session-control
+     * observers receive the whole snapshot. Undefined when the caller takes no progress (`fastagent tool`).
+     */
+    onUpdate?: (partial: unknown) => void;
     /** THE values of {@link DefineToolOptions.secrets}, keyed by the names this tool declared — read
      *  from the process environment per call, so a value rotated THERE takes effect without a restart
      *  (one rotated in `.secrets/.env` does not: that file is loaded once at startup). This is how a
@@ -26,11 +39,20 @@ export interface DefineToolOptions<I extends z.ZodType, S extends readonly strin
     name?: string;
     description: string;
     input: I;
+    /** Pi's native visibility: direct (default), model-only, codemode, deferred, or hidden. */
+    exposure?: ToolExposure;
+    /** Direct tools start active unless false; settings may still select them. */
+    defaultActive?: boolean;
     /**
-     * Registered but NOT initially active: the tool's schema stays out of every request (and the model's sight) until a
-     * loader.
+     * MCP-style hints about what the tool does (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+     * Pi does not enforce them; a permission extension reads them from `pi.getAllTools()` to decide which calls to
+     * confirm, and treats a tool without them as possibly destructive.
      */
-    deferred?: boolean;
+    annotations?: ToolAnnotations;
+    /** Groups the tool with related ones (`{ name, description? }`): codemode lists a namespace under one heading. */
+    namespace?: ToolNamespace;
+    /** Structured output schema for programmatic callers such as codemode. */
+    output?: z.ZodType;
     /** pi's per-tool execution mode: "sequential" makes pi run any batch containing this tool serially. */
     executionMode?: "sequential" | "parallel";
     /**
@@ -46,25 +68,14 @@ export interface DefineToolOptions<I extends z.ZodType, S extends readonly strin
     }) => unknown | Promise<unknown>;
 }
 /** AgentTool with Pi's optional per-call context; absent for sessionless CLI execution. */
-export type MountedTool = Omit<AgentTool, "execute"> & {
-    execute(...args: [...Parameters<AgentTool["execute"]>, context?: ExtensionContext]): ReturnType<AgentTool["execute"]>;
+export type MountedTool = Omit<AgentTool, "execute"> & Pick<ToolDefinition, "exposure" | "defaultActive" | "annotations" | "namespace"> & {
+    execute(...args: [...Parameters<AgentTool["execute"]>, context?: ExtensionToolContext]): ReturnType<AgentTool["execute"]>;
 };
-/** An AgentTool with fastagent's deferral marker. */
-export type FastagentTool = AgentTool & {
-    deferred?: boolean;
+/** A Pi tool with fastagent's declared secrets. */
+export type FastagentTool = MountedTool & {
     /** {@link DefineToolOptions.secrets} — read back by `readSecretDeclaration`; pi ignores it. */
     secrets?: readonly string[];
 };
-/**
- * Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the AgentTool object — pi
- * ignores it).
- */
-export declare function isDeferredTool(tool: MountedTool): boolean;
-/**
- * The same tool without the deferred marker — for a loader that must stay active (a deferred loader could never be
- * activated and would strand every deferred tool).
- */
-export declare function stripDeferredMarker(tool: MountedTool): MountedTool;
 export declare function defineTool<I extends z.ZodType, const S extends readonly string[] = readonly []>(options: DefineToolOptions<I, S>): FastagentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). */
 export interface ToolCollision {

package/dist/engines/pi/tool.js

@@ -5,27 +5,11 @@ import { z } from "zod";
 import { loadModuleDir } from "../../loader.js";
 import { readSecretDeclaration, secretValues } from "../../declared-secrets.js";
 import { turnContext } from "./tool-context.js";
-/**
- * Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the AgentTool object — pi
- * ignores it).
- */
-export function isDeferredTool(tool) {
-    return tool.deferred === true;
-}
-/**
- * The same tool without the deferred marker — for a loader that must stay active (a deferred loader could never be
- * activated and would strand every deferred tool).
- */
-export function stripDeferredMarker(tool) {
-    if (!isDeferredTool(tool))
-        return tool;
-    const { deferred: _drop, ...active } = tool;
-    return active;
-}
 /**
  * Ask the provider to constrain sampling to the tool's schema, the posture pi's own built-ins take. `"prefer"`
- * rather than `"require"`: a schema pi cannot express strictly, or a provider without strict mode, silently falls
- * back to an ordinary function tool instead of failing the turn.
+ * rather than `"require"`: a schema pi cannot express strictly, one using a keyword the provider's strict mode rejects
+ * (Anthropic: numeric bounds, which every `z.number().int()` carries), or a provider without strict mode silently
+ * falls back to an ordinary function tool instead of failing the turn.
  *
  * Nothing here has to undo pi's strict rewrite. To express "optional" strictly, pi marks every property required and
  * unions the optional ones with `null`, so a constrained model emits `null` where it would have omitted the key — and
@@ -36,12 +20,13 @@ export function stripDeferredMarker(tool) {
  */
 const CONSTRAINED_SAMPLING = { type: "json_schema", strict: "prefer" };
 /** Wrap a plain return value into pi's tool-result shape; pass a full result through unchanged. */
-function wrapResult(value) {
+function wrapResult(value, output) {
     if (value && typeof value === "object" && Array.isArray(value.content)) {
         return value;
     }
+    const structuredContent = output ? output.parse(value) : undefined;
     const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
-    return { content: [{ type: "text", text }], details: value };
+    return { content: [{ type: "text", text }], details: value, ...(output ? { structuredContent } : {}) };
 }
 // `S` defaults to the EMPTY tuple, not `readonly string[]`: a tool that declares nothing then gets
 // `ctx.secrets` with no keys, so `ctx.secrets.X_API_KEY` fails to compile instead of type-checking as
@@ -55,15 +40,23 @@ export function defineTool(options) {
         description: options.description,
         parameters,
         constrainedSampling: CONSTRAINED_SAMPLING,
-        ...(options.deferred ? { deferred: true } : {}),
+        ...(options.exposure ? { exposure: options.exposure } : {}),
+        ...(options.defaultActive !== undefined ? { defaultActive: options.defaultActive } : {}),
+        ...(options.annotations ? { annotations: options.annotations } : {}),
+        ...(options.namespace ? { namespace: options.namespace } : {}),
+        ...(options.output ? { outputSchema: z.toJSONSchema(options.output) } : {}),
         ...(options.executionMode ? { executionMode: options.executionMode } : {}),
         ...(options.secrets?.length ? { secrets: options.secrets } : {}),
-        async execute(_toolCallId, rawParams, signal) {
+        async execute(_toolCallId, rawParams, signal, onUpdate, context) {
             const parsed = options.input.safeParse(rawParams);
             if (!parsed.success) {
                 // Validation failure is reported TO THE MODEL (it can correct and retry), not thrown.
                 const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
-                return { content: [{ type: "text", text: `Invalid arguments: ${detail}` }], details: { error: detail } };
+                return {
+                    content: [{ type: "text", text: `Invalid arguments: ${detail}` }],
+                    details: { error: detail },
+                    isError: true,
+                };
             }
             const store = turnContext.getStore();
             return wrapResult(await options.execute(parsed.data, {
@@ -71,8 +64,11 @@ export function defineTool(options) {
                 signal,
                 sessionManager: store?.sessionManager,
                 tools: store?.tools,
+                // Per CALL, not per turn: pi binds `executeTool` to this call's id, the parent of what it runs.
+                executeTool: context?.executeTool,
+                onUpdate: onUpdate && ((partial) => onUpdate(wrapResult(partial))),
                 secrets: secretValues(options.secrets),
-            }));
+            }), options.output);
         },
     };
     return tool;

package/dist/engines/pi/turn-kit.d.ts

@@ -1,7 +1,6 @@
-/** The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. */
-import type { AssistantMessage, ImageContent } from "@earendil-works/pi-ai";
+import { type AssistantMessage, type ImageContent } from "@earendil-works/pi-ai";
 import { type AgentEvent, type Prompt } from "../../agent.ts";
-import type { SessionEvent } from "../../session.ts";
+import type { AnswerOutcome, PromptDisposition, SessionEvent } from "../../session.ts";
 export type Release = () => void;
 export interface Lease {
     /** Try to acquire exclusive write access for the session (fail-fast). */
@@ -14,9 +13,15 @@ export declare function classifyRetryable(details: string, signal: {
     code?: unknown;
 }): boolean;
 /**
- * Terminal mapping, decided by the resolved message's stopReason: pi's `prompt()` RESOLVES a message with stopReason
+ * How an answer ended, read off the stopReason pi records on the message. The ONE reading: `message_finished`,
+ * the `assistant` entry `entries()` publishes, and the invoke terminal all derive from it, so the live outcome and
+ * the recorded one cannot disagree.
+ */
+export declare function answerOutcome(message: AssistantMessage): AnswerOutcome | undefined;
+/**
+ * Terminal mapping, decided by the resolved message's outcome: pi's `prompt()` RESOLVES a message with stopReason
  * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate
- * SPEC MUST 1.
+ * SPEC MUST 1. A truncated final answer still completes the run.
  */
 export declare function toTerminal(message: AssistantMessage): AgentEvent;
 export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
@@ -34,11 +39,15 @@ export declare function toPiPromptOptions(prompt: Prompt, delivery: "prompt" | "
 } | undefined>;
 /** Live modulation handles for one active run — what the control plane's `dispatch` routes to. */
 export interface RunControls {
-    steer(prompt: Prompt): Promise<void>;
-    followUp(prompt: Prompt): Promise<void>;
+    steer(prompt: Prompt): Promise<PromptDisposition>;
+    followUp(prompt: Prompt): Promise<PromptDisposition>;
     abort(): Promise<void>;
 }
 /** The DATA-plane observation seam: every rich event of every run, pushed as it happens. */
 export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
-/** The SPEC projection of the rich stream. */
-export declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
+/**
+ * The SPEC projection of ONE run's rich stream. Stateful only for `tool_progress`, the one event that is a status
+ * rather than a fact: an outer call's status line is sent when it changes, and a call that call makes, at any depth,
+ * is its status. Nested calls are otherwise the observation plane's alone.
+ */
+export declare function agentEventProjection(): (se: SessionEvent) => AgentEvent | null;