@fastagent-sh/fastagent 0.22.0 → 0.23.0

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

@@ -4,84 +4,57 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { SessionManager, SettingsManager, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
 import { bindPiSession, definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
 import { readMachine } from "./machine.js";
 import { resolveModel } from "./config.js";
-import { assembleSystemPrompt, piBasePrompt } from "./create.js";
-import { canonicalPath, loadAgentDefinition, loadExtensionPaths } from "./definition.js";
-import { DEFAULT_THINKING_LEVEL, createPiModelRuntime } from "./models.js";
-import { reportFindingsIfChanged, reportToolCollisions } from "./report.js";
-import { resolveAgentAssembly } from "./open.js";
+import { canonicalPath } from "./definition.js";
+import { reportToolCollisions } from "./report.js";
+import { assembleFront, resolveAgentAssembly } from "./open.js";
+import { resolvePlacement } from "../../paths.js";
 /**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools, skills, and auth
- * resolved exactly as the serving opener does).
+ * Build pi's interactive runtime over the SAME assembly `dev`/`start` serve ({@link assembleFront}): model
+ * registry, prompt, tools, skills, reasoning effort and credentials all come from it, so what differs is only the
+ * session's shape (one resident runtime rather than one session per invoke).
  */
 export async function buildAgentSessionRuntime(dir, options = {}, sessionManager) {
-    async function resolveAssembly(cwd) {
-        // The shared front half — the SAME placement/config/model-spec/tool/auth resolution the serving opener uses
-        // (open.ts).
-        const { config, modelSpec, agentDir, auth, stateRoot, tools, toolCollisions } = await resolveAgentAssembly(cwd, options);
-        reportToolCollisions(toolCollisions);
-        // ONE hub owns model resolution AND per-request auth.
-        // The fallback layer travels too: `chat` resolving credentials differently from dev/start/invoke is exactly the
-        // divergence the layer exists to remove.
-        const modelRuntime = await createPiModelRuntime({ auth, agentDir, stateRoot });
-        const env = new NodeExecutionEnv({ cwd });
-        const definition = await loadAgentDefinition(agentDir, { cwd, env });
-        reportFindingsIfChanged(definition.dir, definition);
-        // Assembly-time, like serving's: this whole function is memoized, so the scan and its warnings happen once per
-        // runtime rather than per session rebuild (/new, /resume, fork).
-        const extensionPaths = await loadExtensionPaths(agentDir, { cwd, env });
-        // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including them here would
-        // duplicate them).
-        const systemPrompt = assembleSystemPrompt({
-            base: piBasePrompt({ tools, persona: definition.persona }),
-            contextFiles: definition.contextFiles,
-        });
-        return {
-            modelRuntime,
-            modelSpec,
-            // Serving honors config.thinkingLevel (config → L2); the resident session must too (fidelity).
-            thinkingLevel: config.thinkingLevel,
-            definition,
-            extensionPaths,
-            tools,
-            systemPrompt,
-        };
+    async function resolveAssembly() {
+        const front = await resolveAgentAssembly(dir, options);
+        reportToolCollisions(front.toolCollisions);
+        const { assembly } = await assembleFront(front);
+        // Read ONCE per runtime: a rebuild (/new, fork) keeps the startup snapshot, because config and tools stay in the
+        // import cache and a half-refreshed agent is worse than a stale one. Restart chat to pick up edits.
+        return { modelSpec: front.modelSpec, assembly, definition: await assembly.readDefinition() };
     }
-    // pi calls the factory again on /new, /resume, switch, and fork.
-    const rootCwd = canonicalPath(dir);
+    // The workspace, like serving's: where tools run and what session records are keyed to. Canonical, because pi's
+    // process.cwd() fallback is a realpath and a symlinked workspace would otherwise mismatch it.
+    const rootCwd = canonicalPath(resolvePlacement(dir).workspace);
+    // pi calls the factory again on /new, /resume, switch, and fork; the assembly is built once.
     let assembly;
     const assemblyFor = (cwd) => {
-        // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would otherwise mismatch a
-        // non-realpath rootCwd.
         const activeCwd = canonicalPath(cwd);
         if (activeCwd !== rootCwd) {
             throw workspaceScopeError(activeCwd);
         }
-        assembly ??= resolveAssembly(rootCwd);
+        assembly ??= resolveAssembly();
         return assembly;
     };
     const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { modelRuntime, modelSpec, thinkingLevel, definition, extensionPaths, tools, systemPrompt } = await assemblyFor(cwd);
+        const { modelSpec, assembly, definition } = await assemblyFor(cwd);
         // Per session, NOT memoized with the assembly.
-        const machine = await readMachine(cwd);
+        const [modelRuntime, machine] = await Promise.all([assembly.modelRuntime(), readMachine(cwd)]);
         const loaded = await createAgentSessionServices({
             cwd,
-            // fastagent's models + auth hub replaces pi's default (~/.pi-backed) one — the auth unification point; see the
-            // header.
+            // fastagent's models + auth hub replaces pi's default (~/.pi-backed) one — the auth unification point.
             modelRuntime,
             // PACKAGELESS, for the loader: fastagent never installs a pi package (machine.ts). Handed pi's own settings, the
             // loader resolves `packages` itself — installing a missing one, and failing chat's start when that fails.
             settingsManager: machine.settingsManager(),
-            // Chat's assembly is fixed for the life of the runtime (a rebuild makes a new one), so these read constants.
             resourceLoaderOptions: definitionResourceLoaderOptions({
-                systemPrompt: () => systemPrompt,
+                systemPrompt: () => definition.systemPrompt,
                 skills: () => definition.skills,
                 machine,
-                extensionPaths,
+                extensionPaths: assembly.extensionPaths,
             }),
         });
         // ...while the SESSION keeps pi's own file-backed settings, so `/settings` in the TUI still saves. pi persists by
@@ -97,13 +70,10 @@ export async function buildAgentSessionRuntime(dir, options = {}, sessionManager
             sessionManager,
             sessionStartEvent,
             model,
-            // The SPELLING serving uses (agent-session-factory), never `thinkingLevel` alone: pi resolves an ABSENT level
-            // from its own settings, which every posture now reads from the machine (`~/.pi/agent/settings.json`). A
-            // `/thinking` + Ctrl+S saved for coding would otherwise silently make this the one posture that answers at a
-            // different reasoning effort than the deployment does — the effort is the DEFINITION's (`thinkingLevel` in
-            // fastagent.config.ts), unlike the engine knobs around it.
-            thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
-            tools,
+            // Always set, never left for pi to fill: pi resolves an ABSENT level from the machine's settings, and the effort
+            // is the definition's (`thinkingLevel` in fastagent.config.ts), like serving's.
+            thinkingLevel: assembly.thinkingLevel,
+            tools: assembly.tools,
             // A tool must see one spelling of the workspace, including when opened through a symlink.
             cwd: rootCwd,
             recordActivations: false,

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

@@ -12,6 +12,7 @@ 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 { entryImages, imageAt } from "./entry-images.js";
 import { startCompaction } from "./agent-session-factory.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
 import { THINKING_LEVELS, activePath, resolveSessionSettings } from "./session-settings.js";
@@ -79,12 +80,15 @@ function toSessionEntry(entry, parentId) {
     };
     if (entry.type === "message") {
         const m = entry.message;
-        if (m.role === "user")
-            return { ...base, kind: "user", data: { text: contentText(m.content, "") } };
+        if (m.role === "user") {
+            return { ...base, kind: "user", data: { text: contentText(m.content, ""), ...entryImages(entry.id, m) } };
+        }
         if (m.role === "assistant") {
+            // `args` is what `tool_started` carries live (pi emits the call's recorded `arguments` there), so a reopened
+            // conversation shows the same call a watcher saw.
             const toolCalls = m.content
                 .filter((b) => b.type === "toolCall")
-                .map((b) => ({ id: b.id ?? "", name: b.name ?? "" }));
+                .map((b) => ({ id: b.id ?? "", name: b.name ?? "", args: b.arguments ?? {} }));
             const data = { text: contentText(m.content, "") };
             if (toolCalls.length > 0)
                 data.toolCalls = toolCalls;
@@ -99,6 +103,7 @@ function toSessionEntry(entry, parentId) {
                     toolName: m.toolName,
                     isError: m.isError ?? false,
                     text: contentText(m.content, ""),
+                    ...entryImages(entry.id, m),
                 },
             };
         }
@@ -354,6 +359,11 @@ export function createPiSessionControl(options) {
             }
             return { entries, ...(leafEntryId ? { leafEntryId } : {}) };
         },
+        async image(session, ref) {
+            // ponytail: opens (parses) the whole record per image; an index when long image-heavy sessions make it show.
+            const opened = await sessions.openIfExists(session);
+            return opened ? imageAt(opened, ref) : undefined;
+        },
         events(session) {
             // ONE CALL IS ONE SUBSCRIPTION, and `ready` is its boundary: the moment after which nothing emitted for this
             // session can be missed (session.ts, SessionEventStream). A second iteration of the same stream would be a
@@ -837,6 +847,7 @@ export function createPiSessionControl(options) {
                 id: session,
                 state: () => reads.state(session),
                 entries: (options) => reads.entries(session, options),
+                image: (ref) => reads.image(session, ref),
                 events: () => reads.events(session),
                 update: (patch) => updateOf(session, patch),
                 steer: (prompt) => runAction(session, { type: "steer", prompt }),

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

@@ -1,4 +1,5 @@
 import { ABORTED_CODE } from "../../agent.js";
+import { log } from "../../log.js";
 export function inProcessLease() {
     const busy = new Set();
     return {
@@ -105,11 +106,16 @@ 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 };
 }

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, 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, 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,6 +42,17 @@ 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. */
     update(patch: SessionUpdate): Promise<SessionResult>;
@@ -232,6 +243,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.
  *
@@ -280,6 +300,19 @@ export type RunSettledEvent = SessionEvent<"run_settled", {
 export type MessageStartedEvent = SessionEvent<"message_started", Record<never, never>> & {
     runId: string;
 };
+/**
+ * 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) 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;
+};
 export type MessageDeltaEvent = SessionEvent<"message_delta", {
     channel: "text" | "thinking";
     delta: string;
@@ -313,10 +346,10 @@ export type ToolFinishedEvent = SessionEvent<"tool_finished", {
 };
 /**
  * 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[];
@@ -368,4 +401,4 @@ export type ServingErrorEvent = SessionEvent<"serving_error", {
  * Every event the in-process observation plane emits today: L0, L1 `queue_changed`, and the L2 events
  * (`state_changed`, `compaction_*`, `retry_scheduled`).
  */
-export type KnownSessionEvent = RunStartedEvent | RunSettledEvent | MessageStartedEvent | MessageDeltaEvent | MessageFinishedEvent | ToolStartedEvent | ToolProgressEvent | ToolFinishedEvent | QueueChangedEvent | StateChangedEvent | CompactionStartedEvent | CompactionFinishedEvent | RetryScheduledEvent;
+export type KnownSessionEvent = RunStartedEvent | RunSettledEvent | MessageStartedEvent | UserMessageEvent | MessageDeltaEvent | MessageFinishedEvent | ToolStartedEvent | ToolProgressEvent | ToolFinishedEvent | QueueChangedEvent | StateChangedEvent | CompactionStartedEvent | CompactionFinishedEvent | RetryScheduledEvent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.22.0",
+  "version": "0.23.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",
@@ -106,6 +106,7 @@
     "@earendil-works/pi-coding-agent": "^0.87.1",
     "@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",