@fastagent-sh/fastagent 0.23.0 → 0.24.0

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;

package/dist/engines/pi/turn-kit.js

@@ -1,3 +1,6 @@
+/** The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. */
+import { stripVTControlCharacters } from "node:util";
+import { contentText } from "@earendil-works/pi-ai";
 import { ABORTED_CODE } from "../../agent.js";
 import { log } from "../../log.js";
 export function inProcessLease() {
@@ -71,19 +74,38 @@ function messageSignal(message) {
     return {};
 }
 /**
- * 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 function answerOutcome(message) {
+    const error = message.errorMessage ? { error: { message: message.errorMessage } } : {};
+    switch (message.stopReason) {
+        case "error":
+            return { status: "failed", ...error };
+        case "aborted":
+            return { status: "aborted", ...error };
+        case "length":
+            return { status: "truncated" };
+        default:
+            return 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 function toTerminal(message) {
-    if (message.stopReason === "aborted") {
+    const outcome = answerOutcome(message);
+    if (outcome?.status === "aborted") {
         // A deliberate stop (a control-plane or consumer abort), not an error — see {@link ABORTED_CODE} for the consumer
         // contract (design §6).
-        const details = message.errorMessage ?? "run aborted";
+        const details = outcome.error?.message ?? "run aborted";
         return { type: "failed", details, retryable: false, code: ABORTED_CODE };
     }
-    if (message.stopReason === "error") {
-        const details = message.errorMessage ?? `model stopped: ${message.stopReason}`;
+    if (outcome?.status === "failed") {
+        const details = outcome.error?.message ?? "model stopped: error";
         return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
     }
     return { type: "completed" };
@@ -119,27 +141,82 @@ export async function toPiPromptOptions(prompt, delivery) {
     }));
     return { images };
 }
-/** The SPEC projection of the rich stream. */
-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.
-            const d = se.data;
-            return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
-        }
-        default:
+/**
+ * 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 function agentEventProjection() {
+    /** Each nested call's outer call, the one the stream announced with `tool_started`. */
+    const outerOf = new Map();
+    /** The status line each outer call last reported. */
+    const shown = new Map();
+    const progress = (id, text) => {
+        if (text === undefined || shown.get(id) === text)
             return null;
+        shown.set(id, text);
+        return { type: "tool_progress", id, text };
+    };
+    return (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;
+                if (!d.parentToolCallId)
+                    return { type: "tool_started", id: d.id, name: d.name, args: d.args };
+                const outer = outerOf.get(d.parentToolCallId) ?? d.parentToolCallId;
+                outerOf.set(d.id, outer);
+                return progress(outer, callLine(d.name, d.args));
+            }
+            case "tool_progress": {
+                const d = se.data;
+                // A nested call's own output is not its caller's status; the nested call starting is (above).
+                if (d.parentToolCallId || !Array.isArray(d.partialResult.content))
+                    return null;
+                return progress(d.id, lastLine(contentText(d.partialResult.content, "\n")));
+            }
+            case "tool_finished": {
+                const d = se.data;
+                if (d.parentToolCallId)
+                    return null;
+                return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
+            }
+            case "retry_scheduled": {
+                // `operation` (compaction | branch_summary) stays session-plane vocabulary.
+                const d = se.data;
+                return {
+                    type: "retrying",
+                    attempt: d.attempt,
+                    maxAttempts: d.maxAttempts,
+                    delayMs: d.delayMs,
+                    reason: d.error,
+                };
+            }
+            default:
+                return null;
+        }
+    };
+}
+/**
+ * The line a terminal shows last: control sequences removed, and a bare `\r`, a progress bar redrawing in place, ends a
+ * line like `\n` does. Undefined when there is no visible text yet (a shell that has printed nothing).
+ */
+function lastLine(text) {
+    const lines = stripVTControlCharacters(text).split(/\r\n|\r|\n/);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim();
+        if (line)
+            return line;
     }
+    return undefined;
+}
+/** A nested call as its caller's status: the tool and its first plain argument, on one line (`weather London`). */
+function callLine(name, args) {
+    const first = args !== null && typeof args === "object" && !Array.isArray(args)
+        ? Object.values(args).find((value) => typeof value === "string" || typeof value === "number")
+        : undefined;
+    return first === undefined ? name : `${name} ${String(first).replace(/\s+/g, " ").trim()}`.trim();
 }

package/dist/pi.d.ts

@@ -5,7 +5,7 @@ export { z } from "zod";
 export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
 /** A conversation record, as the tool runtime and the control plane hold it. */
 export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
-export { availableModelsFromDir, createPiAgentFromDir, type CreatePiAgentFromDirOptions, refreshModelCatalog, } from "./engines/pi/open.ts";
+export { availableModelsFromDir, createPiAgentFromDir, type CreatePiAgentFromDirOptions, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
 export { defineConfig, listModels, resolveModel, type FastagentConfig, } from "./engines/pi/config.ts";
 export type { SessionObserver } from "./engines/pi/turn-kit.ts";

package/dist/pi.js

@@ -2,7 +2,7 @@
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
 export { defineTool, } from "./engines/pi/tool.js";
 export { z } from "zod";
-export { availableModelsFromDir, createPiAgentFromDir, refreshModelCatalog, } from "./engines/pi/open.js";
+export { availableModelsFromDir, createPiAgentFromDir, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.js";
 export { defineConfig, listModels, resolveModel, } from "./engines/pi/config.js";
 export { inProcessLease } from "./engines/pi/turn-kit.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";

package/dist/session.d.ts

@@ -54,14 +54,22 @@ export interface Session {
      */
     image(ref: string): Promise<ImageRef | undefined>;
     events(): SessionEventStream;
-    /** Set durable session properties. */
+    /**
+     * Set durable session properties, applied by the session's next turn. An id with no record (nothing has written it
+     * yet) takes them too: the write creates its record, and the session's first turn runs on them. Refused there:
+     * `leafEntryId` (no entries to point at) and an id no client could address ({@link isAddressableSession}).
+     */
     update(patch: SessionUpdate): Promise<SessionResult>;
     /**
      * Join the active run: delivered after the current turn's tool calls, before the next model call. `prompt.text`
-     * must not be empty (`invalid_command`): a queued prompt is reported by its text ({@link PendingPrompts}).
+     * must not be empty (`invalid_command`): a queued prompt is reported by its text ({@link PendingPrompts}). An
+     * accepted result carries its {@link PromptDisposition}.
      */
     steer(prompt: Prompt): Promise<SessionResult>;
-    /** Queue for the active run, FIFO, delivered when it is otherwise idle. Same non-empty `text` rule as `steer`. */
+    /**
+     * Queue for the active run, FIFO, delivered when it is otherwise idle. Same non-empty `text` rule and
+     * {@link PromptDisposition} as `steer`.
+     */
     followUp(prompt: Prompt): Promise<SessionResult>;
     /** Stop the active run — its queues, its retry delay, its cancellable tool work. */
     abort(): Promise<SessionResult>;
@@ -121,11 +129,22 @@ export interface SessionCapabilities {
     delete: boolean;
     /** Which {@link SessionUpdate} fields this deployment accepts. */
     updatable: SessionUpdateField[];
-    /** The specs `update({ model })` accepts — present iff `model` is updatable. */
-    allowedModels?: string[];
+    /** The models `update({ model })` accepts, by `spec` — present iff `model` is updatable. */
+    allowedModels?: ModelDescriptor[];
     toolProgress: boolean;
     usage: boolean;
 }
+/**
+ * A model as a picker shows it, before any session runs on it. `thinkingLevels` is what `update({ thinkingLevel })`
+ * accepts for a session on this model; `name` and `contextWindow` are absent when the model does not declare them.
+ */
+export interface ModelDescriptor {
+    /** What `update({ model })` takes. */
+    spec: string;
+    name?: string;
+    thinkingLevels: string[];
+    contextWindow?: number;
+}
 /** One name a client can offer the user. */
 export interface AgentCommand {
     name: string;
@@ -144,7 +163,11 @@ export declare const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
 export declare const NO_ACTIVE_RUN_CODE = "no_active_run";
 /** Stable `SessionResult.error.code` for a PAYLOAD that is invalid for this runtime. */
 export declare const INVALID_COMMAND_CODE = "invalid_command";
-/** Stable `SessionResult.error.code` for a write against a session that does not exist. */
+/**
+ * Stable `SessionResult.error.code` for a write that needs a record (fork's source, compact, delete) against an id
+ * that has none, because nothing has written it yet. `update()` creates the record instead, and answers this code only
+ * when a concurrent `delete()` removes the record between its read and its write.
+ */
 export declare const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a write rejected BEFORE acceptance with nothing durable landed. */
 export declare const BOUNDARY_COMMAND_FAILED_CODE = "boundary_command_failed";
@@ -180,6 +203,7 @@ export declare const PARTIAL_UPDATE_CODE = "partial_update";
 export type SessionResult = {
     ok: true;
     runId?: string;
+    disposition?: PromptDisposition;
 } | {
     ok: false;
     error: {
@@ -188,6 +212,13 @@ export type SessionResult = {
         retryable: boolean;
     };
 };
+/**
+ * What became of an accepted `steer`/`followUp` prompt — present on exactly those results. `queued`: it waits in
+ * {@link PendingPrompts} until the run takes it in. `handled`: the engine consumed it before the queue (in pi, a
+ * definition extension's `input` handler), so it never enters the conversation, and no `queue_changed` or
+ * `user_message` reports it.
+ */
+export type PromptDisposition = "queued" | "handled";
 /** One session in {@link SessionControl.sessions} — a conversation-list row, not a session's contents. */
 export interface SessionSummary {
     session: string;
@@ -205,7 +236,10 @@ export interface SessionState {
     /** `compacting` refers to MANUAL compaction (`compact`) at a session boundary. */
     status: "idle" | "running" | "compacting";
     activeRunId?: string;
-    /** What this session will RUN with, not what was recorded. */
+    /**
+     * What this session will RUN with, not what was recorded. An id with no record reports what its first turn would run
+     * on: the defaults, the level clamped to the model.
+     */
     model?: string;
     thinkingLevel?: string;
     /** What `update({ thinkingLevel })` accepts for THIS session — re-read after a model change. */
@@ -319,13 +353,29 @@ export type MessageDeltaEvent = SessionEvent<"message_delta", {
 }> & {
     runId: string;
 };
-export type MessageFinishedEvent = SessionEvent<"message_finished", Record<never, never>> & {
+/**
+ * How an answer ended, when it did not end normally: absent on an answer that did. One value, carried live by its
+ * `message_finished` and durably by its `assistant` entry, so a reopened conversation reads what a watcher saw.
+ * `truncated` is an answer cut off at the output limit — a property of the answer, not of its run, which may still
+ * complete. An answer whose entry a `context_edit { omitted }` targets (`failed` or `truncated`) is an attempt the
+ * engine abandoned; a retry usually, but not always, follows it.
+ */
+export type AnswerOutcome = {
+    status: "failed" | "aborted" | "truncated";
+    error?: {
+        message: string;
+    };
+};
+export type MessageFinishedEvent = SessionEvent<"message_finished", {
+    outcome?: AnswerOutcome;
+}> & {
     runId: string;
 };
 export type ToolStartedEvent = SessionEvent<"tool_started", {
     id: string;
     name: string;
     args: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };
@@ -334,6 +384,7 @@ export type ToolProgressEvent = SessionEvent<"tool_progress", {
     id: string;
     name: string;
     partialResult: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };
@@ -341,6 +392,7 @@ export type ToolFinishedEvent = SessionEvent<"tool_finished", {
     id: string;
     isError: boolean;
     content: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };

package/dist/session.js

@@ -28,7 +28,11 @@ export const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
 export const NO_ACTIVE_RUN_CODE = "no_active_run";
 /** Stable `SessionResult.error.code` for a PAYLOAD that is invalid for this runtime. */
 export const INVALID_COMMAND_CODE = "invalid_command";
-/** Stable `SessionResult.error.code` for a write against a session that does not exist. */
+/**
+ * Stable `SessionResult.error.code` for a write that needs a record (fork's source, compact, delete) against an id
+ * that has none, because nothing has written it yet. `update()` creates the record instead, and answers this code only
+ * when a concurrent `delete()` removes the record between its read and its write.
+ */
 export const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a write rejected BEFORE acceptance with nothing durable landed. */
 export const BOUNDARY_COMMAND_FAILED_CODE = "boundary_command_failed";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",
@@ -101,16 +101,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.87.1",
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-agent-core": "^0.99.2",
+    "@earendil-works/pi-ai": "^0.99.2",
+    "@earendil-works/pi-coding-agent": "^0.99.2",
     "@hono/node-server": "^2.1.1",
     "@larksuiteoapi/node-sdk": "^1.71.1",
     "@smithy/signature-v4": "^5.7.4",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
     "croner": "^10.0.1",
-    "effect": "4.0.0-rc.117",
+    "effect": "4.0.0-rc.118",
     "giget": "^3.3.0",
     "ignore": "^7.0.5",
     "proper-lockfile": "^4.1.2",