cartethyia 2.7.4 → 2.7.5

package/src/transport/request/preparer.ts

@@ -1,12 +1,14 @@
 import { GatewayError } from "../../protocol/gateway-error";
-import type { CanonicalRequest, ServiceKind } from "../../protocol/canonical-model";
+import type { CanonicalRequest, CanonicalMessage, ServiceKind, ContentPart } from "../../protocol/canonical-model";
 import { toolResultParts } from "../../protocol/canonical-model";
 import type { ApiKeyAdmissionService } from "../../security/admission/service";
+import type { VisionHandoffCall, VisionHandoffResult } from "../vision-handoff";
+import { isImageOrPlaceholderPart, lastImageCarryingUserTurnIndex } from "../vision-handoff";
 import type { CallerIdentity } from "../../security/access-control";
 import type { RouteCandidate as RouteCandidate, InMemoryRouteSnapshotService, RoutePlan } from "../routing/route-model";
 import type { RouteContinuationAffinity } from "../routing/route-model";
 import { resolveAliasTarget, type RoutingEngine } from "../routing/router";
-import { projectForRoute, routeCapabilitiesFor } from "../../protocol/translation/capabilities";
+import { projectForRoute, routeCapabilitiesFor, deriveRequiredCapabilities } from "../../protocol/translation/capabilities";
 import type { RequiredCapability } from "../../protocol/translation/capabilities";
 import { isModelAllowed, type ResolvedApiKey } from "../../security/api-key-auth";
 import { allowsCliToolMappings } from "../../security/cli-client-fingerprint";
@@ -36,6 +38,128 @@ function requestNeedsToolRepair(request: CanonicalRequest): boolean {
   return false;
 }
 
+/**
+ * The text that replaces an image part after a successful vision handoff.
+ * The description is wrapped so the receiving model understands it is an
+ * automated description of an image the user attached — not prose the user
+ * typed — which is what made it answer as if it had no image at all.
+ */
+function visionDescriptionText(description: string): string {
+  return `[The user attached an image. A vision model described it for you: ${description}]`;
+}
+
+/**
+ * Replaces every image part (or its `[image]` degradation placeholder) in the
+ * request with a single text part carrying the vision-handoff description.
+ * Returns `null` when the request has neither image parts nor placeholders.
+ * Only user-message parts are replaced; system/tool-result images are left
+ * untouched.
+ */
+function replaceImagePartsWithText(
+  request: CanonicalRequest,
+  description: string,
+): CanonicalRequest | null {
+  const activeIndex = lastImageCarryingUserTurnIndex(request);
+  const strip = (parts: readonly ContentPart[]): readonly ContentPart[] => {
+    const hasImage = parts.some(isImageOrPlaceholderPart);
+    if (!hasImage) return parts;
+    return parts.flatMap((part): ContentPart[] =>
+      isImageOrPlaceholderPart(part)
+        ? [{ kind: "text", text: visionDescriptionText(description) }]
+        : [part],
+    );
+  };
+  const nextMessages = request.messages.map((message, i) => {
+    if (message.role !== "user") return message;
+    // The active turn (the one the handoff actually described) gets the
+    // description; older image-carrying history turns are dropped — they are
+    // not part of the current context the vision model saw, and leaving a
+    // stale image on a text-only route would risk an upstream rejection.
+    if (i === activeIndex) {
+      return { ...message, content: strip(message.content) };
+    }
+    const hasImage = message.content.some(isImageOrPlaceholderPart);
+    if (!hasImage) return message;
+    return { ...message, content: message.content.filter((part) => !isImageOrPlaceholderPart(part)) };
+  });
+  const unchangedMessages = nextMessages.every(
+    (message, i) => message === request.messages[i],
+  );
+  if (unchangedMessages) return null;
+  return { ...request, messages: nextMessages };
+}
+
+/**
+ * When a handoff request is a giant session (opencode CLI sessions routinely
+ * carry hundreds of tool-result turns), the text-only request that goes to the
+ * main model is still enormous: the handoff only replaced the image parts, so
+ * the full history — including 700+ tool transcripts — is forwarded verbatim.
+ * Upstreams reject or reset such payloads (502/ECONNRESET), which is the
+ * "broken on large sessions" report: a small fresh chat works, a session with
+ * a large context dies even though the handoff itself is just a description.
+ *
+ * The handoff describes *an image the user just attached* — it does not need
+ * the rest of the session. For a giant request this pass returns only the
+ * system prompt (when present) plus the active image-carrying turn; the whole
+ * history is dropped so the payload stays small and upstreams do not reset it.
+ * Small requests (< the thresholds) pass through untouched.
+ */
+export function condenseHandoffRequest(request: CanonicalRequest): CanonicalRequest {
+  const activeIndex = lastImageCarryingUserTurnIndex(request);
+  if (activeIndex < 0) return request;
+
+  const totalMessages = request.messages.length;
+  let totalChars = 0;
+  for (const message of request.messages) totalChars += messageCharSize(message);
+  if (totalMessages <= HANDOFF_CONDENSE_MESSAGE_THRESHOLD && totalChars <= HANDOFF_CONDENSE_CHARS_THRESHOLD) {
+    return request;
+  }
+
+  const kept: CanonicalMessage[] = [];
+  for (let i = 0; i < request.messages.length; i += 1) {
+    const message = request.messages[i]!;
+    if (message.role === "system") {
+      kept.push(message);
+      continue;
+    }
+    if (i === activeIndex) {
+      kept.push(message);
+      // Anything after the active turn stays after it (rare, but preserved).
+      kept.push(...request.messages.slice(activeIndex + 1));
+      break;
+    }
+  }
+  // Never return a request that lost the very turn we are answering.
+  if (!kept.includes(request.messages[activeIndex]!)) return request;
+  return { ...request, messages: kept };
+}
+
+const HANDOFF_CONDENSE_MESSAGE_THRESHOLD = 100;
+const HANDOFF_CONDENSE_CHARS_THRESHOLD = 200_000;
+
+function messageCharSize(message: CanonicalMessage): number {
+  let size = 0;
+  for (const part of message.content) {
+    if (part.kind === "text" || part.kind === "refusal") {
+      size += part.text.length;
+    } else if (part.kind === "toolCall") {
+      size += part.name.length;
+      try {
+        size += JSON.stringify(part.arguments).length;
+      } catch {
+        size += 64;
+      }
+    } else {
+      try {
+        size += JSON.stringify((part as { data?: unknown }).data ?? "").length;
+      } catch {
+        size += 64;
+      }
+    }
+  }
+  return size;
+}
+
 /** Prefix of a provider-continuation tool-call id the gateway itself minted. */
 const CURSOR_CALL_PREFIX = "call_cursor_";
 
@@ -46,7 +170,7 @@ const CURSOR_CALL_PREFIX = "call_cursor_";
  * Any other id belongs to a conversation the client owns; it is not a
  * continuation and must not influence routing.
  */
-export function continuationCallIds(request: CanonicalRequest): readonly string[] {
+function continuationCallIds(request: CanonicalRequest): readonly string[] {
   const ids: string[] = [];
   for (const message of request.messages) {
     if (message.role !== "tool" && message.role !== "user") continue;
@@ -70,7 +194,7 @@ export function continuationCallIds(request: CanonicalRequest): readonly string[
  * Returns `undefined` when the request carries no continuation ids — the
  * ordinary routing path.
  */
-export function resolveContinuationAffinity(
+function resolveContinuationAffinity(
   request: CanonicalRequest,
   authorization: ResolvedApiKey,
 ): RouteContinuationAffinity | undefined {
@@ -122,6 +246,46 @@ export function resolveContinuationAffinity(
   return undefined;
 }
 
+/**
+ * True when every continuation call id this request carries is answered by a
+ * matching `toolCall` block in the same conversation — i.e. the request is a
+ * complete replay, not a tail continuation still owed to a live Run.
+ */
+function isCompleteContinuationReplay(request: CanonicalRequest, ids: readonly string[]): boolean {
+  const calledIds = new Set<string>();
+  for (const message of request.messages) {
+    for (const part of message.content) {
+      if (part.kind === "toolCall") calledIds.add(part.call_id);
+    }
+  }
+  return ids.every((id) => calledIds.has(id));
+}
+
+/**
+ * Resolves a request's pending tool results to the one account that owns them,
+ * with rebaseability computed from the conversation shape.
+ *
+ * A hard pin is only safe when the request is still owed to a live Run. But an
+ * account that has since become unroutable (quota exhausted, cooling) must not
+ * turn a complete replay into a hard 400: the whole recorded conversation is
+ * present, so the router may fall through to normal routing and the Cursor
+ * adapter rebases it into a fresh Run on whichever account serves the model.
+ * That is what makes switching provider/model mid-conversation work.
+ */
+function resolveContinuationAffinityWithRebase(
+  request: CanonicalRequest,
+  authorization: ResolvedApiKey,
+): RouteContinuationAffinity | undefined {
+  const affinity = resolveContinuationAffinity(request, authorization);
+  if (affinity === undefined) return undefined;
+  const ids = continuationCallIds(request);
+  if (affinity.rebaseable) return affinity;
+  return {
+    ...affinity,
+    rebaseable: isCompleteContinuationReplay(request, ids),
+  };
+}
+
 /** Looks up one pending call across every provider that records continuations. */
 function lookupPendingCall(
   callId: string,
@@ -170,15 +334,29 @@ export interface PreparedNativeRequest {
   readonly admissionService: ApiKeyAdmissionService;
 }
 
-export interface ProxyRequestPreparerDeps {
+interface ProxyRequestPreparerDeps {
   readonly snapshotService: InMemoryRouteSnapshotService;
   readonly routingEngine: RoutingEngine;
   readonly admissionService: ApiKeyAdmissionService;
 }
 
 export class ProxyRequestPreparer {
+  /**
+   * Vision-handoff runner, injected by boot once the request state store and
+   * the full dispatch dependency surface exist. Absent (or when the feature is
+   * not configured) means the legacy `[image]` placeholder path.
+   */
+  #runVisionHandoff: ((input: VisionHandoffCall) => Promise<readonly VisionHandoffResult[]>) | undefined;
+
   constructor(private readonly deps: ProxyRequestPreparerDeps) {}
 
+  /** Injects the vision-handoff runner (called once from boot wiring). */
+  bindVisionHandoff(
+    runner: (input: VisionHandoffCall) => Promise<readonly VisionHandoffResult[]>,
+  ): void {
+    this.#runVisionHandoff = runner;
+  }
+
   async prepare(input: {
     readonly canonicalRequest: CanonicalRequest;
     readonly authorization: ResolvedApiKey;
@@ -186,6 +364,8 @@ export class ProxyRequestPreparer {
     readonly signal?: AbortSignal;
     /** Inbound `User-Agent`; gates remote CLI remaps so short slots stay tool-local. */
     readonly clientUserAgent?: string;
+    /** Suppresses nested vision handoff; internal sub-requests set this. */
+    readonly disableVisionHandoff?: boolean;
   }): Promise<PreparedProxyRequest> {
     const { canonicalRequest: initialRequest, authorization, signal } = input;
     if (signal?.aborted)
@@ -266,7 +446,7 @@ export class ProxyRequestPreparer {
     // degradation could narrow the candidate set past it. This is also the
     // point where a mismatched or expired call id becomes a 400 the caller can
     // act on, instead of a dispatch that silently starts a new upstream turn.
-    const continuationAffinity = resolveContinuationAffinity(request, authorization);
+    const continuationAffinity = resolveContinuationAffinityWithRebase(requestWithAttachments, authorization);
     // Capability-aware routing: derive requirements BEFORE planning so the
     // router filters candidates against snapshot profiles. When nothing
     // supports the full request, degrade (same greedy order) and re-plan
@@ -296,9 +476,108 @@ export class ProxyRequestPreparer {
           continuationAffinity,
         );
       } catch (error) {
-        if (error instanceof GatewayError && error.code === "capability_unsupported") continue;
+        // `plan()` collapses "no candidate supports this capability" into
+        // `accounts_unavailable` (503), not `capability_unsupported` — a
+        // candidate that exists but cannot carry the required capability is
+        // evaluated ineligible, and an all-ineligible set reads as "no usable
+        // account". Both mean "try the next, more degraded variant" here.
+        // `accounts_unavailable` is swallowed on the pristine variant (so a
+        // genuinely unhealthy pool falls through to a degraded plan) and on any
+        // variant that still carries requirements (a capability the route
+        // lacks, not a dead pool). Only a fully degraded variant — nothing left
+        // to drop — that still refuses means the pool itself is unusable, and
+        // that 503 must surface.
+        if (
+          error instanceof GatewayError &&
+          (error.code === "capability_unsupported" ||
+            (error.code === "accounts_unavailable" &&
+              (variant.degraded.length === 0 || variant.required.length > 0)))
+        ) {
+          continue;
+        }
         throw error;
       }
+      // Vision handoff: when the winning route cannot carry images (the image
+      // capability was degraded), try to describe the images with a configured
+      // vision model and plan the resulting text-only request instead. This
+      // only runs when the selected model is NOT image-capable — a vision route
+      // that plans without degradation keeps the real image. The handoff is
+      // best-effort; any failure keeps the legacy `[image]` placeholder plan.
+      if (
+        variant.degraded.includes("image") &&
+        input.disableVisionHandoff !== true &&
+        this.#runVisionHandoff !== undefined
+      ) {
+        try {
+          const handedOff = await this.#runVisionHandoff({
+            canonicalRequest: requestWithAttachments,
+            authorization,
+            deadlineMs: input.deadlineMs,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.clientUserAgent === undefined ? {} : { clientUserAgent: input.clientUserAgent }),
+          });
+          if (handedOff.length > 0) {
+            const description = handedOff.map((result) => result.description).join("\n");
+            // Replace on the already-degraded variant so earlier degradations
+            // (tools, reasoning, …) survive alongside the handoff — a chain
+            // variant carries them, and rewriting from the pristine request
+            // would reintroduce capabilities the winning route lacks.
+            // Condense first (while the active turn still carries its image, so
+            // it can be located): a session with hundreds of tool-result turns
+            // forwards a multi-megabyte body that upstreams reset or reject
+            // (502 / ECONNRESET) — the "broken on large sessions" report. The
+            // handoff only needs to describe the attached image, so the giant
+            // history is dropped entirely, leaving system + active turn.
+            const condensedBase = condenseHandoffRequest(variant.request);
+            const replaced = replaceImagePartsWithText(condensedBase, description);
+            if (replaced !== null) {
+              const requiredAfter = deriveRequiredCapabilities(replaced);
+              try {
+                const handoffPlan = await this.deps.routingEngine.plan(
+                  request.model,
+                  snapshot,
+                  authorization.tenantId,
+                  requiredAfter,
+                  allowCliMappings,
+                  authorization.cliMappingOwnerId ?? authorization.id,
+                  continuationAffinity,
+                );
+                plan = handoffPlan;
+                variantRequest = replaced;
+                degraded = [
+                  ...degraded,
+                  ...variant.degraded.filter(
+                    (cap) => cap !== "image" && !degraded.includes(cap),
+                  ),
+                ];
+                break;
+              } catch (error) {
+                if (
+                  error instanceof GatewayError &&
+                  (error.code === "capability_unsupported" ||
+                    error.code === "accounts_unavailable")
+                ) {
+                  // Re-plan failed without the image requirement; keep the
+                  // degraded `[image]` plan captured above. `accounts_unavailable`
+                  // is also swallowed: the text-only re-plan can be refused for
+                  // the same health/pool reasons the original plan was, and the
+                  // parent request must never fail because a best-effort
+                  // handoff could not be re-planned.
+                } else {
+                  throw error;
+                }
+              }
+            }
+          }
+        } catch (error) {
+          // Best-effort only: a handoff failure never fails the parent request.
+          log.warn("[vision-handoff] handoff failed; falling back to [image] placeholder", {
+            model: request.model,
+            tenantId: authorization.tenantId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
       variantRequest = variant.request;
       degraded = [...degraded, ...variant.degraded.filter((cap) => !degraded.includes(cap))];
       break;

package/src/transport/request/rtk/compress-request.ts

@@ -26,7 +26,7 @@ import { autoDetectFilter, dedupLogFilter, safeApplyFilter, smartTruncateFilter
 import { RTK_RAW_CAP, rtkProfile, type RtkLevel } from "./rtk-constants";
 import { ponyTailPrompt, type PonyTailLevel } from "./ponytail-prompt";
 
-export interface CompressionOptions {
+interface CompressionOptions {
   /** Compact bulky tool-result text in the message history. */
   readonly rtkPrune?: boolean;
   /** RTK strength; `full` when omitted. See {@link RtkLevel}. */
@@ -35,7 +35,7 @@ export interface CompressionOptions {
   readonly ponyTail?: PonyTailLevel | null | undefined;
 }
 
-export interface CompressionStats {
+interface CompressionStats {
   /** Tool-result text parts actually shortened. */
   readonly prunedParts: number;
   /** Characters removed by RTK (>= 0). */
@@ -45,7 +45,7 @@ export interface CompressionStats {
 }
 
 /** Compresses one text blob with RTK at a strength level, or returns it unchanged. */
-export function compressToolText(text: string, level?: RtkLevel | null): string {
+function compressToolText(text: string, level?: RtkLevel | null): string {
   const profile = rtkProfile(level);
   if (text.length < profile.minSize || text.length > RTK_RAW_CAP) return text;
   const filter = autoDetectFilter(text, { genericFallback: profile.genericFallback });

package/src/transport/request/rtk/rtk-constants.ts

@@ -2,7 +2,7 @@
 // not env knobs: these are safety margins, not deployment settings.
 
 /** Skip blobs smaller than this — compressing tiny tool results only adds noise. */
-export const RTK_MIN_COMPRESS_SIZE = 500;
+const RTK_MIN_COMPRESS_SIZE = 500;
 /** Never touch a blob larger than this; a multi-megabyte dump is not a tool result to prune. */
 export const RTK_RAW_CAP = 10 * 1024 * 1024;
 /** How many leading characters autodetect inspects when classifying a blob. */
@@ -22,7 +22,7 @@ export const RTK_DETECT_WINDOW = 1024;
 export const RTK_LEVELS = ["lite", "full", "ultra"] as const;
 export type RtkLevel = (typeof RTK_LEVELS)[number];
 
-export interface RtkProfile {
+interface RtkProfile {
   /** Blobs smaller than this are left alone at this level. */
   readonly minSize: number;
   /** Whether the generic fallbacks (dedup-log, smart-truncate) may classify a blob. */

package/src/transport/request/rtk/rtk-filters.ts

@@ -29,10 +29,10 @@ import {
   TREE_MAX_LINES,
 } from "./rtk-constants";
 
-export type RtkFilter = ((input: string) => string) & { filterName?: string };
+type RtkFilter = ((input: string) => string) & { filterName?: string };
 
 /** `git diff` → per-file header, per-hunk truncation, +/- counts. */
-export const gitDiffFilter: RtkFilter = (diff) => {
+const gitDiffFilter: RtkFilter = (diff) => {
   const result: string[] = [];
   let currentFile = "";
   let added = 0;
@@ -83,7 +83,7 @@ export const gitDiffFilter: RtkFilter = (diff) => {
 gitDiffFilter.filterName = "git-diff";
 
 /** `git log` → one line per commit, capped. */
-export const gitLogFilter: RtkFilter = (input) => {
+const gitLogFilter: RtkFilter = (input) => {
   const lines = input.split("\n");
   const out: string[] = [];
   for (const line of lines) {
@@ -99,7 +99,7 @@ export const gitLogFilter: RtkFilter = (input) => {
 gitLogFilter.filterName = "git-log";
 
 /** `git status` → branch line, changed-file counts, file list capped. */
-export const gitStatusFilter: RtkFilter = (input) => {
+const gitStatusFilter: RtkFilter = (input) => {
   const lines = input.split("\n");
   const out: string[] = [];
   let changed = 0;
@@ -119,7 +119,7 @@ export const gitStatusFilter: RtkFilter = (input) => {
 gitStatusFilter.filterName = "git-status";
 
 /** `grep`/`rg` dump (`file:line:content`) → grouped by file, capped per file. */
-export const grepFilter: RtkFilter = (input) => {
+const grepFilter: RtkFilter = (input) => {
   const byFile = new Map<string, Array<[string, string]>>();
   let total = 0;
   for (const line of input.split("\n")) {
@@ -151,7 +151,7 @@ export const grepFilter: RtkFilter = (input) => {
 grepFilter.filterName = "grep";
 
 /** `find` dump (path-per-line) → grouped by parent directory, capped. */
-export const findFilter: RtkFilter = (input) => {
+const findFilter: RtkFilter = (input) => {
   const byDir = new Map<string, string[]>();
   for (const line of input.split("\n")) {
     const path = line.trim();
@@ -177,7 +177,7 @@ export const findFilter: RtkFilter = (input) => {
 findFilter.filterName = "find";
 
 /** `ls -la` dump → directories and files with human sizes, noise dirs dropped. */
-export const lsFilter: RtkFilter = (input) => {
+const lsFilter: RtkFilter = (input) => {
   const dirs: string[] = [];
   const files: Array<[string, number]> = [];
   const byExt = new Map<string, number>();
@@ -219,7 +219,7 @@ export const lsFilter: RtkFilter = (input) => {
 lsFilter.filterName = "ls";
 
 /** `tree` dump → collapsed, noise dirs dropped, capped. */
-export const treeFilter: RtkFilter = (input) => {
+const treeFilter: RtkFilter = (input) => {
   const out: string[] = [];
   for (const line of input.split("\n")) {
     const trimmed = line.replace(/[│├└─]/g, " ").trim();

package/src/transport/request/state.ts

@@ -156,10 +156,9 @@ export interface ProxyRequestState {
    */
   extendDeadline(ms: number): void;
   cleanup(): void;
-  addCleanup(cleanup: () => void): void;
 }
 
-export interface RequestTracker {
+interface RequestTracker {
   track(id: string): void;
   untrack(id: string): void;
 }
@@ -316,7 +315,6 @@ export class ProxyRequestStateStore {
     else request.signal.addEventListener("abort", onAbort, { once: true });
     let cleaned = false;
     let providerFlightStarted = false;
-    const cleanups: Array<() => void> = [];
     const armDeadline = (ms: number): void => {
       clearTimeout(timer);
       timer = setTimeout(() => {
@@ -390,22 +388,12 @@ export class ProxyRequestStateStore {
           request.signal.removeEventListener("abort", onAbort);
         } catch {
         }
-        for (const cleanup of cleanups.splice(0)) {
-          try {
-            cleanup();
-          } catch {
-          }
-        }
         try {
           abortController.abort(new DOMException("request complete", "AbortError"));
         } catch {
         }
         this.states.delete(request);
       },
-      addCleanup: (cleanup) => {
-        if (cleaned) cleanup();
-        else cleanups.push(cleanup);
-      },
     };
     this.liveControllers.set(state.requestId, abortController);
     this.tracker?.track(state.requestId);

package/src/transport/request/system-prompt-injection.ts

@@ -8,8 +8,9 @@
  * injection (Claude identity/billing prepend, buddy fixed system turn,
  * antigravity identity) happens later, in the adapters, and is untouched.
  *
- * Resolution is most-specific-wins: model > provider > global, where a
- * provider either follows the tenant's global prompt or carries a custom one.
+ * Resolution is most-specific-wins: alias/combo (when the caller's requested
+ * name matches one) > model > provider > global. A scope either references a
+ * named preset, carries a custom setting, or follows the global prompt.
  * Failure is non-fatal — an unusable configuration must not fail a
  * dispatchable request.
  */
@@ -17,6 +18,7 @@ import type { CanonicalRequest } from "../../protocol/canonical-model";
 import type { ServiceKind } from "../../protocol/canonical-model";
 import type {
   PromptSetting,
+  ScopePromptRef,
   TenantSystemPrompts,
 } from "../../console/system-prompt/contracts";
 import {
@@ -28,28 +30,89 @@ export interface SystemPromptRoute {
   readonly providerId: string;
   readonly modelId: string;
   readonly serviceKind: ServiceKind;
+  /** The model name the client asked for (pre-alias/combo resolution), when
+   * it differs from the resolved `modelId` — lets a combo/alias carry its
+   * own injection reference. */
+  readonly requestedModel?: string;
+}
+
+/**
+ * Resolves one scope reference to a concrete prompt setting. Returns
+ * `undefined` when the scope has nothing to say (no entry, preset
+ * missing/disabled, custom disabled). `undefined` here means "skip this
+ * scope" — the caller decides the final global fallback.
+ *
+ * `global` is itself a `ScopePromptRef | null`, so the `{ kind: "global" }`
+ * marker resolves through the global ref — which may be a preset, a custom
+ * setting, or `null` (nothing). An explicit `{ kind: "off" }` is handled by
+ * the caller before this function runs.
+ */
+function resolveRef(
+  prompts: TenantSystemPrompts,
+  ref: ScopePromptRef | undefined,
+): PromptSetting | undefined {
+  if (ref === undefined || ref.kind === "off" || ref.kind === "global") return undefined;
+  if (ref.kind === "preset") {
+    const preset = prompts.presets[ref.presetId];
+    if (preset === undefined || !preset.enabled) return undefined;
+    return { enabled: true, mode: preset.mode, text: preset.text };
+  }
+  return ref.setting.enabled ? ref.setting : undefined;
+}
+
+/**
+ * Whether a scope entry explicitly stops injection. An explicit `off` is
+ * terminal — it does NOT fall through to the global prompt.
+ */
+function isExplicitOff(ref: ScopePromptRef | undefined): boolean {
+  return ref?.kind === "off";
 }
 
 /**
  * Resolves the effective prompt for a route: the most-specific enabled scope
- * wins. A provider scope honours its `followGlobal` toggle; model scope is
- * always explicit. Returns `undefined` when nothing applies.
+ * wins. Alias/combo scopes (keyed by the requested name) beat the model scope;
+ * a provider scope honours its reference; model scope is always explicit. An
+ * explicit `off` at any scope stops injection for that request — it does not
+ * fall through to the global prompt. Returns `undefined` when nothing applies.
  */
 export function resolveTenantSystemPrompt(
   prompts: TenantSystemPrompts | undefined,
-  route: Pick<SystemPromptRoute, "providerId" | "modelId">,
+  route: Pick<SystemPromptRoute, "providerId" | "modelId" | "requestedModel">,
 ): PromptSetting | undefined {
   if (prompts === undefined) return undefined;
+  const global = prompts.global;
+
+  const requested = route.requestedModel;
+  if (requested !== undefined && requested.length > 0 && requested !== route.modelId) {
+    const aliasRef = prompts.aliases[requested];
+    if (aliasRef !== undefined) {
+      if (isExplicitOff(aliasRef)) return undefined;
+      const aliasSetting = resolveRef(prompts, aliasRef);
+      if (aliasSetting !== undefined) return aliasSetting;
+    }
+    const comboRef = prompts.combos[requested];
+    if (comboRef !== undefined) {
+      if (isExplicitOff(comboRef)) return undefined;
+      const comboSetting = resolveRef(prompts, comboRef);
+      if (comboSetting !== undefined) return comboSetting;
+    }
+  }
+
   const model = prompts.models[systemPromptModelKey(route.providerId, route.modelId)];
-  if (model !== undefined && model.enabled) return model;
+  if (model !== undefined) {
+    if (isExplicitOff(model)) return undefined;
+    const modelSetting = resolveRef(prompts, model);
+    if (modelSetting !== undefined) return modelSetting;
+  }
+
   const provider = prompts.providers[route.providerId];
   if (provider !== undefined) {
-    if (provider.followGlobal) {
-      return prompts.global !== null && prompts.global.enabled ? prompts.global : undefined;
-    }
-    if (provider.setting !== undefined && provider.setting.enabled) return provider.setting;
+    if (isExplicitOff(provider)) return undefined;
+    const providerSetting = resolveRef(prompts, provider);
+    if (providerSetting !== undefined) return providerSetting;
   }
-  return prompts.global !== null && prompts.global.enabled ? prompts.global : undefined;
+
+  return resolveRef(prompts, global ?? undefined);
 }
 
 /** Marker text guard so retries never double-inject. */

package/src/transport/request/tenant-preferences.ts

@@ -107,6 +107,27 @@ export async function resolveTenantImageClampMaxBytes(
   }
 }
 
+/**
+ * The tenant's ordered vision-handoff model list, or `[]` when none is
+ * configured (legacy `[image]` placeholder behavior). Read through the shared
+ * revision-keyed preference reader; a settings outage yields an empty list,
+ * which is the safe direction (handoff is an upgrade, never a prerequisite).
+ */
+export async function resolveTenantVisionHandoffModels(
+  db: CartethyiaDatabase,
+  tenantId: string | undefined,
+): Promise<readonly string[]> {
+  if (tenantId === undefined) return [];
+  try {
+    const prefs = await preferencesReaderFor(db).readPreferences(tenantId);
+    const models = prefs?.visionHandoffModels;
+    if (!Array.isArray(models)) return [];
+    return models.filter((model): model is string => typeof model === "string" && model.trim().length > 0);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Applies request shaping owned by tenant preferences and deployment config:
  * thinking normalization and the Responses reasoning summary override.
@@ -133,6 +154,7 @@ export async function applyTenantPreferences(
       providerId: candidate.provider_id,
       modelId: candidate.model_id,
       serviceKind: candidate.service_kind ?? "llm",
+      requestedModel: prepared.plan?.requested_model ?? candidate.model_id,
     });
     if (prefs) {
       // When the routed model is Responses (codex/openai/muse-spark) and the