@nathapp/nax-agent 0.91.7-canary.9 → 0.91.7

package/dist/native/session/transcript-images.js

@@ -0,0 +1,247 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, readFile, realpath, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { NaxError } from "#src/infra/index";
+import { writeFileAtomic } from "#src/internal/atomic-write";
+/** Filesystem operations separate from the atomic writer's write/rename seam. */
+export const _transcriptImagesDeps = {
+    link,
+    mkdir,
+    open,
+    realpath,
+    lstat,
+    readFile: (path) => readFile(path),
+    rm,
+    stat: (path) => stat(path),
+    writeFileAtomic,
+};
+const extensions = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+export function transcriptImagesPath(path) {
+    return path.replace(/\.json$/, ".images");
+}
+function extension(mimeType) {
+    const ext = Object.hasOwn(extensions, mimeType) ? extensions[mimeType] : undefined;
+    if (ext !== undefined)
+        return ext;
+    throw new NaxError(`Unsupported transcript image type: ${mimeType}`, "TRANSCRIPT_IMAGE_TYPE_UNSUPPORTED", {
+        stage: "native-session",
+    });
+}
+/** A hard link publishes complete bytes atomically, failing rather than replacing a winner. */
+async function publishImageOnce(path, bytes) {
+    const staged = `${path}.${randomUUID()}.tmp`;
+    try {
+        // Keep atomic staging (and its rename seam), but never rename over the final name.
+        await _transcriptImagesDeps.writeFileAtomic(staged, bytes);
+        try {
+            await _transcriptImagesDeps.link(staged, path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            // Another writer published this content-addressed image first; leave it untouched.
+        }
+    }
+    finally {
+        await _transcriptImagesDeps.rm(staged, { force: true });
+    }
+}
+async function assertSafeImageFolder(folder) {
+    if ((await canonicalImageFolder(folder)) === null) {
+        throw new NaxError("Unsafe transcript image sidecar", "TRANSCRIPT_IMAGE_PATH_UNSAFE", {
+            stage: "native-session",
+        });
+    }
+}
+async function publishImage(folder, image) {
+    await assertSafeImageFolder(folder);
+    const bytes = Buffer.from(image.data, "base64");
+    const ref = createHash("sha256").update(bytes).digest("hex");
+    const path = join(folder, `${ref}.${extension(image.mimeType)}`);
+    try {
+        await _transcriptImagesDeps.stat(path);
+        const entry = await _transcriptImagesDeps.lstat(path);
+        if (!entry.isFile()) {
+            throw new NaxError("Unsafe transcript image entry", "TRANSCRIPT_IMAGE_PATH_UNSAFE", {
+                stage: "native-session",
+            });
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        await publishImageOnce(path, bytes);
+    }
+    if ((await readImageBytes(folder, basename(path))) === null) {
+        throw new NaxError("Unsafe transcript image entry", "TRANSCRIPT_IMAGE_PATH_UNSAFE", {
+            stage: "native-session",
+        });
+    }
+    const { data: _data, ...metadata } = image;
+    return { ...metadata, ref };
+}
+/** Preflight the WHOLE document before even creating the image directory. */
+export async function splitTranscriptImages(path, doc) {
+    let hasImages = false;
+    for (const message of doc.messages) {
+        if (message.role !== "user")
+            continue;
+        for (const image of message.images ?? []) {
+            extension(image.mimeType);
+            hasImages = true;
+        }
+    }
+    if (!hasImages)
+        return doc;
+    const folder = transcriptImagesPath(path);
+    await _transcriptImagesDeps.mkdir(folder, { recursive: true });
+    await assertSafeImageFolder(folder);
+    const messages = [];
+    // Sequential publication deduplicates repeated images within this save too.
+    for (const message of doc.messages) {
+        if (message.role !== "user" || !message.images?.length) {
+            messages.push(message);
+            continue;
+        }
+        const images = [];
+        for (const image of message.images)
+            images.push(await publishImage(folder, image));
+        messages.push({ ...message, images });
+    }
+    return { ...doc, schemaVersion: 2, messages };
+}
+/** Reject redirected sidecars as well as symlinked image entries. */
+async function canonicalImageFolder(folder) {
+    if (!(await _transcriptImagesDeps.lstat(folder)).isDirectory())
+        return null;
+    const parent = await _transcriptImagesDeps.realpath(dirname(folder));
+    const expected = join(parent, basename(folder));
+    return (await _transcriptImagesDeps.realpath(folder)) === expected ? expected : null;
+}
+async function readImageBytes(folder, name) {
+    const canonical = await canonicalImageFolder(folder);
+    if (canonical === null)
+        return null;
+    const path = join(canonical, name);
+    // O_NOFOLLOW closes the lstat/open race for the final path component.
+    const handle = await _transcriptImagesDeps.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        // Verify containment and identity AFTER open, before consuming any bytes.
+        const resolved = await _transcriptImagesDeps.realpath(path);
+        if (dirname(resolved) !== canonical || (await canonicalImageFolder(folder)) !== canonical)
+            return null;
+        const opened = await handle.stat();
+        const current = await _transcriptImagesDeps.lstat(path);
+        if (!opened.isFile() || !current.isFile() || opened.dev !== current.dev || opened.ino !== current.ino)
+            return null;
+        return await _transcriptImagesDeps.readFile(handle);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readStoredImage(folder, image) {
+    const { ref, ...metadata } = image;
+    // Validate both fields before deriving a path or touching the filesystem.
+    if (typeof ref !== "string" || !/^[a-f0-9]{64}$/.test(ref) || !Object.hasOwn(extensions, image.mimeType)) {
+        return null;
+    }
+    try {
+        const bytes = await readImageBytes(folder, `${ref}.${extensions[image.mimeType]}`);
+        return bytes === null ? null : { ...metadata, data: bytes.toString("base64") };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR")
+            return null;
+        throw error;
+    }
+}
+/** A note the loader writes in place of an image it could not read back: numbered, or bare. */
+const MISSING_IMAGE_NOTE = /^\[image missing(?: #(\d+))?\]$/;
+const LINE_BREAK = /\r\n|[\r\n]/;
+/** A `schemaVersion` 2 document whose image list is not a list: unreadable, not merely lossy. */
+function corruptImageList() {
+    return new NaxError("transcript image list is not an array", "TRANSCRIPT_CORRUPT", {
+        stage: "native-session",
+    });
+}
+/**
+ * The 1-based slots a stored message's content already notes as lost.
+ *
+ * A later save keeps the notes an earlier load wrote — they travel with the content — and
+ * stores only the images that were readable. The array the next load enumerates is therefore
+ * the survivors of an earlier one, and a lost image must still be numbered by the slot it
+ * held in the original message rather than by its place among the survivors. Notes are read
+ * from the trailing run only, exactly as replay strips them, so a user's own line in the
+ * middle of a message is never mistaken for one, and a bare note (an older build's, which
+ * recorded no position) claims no slot here.
+ */
+function notedSlots(content) {
+    const slots = new Set();
+    if (typeof content !== "string")
+        return slots;
+    const lines = content.split(LINE_BREAK);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const note = MISSING_IMAGE_NOTE.exec(lines[index] ?? "");
+        if (note === null)
+            break;
+        const slot = note[1];
+        if (slot !== undefined)
+            slots.add(Number(slot));
+    }
+    return slots;
+}
+/** The slot the `index`-th stored image holds: the next 1-based position no note claims. */
+function slotOf(index, noted) {
+    let remaining = index + 1;
+    let slot = 0;
+    while (remaining > 0) {
+        slot += 1;
+        if (!noted.has(slot))
+            remaining -= 1;
+    }
+    return slot;
+}
+/** Decode the private disk format; callers only ever see inline attachments. */
+export async function rehydrateTranscriptImages(path, value) {
+    const doc = value;
+    if (typeof doc.schemaVersion === "number" && doc.schemaVersion > 2) {
+        throw new NaxError(`Unsupported transcript schemaVersion ${doc.schemaVersion}`, "TRANSCRIPT_SCHEMA_UNSUPPORTED", {
+            stage: "native-session",
+        });
+    }
+    if (doc.schemaVersion !== 2)
+        return value;
+    const { schemaVersion: _version, ...rest } = doc;
+    const messages = [];
+    for (const message of doc.messages) {
+        if (message.role !== "user" || !message.images?.length) {
+            messages.push(message);
+            continue;
+        }
+        if (!Array.isArray(message.images))
+            throw corruptImageList();
+        const images = [];
+        let content = message.content;
+        const noted = notedSlots(content);
+        for (const [index, image] of message.images.entries()) {
+            const hydrated = await readStoredImage(transcriptImagesPath(path), image);
+            if (hydrated)
+                images.push(hydrated);
+            else {
+                const marker = `[image missing #${slotOf(index, noted)}]`;
+                content = content ? `${content}\n${marker}` : marker;
+            }
+        }
+        const { images: _storedImages, ...text } = message;
+        messages.push({ ...text, content, ...(images.length ? { images } : {}) });
+    }
+    return { ...rest, messages };
+}

package/dist/native/session/transcript-store.d.ts

@@ -6,9 +6,15 @@
  * nax stored nothing; SessionDescriptor still has no message field, and gains
  * none. See ADR-028 sections 2 and 3.
  */
+import { rename, rm } from "node:fs/promises";
 import type { ConversationMessage } from "@nathapp/nax-ai";
 import { type TranscriptIdentity } from "./transcript-identity.ts";
 import type { TranscriptDoc, TranscriptStore } from "./transcript-types.ts";
+/** Folder lifecycle seam; the JSON operations retain their existing behavior. */
+export declare const _transcriptLifecycleDeps: {
+    rename: typeof rename;
+    rm: typeof rm;
+};
 export { type TranscriptIdentity, transcriptModelIdentity } from "./transcript-identity.ts";
 export declare function transcriptPath(dir: string, sessionName: string): string;
 /**

package/dist/native/session/transcript-store.js

@@ -11,6 +11,9 @@ import { join } from "node:path";
 import { getLogger, NaxError } from "#src/infra/index";
 import { writeFileAtomic } from "#src/internal/atomic-write";
 import { historyFromTranscript, transcriptDocFor } from "./transcript-identity.js";
+import { rehydrateTranscriptImages, splitTranscriptImages, transcriptImagesPath } from "./transcript-images.js";
+/** Folder lifecycle seam; the JSON operations retain their existing behavior. */
+export const _transcriptLifecycleDeps = { rename, rm };
 export { transcriptModelIdentity } from "./transcript-identity.js";
 export function transcriptPath(dir, sessionName) {
     return join(dir, `${sessionName}.transcript.json`);
@@ -56,13 +59,15 @@ export async function readTranscriptDoc(dir, sessionName) {
         return { savedAt: LEGACY_SAVED_AT, messages: parsed };
     if (typeof parsed !== "object" || parsed === null)
         throw corruptTranscript(sessionName, "not a transcript document");
-    const doc = parsed;
+    const doc = await rehydrateTranscriptImages(transcriptPath(dir, sessionName), parsed);
     return { ...doc, messages: doc.messages ?? [] };
 }
 async function writeTranscriptDoc(dir, sessionName, doc) {
+    const path = transcriptPath(dir, sessionName);
+    const stored = await splitTranscriptImages(path, doc);
     await mkdir(dir, { recursive: true });
-    // Atomic (#3): a torn transcript is unrecoverable — every later load throws TRANSCRIPT_CORRUPT.
-    await writeFileAtomic(transcriptPath(dir, sessionName), JSON.stringify(doc, null, 2));
+    // Publish JSON only after all image files have been published successfully.
+    await writeFileAtomic(path, JSON.stringify(stored, null, 2));
 }
 /**
  * The file store: `<dir>/<name>.transcript.json`, written as given (the loop's
@@ -111,17 +116,45 @@ export async function saveTranscript(dir, sessionName, messages, identity = {})
  */
 export async function retainTranscript(dir, sessionName) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const live = transcriptPath(dir, sessionName);
+    const retained = join(dir, `${sessionName}.transcript.failed-${stamp}.json`);
     try {
-        await rename(transcriptPath(dir, sessionName), join(dir, `${sessionName}.transcript.failed-${stamp}.json`));
+        await rename(live, retained);
     }
     catch (err) {
         if (err.code === "ENOENT")
             return;
         throw err;
     }
+    try {
+        await _transcriptLifecycleDeps.rename(transcriptImagesPath(live), transcriptImagesPath(retained));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        // Restore the live JSON on failure so its still-live sidecar remains loadable
+        // and a later retention attempt can move the pair again.
+        try {
+            await _transcriptLifecycleDeps.rename(retained, live);
+        }
+        catch (rollbackError) {
+            throw new NaxError("Transcript retention rollback failed", "TRANSCRIPT_RETENTION_ROLLBACK_FAILED", {
+                stage: "native-session",
+                cause: err,
+                rollbackError,
+                live,
+                retained,
+            });
+        }
+        throw err;
+    }
+}
+async function deleteTranscriptFile(path) {
+    await rm(path, { force: true });
+    await _transcriptLifecycleDeps.rm(transcriptImagesPath(path), { recursive: true, force: true });
 }
 export async function deleteTranscript(dir, sessionName) {
-    await rm(transcriptPath(dir, sessionName), { force: true });
+    await deleteTranscriptFile(transcriptPath(dir, sessionName));
 }
 /**
  * Cap on transcripts retained per feature's `sessions/` directory. Transcripts
@@ -180,7 +213,7 @@ export async function pruneRetainedTranscripts(dir, maxRetained = MAX_RETAINED_T
     // Oldest first, so the slice below drops exactly the excess over the cap.
     withMtimes.sort((a, b) => a.mtimeMs - b.mtimeMs);
     const toDelete = withMtimes.slice(0, withMtimes.length - maxRetained);
-    await Promise.all(toDelete.map((f) => rm(f.path, { force: true })));
+    await Promise.all(toDelete.map((f) => deleteTranscriptFile(f.path)));
     if (!hasWarnedAboutTranscriptTruncation) {
         hasWarnedAboutTranscriptTruncation = true;
         getLogger().warn("native-session", "Transcript retention cap reached — oldest kept-on-failure transcripts pruned", {

package/dist/native/session/turn-compaction-step.js

@@ -22,6 +22,7 @@
  */
 import { getSafeLogger } from "#src/infra/index";
 import { applyCompaction, estimateContextTokens, keepBudget, prepareCompaction, } from "./compaction.js";
+import { imagesAsNotes } from "./image-context.js";
 import { usageBeat } from "./turn-accumulator.js";
 /**
  * The half both branches share: summarize the dropped span, then apply the
@@ -31,7 +32,7 @@ import { usageBeat } from "./turn-accumulator.js";
 async function summarizeAndApply(messages, plan, deps, source = {}) {
     const summary = source.replacementSummary !== undefined
         ? { text: source.replacementSummary, usage: { inputTokens: 0, outputTokens: 0 }, costUsd: 0 }
-        : await deps.summarize(plan.toSummarize, plan.previousSummary);
+        : await deps.summarize(imagesAsNotes(plan.toSummarize), plan.previousSummary);
     // Rebound, not spliced in place: `messages` is a local accumulator and
     // rebinding it keeps the compacted array a fresh value.
     const compacted = applyCompaction(messages, plan, summary.text);

package/dist/native/session/turn-complete-step.js

@@ -19,6 +19,7 @@
  * which recovery a thrown round trip gets.
  */
 import { getSafeLogger } from "#src/infra/index";
+import { capRequestImages } from "./image-context.js";
 import { applyHistoryPatch } from "./loop-events/cache-boundary.js";
 import { takePartialSpend } from "./partial-spend.js";
 import { usageBeat } from "./turn-accumulator.js";
@@ -89,7 +90,9 @@ export async function completeWithRecovery(args) {
         // successful attempt is the last one to reach this line — `honoured`
         // describes the wire the provider actually answered (spec 3.6).
         honoured = wire.honoured;
-        return deps.complete(wire.messages, tools, options, turnEvents.deltaSink(roundTrip));
+        // Cap after history patches, on every attempt; saved history stays untouched.
+        // Dropping an image may stale the prompt-cache prefix/anchor estimate.
+        return deps.complete(capRequestImages(wire.messages), tools, options, turnEvents.deltaSink(roundTrip));
     };
     // A failed round trip was still billed for what it streamed. Folding it in
     // here, per attempt, is what makes a retry count both attempts and an

package/dist/native/session/turn-loop.js

@@ -33,6 +33,41 @@ import { createTurnEventEmitter } from "./turn-event-emitter.js";
 import { runRoundTripLoop, runTurnEndPhase } from "./turn-loop-round-trip.js";
 import { buildTurnResult, logTurnTailWarnings } from "./turn-result.js";
 import { recordNativeTurnFailureUsage } from "./turn-types.js";
+/**
+ * What a refusal says when the patch carries no usable reason.
+ *
+ * A plugin's `loop-handlers` are raw JavaScript: TypeScript's
+ * `{ reason: string }` is not enforced on them, so `{ block: {} }`,
+ * `{ block: { reason: undefined } }`, `{ block: { reason: "   " } }` and a
+ * non-object `block` all reach this point. The turn still fails closed — a
+ * malformed block is a block — but the reason is the whole turn-error line the
+ * user reads (`NATIVE_TURN_BLOCKED: <reason>` in chat, a failed turn in a run),
+ * so an empty message would say nothing about why the prompt vanished.
+ */
+const BLOCK_REASON_FALLBACK = "before_turn handler blocked the turn without a reason";
+/** The reason a `block` patch refuses the turn with — never empty (US-001). */
+function blockRefusalReason(block) {
+    const reason = typeof block === "object" && block !== null ? block.reason : undefined;
+    if (typeof reason === "string" && reason.trim() !== "")
+        return reason;
+    getSafeLogger()?.warn("native-loop-events", "before_turn block patch carries no reason text; refusing the turn anyway", {
+        blockKind: typeof block,
+    });
+    return BLOCK_REASON_FALLBACK;
+}
+/**
+ * A `block` patch refuses the turn (US-001).
+ *
+ * Thrown BEFORE `messages.push` and before any provider request, so a blocked
+ * prompt is neither sent nor persisted. `reason` is the message, which is what
+ * makes the chat's turn-error line read `NATIVE_TURN_BLOCKED: <reason>`
+ * (`applyTurnEnd` in nax's transcript-model renders `CODE: message`).
+ */
+function assertTurnNotBlocked(block, sessionName) {
+    if (block === undefined)
+        return;
+    throw new NaxError(blockRefusalReason(block), "NATIVE_TURN_BLOCKED", { stage: "native-session", sessionName });
+}
 /**
  * The messages `before_turn` appends as the turn's seed: the handler's patch
  * when it is a non-empty user-role array (spec 6.1's stop rule), otherwise the
@@ -41,13 +76,52 @@ import { recordNativeTurnFailureUsage } from "./turn-types.js";
  * empty or speaks with another role hands the model a conversation it cannot
  * answer as itself.
  */
-function beforeTurnSeed(patch, prompt) {
+function seededMessages(patch, prompt, images) {
+    const seed = {
+        role: "user",
+        content: prompt,
+        ...(images?.length ? { images } : {}),
+    };
     if (patch === undefined)
-        return [{ role: "user", content: prompt }];
+        return [seed];
     if (patch.length > 0 && patch.every((m) => m.role === "user"))
         return [...patch];
     getSafeLogger()?.warn("native-loop-events", "before_turn seed patch rejected: seed must be a non-empty user-role array", { seedLength: patch.length });
-    return [{ role: "user", content: prompt }];
+    return [seed];
+}
+/**
+ * `promptContext` is PREFIXED to the seed's first message (US-001).
+ *
+ * Not a `seed` patch: that one replaces the prompt message, and the caller's
+ * images go with it. Only `content` changes here, so a message's images,
+ * toolCallId and role survive untouched. An empty context is no context.
+ *
+ * A plugin's `loop-handlers` are raw JavaScript (see `blockRefusalReason`), so a
+ * non-string context reaches here too; it is dropped with a warning rather than
+ * stringified into the prompt as `[object Object]`.
+ */
+function withPromptContext(seed, promptContext) {
+    if (promptContext === undefined || promptContext === "")
+        return [...seed];
+    if (typeof promptContext !== "string") {
+        getSafeLogger()?.warn("native-loop-events", "before_turn promptContext is not a string; prompt unchanged", {
+            promptContextKind: promptContext === null ? "null" : typeof promptContext,
+        });
+        return [...seed];
+    }
+    const [first, ...rest] = seed;
+    if (first === undefined)
+        return [];
+    return [{ ...first, content: `${promptContext}\n\n${first.content}` }, ...rest];
+}
+/**
+ * What the turn actually appends. `block` is checked FIRST — a patch carrying
+ * both a block and a context refuses the turn, because the reason is the whole
+ * answer and there is no turn left for the context to sit in front of.
+ */
+function beforeTurnSeed({ patch, prompt, images, sessionName }) {
+    assertTurnNotBlocked(patch?.block, sessionName);
+    return withPromptContext(seededMessages(patch?.seed, prompt, images), patch?.promptContext);
 }
 /** Keep billed spend on the original error for both loop and persistence failures. */
 function recordFailureSpend(err, usage) {
@@ -126,7 +200,12 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
             event: "before_turn",
         }).messages,
     ];
-    messages.push(...beforeTurnSeed(turnStart.seed, prompt));
+    messages.push(...beforeTurnSeed({
+        patch: turnStart,
+        prompt,
+        images: opts.images,
+        sessionName: handle.id,
+    }));
     const codingTools = opts.codingTools ?? [];
     const codingToolNames = new Set(codingTools.map((t) => t.name));
     // Native spends the budget ONLY on ask_human exchanges. Unlike ACP it is

package/dist/native/session-adapter.d.ts

@@ -54,6 +54,8 @@ export declare class NativeSessionAdapter implements AgentSessionAdapter {
      */
     hasCredentials(): Promise<boolean>;
     openSession(name: string, opts: OpenSessionOpts): Promise<SessionHandle>;
+    /** Resolve the current handle's model; absent input metadata is text-only. */
+    imageInput(handle: SessionHandle): Promise<boolean>;
     sendTurn(handle: SessionHandle, prompt: string, opts: SendTurnOpts): Promise<TurnResult>;
     closeSession(handle: SessionHandle): Promise<void>;
     /**

package/dist/native/session-adapter.js

@@ -59,6 +59,11 @@ function perTurnDeps(opts) {
         ...(opts.onTurnEvent !== undefined ? { onTurnEvent: opts.onTurnEvent } : {}),
     };
 }
+function assertImageInput(handle, resolved, images) {
+    if (images?.length && resolved.input?.includes("image") !== true) {
+        throw new NaxError(`Native model "${resolved.provider}/${resolved.id}" does not support image input`, "NATIVE_IMAGE_INPUT_UNSUPPORTED", { stage: "native-session", sessionName: handle.id, provider: resolved.provider, model: resolved.id });
+    }
+}
 const adapterStates = new WeakMap();
 /** The adapter's per-session state. `/internal` only: tests and the S3 facade read it; nax never does. */
 export function nativeSessionStateOf(adapter) {
@@ -140,11 +145,20 @@ export class NativeSessionAdapter {
     openSession(name, opts) {
         return openNativeSession(this.state, name, opts);
     }
+    /** Resolve the current handle's model; absent input metadata is text-only. */
+    async imageInput(handle) {
+        const { provider, model } = parseNativeModel(handle.modelDef?.model ?? "");
+        const client = await this.client();
+        const resolved = await client.model(provider, model);
+        return resolved.input?.includes("image") === true;
+    }
     async sendTurn(handle, prompt, opts) {
         const { provider, model, effort } = parseNativeModel(handle.modelDef?.model ?? "");
         const thinking = toThinkingLevel(effort);
         const client = await this.client();
         const resolved = await client.model(provider, model);
+        // Refuse before runNativeTurn: its error path deliberately saves history.
+        assertImageInput(handle, resolved, opts.images);
         const contextWindow = resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow);
         this.state.repositoryInstructions
             .get(handle.id)

package/dist/session/agent-session-errors.d.ts

@@ -4,7 +4,7 @@
  * or registerCodingTool's TOOL_NAME_RESERVED.
  */
 import { NaxError } from "#src/infra/nax-error";
-export type AgentSessionErrorCode = "AGENT_SESSION_INVALID_OPTIONS" | "AGENT_SESSION_EXISTS" | "AGENT_SESSION_BUSY" | "AGENT_SESSION_CLOSED" | "AGENT_SESSION_INVALID_ANSWER" | "AGENT_SESSION_NOT_FOUND" | "AGENT_SESSION_SCHEMA_UNSUPPORTED" | "AGENT_SESSION_MODEL_MISMATCH" | "AGENT_SESSION_SANDBOX_UNAVAILABLE" | "AGENT_SESSION_TOOL_NAME_RESERVED" | "AGENT_SESSION_BACKEND_UNAVAILABLE" | "AGENT_SESSION_AUTH_REQUIRED" | "AGENT_SESSION_RATE_LIMITED" | "AGENT_SESSION_CAPABILITY_UNSUPPORTED" | "AGENT_SESSION_BACKEND_MISMATCH";
+export type AgentSessionErrorCode = "AGENT_SESSION_INVALID_OPTIONS" | "AGENT_SESSION_INVALID_INPUT" | "AGENT_SESSION_EXISTS" | "AGENT_SESSION_BUSY" | "AGENT_SESSION_CLOSED" | "AGENT_SESSION_INVALID_ANSWER" | "AGENT_SESSION_NOT_FOUND" | "AGENT_SESSION_SCHEMA_UNSUPPORTED" | "AGENT_SESSION_MODEL_MISMATCH" | "AGENT_SESSION_SANDBOX_UNAVAILABLE" | "AGENT_SESSION_TOOL_NAME_RESERVED" | "AGENT_SESSION_BACKEND_UNAVAILABLE" | "AGENT_SESSION_AUTH_REQUIRED" | "AGENT_SESSION_RATE_LIMITED" | "AGENT_SESSION_CAPABILITY_UNSUPPORTED" | "AGENT_SESSION_BACKEND_MISMATCH";
 export declare class AgentSessionError extends NaxError {
     readonly code: AgentSessionErrorCode;
     constructor(message: string, code: AgentSessionErrorCode, context?: Record<string, unknown>);

package/dist/session/agent-session-turn.d.ts

@@ -1,5 +1,6 @@
 import type { TranscriptStore } from "#src/native/session/transcript-types";
 import type { SessionEvent, SessionEventBody, TurnEndStatus } from "./agent-session-types.ts";
+import type { SendInput } from "./image-input.ts";
 import type { TurnContribution } from "./session-backend.ts";
 import { type AgentSessionAdapter, type SessionHandle, type TurnResult } from "./session-types.ts";
 /** The ask_human budget per turn: nax's agent.maxInteractionTurns default. */
@@ -27,7 +28,7 @@ export interface ClaimedTurn {
     readonly settled: Promise<void>;
     cancel(reason: string): void;
 }
-export interface ClaimTurnHooks {
+export interface ClaimTurnHooks extends SendInput {
     readonly onStart: (live: LiveTurn) => void;
     /** Runs before turn_end is emitted. `status` is undefined for a voided claim. */
     readonly onSettle: (turnId: string, status: TurnEndStatus | undefined) => void;

package/dist/session/agent-session-turn.js

@@ -81,9 +81,10 @@ function fromError(err, signal) {
         return { ...base, status: "cancelled" };
     return { ...base, status: "errored", error: errorOf(err) };
 }
-function sendTurn(ctx, live, message) {
-    return ctx.adapter.sendTurn(ctx.handle, message, {
+function sendTurn(ctx, live, input) {
+    return ctx.adapter.sendTurn(ctx.handle, input.message, {
         ...ctx.turnOpts(),
+        ...(input.images?.length ? { images: input.images } : {}),
         maxInteractions: ASK_HUMAN_BUDGET,
         turnId: live.turnId,
         signal: live.signal,
@@ -104,14 +105,14 @@ async function markTurn(ctx, turnId, state) {
         return { error };
     }
 }
-async function runTurn(ctx, live, message) {
+async function runTurn(ctx, live, input) {
     live.emit({ type: "turn_start" });
     const started = await markTurn(ctx, live.turnId, "running");
     if (started !== undefined)
         return fromError(started.error, live.signal);
     let end;
     try {
-        end = turnEndFromResult(await sendTurn(ctx, live, message));
+        end = turnEndFromResult(await sendTurn(ctx, live, input));
     }
     catch (err) {
         end = fromError(err, live.signal);
@@ -167,7 +168,7 @@ export function claimTurn(ctx, message, hooks) {
         state = "running";
         const timer = _agentSessionDeps.setTimeout(() => controller.abort(abortReason(TIMED_OUT, "turn deadline")), ctx.turnTimeoutSeconds * 1000);
         hooks.onStart(live);
-        void runTurn(ctx, live, message)
+        void runTurn(ctx, live, { message, images: hooks.images })
             .catch((err) => fromError(err, controller.signal))
             .then((end) => {
             _agentSessionDeps.clearTimeout(timer);

package/dist/session/agent-session-types.d.ts

@@ -9,6 +9,7 @@ import type { TokenUsage } from "#src/cost/standard-types";
 import type { TranscriptStore } from "#src/native/session/transcript-types";
 import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
+import type { SendInput } from "./image-input.ts";
 import type { BackendInfo, SessionBackend } from "./session-backend.ts";
 import type { JSONSchema } from "./tool-descriptor.ts";
 /**
@@ -179,7 +180,19 @@ export interface CommandRunResult {
     readonly content: string;
     readonly isError: boolean;
 }
+/** What `AgentSession.configure` changes on a live session; at least one field, never an empty string. */
+export interface SessionConfigureInput {
+    readonly model?: string;
+    readonly effort?: string;
+}
 export interface AgentSession {
+    /**
+     * Sets the model and/or effort on the live session without a new process. Refuses, in order:
+     * `AGENT_SESSION_CLOSED`, `AGENT_SESSION_BUSY` (a turn, a command or another configure is in
+     * flight), `AGENT_SESSION_INVALID_OPTIONS` (neither field, or an empty string), then
+     * `AGENT_SESSION_CAPABILITY_UNSUPPORTED` (the backend cannot). The facade always provides this method.
+     */
+    configure?(input: SessionConfigureInput): Promise<void>;
     /** Run through the session's Bash tool without a model turn. The facade always provides this method. */
     runCommand?(command: string, onEvent: (event: SessionEvent) => void): Promise<CommandRunResult>;
     readonly id: string;
@@ -191,7 +204,9 @@ export interface AgentSession {
         readonly status: TurnEndStatus;
     } | undefined;
     /** Claims the session's single turn slot synchronously; the turn starts on the first `next()`. */
-    send(message: string): AsyncIterable<SessionEvent>;
+    send(message: string, input?: SendInput): AsyncIterable<SessionEvent>;
+    /** Whether the current backend/model reads images. The facade always provides this method. */
+    acceptsImages?(): Promise<boolean>;
     answer(requestId: string, reply: AnswerReply): AnswerStatus;
     /** Aborts the running turn; a no-op when none runs. */
     cancel(reason?: string): void;