@yaag/runtime 0.6.2 → 0.8.0

package/src/config/effective-config.ts

@@ -0,0 +1,116 @@
+import { type ConfigLayer, readConfigLayer } from "./config-file.ts";
+import {
+  type ConfigEnvironment,
+  projectConfigPath,
+  resolveGlobalConfigPath,
+} from "./config-paths.ts";
+
+/** Which of the three layers a config value came from. */
+export type ConfigLayerName = "global" | "project" | "run";
+
+/** One extension declaration, kept exactly as written, with its resolution base. */
+export interface ConfigExtension {
+  /** The declaration as written in the config file; never resolved here. */
+  readonly declaration: string;
+  /** The declaring config file's own directory (spec rule 4). */
+  readonly baseDirectory: string;
+  readonly layer: ConfigLayerName;
+  /** The declaring file, for diagnostics. */
+  readonly file: string;
+}
+
+/** The merged configuration one Run reads at start. */
+export interface EffectiveConfig {
+  /** Extension declarations, concatenated global → project → run (spec rule 3). */
+  readonly extensions: readonly ConfigExtension[];
+  /** Config files that contributed, in merge order. */
+  readonly files: readonly string[];
+}
+
+/** What to discover and read. */
+export interface EffectiveConfigRequest {
+  /** Environment for Global Config discovery; defaults to `process.env`. */
+  readonly env?: ConfigEnvironment;
+  /** Program Directory of the Run; absent means no Project Config layer. */
+  readonly programDirectory?: string;
+  /** Explicit Run Config path; a missing file here is an error. */
+  readonly configPath?: string;
+  /** Suppresses the discovered layers only; an explicit `configPath` survives (spec rule 8). */
+  readonly noConfig?: boolean;
+}
+
+/** The Effective Config of a Run that found no config at all. */
+export const EMPTY_EFFECTIVE_CONFIG: EffectiveConfig = Object.freeze({
+  extensions: Object.freeze([]) as readonly ConfigExtension[],
+  files: Object.freeze([]) as readonly string[],
+});
+
+interface LoadedLayer {
+  readonly layer: ConfigLayer;
+  readonly name: ConfigLayerName;
+}
+
+interface Candidate {
+  readonly path: string;
+  readonly layer: ConfigLayerName;
+  readonly required: boolean;
+}
+
+/**
+ * Locates, reads, validates, and merges the three config layers.
+ *
+ * The result is frozen: the Effective Config is read once at Run start, so a
+ * config edit mid-Run changes nothing until the next Run (spec rule 6). Nothing
+ * is resolved, existence-checked, or deduplicated here — dedup happens by
+ * resolved path once the spawn knows its base directories (ADR-0040).
+ */
+export async function loadEffectiveConfig(
+  request: EffectiveConfigRequest = {},
+): Promise<EffectiveConfig> {
+  const found: LoadedLayer[] = [];
+  // Read in order, sequentially: the first failing file is the reported one.
+  for (const candidate of candidates(request)) {
+    const layer = await readConfigLayer(candidate.path, { required: candidate.required });
+    if (layer !== undefined) found.push({ layer, name: candidate.layer });
+  }
+  return mergeLayers(found);
+}
+
+function candidates(request: EffectiveConfigRequest): readonly Candidate[] {
+  const discovered: Candidate[] = [];
+  if (request.noConfig !== true) {
+    discovered.push({
+      path: resolveGlobalConfigPath(request.env),
+      layer: "global",
+      required: false,
+    });
+    if (request.programDirectory !== undefined) {
+      discovered.push({
+        path: projectConfigPath(request.programDirectory),
+        layer: "project",
+        required: false,
+      });
+    }
+  }
+  if (request.configPath !== undefined) {
+    discovered.push({ path: request.configPath, layer: "run", required: true });
+  }
+  return discovered;
+}
+
+function mergeLayers(found: readonly LoadedLayer[]): EffectiveConfig {
+  const extensions = found.flatMap(({ layer, name }) =>
+    (layer.document.agents?.extensions ?? []).map((declaration) =>
+      Object.freeze({
+        declaration,
+        baseDirectory: layer.directory,
+        layer: name,
+        file: layer.file,
+      }),
+    ),
+  );
+  return Object.freeze({
+    extensions: Object.freeze(extensions),
+    files: Object.freeze(found.map(({ layer }) => layer.file)),
+  });
+}

package/src/config/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Public surface of the `config/` module: the Global, Project, and Run Config
+ * layers and the frozen Effective Config a Run reads at start (ADR-0040).
+ * Files inside this directory import each other directly.
+ */
+
+export {
+  CONFIG_FILE_NAME,
+  type ConfigEnvironment,
+  PROJECT_CONFIG_DIR,
+  projectConfigPath,
+  resolveGlobalConfigPath,
+} from "./config-paths.ts";
+export type { YaagConfigDocument } from "./config-schema.ts";
+export {
+  type ConfigExtension,
+  type ConfigLayerName,
+  type EffectiveConfig,
+  type EffectiveConfigRequest,
+  EMPTY_EFFECTIVE_CONFIG,
+  loadEffectiveConfig,
+} from "./effective-config.ts";

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
@@ -39,13 +46,15 @@ export type YaagErrorCode =
   | "ASK_STALLED" // no frame arrived within the silence budget; escalated, then kill
   | "ASK_INVALID_OUTPUT" // settled text could not be extracted or satisfy outputSchema
   | "ARGS_INVALID" // arguments failed schema validation before the Run started
+  | "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema
   | "OPTIONS_CONFLICT" // incompatible Run options were supplied
   | "REPLAY_DIVERGED" // replayed program differed from its Cassette
   | "RESUME_REFUSED" // resume metadata is absent or the recorded tree moved
   | "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 +75,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 +109,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 +140,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/extension/extension-paths.ts

@@ -7,16 +7,24 @@ import { parseExtensionSource } from "./extension-source.ts";
 export interface ExtensionResolutionOptions extends ExtensionInstallRoots {
   /** Orchestration Program source path, required by relative declarations. */
   readonly programFile?: string;
+  /**
+   * Directory a relative declaration resolves against, and which wins over
+   * `programFile`: a config-sourced entry resolves from its own config file's
+   * directory (ADR-0040, spec rule 4).
+   */
+  readonly baseDirectory?: string;
 }
 
 /**
  * Resolves declared extensions into launch-ready `pi -e` arguments before transport opening.
  *
- * Filesystem declarations are resolved against the Orchestration Program directory and
+ * Filesystem declarations are resolved against `baseDirectory` when given, and against
+ * the Orchestration Program directory otherwise, and are
  * checked for existence. `npm:`/`git:` specifiers expand to the entry points of the
  * already-installed package (project install shadows the user install); an uninstalled
  * specifier passes through verbatim so pi temp-installs it. Results retain declaration
- * order. Rejects missing paths and a relative declaration without `programFile`.
+ * order. Rejects missing paths, and a relative declaration that has neither
+ * `baseDirectory` nor `programFile`.
  */
 export async function resolveExtensionPaths(
   declarations: readonly string[],
@@ -35,7 +43,7 @@ async function resolveOne(
 ): Promise<readonly string[]> {
   const source = parseExtensionSource(declaration);
   if (source.kind === "path") {
-    const path = resolveDeclaration(declaration, options.programFile);
+    const path = resolveDeclaration(declaration, options);
     await requireExists(declaration, path);
     return [path];
   }
@@ -45,12 +53,13 @@ async function resolveOne(
   return installed;
 }
 
-function resolveDeclaration(declaration: string, programFile: string | undefined): string {
+function resolveDeclaration(declaration: string, options: ExtensionResolutionOptions): string {
   if (isAbsolute(declaration)) return declaration;
-  if (programFile === undefined) {
+  if (options.baseDirectory !== undefined) return resolve(options.baseDirectory, declaration);
+  if (options.programFile === undefined) {
     throw new Error(`relative extension "${declaration}" requires RunOptions.programFile`);
   }
-  return resolve(dirname(programFile), declaration);
+  return resolve(dirname(options.programFile), declaration);
 }
 
 async function requireExists(declaration: string, path: string): Promise<void> {

package/src/index.ts

@@ -18,11 +18,24 @@ export {
   replayTransport,
   resumeTransport,
 } from "./cassette/index.ts";
+export type {
+  ConfigEnvironment,
+  ConfigExtension,
+  ConfigLayerName,
+  EffectiveConfig,
+  EffectiveConfigRequest,
+} from "./config/index.ts";
+export {
+  EMPTY_EFFECTIVE_CONFIG,
+  loadEffectiveConfig,
+  PROJECT_CONFIG_DIR,
+} from "./config/index.ts";
 export type {
   AskInvalidOutputOutcome,
   AskLimitKind,
   AskLimitOutcome,
   AskStalledOutcome,
+  ModelResolutionOutcome,
   YaagErrorCode,
 } from "./errors.ts";
 export { isYaagError, YaagError } from "./errors.ts";
@@ -68,6 +81,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();
+}