@yaag/runtime 0.6.1 → 0.7.0

package/src/cassette/recording-transport.ts

@@ -6,6 +6,7 @@ import type {
   AskPlayback,
   Frame,
   OpenOptions,
+  RecordedSpawnSelection,
   TransportFactory,
   TransportStartup,
   TransportStartupObserver,
@@ -43,6 +44,12 @@ export function recordingTransport(inner: TransportFactory, sink: CassetteSink):
         throw error;
       }
     },
+
+    // The recorder is the outermost wrapper of every composition, so a
+    // Cassette-backed inner factory answers the recorded-selection peek.
+    recordedSpawn(options: OpenOptions): RecordedSpawnSelection | undefined {
+      return inner.recordedSpawn?.(options);
+    },
   };
 }
 

package/src/cassette/replay-divergence.ts

@@ -1,5 +1,10 @@
 import { YaagError } from "../errors.ts";
-import type { AskMarker, AskMarkerContext, OpenOptions } from "../transport/index.ts";
+import type {
+  AskMarker,
+  AskMarkerContext,
+  OpenOptions,
+  RecordedSpawnSelection,
+} from "../transport/index.ts";
 import type { CassetteAgent, CassetteAsk, CassetteSpawn } from "./cassette.ts";
 
 /** A pure description of the first strict replay identity mismatch. */
@@ -28,7 +33,13 @@ export const replayMismatch = {
     const actualHash = spawnHash(actual);
     return expectedHash === actualHash
       ? null
-      : { kind: "spawn-options", agent: actual.name, expectedHash, actualHash };
+      : {
+          kind: "spawn-options",
+          agent: actual.name,
+          expectedHash,
+          actualHash,
+          changedFields: spawnChangedFields(expected.spawn, actual),
+        };
   },
 
   ask(agent: CassetteAgent, cursor: number, actual: AskMarker): ReplayMismatch | null {
@@ -73,13 +84,73 @@ export function strictReplay(mismatch: ReplayMismatch): never {
     );
   }
   const at = mismatch.index === undefined ? "spawn" : `Ask ${mismatch.index}`;
+  const changed =
+    mismatch.kind === "spawn-options" && mismatch.changedFields !== undefined
+      ? ` changed ${mismatch.changedFields.join(", ")};`
+      : "";
   throw new YaagError(
     "REPLAY_DIVERGED",
-    `replay diverged for agent "${mismatch.agent}" at ${at}: expected ${mismatch.expectedHash}, actual ${mismatch.actualHash}`,
+    `replay diverged for agent "${mismatch.agent}" at ${at}:${changed} expected ${mismatch.expectedHash}, actual ${mismatch.actualHash}`,
     mismatch.agent,
   );
 }
 
+/** The identity fields a changed spawn altered, for the Divergence report (ADR-0039). */
+function spawnChangedFields(expected: CassetteSpawn, actual: OpenOptions): readonly string[] {
+  return changedAmong(SPAWN_OPEN_FIELDS, expected, actual);
+}
+
+/**
+ * True when a live spawn matches the recorded one on every identity field
+ * except the resolved model and thinking, so a resume may adopt the recorded
+ * selection instead of re-running Model Resolution (ADR-0039).
+ */
+export function spawnMatchesExceptModel(expected: CassetteSpawn, actual: OpenOptions): boolean {
+  return (
+    spawnHash({ ...expected, model: undefined, thinking: undefined }) ===
+    spawnHash({ ...actual, model: undefined, thinking: undefined })
+  );
+}
+
+/** The recorded resolved selection of one Agent, or `undefined` when none is recorded. */
+export function recordedSpawnSelection(
+  agent: CassetteAgent | null,
+): RecordedSpawnSelection | undefined {
+  if (agent === null) return undefined;
+  return {
+    ...(agent.spawn.model === undefined ? {} : { model: agent.spawn.model }),
+    ...(agent.spawn.thinking === undefined ? {} : { thinking: agent.spawn.thinking }),
+  };
+}
+
+/** The spawn fields both Divergence reports compare, so the two cannot drift apart. */
+const SPAWN_IDENTITY_FIELDS = [
+  "cwd",
+  "model",
+  "systemPrompt",
+  "thinking",
+  "appendSystemPrompt",
+  "tools",
+  "disallowedTools",
+  "skills",
+  "disallowedSkills",
+  "worktree",
+] as const;
+
+/** The spawn identity fields plus the Agent name, which only an open request carries. */
+const SPAWN_OPEN_FIELDS = ["name", ...SPAWN_IDENTITY_FIELDS] as const;
+
+/** The listed fields whose canonical JSON differs between two identity records. */
+function changedAmong<Key extends string>(
+  fields: readonly Key[],
+  expected: { readonly [Field in Key]?: unknown },
+  actual: { readonly [Field in Key]?: unknown },
+): readonly Key[] {
+  return fields.filter(
+    (field) => JSON.stringify(expected[field]) !== JSON.stringify(actual[field]),
+  );
+}
+
 function askMatches(expected: CassetteAsk, actual: AskMarker): boolean {
   return (
     expected.index === actual.index &&
@@ -93,22 +164,7 @@ function askMatches(expected: CassetteAsk, actual: AskMarker): boolean {
 function changedFields(expected: AskMarkerContext, actual: AskMarkerContext): readonly string[] {
   const fields: string[] = [];
   if (expected.prompt !== actual.prompt) fields.push("prompt");
-  for (const field of [
-    "cwd",
-    "model",
-    "systemPrompt",
-    "thinking",
-    "appendSystemPrompt",
-    "tools",
-    "disallowedTools",
-    "skills",
-    "disallowedSkills",
-    "worktree",
-  ] as const) {
-    if (JSON.stringify(expected.spawn[field]) !== JSON.stringify(actual.spawn[field])) {
-      fields.push(field);
-    }
-  }
+  fields.push(...changedAmong(SPAWN_IDENTITY_FIELDS, expected.spawn, actual.spawn));
   for (const field of [
     "maxTurns",
     "maxToolCalls",

package/src/cassette/replay-transport.ts

@@ -5,12 +5,13 @@ import type {
   AskPlayback,
   Frame,
   OpenOptions,
+  RecordedSpawnSelection,
   TransportFactory,
   TransportStartupObserver,
 } from "../transport/index.ts";
 import type { Cassette } from "./cassette.ts";
 import { CassetteReplay } from "./cassette-replay.ts";
-import { replayMismatch, strictReplay } from "./replay-divergence.ts";
+import { recordedSpawnSelection, replayMismatch, strictReplay } from "./replay-divergence.ts";
 
 /**
  * Creates a strict Cassette-backed transport factory without starting pi.
@@ -32,6 +33,12 @@ export function replayTransport(cassette: Cassette): TransportFactory {
       if (agent.worktree !== undefined) observeStartup?.({ worktree: agent.worktree });
       return new ReplayTransport(new CassetteReplay(agent));
     },
+
+    // Strict replay always offers the recorded selection: an outcome the
+    // declared spec can no longer produce must diverge at open (ADR-0039).
+    recordedSpawn(): RecordedSpawnSelection | undefined {
+      return recordedSpawnSelection(cassette.agents[spawnCursor] ?? null);
+    },
   };
 }
 

package/src/cassette/resume-transport.ts

@@ -6,13 +6,18 @@ import type {
   AskPlayback,
   Frame,
   OpenOptions,
+  RecordedSpawnSelection,
   TransportFactory,
   TransportStartupObserver,
 } from "../transport/index.ts";
 import { FrameQueue } from "../transport/index.ts";
 import type { Cassette, CassetteAgent } from "./cassette.ts";
 import { CassetteReplay } from "./cassette-replay.ts";
-import { replayMismatch } from "./replay-divergence.ts";
+import {
+  recordedSpawnSelection,
+  replayMismatch,
+  spawnMatchesExceptModel,
+} from "./replay-divergence.ts";
 import { checkResumePreconditions } from "./resume-preconditions.ts";
 
 /**
@@ -39,6 +44,14 @@ export function resumeTransport(cassette: Cassette, live: TransportFactory): Tra
       });
       return new ResumeTransport(agent, live, options);
     },
+
+    // A changed spawn must not silently inherit the recorded model, so the
+    // recorded selection is offered only when every other field matches.
+    recordedSpawn(options: OpenOptions): RecordedSpawnSelection | undefined {
+      const agent = cassette.agents[spawnCursor] ?? null;
+      if (agent === null || !spawnMatchesExceptModel(agent.spawn, options)) return undefined;
+      return recordedSpawnSelection(agent);
+    },
   };
 }
 

package/src/errors.ts

@@ -7,8 +7,10 @@ export interface AskLimitOutcome {
   readonly count: number;
 }
 
+import type { ModelError } from "./model/index.ts";
 import type { AgentProgress } from "./transport/index.ts";
 
+export type { ModelError } from "./model/index.ts";
 export type { AgentProgress } from "./transport/index.ts";
 
 /** The recorded result when yaag rejects an Ask because no frame arrived within `idleMs`. */
@@ -29,6 +31,11 @@ export interface AskInvalidOutputOutcome {
   readonly errors: readonly string[];
 }
 
+/** The recorded history when every model candidate of one Model Resolution loop failed. */
+export interface ModelResolutionOutcome {
+  readonly modelErrors: readonly ModelError[];
+}
+
 /** Why an Ask, spawn, or Run failed. Programs may branch on this; most won't. */
 export type YaagErrorCode =
   | "AGENT_FAILED" // turn settled with stopReason error/aborted, or empty text
@@ -45,7 +52,8 @@ export type YaagErrorCode =
   | "RUN_CLOSED" // spawn was requested after the Run began settling
   | "RUN_STOPPED" // the Run's abort signal fired before the program completed
   | "WORKTREE_REFUSED" // base cwd is not a clean Git repository
-  | "SPAWN_FAILED"; // pi failed to start, e.g. unknown model
+  | "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
+  | "SPAWN_FAILED"; // pi failed to start, e.g. a broken tool contract or a startup timeout
 
 /** The single error class of the runtime (ADR-0003). */
 export class YaagError extends Error {
@@ -66,12 +74,22 @@ export class YaagError extends Error {
   readonly steeringEfforts?: number;
   /** Localized extraction or schema errors, present only for `ASK_INVALID_OUTPUT`. */
   readonly errors?: readonly string[];
+  /**
+   * Failed model candidates, present only for `MODEL_RESOLUTION_FAILED`. It
+   * holds one entry for each attempt, oldest first. A candidate that already
+   * failed with `not_found` or `auth` is refused again (ADR-0037).
+   */
+  readonly modelErrors?: readonly ModelError[];
 
   constructor(
     code: YaagErrorCode,
     message: string,
     agent?: string,
-    options?: AskLimitOutcome | AskStalledOutcome | AskInvalidOutputOutcome,
+    options?:
+      | AskLimitOutcome
+      | AskStalledOutcome
+      | AskInvalidOutputOutcome
+      | ModelResolutionOutcome,
   ) {
     super(message);
     this.name = "YaagError";
@@ -90,6 +108,9 @@ export class YaagError extends Error {
       this.steeringEfforts = options.steeringEfforts;
       this.errors = options.errors;
     }
+    if (options !== undefined && "modelErrors" in options) {
+      this.modelErrors = options.modelErrors;
+    }
   }
 }
 
@@ -118,6 +139,38 @@ export function askStalledError(agent: string, outcome: AskStalledOutcome): Yaag
   );
 }
 
+/** The MODEL_RESOLUTION_FAILED rejection for an exhausted or self-repeating resolver. */
+export function modelResolutionError(
+  agent: string,
+  errors: readonly ModelError[],
+  refusedCandidate?: string,
+): YaagError {
+  if (errors.length === 0) {
+    return new YaagError(
+      "MODEL_RESOLUTION_FAILED",
+      `agent "${agent}": no model candidate to try`,
+      agent,
+      { modelErrors: errors },
+    );
+  }
+  const history = errors.map((error) => `${error.failedModel} (${error.reason})`).join(", ");
+  // The guard only refuses a candidate that has a matching permanent entry.
+  const refusal =
+    refusedCandidate === undefined
+      ? ""
+      : `; refused to retry "${refusedCandidate}", which already failed with ${
+          errors.find((error) => error.failedModel === refusedCandidate)?.reason
+        }`;
+  return new YaagError(
+    "MODEL_RESOLUTION_FAILED",
+    `agent "${agent}": model resolution gave up after ${errors.length} attempt${
+      errors.length === 1 ? "" : "s"
+    }: ${history}${refusal}`,
+    agent,
+    { modelErrors: errors },
+  );
+}
+
 /** Narrows an unknown rejection reason to a YaagError. */
 export function isYaagError(value: unknown): value is YaagError {
   return value instanceof YaagError;

package/src/events.ts

@@ -7,9 +7,11 @@
  * dedicated fd arrives with the extension.
  */
 import type { SettlementCause } from "./ask/index.ts";
+import type { ModelErrorReason } from "./model/index.ts";
 import type { TokenBreakdown, WorktreeResolution } from "./transport/index.ts";
 
 export type { SettlementCause } from "./ask/index.ts";
+export type { ModelErrorReason } from "./model/index.ts";
 
 /**
  * A Run's outcome (ADR-0022). `paused` arrives with the pause slice.
@@ -118,6 +120,23 @@ export type LifecycleEventBody =
        */
       readonly cause?: SettlementCause;
     }
+  | {
+      /**
+       * One failed Model Resolution attempt and the candidate that replaced it.
+       * yaag emits it at spawn time and inside an Ask (ADR-0037, ADR-0038).
+       * A resolver that gives up emits none: the Run fails with
+       * MODEL_RESOLUTION_FAILED, which already carries the full history.
+       */
+      readonly type: "model_fallback";
+      readonly agent: string;
+      /** The candidate pattern that failed, after inline-suffix stripping. */
+      readonly failedModel: string;
+      readonly reason: ModelErrorReason;
+      /** 0-based index of the failed attempt, as the resolver's history numbers it. */
+      readonly attempt: number;
+      /** The candidate resolution picked next. */
+      readonly resolvedModel: string;
+    }
   | {
       readonly type: "agent_usage";
       readonly agent: string;

package/src/index.ts

@@ -23,6 +23,7 @@ export type {
   AskLimitKind,
   AskLimitOutcome,
   AskStalledOutcome,
+  ModelResolutionOutcome,
   YaagErrorCode,
 } from "./errors.ts";
 export { isYaagError, YaagError } from "./errors.ts";
@@ -68,6 +69,7 @@ export type {
   EndedRunSummary,
   ExitedAgentInfo,
   IdleAgentInfo,
+  ModelFallbackInfo,
   NodeInfo,
   RunningRunSummary,
   RunOutcome,

package/src/model/index.ts

@@ -2,9 +2,14 @@
  * Public surface of the `model/` module: model resolution.
  * Files inside this directory import each other directly.
  */
+export { ModelErrorHistory } from "./model-error-history.ts";
+export { classifyAskFailure, classifyModelFailure } from "./model-failure.ts";
+export type { ModelFallback, ModelFallbackSink } from "./model-fallback.ts";
+export type { AvailableModel } from "./model-match.ts";
 export {
   type ModelError,
   type ModelErrorReason,
+  type ModelResolution,
   type ModelResolver,
   type ModelSelection,
   type ModelSpec,
@@ -12,4 +17,17 @@ export {
   type ThinkingResolver,
   type ThinkingSpec,
 } from "./model-resolution.ts";
+export { type ModelSwapResult, swapModel } from "./model-swap.ts";
+export {
+  type RecordedResolution,
+  type RecordedResolutionOptions,
+  type RecordedSpawnSelection,
+  resolveRecordedModel,
+} from "./recorded-resolution.ts";
+export {
+  type FallbackLoopOptions,
+  type ResolutionLoopOptions,
+  resolveModel,
+  retryOnModelFailure,
+} from "./resolution-loop.ts";
 export type { ThinkingLevel } from "./thinking-level.ts";

package/src/model/model-error-history.ts

@@ -0,0 +1,36 @@
+import type { ModelError, ModelErrorReason } from "./model-resolution.ts";
+
+/**
+ * The Model Resolution attempt history of one Agent.
+ *
+ * The spawn-time loop and every mid-Ask fallback loop of the same Agent share
+ * one history, so a resolver sees every candidate that already failed, whenever
+ * it failed.
+ */
+export class ModelErrorHistory {
+  readonly #errors: ModelError[] = [];
+
+  /** Every failed attempt so far, oldest first. */
+  get errors(): readonly ModelError[] {
+    return this.#errors;
+  }
+
+  /**
+   * Appends one failed attempt and returns it; the attempt number is the
+   * history length before the push.
+   */
+  record(reason: ModelErrorReason, failedModel: string): ModelError {
+    const error: ModelError = { reason, failedModel, attempt: this.#errors.length };
+    this.#errors.push(error);
+    return error;
+  }
+
+  /** True when this candidate already failed for a reason a retry cannot fix. */
+  failedPermanently(candidate: string): boolean {
+    return this.#errors.some(
+      (error) =>
+        error.failedModel === candidate &&
+        (error.reason === "not_found" || error.reason === "auth"),
+    );
+  }
+}

package/src/model/model-failure.ts

@@ -0,0 +1,78 @@
+import { isYaagError } from "../errors.ts";
+import type { ModelErrorReason } from "./model-resolution.ts";
+
+/**
+ * Classification reads pi's English diagnostics, and pi offers nothing else
+ * (ADR-0037). A reworded upstream message matches no pattern, so the failure
+ * stays generic and fallback stops: the degradation never fires wrongly.
+ *
+ * Message patterns pi emits when a model pattern matches nothing.
+ * Sources: `core/model-resolver.js` (`resolveCliModel`), `modes/rpc/rpc-mode.js`
+ * (`set_model` miss) and the CLI catalog guard in `core/model-registry.js`.
+ */
+const NOT_FOUND: readonly RegExp[] = [
+  /model "[^"]*" not found/i,
+  // Covers `Model not found: <p>/<id>` and `Model not found or no API key - …`.
+  /model not found/i,
+  /no models match pattern/i,
+  /unknown provider "/i,
+  /is ambiguous across providers/i,
+  /no models available/i,
+];
+
+/**
+ * Message patterns pi emits when credentials are missing or rejected.
+ * Sources: `core/model-registry.js` (`No API key found for "<provider>"`),
+ * `core/agent-session.js` (`No API key for <provider>/<id>`) and provider HTTP errors.
+ */
+const AUTH: readonly RegExp[] = [
+  // Covers `No API key for <p>/<id>`, `No API key found for "<p>"` and
+  // `No API key provided for provider <p>`.
+  /no api key\b/i,
+  /\b401\b|\b403\b/,
+  /unauthorized|invalid api key|authentication/i,
+];
+
+/** Provider throttling. Declared here so mid-Ask fallback reuses one table. */
+const RATE_LIMITED: readonly RegExp[] = [/\b429\b/, /rate.?limit/i, /quota exceeded/i];
+
+/**
+ * Classifies a spawn or Ask failure into a Model Resolution trigger, or
+ * `undefined` for a generic failure that must stay an ordinary failure.
+ *
+ * Evaluation order is `not_found` → `auth` → `rate_limited`, first match wins:
+ * a "model not found" diagnostic may also mention API keys in its help text, so
+ * the most specific table has to be consulted first.
+ */
+export function classifyModelFailure(error: unknown): ModelErrorReason | undefined {
+  const message = messageOf(error);
+  if (message === "") return undefined;
+  if (NOT_FOUND.some((pattern) => pattern.test(message))) return "not_found";
+  if (AUTH.some((pattern) => pattern.test(message))) return "auth";
+  if (RATE_LIMITED.some((pattern) => pattern.test(message))) return "rate_limited";
+  return undefined;
+}
+
+/**
+ * Classifies one Ask rejection into a Model Resolution trigger.
+ *
+ * Only AGENT_FAILED can be a trigger: ASK_STALLED is generic and never enters
+ * resolution (ADR-0029), ASK_LIMIT/ASK_TIMEOUT/ASK_INVALID_OUTPUT are yaag's own
+ * verdicts, and AGENT_DIED leaves nothing to swap a model on.
+ */
+export function classifyAskFailure(error: unknown): ModelErrorReason | undefined {
+  if (!isYaagError(error) || error.code !== "AGENT_FAILED") return undefined;
+  return classifyModelFailure(error);
+}
+
+/** The error's own message plus its cause chain, so a wrapped diagnostic still classifies. */
+function messageOf(error: unknown): string {
+  if (!(error instanceof Error)) return String(error ?? "");
+  const parts: string[] = [error.message];
+  let cause: unknown = error.cause;
+  for (let depth = 0; cause !== undefined && cause !== null && depth < 5; depth += 1) {
+    parts.push(cause instanceof Error ? cause.message : String(cause));
+    cause = cause instanceof Error ? cause.cause : undefined;
+  }
+  return parts.join(" ");
+}

package/src/model/model-fallback.ts

@@ -0,0 +1,15 @@
+import type { ModelErrorReason } from "./model-resolution.ts";
+
+/** One failed Model Resolution attempt and the candidate that replaced it. */
+export interface ModelFallback {
+  /** The candidate pattern that failed, after inline-suffix stripping. */
+  readonly failedModel: string;
+  readonly reason: ModelErrorReason;
+  /** 0-based index of the failed attempt in the Agent's shared history. */
+  readonly attempt: number;
+  /** The candidate the resolver picked next. */
+  readonly resolvedModel: string;
+}
+
+/** Where a Model Resolution loop reports each fallback it takes. */
+export type ModelFallbackSink = (fallback: ModelFallback) => void;

package/src/model/model-match.ts

@@ -0,0 +1,99 @@
+/** One entry of pi's `get_available_models` snapshot. */
+export interface AvailableModel {
+  readonly provider: string;
+  readonly id: string;
+  readonly name?: string;
+}
+
+/** What matching one yaag model pattern against pi's snapshot produced. */
+export type ModelMatch =
+  | { readonly kind: "matched"; readonly model: AvailableModel }
+  | { readonly kind: "no_match" }
+  | { readonly kind: "ambiguous"; readonly candidates: readonly string[] };
+
+/**
+ * Matches one yaag model pattern against the models pi reports as available.
+ *
+ * A reduced mirror of pi's `core/model-resolver.js` (`resolveCliModel` /
+ * `tryMatchModel`): exact `provider/id`, exact bare `id`, then a known provider
+ * prefix, then a partial `id`/`name` search. A bare id that exists under several
+ * providers is refused rather than guessed, because yaag cannot see pi's
+ * configured-auth ordering. No suffix parsing happens here: an inline thinking
+ * suffix is already stripped by `normalizeModelResolution`.
+ */
+export function matchAvailableModel(
+  pattern: string,
+  models: readonly AvailableModel[],
+): ModelMatch {
+  const needle = pattern.trim().toLowerCase();
+  if (needle === "" || models.length === 0) return { kind: "no_match" };
+
+  const exactPair = models.filter((model) => qualified(model) === needle);
+  if (exactPair.length > 0) return matched(exactPair[0]);
+
+  const exactId = models.filter((model) => model.id.toLowerCase() === needle);
+  if (exactId.length === 1) return matched(exactId[0]);
+  if (exactId.length > 1) return ambiguous(exactId);
+
+  const slash = needle.indexOf("/");
+  if (slash > 0) {
+    const provider = needle.slice(0, slash);
+    const rest = needle.slice(slash + 1);
+    const scoped = models.filter((model) => model.provider.toLowerCase() === provider);
+    if (scoped.length > 0) return search(rest, scoped);
+    return { kind: "no_match" };
+  }
+  return search(needle, models);
+}
+
+/** Reads pi's `get_available_models` payload, or `null` when it is not one. */
+export function readAvailableModels(data: unknown): readonly AvailableModel[] | null {
+  if (typeof data !== "object" || data === null) return null;
+  const list: unknown = (data as { models?: unknown }).models;
+  if (!Array.isArray(list)) return null;
+  const models: AvailableModel[] = [];
+  for (const entry of list) {
+    const model = readAvailableModel(entry);
+    if (model !== null) models.push(model);
+  }
+  return models;
+}
+
+/** Reads one pi Model object, or `null` when the payload is not one. */
+export function readAvailableModel(entry: unknown): AvailableModel | null {
+  if (typeof entry !== "object" || entry === null) return null;
+  const record = entry as { provider?: unknown; id?: unknown; name?: unknown };
+  if (typeof record.provider !== "string" || typeof record.id !== "string") return null;
+  return {
+    provider: record.provider,
+    id: record.id,
+    ...(typeof record.name === "string" ? { name: record.name } : {}),
+  };
+}
+
+function search(needle: string, models: readonly AvailableModel[]): ModelMatch {
+  const exact = models.filter((model) => model.id.toLowerCase() === needle);
+  if (exact.length === 1) return matched(exact[0]);
+  if (exact.length > 1) return ambiguous(exact);
+  const partial = models.filter(
+    (model) =>
+      model.id.toLowerCase().includes(needle) || (model.name ?? "").toLowerCase().includes(needle),
+  );
+  if (partial.length === 0) return { kind: "no_match" };
+  // pi prefers its aliases and its newest dated ids; the highest-sorting id is a
+  // deterministic stand-in yaag can compute without pi's catalog metadata.
+  const sorted = [...partial].sort((left, right) => right.id.localeCompare(left.id));
+  return matched(sorted[0]);
+}
+
+function matched(model: AvailableModel | undefined): ModelMatch {
+  return model === undefined ? { kind: "no_match" } : { kind: "matched", model };
+}
+
+function ambiguous(models: readonly AvailableModel[]): ModelMatch {
+  return { kind: "ambiguous", candidates: models.map(qualified) };
+}
+
+function qualified(model: AvailableModel): string {
+  return `${model.provider}/${model.id}`.toLowerCase();
+}