A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
feat(images): route image turns to a configured image model (#2453)
Seth Karten3b1aa5ff324b
diff --git a/packages/agent/.changes/image-model-override.md b/packages/agent/.changes/image-model-override.mdnew file mode 100644index 0000000000..450f3b1143--- /dev/null+++ b/packages/agent/.changes/image-model-override.md@@ -0,0 +1 @@+- Added an optional `modelOverride` run field: when set, prompt and continuation runs use that model (with its own thinking level and service tier) while `state.model` keeps identifying the session model; failures are tagged with the model that served the run.diff --git a/packages/agent/src/agent.ts b/packages/agent/src/agent.tsindex 9c7960bc4a..1dc7616532 100644--- a/packages/agent/src/agent.ts+++ b/packages/agent/src/agent.ts@@ -3,6 +3,7 @@ import {type ImageContent,type Message,type Model,+ type ServiceTier,type SimpleStreamOptions,streamSimple,type TextContent,@@ -24,6 +25,7 @@ import type {GetContinuationMessagesContext,ShouldStopAfterTurnContext,StreamFn,+ ThinkingLevel,ToolExecutionMode,} from "./types.js";@@ -169,11 +171,20 @@ type ActiveRun = {promise: Promise<void>;resolve: () => void;abortController: AbortController;+ /** Model serving the run when it started; failures stay attributed to it. */+ model: Model<any>;};/** Why {@link Agent.continue} refused to start a continuation. */export type AgentContinueErrorCode = "busy" | "nothing-to-continue";+/** Model that serves the LLM requests of a routed run, with per-request fields clamped for it. */+export interface AgentModelOverride {+ model: Model<any>;+ thinkingLevel: ThinkingLevel;+ serviceTier: ServiceTier;+}+/** Typed precondition failure from {@link Agent.continue}, so callers classify by code instead of message text. */export class AgentContinueError extends Error {constructor(@@ -211,6 +222,16 @@ export class Agent {context: GetContinuationMessagesContext,signal?: AbortSignal,) => Promise<AgentMessage[]>;+ /**+ * Per-run model override. When set, every LLM request for prompt and+ * continuation runs uses this model (with its own thinking level and+ * service tier), while `state.model` keeps identifying the session model+ * for UI and persistence. The owner sets it right before starting a+ * routed run and re-evaluates it before the next one; retries and+ * post-compaction continuations re-read it, so they stay on the model+ * that served the routed turn.+ */+ modelOverride?: AgentModelOverride;private activeRun?: ActiveRun;public sessionId?: string;public thinkingBudgets?: ThinkingBudgets;@@ -458,10 +479,11 @@ export class Agent {private createLoopConfig(options: { skipInitialSteeringPoll?: boolean } = {}): AgentLoopConfig {let skipInitialSteeringPoll = options.skipInitialSteeringPoll === true;+ const override = this.modelOverride;return {- model: this._state.model,- reasoning: this._state.thinkingLevel,- serviceTier: this._state.serviceTier,+ model: override?.model ?? this._state.model,+ reasoning: override?.thinkingLevel ?? this._state.thinkingLevel,+ serviceTier: override?.serviceTier ?? this._state.serviceTier,sessionId: this.sessionId,onPayload: this.onPayload,onResponse: this.onResponse,@@ -498,7 +520,12 @@ export class Agent {const promise = new Promise<void>((resolve) => {resolvePromise = resolve;});- this.activeRun = { promise, resolve: resolvePromise, abortController };+ this.activeRun = {+ promise,+ resolve: resolvePromise,+ abortController,+ model: this.modelOverride?.model ?? this._state.model,+ };this._state.isStreaming = true;this._state.streamingMessage = undefined;@@ -514,12 +541,16 @@ export class Agent {}private async handleRunFailure(error: unknown, aborted: boolean): Promise<void> {+ // The model that served the run when it started tags its failures: a+ // routed run keeps the override, and even a mid-run override change+ // cannot re-attribute an in-flight request to a model that never saw it.+ const runModel = this.activeRun?.model ?? this.modelOverride?.model ?? this._state.model;const failureMessage = {role: "assistant",content: [{ type: "text", text: "" }],- api: this._state.model.api,- provider: this._state.model.provider,- model: this._state.model.id,+ api: runModel.api,+ provider: runModel.provider,+ model: runModel.id,usage: EMPTY_USAGE,stopReason: aborted ? "aborted" : "error",errorMessage: error instanceof Error ? error.message : String(error),diff --git a/packages/coding-agent/.changes/image-model-override.md b/packages/coding-agent/.changes/image-model-override.mdnew file mode 100644index 0000000000..371909ecec--- /dev/null+++ b/packages/coding-agent/.changes/image-model-override.md@@ -0,0 +1,2 @@+- Added an `imageModel` setting that routes image-attaching turns to an image-capable model when the session or subagent model is text-only.+- Image turns on a text-only session model now fail with an actionable error naming `imageModel` instead of silently dropping the images when the setting is unset or unusable.diff --git a/packages/coding-agent/docs/settings.md b/packages/coding-agent/docs/settings.mdindex 2a71b6f01d..a0308dc836 100644--- a/packages/coding-agent/docs/settings.md+++ b/packages/coding-agent/docs/settings.md@@ -18,6 +18,7 @@ Edit directly or use `/settings` for common options.| `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) || `defaultModel` | string | - | Default model ID || `subagentDefaultModel` | string | - | Model selector (`"provider/id"`) used when `rlm.spawn` does not pin a model; unset inherits the parent model |+| `imageModel` | string | none | Model (`"provider/model-id"` or a bare id) that serves turns attaching images when the session model does not accept image input || `defaultThinkingLevel` | string | `"medium"` | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` || `thinkingBudgets` | object | - | Custom token budgets per thinking level |@@ -25,6 +26,19 @@ Edit directly or use `/settings` for common options.When `defaultThinkingLevel` is unset, new sessions start at `"medium"` reasoning, clamped to the levels each model supports.+`imageModel` routes image turns on text-only session or subagent models. When a+turn attaches images and the selected model has no image input, that turn (and+its retries and post-compaction continuations) is served by the configured+image-capable model instead; the session model selection stays unchanged, and+the routed assistant messages record the model that served them. Later+image-free turns return to the session model, where images already in the+transcript appear as "(image omitted: model does not support images)"+placeholders. With no `imageModel` set (default), image turns on a text-only+model fail with an actionable error instead of silently dropping the images:+switch the session model with `/model` or configure `imageModel`. Set+`images.blockImages: true` to drop images everywhere instead of routing or+refusing.+### Autonomous Runs| Setting | Type | Default | Description |diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.tsindex be9a0d1a9c..a8ea514d9b 100644--- a/packages/coding-agent/src/core/agent-session.ts+++ b/packages/coding-agent/src/core/agent-session.ts@@ -9,6 +9,7 @@ import {AgentContinueError,type AgentEvent,type AgentMessage,+ type AgentModelOverride,type AgentState,type AgentTool,type GetContinuationMessagesContext,@@ -171,6 +172,7 @@ import {validateGoalBudget,validateGoalObjective,} from "./goals.js";+import { resolveImageModelOverride } from "./image-model-routing.js";import type { HostRequestHandlers, KernelSentAgentMessage } from "./kernel/index.js";import { type RestoreResult, snapshotPathIn } from "./kernel/state-snapshot.js";import type { AcpMcpServerConfig } from "./mcp/acp-mcp-types.js";@@ -841,6 +843,15 @@ function normalizeMessageContent(content: string | (TextContent | ImageContent)[return { text, ...(images.length > 0 ? { images } : {}) };}+/**+ * Whether a delivered message attaches image content. Used to route+ * image-carrying turns off session models without image input.+ */+function messageCarriesImages(message: QueuedAgentMessage | AgentMessage): boolean {+ const content = (message as { content?: unknown }).content;+ return Array.isArray(content) && content.some((part: { type?: string }) => part?.type === "image");+}+function queuedAgentMessagePreview(action: QueuedSessionAction): string {const payload = action.payload;if (payload.kind === "session_command") return payload.text;@@ -1473,6 +1484,8 @@ export class AgentSession {primary: Model<any>;thinkingLevel: ThinkingLevel;serviceTier: ServiceTier;+ /** Image-model routing active when the backup took over; restored on return. */+ routedOverride?: AgentModelOverride;}| undefined = undefined;private _agentMessageClearEpoch = 0;@@ -2514,6 +2527,87 @@ export class AgentSession {}}+ /**+ * Routing decision for a dispatched turn batch: when any delivered message+ * attaches images and the session model has no image input, serve the turn+ * on the user-configured imageModel (settings.imageModel) instead.+ *+ * The override is stored on the agent, so retries and post-compaction+ * continuations of the routed turn keep serving it; the next dispatch+ * re-evaluates it, so later image-free turns return to the session model.+ * A missing session model is reported by _validateCanStartAgentRun.+ */+ private _imageModelOverrideForTurns(+ turns: SessionAction<PreparedTurnPayload>[],+ extraMessages: AgentMessage[] = [],+ ): AgentModelOverride | undefined {+ const sessionModel = this.model;+ if (!sessionModel) return undefined;+ const carriesImages =+ extraMessages.some((message) => messageCarriesImages(message)) ||+ turns.some((action) => action.payload.records.some((record) => messageCarriesImages(record.message)));+ if (!carriesImages) return undefined;+ return resolveImageModelOverride({+ sessionModel,+ thinkingLevel: this.thinkingLevel,+ serviceTier: this.serviceTier,+ imageModelReference: this.settingsManager.getImageModel(),+ availableModels: this._modelRegistry.getAvailable(),+ hasConfiguredAuth: (model) => this._modelRegistry.hasConfiguredAuth(model),+ blockImages: this.settingsManager.getBlockImages(),+ });+ }++ /**+ * Model serving the current run: the routed image model while a routed+ * turn (or its retries/continuations) is active, the session model+ * otherwise. Compaction decisions compare context against the model that+ * actually serves the requests, so a routed run uses the routed model's+ * context window and accepts its assistant messages as its own.+ */+ private _runModel(): Model<any> | undefined {+ return this.agent.modelOverride?.model ?? this.model;+ }++ /**+ * Whether a dispatched turn is still in flight: streaming, retrying with+ * backoff, compacting before a continuation, an overflow recovery or+ * provider wait still settling, or a post-compaction continuation that+ * has been scheduled but not yet dispatched. Model selection during any+ * of these must not tear down a routed run's override, or the run's+ * retries, continuations, and failure attribution would leave the+ * image-capable model mid-turn.+ */+ private get _hasActiveTurnLifecycle(): boolean {+ return (+ this.isStreaming ||+ this.isRetrying ||+ this.isCompacting ||+ this._postCompactionContinuationScheduled ||+ // Covers the whole submission-to-settled window: preflight (before the+ // action enqueues), the queued turn, and any in-flight run - without+ // latching on stale overflow-recovery state.+ this._promptSubmissionInFlight ||+ this._hasPendingOrRunningTurnAction+ );+ }++ private get _hasPendingOrRunningTurnAction(): boolean {+ return this._actionStore.unfinishedActions().some((action) => action.payload.kind === "turn");+ }++ /**+ * An explicit selection wins over image-model routing still lingering from+ * the last dispatched turn, but not over the model already serving an+ * active run. Cycling or switching mid-stream keeps the routed override+ * until the turn settles; the next dispatch re-evaluates the routing+ * against the new selection.+ */+ private _clearModelOverrideWhenIdle(): void {+ if (this._hasActiveTurnLifecycle) return;+ this.agent.modelOverride = undefined;+ }+/*** Goals are pursued through the kernel goal skill, so the only tool the* model needs is ipython. Force-activate it (including into a live@@ -3495,7 +3589,7 @@ export class AgentSession {const settings = this.settingsManager.getCompactionSettings();if (!settings.enabled) return false;- const contextWindow = this.model?.contextWindow ?? 0;+ const contextWindow = this._runModel()?.contextWindow ?? 0;const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());const compactionTimestamp = compactionEntry ? new Date(compactionEntry.timestamp).getTime() : undefined;if (compactionTimestamp !== undefined && context.message.timestamp <= compactionTimestamp) {@@ -5683,7 +5777,21 @@ export class AgentSession {}}+ private _promptSubmissionInFlight = false;+private async _prompt(text: string, options?: InternalPromptOptions): Promise<void> {+ // Synchronous preflight guard: from submission until the prompt promise+ // settles, a model switch must not tear down a routed turn's override+ // (the routing decision for this turn's images may already be made).+ this._promptSubmissionInFlight = true;+ try {+ return await this._promptInner(text, options);+ } finally {+ this._promptSubmissionInFlight = false;+ }+ }++ private async _promptInner(text: string, options?: InternalPromptOptions): Promise<void> {const resumeSuspendedInput = options?.resumeIfIdle !== false;if (!this.isStreaming) {if (resumeSuspendedInput) this._resumeSessionInputAdmission();@@ -6872,6 +6980,12 @@ export class AgentSession {if (this._isSessionInputHandoffDeferred(epoch)) {throw new DeferredSessionInputError("Session input paused before preflight");}+ // Re-evaluate image routing for this batch before any pre-commit read of+ // the serving model: pre-turn compaction must not follow the previous+ // turn's override. Retries and post-compaction continuations of a routed+ // turn re-read the override, so they keep serving it; the next dispatch+ // overwrites it with its fresh decision.+ this.agent.modelOverride = this._imageModelOverrideForTurns(activeTurns());},prepare: async () => {if (executionPolicy.nextTurnContextTiming === "preparation") {@@ -6969,6 +7083,10 @@ export class AgentSession {for (const action of turns) transitionSessionAction(action, { state: "committing" });this._notifySessionInputCheckpointChange();this._emitQueueUpdate();+ // Re-evaluate image routing for the exact message set being sent:+ // before_agent_start injections land after the earlier per-turn+ // decision and may carry images the session model cannot serve.+ this.agent.modelOverride = this._imageModelOverrideForTurns(turns, preparedMessages);return turns.some((action) => action.suppressAutonomousContinuation)? this._runWithAutonomousContinuationSuppressed(() => this.agent.prompt(preparedMessages)): this.agent.prompt(preparedMessages);@@ -8062,6 +8180,7 @@ export class AgentSession {const thinkingLevel = this._getThinkingLevelForModelSwitch();const serviceTier = this._getServiceTierForModelSwitch();this.agent.state.model = model;+ this._clearModelOverrideWhenIdle();this.sessionManager.appendModelChange(model.provider, model.id);this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);@@ -8129,6 +8248,7 @@ export class AgentSession {const serviceTier = this._getServiceTierForModelSwitch();this.agent.state.model = next.model;+ this._clearModelOverrideWhenIdle();this.sessionManager.appendModelChange(next.model.provider, next.model.id);this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);@@ -8168,6 +8288,7 @@ export class AgentSession {const thinkingLevel = this._getThinkingLevelForModelSwitch();const serviceTier = this._getServiceTierForModelSwitch();this.agent.state.model = nextModel;+ this._clearModelOverrideWhenIdle();this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);@@ -9750,14 +9871,18 @@ export class AgentSession {}const settings = this.settingsManager.getCompactionSettings();- const contextWindow = this.model?.contextWindow ?? 0;+ const runModel = this._runModel();+ const contextWindow = runModel?.contextWindow ?? 0;// Skip overflow check if the message came from a different model.// This handles the case where user switched from a smaller-context model (e.g. opus)// to a larger-context model (e.g. codex) - the overflow error from the old model- // shouldn't trigger compaction for the new model.+ // shouldn't trigger compaction for the new model. A routed image-model turn keeps+ // its override, so its overflow errors recover like the session model's own.const sameModel =- this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;+ runModel !== undefined &&+ assistantMessage.provider === runModel.provider &&+ assistantMessage.model === runModel.id;// Skip overflow/threshold checks if this assistant message is older than the// latest compaction boundary. This prevents a stale pre-compaction usage/error@@ -12549,7 +12674,7 @@ export class AgentSession {private _isRetryableError(message: AssistantMessage): boolean {if (message.stopReason !== "error" || !message.errorMessage) return false;- const contextWindow = this.model?.contextWindow ?? 0;+ const contextWindow = this._runModel()?.contextWindow ?? 0;if (isContextOverflow(message, contextWindow)) return false;if (this._isFauxProviderQueueExhausted(message)) {@@ -12695,10 +12820,13 @@ export class AgentSession {// User-defined backup model (settings.providerBackupModel, default none):// route the failed turn to the backup instead of waiting while the- // primary is quota-blocked or its provider is unavailable.+ // primary is quota-blocked or its provider is unavailable. The guard+ // compares against the model serving the run, so a backup equal to a+ // routed turn's image model is recognized as the duplicate it is instead+ // of reporting a no-op backup switch with a zero-delay retry.if (waitClass !== "permanent") {const backupModel = this._resolveBackupModel();- if (backupModel && !modelsAreEqual(this.model, backupModel)) {+ if (backupModel && !modelsAreEqual(this._runModel(), backupModel)) {return this._handleBackupModelRetry(message, options, backupModel);}}@@ -12853,7 +12981,10 @@ export class AgentSession {/*** Resolve the user-configured backup model reference against the available* models. Unknown or unauthenticated references resolve to undefined: the- * wait loop runs instead, and never surprises the user with a switch.+ * wait loop runs instead, and never surprises the user with a switch. A+ * run routed for images also rejects a text-only backup the same way: the+ * retry then stays on the routed model instead of serving the turn's+ * images to a model that would silently downgrade them to placeholders.*/private _resolveBackupModel(): Model<any> | undefined {const reference = this.settingsManager.getProviderBackupModel();@@ -12862,6 +12993,9 @@ export class AgentSession {if (!backupModel || !this._modelRegistry.hasConfiguredAuth(backupModel)) {return undefined;}+ if (this.agent.modelOverride && !backupModel.input.includes("image")) {+ return undefined;+ }return backupModel;}@@ -12879,11 +13013,22 @@ export class AgentSession {const previousModel = this.agent.state.model;const previousThinkingLevel = this.agent.state.thinkingLevel;const previousServiceTier = this.agent.state.serviceTier;+ // A routed image-model turn keeps serving on the override, so the backup+ // must take the override too or the retry would silently return to the+ // routed model while reporting the backup.+ const routedOverride = this.agent.modelOverride;this.agent.state.model = backupModel;// Clamp per-request fields to what the backup supports; all of them are// restored when the turn returns to the primary.this.agent.state.thinkingLevel = clampThinkingLevel(backupModel, previousThinkingLevel) as ThinkingLevel;this._clampServiceTierForModel();+ if (routedOverride) {+ this.agent.modelOverride = {+ model: backupModel,+ thinkingLevel: this.agent.state.thinkingLevel,+ serviceTier: this.agent.state.serviceTier,+ };+ }// Session-log the switch so primary->backup->primary transitions stay debuggable.this.sessionManager.appendModelChange(backupModel.provider, backupModel.id);this._backupModel = {@@ -12891,6 +13036,7 @@ export class AgentSession {primary: previousModel,thinkingLevel: previousThinkingLevel,serviceTier: previousServiceTier,+ routedOverride,};this._retryAttempt++;this._providerWait = undefined;@@ -12977,6 +13123,7 @@ export class AgentSession {if (!backup || !modelsAreEqual(this.model, backup.backup)) return undefined;this.agent.state.model = backup.primary;this.agent.state.thinkingLevel = backup.thinkingLevel;+ this.agent.modelOverride = backup.routedOverride;// Restore the saved effective tier: reclamping from the current state// would keep the tier the backup clamped it to.this._clampServiceTierForModel(backup.serviceTier);diff --git a/packages/coding-agent/src/core/auth-guidance.ts b/packages/coding-agent/src/core/auth-guidance.tsindex 881f3d8566..128b6e5a5d 100644--- a/packages/coding-agent/src/core/auth-guidance.ts+++ b/packages/coding-agent/src/core/auth-guidance.ts@@ -44,6 +44,31 @@ export function formatAuthenticationFailedMessage(provider: string): string {);}+/**+ * Image-attaching turns on a model without image input must not silently drop+ * the images: name the session model, the setting, and the alternatives so the+ * user can act immediately.+ */+export function formatImageModelRequiredMessage(sessionModelId: string): string {+ return [+ `This turn attaches images, but the selected model (${sessionModelId}) does not accept image input.`,+ "",+ "Pick one:",+ `- Switch the session model to an image-capable one with /model, or`,+ `- Set imageModel in settings.json to an image-capable model ("provider/model-id" or a bare id), e.g. "anthropic/claude-sonnet-4-5"`,+ "",+ "Then resend the message. Without it the request would silently drop the images.",+ ].join("\n");+}++export function formatImageModelUnusableMessage(reference: string): string {+ return [+ `imageModel "${reference}" could not be resolved to an available, image-capable, authenticated model.`,+ "",+ "Fix the imageModel setting (settings.json) or authenticate the provider, then resend the message.",+ ].join("\n");+}+export function isLikelyAuthenticationError(message: string): boolean {return (/\b(401|403)\b/i.test(message) ||diff --git a/packages/coding-agent/src/core/image-model-routing.ts b/packages/coding-agent/src/core/image-model-routing.tsnew file mode 100644index 0000000000..64cf133d31--- /dev/null+++ b/packages/coding-agent/src/core/image-model-routing.ts@@ -0,0 +1,50 @@+/**+ * Routing for image-attaching turns on session models without image input.+ */++import type { AgentModelOverride, ThinkingLevel } from "@earendil-works/pi-agent-core";+import { type Api, clampThinkingLevel, type Model, type ServiceTier, supportsFastMode } from "@earendil-works/pi-ai";+import { formatImageModelRequiredMessage, formatImageModelUnusableMessage } from "./auth-guidance.js";+import { findExactModelReferenceMatch } from "./model-resolver.js";++/** Session state the routing decision needs when a turn batch commits. */+export interface ImageModelRoutingInputs {+ /** Model selected for the session; the routed turns carry images it cannot see. */+ sessionModel: Model<any>;+ /** Session thinking level; clamped to what the routed model supports. */+ thinkingLevel: ThinkingLevel;+ /** Session service tier; clamped to what the routed model supports. */+ serviceTier: ServiceTier;+ /** settings.imageModel reference ("provider/model-id" or a bare id). */+ imageModelReference: string | undefined;+ /** Registry models the reference may resolve to. */+ availableModels: Model<Api>[];+ /** Whether the registry has working credentials for a model. */+ hasConfiguredAuth: (model: Model<any>) => boolean;+ /** settings.images.blockImages: no image reaches any provider, so no turn routes. */+ blockImages: boolean;+}++/**+ * Resolve the model that serves turns attaching images: the configured image+ * model when the session model has no image input, undefined when the session+ * model serves them natively. Throws an actionable error when the turn cannot+ * be served honestly: a text-only session model would otherwise downgrade the+ * images to an "(image omitted)" placeholder.+ */+export function resolveImageModelOverride(inputs: ImageModelRoutingInputs): AgentModelOverride | undefined {+ const { sessionModel } = inputs;+ if (sessionModel.input.includes("image") || inputs.blockImages) return undefined;+ if (!inputs.imageModelReference) {+ throw new Error(formatImageModelRequiredMessage(`${sessionModel.provider}/${sessionModel.id}`));+ }+ const imageModel = findExactModelReferenceMatch(inputs.imageModelReference, inputs.availableModels);+ if (!imageModel || !imageModel.input.includes("image") || !inputs.hasConfiguredAuth(imageModel)) {+ throw new Error(formatImageModelUnusableMessage(inputs.imageModelReference));+ }+ return {+ model: imageModel,+ thinkingLevel: clampThinkingLevel(imageModel, inputs.thinkingLevel) as ThinkingLevel,+ serviceTier: inputs.serviceTier === "priority" && !supportsFastMode(imageModel) ? "default" : inputs.serviceTier,+ };+}diff --git a/packages/coding-agent/src/core/settings-manager.ts b/packages/coding-agent/src/core/settings-manager.tsindex 9e9733940e..e2aa28f77d 100644--- a/packages/coding-agent/src/core/settings-manager.ts+++ b/packages/coding-agent/src/core/settings-manager.ts@@ -221,6 +221,13 @@ export interface Settings {* Default: none - requests never silently switch models.*/providerBackupModel?: string;+ /**+ * Model ("provider/model-id" or a bare model id) that serves turns+ * attaching images when the session model does not accept image input.+ * Default: none - image turns on a text-only model fail with a+ * configuration hint instead of silently dropping the images.+ */+ imageModel?: string;autonomous?: AutonomousSettings;shellPath?: string; // Custom shell path (e.g., for Cygwin users on Windows)quietStartup?: boolean;@@ -1098,6 +1105,14 @@ export class SettingsManager {return reference.trim() ? reference.trim() : undefined;}+ getImageModel(): string | undefined {+ // Same shape as providerBackupModel: malformed values behave as unset+ // and the image-turn refusal names the setting instead.+ const reference = this.settings.imageModel;+ if (typeof reference !== "string") return undefined;+ return reference.trim() ? reference.trim() : undefined;+ }+getShellPath(): string | undefined {return this.settings.shellPath;}diff --git a/packages/coding-agent/src/modes/interactive/interactive-mode.ts b/packages/coding-agent/src/modes/interactive/interactive-mode.tsindex 788ade0d31..370941241c 100644--- a/packages/coding-agent/src/modes/interactive/interactive-mode.ts+++ b/packages/coding-agent/src/modes/interactive/interactive-mode.ts@@ -4817,8 +4817,15 @@ export class InteractiveMode {this.ui.requestRender();const model = this.getCurrentModel();- if (model && !model.input.includes("image")) {- this.showStatus("Current model does not support images; the attachment will be omitted.");+ if (+ model &&+ !model.input.includes("image") &&+ !this.settingsManager.getImageModel() &&+ !this.settingsManager.getBlockImages()+ ) {+ this.showStatus(+ "Current model does not support images; set imageModel in settings.json or the turn will fail with setup guidance.",+ );}} catch {// Silently ignore clipboard errors (may not have permission, etc.)@@ -4871,15 +4878,11 @@ export class InteractiveMode {* dequeue) brings it back. Marker presence in the sent text is the single* source of truth.*- * Resolved against the current model: if it has no image input, attachments- * are dropped here (matching the paste-time hint) rather than sent and- * downgraded downstream.+ * Attachments always reach the session: a text-only session model is either+ * routed to settings.imageModel at dispatch or the turn fails there with an+ * actionable setup error, so nothing is silently downgraded downstream.*/private collectImagesFor(text: string): ImageContent[] | undefined {- const model = this.getCurrentModel();- if (model && !model.input.includes("image")) {- return undefined;- }const images = collectMarkedImages(this.pastedImages, text);return images.length > 0 ? images : undefined;}diff --git a/packages/coding-agent/test/image-model-override.test.ts b/packages/coding-agent/test/image-model-override.test.tsnew file mode 100644index 0000000000..da836dd277--- /dev/null+++ b/packages/coding-agent/test/image-model-override.test.ts@@ -0,0 +1,108 @@+/** Image-turn routing: `settings.imageModel` serves image turns on text-only session models. */++import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { Agent } from "@earendil-works/pi-agent-core";+import type { AssistantMessage, AssistantMessageEvent } from "@earendil-works/pi-ai";+import { EventStream, getModel, type ImageContent } from "@earendil-works/pi-ai";+import { expect, it } from "vitest";+import { AgentSession } from "../src/core/agent-session.js";+import { AuthStorage } from "../src/core/auth-storage.js";+import { ModelRegistry } from "../src/core/model-registry.js";+import { SessionManager } from "../src/core/session-manager.js";+import { SettingsManager } from "../src/core/settings-manager.js";+import { assistantMsg, createTestResourceLoader } from "./utilities.js";++const IMAGE: ImageContent = { type: "image", mimeType: "image/png", data: "aGk=" };+const SET = { imageModel: "claude-haiku-4-5" };+const SET_BLOCKED = { imageModel: "claude-haiku-4-5", images: { blockImages: true } };+const SET_UNUSABLE = { imageModel: "openai/gpt-5.4" };+const SET_TEXTONLY = { imageModel: "deepseek/deepseek-v4-pro" };+const RETRY = { enabled: true, maxRetries: 3, baseDelayMs: 1 };+const SET_BACKUP_TEXT = { ...SET, providerBackupModel: "deepseek/deepseek-v4-pro", retry: RETRY };+const SET_BACKUP_VISION = { ...SET, providerBackupModel: "claude-opus-4-7", retry: RETRY };+const SET_BACKUP_SAME = { ...SET, providerBackupModel: "claude-haiku-4-5", retry: RETRY };+const SERVED_IMAGE = ["claude-haiku-4-5", "claude-haiku-4-5"];+const SERVED_BACKUP = ["claude-haiku-4-5", "claude-opus-4-7"];+const transientFailure = (): AssistantMessage => ({+ ...assistantMsg(""),+ stopReason: "error",+ errorMessage: "overloaded_error",+ diagnostics: [{ type: "provider_stream_failure", timestamp: Date.now(), details: { kind: "overloaded" } }],+});++// [name, settings, vision session model, attaches images, served model ids, rejection]+it.each([+ ["routes image turns to imageModel", SET, false, true, "claude-haiku-4-5", undefined],+ ["vision session model serves image turns", SET, true, true, "claude-opus-4-7", undefined],+ ["session model serves image-free turns", SET, false, false, "claude-opus-4-7-text-only", undefined],+ ["session model serves blocked-image turns", SET_BLOCKED, false, true, "claude-opus-4-7-text-only", undefined],+ ["refuses image turns without imageModel", {}, false, true, undefined, /does not accept image input/],+ ["refuses an unusable imageModel", SET_UNUSABLE, false, true, undefined, /could not be resolved/],+ ["refuses a text-only imageModel", SET_TEXTONLY, false, true, undefined, /could not be resolved/],+ ["skips a text-only backup for image turns", SET_BACKUP_TEXT, false, true, SERVED_IMAGE, undefined],+ ["image-capable backup serves the retry", SET_BACKUP_VISION, false, true, SERVED_BACKUP, undefined],+ ["duplicate backup skips the no-op switch", SET_BACKUP_SAME, false, true, SERVED_IMAGE, undefined],+ ["cycling mid-stream keeps routing", SET, false, true, SERVED_IMAGE, undefined, undefined, true],+ ["cycling clears the routed override", SET, false, true, "claude-haiku-4-5", undefined, true],+])("%s", async (_name, settings, vision, images, served, reject, cycleAfter?: boolean, cycleMidStream?: boolean) => {+ const dir = mkdtempSync(join(tmpdir(), "pi-image-model-"));+ writeFileSync(join(dir, "settings.json"), JSON.stringify(settings));+ const base = getModel("anthropic", "claude-opus-4-7")!;+ const sessionModel = (vision ? base : { ...base, id: "claude-opus-4-7-text-only", input: ["text"] }) as typeof base;+ const servedIds: string[] = [];+ let cycleMidStreamHook: (() => void) | undefined;+ const agent = new Agent({+ getApiKey: () => "test-key",+ initialState: { model: sessionModel, systemPrompt: "Test", tools: [] },+ streamFn: (model) => {+ servedIds.push(model.id);+ if (cycleMidStream && servedIds.length === 1) cycleMidStreamHook?.();+ const stream = new EventStream<AssistantMessageEvent, AssistantMessage>(+ (e) => e.type === "done",+ (e: any) => e.message,+ );+ // Rows listing a served sequence inject the transient failure that+ // triggers the backup retry; the retry serves the next entry.+ const message = Array.isArray(served) && servedIds.length === 1 ? transientFailure() : assistantMsg("ok");+ stream.push({ type: "done", reason: "stop", message });+ return stream;+ },+ });+ const auth = AuthStorage.create(join(dir, "auth.json"));+ auth.setRuntimeApiKey("anthropic", "test-key");+ auth.setRuntimeApiKey("deepseek", "test-key");+ const session = new AgentSession({+ agent,+ sessionManager: SessionManager.inMemory(),+ settingsManager: SettingsManager.create(dir, dir),+ cwd: dir,+ modelRegistry: ModelRegistry.create(auth, dir),+ resourceLoader: createTestResourceLoader(),+ });+ cycleMidStreamHook = () => void session.cycleModel("forward", { waitForExtensions: false });+ const backupSwitches: string[] = [];+ session.subscribe((event) => {+ if (event.type === "auto_retry_start" && event.reason === "backup") backupSwitches.push(event.reason);+ });+ try {+ const prompt = session.prompt("describe", images ? { images: [IMAGE] } : undefined);+ if (reject) return await expect(prompt).rejects.toThrow(reject);+ await prompt;+ expect(servedIds).toEqual(Array.isArray(served) ? served : [served]);+ expect(backupSwitches).toEqual(Array.isArray(served) && served[1] !== served[0] ? ["backup"] : []);+ if (cycleMidStream) expect(session.model?.id).not.toBe(sessionModel.id);+ else expect(session.model?.id).toBe(sessionModel.id);+ if (!cycleAfter) return;+ // The routed turn leaves its override behind; cycling must clear it so+ // the selection wins over later continues, retries, and compaction.+ expect(session.agent.modelOverride?.model.id).toBe(served);+ await session.cycleModel("forward", { waitForExtensions: false });+ expect(session.agent.modelOverride).toBeUndefined();+ expect(session.model?.id).not.toBe(sessionModel.id);+ } finally {+ session.dispose();+ rmSync(dir, { recursive: true, force: true });+ }+});