Skip to content

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.md
new file mode 100644
index 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.ts
index 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.md
new file mode 100644
index 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.md
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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 });
+ }
+});