@fastagent-sh/fastagent 0.22.1 → 0.24.0

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

@@ -1,4 +1,8 @@
+/** 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() {
     const busy = new Set();
     return {
@@ -70,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" };
@@ -105,35 +128,95 @@ export async function toPiPromptOptions(prompt, delivery) {
         return { images: prompt.images.map((img) => ({ type: "image", data: img.data, mimeType: img.mimeType })) };
     }
     const { resizeImage } = await import("@earendil-works/pi-coding-agent");
-    const images = await Promise.all(prompt.images.map(async (img) => {
-        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType).catch(() => null);
-        return resized
-            ? { type: "image", data: resized.data, mimeType: resized.mimeType }
-            : { type: "image", data: img.data, mimeType: img.mimeType };
+    const images = await Promise.all(prompt.images.map(async (img, i) => {
+        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType);
+        if (resized)
+            return { type: "image", data: resized.data, mimeType: resized.mimeType };
+        // `null` covers an image it cannot decode or shrink under the limit AND an image backend that did not load,
+        // and does not say which. pi's own tool-result path keeps the original in that case rather than drop what the
+        // sender attached, and so does this; a provider that refuses it fails the turn with its own message.
+        log.warn(`[fastagent] queued image ${i + 1} (${img.mimeType}) could not be resized; sending it as given — ` +
+            "the provider may refuse it");
+        return { type: "image", data: img.data, mimeType: img.mimeType };
     }));
     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/open-url.d.ts

@@ -1,2 +1,16 @@
-/** Best-effort open a URL in the default browser. */
+/**
+ * How to hand `url` to the default browser on `platform`, or undefined when it must not be handed over at all.
+ *
+ * Only a web page: `https:`, or `http:` on a loopback host. Some callers pass URLs they did not build — a deployed box's
+ * login relays its own (`cli/login-relay.ts`), and that box runs code its agent can rewrite — and the platform openers
+ * open anything: a local path, a `file:`/`smb:` URL, an argument that starts with `-`. Parsed and re-serialized, so
+ * what reaches the opener is what was checked. No shell anywhere: on Windows `start` needs one, and cmd reads the `&`
+ * every OAuth URL carries as a command separator, so `rundll32 url.dll,FileProtocolHandler` takes the URL as one
+ * argument instead.
+ */
+export declare function browserCommand(url: string, platform: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+} | undefined;
+/** Best-effort open a URL in the default browser (callers print it too). A URL that is not a web page is refused, visibly. */
 export declare function openExternalUrl(url: string): void;

package/dist/open-url.js

@@ -1,6 +1,38 @@
 import { spawn } from "node:child_process";
-/** Best-effort open a URL in the default browser. */
+/**
+ * How to hand `url` to the default browser on `platform`, or undefined when it must not be handed over at all.
+ *
+ * Only a web page: `https:`, or `http:` on a loopback host. Some callers pass URLs they did not build — a deployed box's
+ * login relays its own (`cli/login-relay.ts`), and that box runs code its agent can rewrite — and the platform openers
+ * open anything: a local path, a `file:`/`smb:` URL, an argument that starts with `-`. Parsed and re-serialized, so
+ * what reaches the opener is what was checked. No shell anywhere: on Windows `start` needs one, and cmd reads the `&`
+ * every OAuth URL carries as a command separator, so `rundll32 url.dll,FileProtocolHandler` takes the URL as one
+ * argument instead.
+ */
+export function browserCommand(url, platform) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined; // not a URL: nothing to open
+    }
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+    if (!(parsed.protocol === "https:" || (parsed.protocol === "http:" && loopback)))
+        return undefined;
+    const href = parsed.href;
+    if (platform === "darwin")
+        return { cmd: "open", args: [href] };
+    if (platform === "win32")
+        return { cmd: "rundll32", args: ["url.dll,FileProtocolHandler", href] };
+    return { cmd: "xdg-open", args: [href] };
+}
+/** Best-effort open a URL in the default browser (callers print it too). A URL that is not a web page is refused, visibly. */
 export function openExternalUrl(url) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).on("error", () => { });
+    const command = browserCommand(url, process.platform);
+    if (!command) {
+        console.error(`[fastagent] not opening ${JSON.stringify(url)}: only an https URL, or http on this machine, opens`);
+        return;
+    }
+    spawn(command.cmd, command.args, { stdio: "ignore", detached: true }).on("error", () => { });
 }

package/dist/paths.d.ts

@@ -1,7 +1,7 @@
 /** The directory name `init` gives an agent (`<workspace>/fastagent/`) unless `--agent-dir` names another. */
 export declare const DEFAULT_AGENT_DIRNAME = "fastagent";
-/** The user-global machinery home under `$HOME`. */
-export declare const GLOBAL_HOME_DIR = ".fastagent";
+/** The user-global machinery home, `~/.fastagent`: the machine's credentials, models.json and model catalog. */
+export declare function globalHome(): string;
 /**
  * The secrets segment inside an agent dir (or the global home). Every path fastagent resolves — `.env`,
  * `.env.example`, auth.json, the scaffold's write — derives from it, so they cannot drift apart.
@@ -19,6 +19,8 @@ export declare const STATE_DIRNAME = ".state";
 export declare const AGENT_CONFIG_FILE = "fastagent.config.ts";
 /** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). */
 export declare const AGENT_MODELS_FILE = "models.json";
+/** The agent's model catalog: pi.dev's models newer than pi's bundled catalog, fetched by `models --refresh`. */
+export declare const AGENT_MODEL_CATALOG_FILE = "models-store.json";
 export interface ResolvedPlacement {
     /**
      * The AGENT directory — where the definition (persona.md/skills/tools/channels/routines), the config, and the

package/dist/paths.js

@@ -8,8 +8,10 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 /** The directory name `init` gives an agent (`<workspace>/fastagent/`) unless `--agent-dir` names another. */
 export const DEFAULT_AGENT_DIRNAME = "fastagent";
-/** The user-global machinery home under `$HOME`. */
-export const GLOBAL_HOME_DIR = ".fastagent";
+/** The user-global machinery home, `~/.fastagent`: the machine's credentials, models.json and model catalog. */
+export function globalHome() {
+    return join(homedir(), ".fastagent");
+}
 /**
  * The secrets segment inside an agent dir (or the global home). Every path fastagent resolves — `.env`,
  * `.env.example`, auth.json, the scaffold's write — derives from it, so they cannot drift apart.
@@ -27,6 +29,8 @@ export const STATE_DIRNAME = ".state";
 export const AGENT_CONFIG_FILE = "fastagent.config.ts";
 /** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). */
 export const AGENT_MODELS_FILE = "models.json";
+/** The agent's model catalog: pi.dev's models newer than pi's bundled catalog, fetched by `models --refresh`. */
+export const AGENT_MODEL_CATALOG_FILE = "models-store.json";
 /**
  * The definition paths an agent LOADS content from — the surface a second agent must not be scaffolded inside
  * ({@link agentDefinitionOwner}), because the outer agent would read it as its own skills/tools.

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, } 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";
@@ -14,9 +14,11 @@ export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./e
 export { piInMemorySessionRecordStore, piSessionRecordStore, type PiSessionRecordStore, } from "./engines/pi/session-store.ts";
 export type { SessionInheritance } from "./engines/pi/session-inheritance.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
-export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
+export { createPiModels, type CreatePiModelsOptions } from "./engines/pi/agent-models.ts";
+export { probeAuthSource } from "./engines/pi/models.ts";
 export { login, loginOptions, LoginCancelled, type LoginMethod, type LoginOption, type LoginRequest, type LoginResult, } from "./engines/pi/login.ts";
-export type { AuthEvent, AuthInteraction, AuthPrompt } from "@earendil-works/pi-ai";
+/** pi-ai's sign-in types, and the `CredentialStore` a caller supplies as `credentialStore` (with what it holds). */
+export type { AuthEvent, AuthInteraction, AuthPrompt, Credential, CredentialStore } from "@earendil-works/pi-ai";
 export type { Models } from "@earendil-works/pi-ai";
 export type { Provider, ProviderAuth } from "@earendil-works/pi-ai";
 export type { Model } from "@earendil-works/pi-ai";

package/dist/pi.js

@@ -2,13 +2,14 @@
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
 export { defineTool, } from "./engines/pi/tool.js";
 export { z } from "zod";
-export { availableModelsFromDir, createPiAgentFromDir, } 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";
 export { piInMemorySessionRecordStore, piSessionRecordStore, } from "./engines/pi/session-store.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
-export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
+export { createPiModels } from "./engines/pi/agent-models.js";
+export { probeAuthSource } from "./engines/pi/models.js";
 export { login, loginOptions, LoginCancelled, } from "./engines/pi/login.js";
 // The product's one-call assembly: a directory becomes a live service.
 export { createAgentService } from "./engines/pi/service.js";

package/dist/service.d.ts

@@ -7,9 +7,9 @@ import type { LoadedRoutine } from "./schedule/routine.ts";
 export interface ServingSurface {
     /**
      * The routes that AUTHENTICATE NOBODY — `GET /health`, `POST /invoke`, and `POST /run` where the definition
-     * declares routines, minus what a channel took over or `http.invoke: false` withheld. Kept APART from the channels' rather than merged with a list of which keys are
-     * which: three separate decisions read this (browser reachability, the JSON body gate, what the startup line
-     * calls unauthenticated), and while it was a derived list each of them could answer differently.
+     * declares routines, minus what a channel took over or `http.invoke: false` withheld. Kept APART from the
+     * channels' table rather than derived from it, because three decisions read it (browser reachability, the JSON
+     * body gate, what the startup line calls unauthenticated) and must give the same answer.
      */
     unverified: Routes;
     /**
@@ -133,11 +133,8 @@ export interface AgentService {
         longConnections: string[];
     };
     /**
-     * The route keys on this port that AUTHENTICATE NOBODY — `GET /health`, `POST /invoke`, and `POST /run` where
-     * the definition declares routines, minus what a channel took over or `http.invoke: false` withheld. The FACT a caller needs to describe this surface: reading it off
-     * `routes` instead answers a different question, since a channel may serve one of those paths with a protocol of
-     * its own. That mistake ran in both directions here — a try-it curl for a route that 404s, and a warning about an
-     * unauthenticated `/invoke` that was really a signature-checked channel.
+     * The keys of {@link ServingSurface.unverified}: what a caller reads to describe this surface. Not derivable from
+     * `routes`, where a channel may serve one of those paths behind its own signature check.
      */
     unverifiedRoutes: readonly string[];
     /**

package/dist/session-remote.js

@@ -271,6 +271,19 @@ export async function connectSessionControl(options) {
                     id: session,
                     state: () => get(`/control/sessions/${id(session)}`),
                     entries: (options) => get(`/control/sessions/${id(session)}/entries${options?.since !== undefined ? `?since=${encodeURIComponent(options.since)}` : ""}`, PAYLOAD_TIMEOUT_MS),
+                    image: async (ref) => {
+                        const res = await fetchFn(`${base}/control/sessions/${id(session)}/image?ref=${encodeURIComponent(ref)}`, {
+                            signal: AbortSignal.timeout(PAYLOAD_TIMEOUT_MS),
+                        });
+                        if (!res.ok)
+                            throw await controlError(res);
+                        if (res.status === 204)
+                            return undefined;
+                        return {
+                            data: toBase64(new Uint8Array(await res.arrayBuffer())),
+                            mimeType: res.headers.get("content-type") ?? "application/octet-stream",
+                        };
+                    },
                     events: () => eventsOf(session),
                     update: (patch) => write(`/control/sessions/${id(session)}`, "PATCH", patch),
                     steer: (prompt) => write(`/control/sessions/${id(session)}/actions`, "POST", { type: "steer", prompt }),
@@ -404,6 +417,14 @@ export function connectAgent(options) {
         },
     };
 }
+/** Base64 without `Buffer` (this module runs in any Fetch runtime), in chunks: spreading megabytes of bytes into one
+ *  `String.fromCharCode` call overflows the argument limit. */
+function toBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
 /** Minimal SSE reader: yields each `data:` payload; ignores comments (heartbeats) and other fields. */
 async function* sseData(body, watch) {
     const decoder = new TextDecoder();

package/dist/session.d.ts

@@ -1,7 +1,7 @@
 /**
  * Session control plane — the engine-neutral serving extension beside Agent Handler (docs/design/session-control.md).
  */
-import type { Json, Prompt } from "./agent.ts";
+import type { ImageRef, Json, Prompt } from "./agent.ts";
 export interface SessionControl {
     capabilities(): SessionCapabilities;
     /** The names this agent exposes — what a composer's `/` completion LISTS. */
@@ -42,15 +42,34 @@ export interface Session {
     entries(options?: {
         since?: string;
     }): Promise<SessionEntries>;
+    /**
+     * The bytes behind an {@link EntryImage.ref} this session published; `undefined` when this session holds no such
+     * image. Total, like every read but `list()`.
+     *
+     * Over the wire, a `mimeType` other than `image/png`, `image/jpeg`, `image/gif` or `image/webp` reads back as
+     * `application/octet-stream`: the transport will not serve a sender-declared type it cannot trust (the entry still
+     * lists the declared one). pi normalizes an invoke's opening prompt images to those four; a `steer`/`followUp`
+     * image and a tool result keep whatever type the sender declared, so `image/jpg`, a type with parameters, or
+     * `image/svg+xml` sent that way reads back as `application/octet-stream` remotely.
+     */
+    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>;
@@ -110,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;
@@ -133,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";
@@ -169,6 +203,7 @@ export declare const PARTIAL_UPDATE_CODE = "partial_update";
 export type SessionResult = {
     ok: true;
     runId?: string;
+    disposition?: PromptDisposition;
 } | {
     ok: false;
     error: {
@@ -177,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;
@@ -194,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. */
@@ -232,6 +277,15 @@ export interface SessionEntry {
     kind: string;
     data: Json;
 }
+/**
+ * One image a message carried, as `data.images` lists it on a `user` or `tool` entry and on `user_message` (absent
+ * when there are none). Bytes stay out: `entries()` is read on every open and reconnect, and one screenshot is
+ * megabytes. `ref` is opaque; {@link Session.image} of the same session reads the bytes.
+ */
+export type EntryImage = {
+    ref: string;
+    mimeType: string;
+};
 /**
  * A live event subscription, plus the ONE thing a reconnecting client cannot infer: when it started.
  *
@@ -283,12 +337,13 @@ export type MessageStartedEvent = SessionEvent<"message_started", Record<never,
 /**
  * A user message entered the conversation: the run's opening prompt, a steer or follow-up leaving `pending`, or one an
  * extension sent. It reports after the message is recorded, so `entries()` already holds `entryId` with the same
- * `text` (a slash command expanded, images not included), and before the answer to it starts. The one live event a
- * backfill can be deduplicated against exactly.
+ * `text` (a slash command expanded) and `images`, and before the answer to it starts. The one live event a backfill
+ * can be deduplicated against exactly.
  */
 export type UserMessageEvent = SessionEvent<"user_message", {
     entryId: string;
     text: string;
+    images?: EntryImage[];
 }> & {
     runId: string;
 };
@@ -298,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;
 };
@@ -313,6 +384,7 @@ export type ToolProgressEvent = SessionEvent<"tool_progress", {
     id: string;
     name: string;
     partialResult: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };
@@ -320,15 +392,16 @@ export type ToolFinishedEvent = SessionEvent<"tool_finished", {
     id: string;
     isError: boolean;
     content: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };
 /**
  * The prompts queued on the active run, oldest first, as the engine queued them: plain text as sent, a slash command
- * already expanded (a `/skill:…` becomes the skill's text), images not included. A prompt LEAVES its list when it
- * enters the conversation as a user message: from then on it is in the record and in every later model call (an abort
- * can still end the run before the model answers it). Whatever is still listed when the run settles never entered
- * the conversation and is dropped with the run.
+ * already expanded (a `/skill:…` becomes the skill's text), without its images (its `user_message` carries them). A
+ * prompt LEAVES its list when it enters the conversation as a user message: from then on it is in the record and in
+ * every later model call (an abort can still end the run before the model answers it). Whatever is still listed when
+ * the run settles never entered the conversation and is dropped with the run.
  */
 export type PendingPrompts = {
     steering: 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.22.1",
+  "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,15 +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",