@yaag/cli 0.6.2 → 0.8.0

package/README.md

@@ -0,0 +1,31 @@
+# @yaag/cli
+
+The `yaag` CLI. It runs an Orchestration Program on Bun, describes one, and
+prepares a workspace for authoring.
+
+## Install
+
+```bash
+bun add @yaag/cli
+```
+
+The CLI needs Bun. Install Bun with `curl -fsSL https://bun.sh/install | bash`.
+
+## Commands
+
+- `yaag run <program.ts>` — run an Orchestration Program. `--args <json>`,
+  `--record <file>`, `--resume <file>`, `--replay <file>`, `--quiet`.
+- `yaag describe <program.ts>` — report the name, description, and args schema.
+- `yaag setup-workspace [dir]` — create `.yaag/` with the editor types.
+
+`yaag` with no valid command prints its usage text and exits with code 2.
+
+## Docs
+
+The full doc set ships with `@yaag/extension`:
+
+- [`getting-started.md`](../../packages/extension/docs/getting-started.md)
+- [`authoring.md`](../../packages/extension/docs/authoring.md)
+- [`examples.md`](../../packages/extension/docs/examples.md)
+- [`cli.md`](../../packages/extension/docs/cli.md)
+- [`troubleshooting.md`](../../packages/extension/docs/troubleshooting.md)

package/assets/types/runtime/agent/agent.d.ts

@@ -1,7 +1,16 @@
 import type { Static, TSchema } from "typebox";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentStats, AgentTransport } from "../transport/index.ts";
 import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.ts";
+/** The mid-Ask Model Resolution one Agent's spawn handed it (ADR-0038). */
+export interface AgentModelFallback {
+    readonly resolution: ModelResolution;
+    /** The Agent-wide attempt history, shared with its spawn loop. */
+    readonly history: ModelErrorHistory;
+    /** The model candidate this Agent's spawn settled on. */
+    readonly candidate: string;
+}
 export interface AgentOptions {
     readonly name: string;
     readonly cwd: string;
@@ -10,6 +19,11 @@ export interface AgentOptions {
     readonly emit: EventSink;
     /** The options this Agent was spawned with, for the ADR-0014 Ask hash. */
     readonly spawnOptions: ResolvedSpawnOptions;
+    /**
+     * Mid-Ask Model Resolution for this Agent, sharing the spawn loop's history.
+     * Absent when the spawn named no candidate: there is nothing to fall back from.
+     */
+    readonly modelFallback?: AgentModelFallback;
     /** Definition-owned defaults merged below explicit per-Ask options. */
     readonly askDefaults?: AskOptions;
     /** Definition identity recorded on its Asks, outside replay identity. */
@@ -27,8 +41,9 @@ export declare class Agent implements Handle {
     readonly name: string;
     readonly cwd: string;
     readonly branch: string | undefined;
-    readonly model: string;
     constructor(options: AgentOptions);
+    /** The model pi reports for this Agent now; a mid-Ask swap updates it. */
+    get model(): string;
     ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;
     ask(prompt: string, options?: AskOptions): Promise<string>;
     /** True when the Agent was killed mid-Ask, so its cost is a floor (ADR-0012). */

package/assets/types/runtime/agent/define-agent.d.ts

@@ -12,10 +12,18 @@ export interface AgentConfig {
     /**
      * Model id handed to `pi --model`. Unset = pi's default. An array is an ordered
      * fallback list, a function picks the next candidate from the failures so far,
-     * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`).
+     * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`),
+     * which wins over `thinking`. Each attempt settles the model first, then the
+     * thinking level for that model. yaag starts a new attempt only when pi
+     * reports `not_found`, `auth`, or `rate_limited` (ADR-0037).
      */
     readonly model?: ModelSpec;
-    /** Thinking budget for the Agent's turns, as a level or a resolver. */
+    /**
+     * Thinking budget for the Agent's turns, as a level or a resolver. The
+     * resolver runs again for each attempt, with the model that settled for that
+     * attempt. A resolver kept in a definition is frozen policy, so it must stay
+     * pure and synchronous (ADR-0037).
+     */
     readonly thinking?: ThinkingSpec;
     /** Allow-list of tool names. Unset = pi's default tool set. */
     readonly tools?: readonly string[];
@@ -25,6 +33,13 @@ export interface AgentConfig {
     readonly skills?: readonly string[];
     /** Deny-list of skill names, applied after `skills`. */
     readonly disallowedSkills?: readonly string[];
+    /**
+     * Load the Effective Config's `agents.extensions` for Agents of this
+     * definition. Default true. A spawn's own `SpawnOptions.configExtensions`
+     * wins over this value; spawn *overrides* stay topology-only, so the opt-out
+     * is not one of them (ADR-0019, ADR-0040).
+     */
+    readonly configExtensions?: boolean;
     /** Ask options applied to every Ask on this Agent unless overridden per call. */
     readonly askDefaults?: AskOptions;
 }
@@ -40,7 +55,9 @@ export interface AgentDefinition {
  * Throws a TypeError when `name` is missing or blank, or when `cwd`/`worktree`
  * appear — those are topology, chosen at spawn time, not baked into a definition.
  * The config is defensively copied and deep-frozen, so later mutation of the
- * caller's arrays cannot change the definition.
+ * caller's arrays cannot change the definition. `defineAgent` also copies and
+ * freezes a model array, so a later change of the caller's array cannot change
+ * Model Resolution (ADR-0037).
  */
 export declare function defineAgent(config: AgentConfig): AgentDefinition;
 /** True only for values produced by `defineAgent`. */

package/assets/types/runtime/agent/spawn-extensions.d.ts

@@ -0,0 +1,39 @@
+import type { ConfigExtension } from "../config/index.ts";
+/** Everything one spawn needs to turn declarations into `-e` arguments. */
+export interface SpawnExtensionRequest {
+    /** Effective Config entries in merge order: global → project → run (spec rule 3). */
+    readonly configExtensions: readonly ConfigExtension[];
+    /** `SpawnOptions.extensions`, resolved against the program file as before. */
+    readonly declared?: readonly string[] | undefined;
+    /** False when the spawn or its definition opted out (spec rule 7). */
+    readonly useConfigExtensions: boolean;
+    /** Orchestration Program source path, the base of a relative spawn declaration. */
+    readonly programFile?: string | undefined;
+    /** Agent working directory, the project install root for `npm:`/`git:`. */
+    readonly projectRoot: string;
+}
+/** The two projections of one Agent's extensions: what launches, and what identifies. */
+export interface SpawnExtensions {
+    /** Absolute launch-ready `-e` arguments, deduplicated, in final order. */
+    readonly resolvedPaths: readonly string[];
+    /** The surviving declarations behind them, same order, unresolved (ADR-0040). */
+    readonly declared: readonly string[];
+}
+/**
+ * Resolves the extensions of one Agent: config-sourced first, spawn-declared
+ * last, deduplicated by resolved path with the first occurrence keeping its
+ * place. Returns undefined when nothing is declared at all, so an
+ * extension-free spawn keeps its request shape.
+ *
+ * The two bases are deliberately different: a relative *path* from a config
+ * file resolves against that file's directory, while an `npm:`/`git:`
+ * specifier still installs from the Agent working directory (`projectRoot`).
+ * An uninstalled specifier passes through verbatim and dedups by its literal
+ * string.
+ *
+ * A declaration joins `declared` only when it contributed at least one new
+ * resolved path, so the identity list describes what actually ran. Two
+ * different declarations that resolve to the same path therefore keep only the
+ * first, which is machine-dependent by nature of the resolution itself.
+ */
+export declare function resolveSpawnExtensions(request: SpawnExtensionRequest): Promise<SpawnExtensions | undefined>;

package/assets/types/runtime/agent/spawn-request.d.ts

@@ -0,0 +1,24 @@
+import type { ModelSelection } from "../model/index.ts";
+import type { OpenOptions } from "../transport/index.ts";
+import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
+/** Everything one spawn needs to build its open request, before a model settles. */
+export interface OpenRequestOptions {
+    readonly name: string;
+    readonly cwd: string;
+    readonly spawnOptions: SpawnOptions;
+    readonly resolvedExtensionPaths?: readonly string[];
+    readonly declaredExtensions?: readonly string[];
+    readonly sessionDir: string | undefined;
+}
+/**
+ * Builds one spawn's open request from its options.
+ *
+ * A caller that has not settled a model yet passes the declared options: the
+ * request then carries a literal `model`/`thinking` and carries none for an
+ * array or resolver spec. That request is what a Cassette-backed factory peeks
+ * at, which is why the resume peek blanks model and thinking before it compares
+ * the request with the recorded spawn (ADR-0039).
+ */
+export declare function openRequest(options: OpenRequestOptions): OpenOptions;
+/** Replaces the caller's `model`/`thinking` forms with one attempt's settled selection. */
+export declare function withSelection(options: SpawnOptions, selection: ModelSelection): ResolvedSpawnOptions;

package/assets/types/runtime/agent/spawn.d.ts

@@ -1,3 +1,4 @@
+import type { ConfigExtension } from "../config/index.ts";
 import type { EventSink } from "../events.ts";
 import type { RunContext } from "../run/index.ts";
 import type { TransportFactory } from "../transport/index.ts";
@@ -9,6 +10,8 @@ export interface SpawnDependencies {
     readonly emit: EventSink;
     readonly sessionDir: string | undefined;
     readonly programFile: string | undefined;
+    /** Effective Config entries, in merge order; empty when the Run has no config. */
+    readonly configExtensions: readonly ConfigExtension[];
 }
 /** A RunContext spawn function that can synchronously stop accepting new Agents. */
 export interface SpawnGate {

package/assets/types/runtime/ask/ask-exchange-events.d.ts

@@ -1,4 +1,5 @@
 import type { AgentActivity, AskOutputChannel, EventSink } from "../events.ts";
+import type { ModelFallback } from "../model/index.ts";
 import type { NodeSnapshot } from "../node/index.ts";
 import type { SettlementCause } from "./stall-watchdog.ts";
 /** What one finished Ask reports in its `ask_end` Lifecycle Event. */
@@ -9,7 +10,10 @@ export interface AskEndOutcome {
     readonly maxFrameGapMs: number | undefined;
     readonly cause?: SettlementCause;
 }
-/** Emits the four Ask-scoped Lifecycle Events for one exchange. */
+/**
+ * Emits the Ask-scoped Lifecycle Events for one exchange, plus the Agent-scoped
+ * `model_fallback` this exchange's fallback loop reports.
+ */
 export declare class AskEvents {
     #private;
     constructor(emit: EventSink, agent: string, index: number);
@@ -18,6 +22,8 @@ export declare class AskEvents {
     output: (channel: AskOutputChannel, text: string) => void;
     /** Composes the Nested Node path from this Ask's identity, then reports it. */
     node: (snapshot: NodeSnapshot) => void;
+    /** Not Ask-scoped: a fallback names the Agent only, like the spawn-time loop. */
+    fallback: (fallback: ModelFallback) => void;
     /** A `normal` cause is the absent default, so ordinary settlements stay lean. */
     end(outcome: AskEndOutcome): void;
 }

package/assets/types/runtime/ask/ask-exchange-options.d.ts

@@ -1,5 +1,6 @@
 import type { ReportResultTool } from "../ask-contract/index.ts";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentTransport, Connection, Frame } from "../transport/index.ts";
 import type { ResolvedSpawnOptions } from "../types.ts";
 import type { EffectiveAskOptions } from "./ask-hash.ts";
@@ -7,6 +8,15 @@ import type { EffectiveAskOptions } from "./ask-hash.ts";
 export interface FrameObserver {
     observe(frame: Frame): void;
 }
+/** Mid-Ask Model Resolution for one Agent, shared with its spawn-time loop. */
+export interface AskModelFallback {
+    readonly resolution: ModelResolution;
+    readonly history: ModelErrorHistory;
+    /** The model candidate the Agent runs right now; a failure is attributed to it. */
+    currentModel(): string;
+    /** Reports the candidate a successful swap applied, and the model pi now reports. */
+    onSwapped(candidate: string, reportedModel: string): void;
+}
 /** Options that connect one Ask exchange to its Agent's identity and event stream. */
 export interface AskExchangeOptions {
     readonly agent: string;
@@ -23,6 +33,8 @@ export interface AskExchangeOptions {
     readonly emit: EventSink;
     /** The Agent's persistent usage accumulator; fed frames only during live Asks. */
     readonly usage: FrameObserver;
+    /** Mid-Ask Model Resolution; absent when this Agent's spawn named no candidate. */
+    readonly modelFallback: AskModelFallback | undefined;
     /** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
     readonly close: () => void;
     /** Test-only override for the fixed duration-limit grace. */

package/assets/types/runtime/ask/index.d.ts

@@ -3,5 +3,6 @@
  * Files inside this directory import each other directly.
  */
 export { exchangeAsk } from "./ask-exchange.ts";
+export type { AskModelFallback } from "./ask-exchange-options.ts";
 export { askHash, askMarkerContext, type EffectiveAskOptions } from "./ask-hash.ts";
 export type { SettlementCause } from "./stall-watchdog.ts";

package/assets/types/runtime/cassette/cassette-schema.d.ts

@@ -30,6 +30,7 @@ export declare const CassetteSchema: Type.TObject<{
             name: Type.TString;
             cwd: Type.TString;
             worktree: Type.TOptional<Type.TLiteral<true>>;
+            declaredExtensions: Type.TOptional<Type.TArray<Type.TString>>;
         }>;
         model: Type.TString;
         sessionFile: Type.TOptional<Type.TString>;

package/assets/types/runtime/cassette/cassette.d.ts

@@ -67,6 +67,11 @@ export interface CassetteSpawn {
     readonly disallowedSkills?: readonly string[];
     /** Deterministic request, present only when the Agent requested a worktree. */
     readonly worktree?: true;
+    /**
+     * Declared extensions in declaration order, unresolved so a Cassette matches
+     * across machines (ADR-0040). Absent when the Agent ran no extension.
+     */
+    readonly declaredExtensions?: readonly string[];
 }
 /** The frames attributed to one Ask marker. */
 export interface CassetteAsk {

package/assets/types/runtime/cassette/replay-divergence.d.ts

@@ -1,5 +1,5 @@
-import type { AskMarker, OpenOptions } from "../transport/index.ts";
-import type { CassetteAgent } from "./cassette.ts";
+import type { AskMarker, OpenOptions, RecordedSpawnSelection } from "../transport/index.ts";
+import type { CassetteAgent, CassetteSpawn } from "./cassette.ts";
 /** A pure description of the first strict replay identity mismatch. */
 export interface ReplayMismatch {
     readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
@@ -17,3 +17,11 @@ export declare const replayMismatch: {
 };
 /** Converts a detected mismatch into strict replay's public failure. */
 export declare function strictReplay(mismatch: ReplayMismatch): never;
+/**
+ * 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 declare function spawnMatchesExceptModel(expected: CassetteSpawn, actual: OpenOptions): boolean;
+/** The recorded resolved selection of one Agent, or `undefined` when none is recorded. */
+export declare function recordedSpawnSelection(agent: CassetteAgent | null): RecordedSpawnSelection | undefined;

package/assets/types/runtime/config/config-file.d.ts

@@ -0,0 +1,22 @@
+import { type YaagConfigDocument } from "./config-schema.ts";
+/** One config file that contributed to the Effective Config. */
+export interface ConfigLayer {
+    /** The file this layer was read from. */
+    readonly file: string;
+    /** The file's own directory: relative paths inside it resolve here (spec rule 4). */
+    readonly directory: string;
+    readonly document: YaagConfigDocument;
+}
+/** Whether an absent file is an empty layer or a Run-start failure. */
+export interface ReadConfigOptions {
+    /** True for the explicit Run Config: a missing file is then an error. */
+    readonly required: boolean;
+}
+/**
+ * Reads, parses, and validates one config layer.
+ *
+ * A missing file at a discovered location yields `undefined` (an empty layer);
+ * a missing explicit Run Config fails. Any other errno — `EACCES`, say — always
+ * throws: a config yaag cannot read is not an empty config.
+ */
+export declare function readConfigLayer(path: string, options: ReadConfigOptions): Promise<ConfigLayer | undefined>;

package/assets/types/runtime/config/config-issues.d.ts

@@ -0,0 +1,12 @@
+import type { TLocalizedValidationError } from "typebox/error";
+/**
+ * Turns TypeBox errors into config diagnostics that name the offending key
+ * (spec rule 2).
+ *
+ * A strict object reports an unknown key twice: once at the key itself with the
+ * unhelpful `"schema is false"`, and once at the owning object carrying the key
+ * name. Neither alone reads well, so the pair collapses into one line. Every
+ * other keyword delegates to the shared formatter, which stays untouched
+ * because args validation and ADR-0032 steering text depend on its wording.
+ */
+export declare function describeConfigIssues(value: unknown, errors: Iterable<TLocalizedValidationError>): readonly string[];

package/assets/types/runtime/config/config-paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The part of the environment this module reads. It is structural on purpose:
+ * the vendored declaration tree compiles with no ambient Node globals.
+ */
+export interface ConfigEnvironment {
+    readonly [name: string]: string | undefined;
+}
+/** Every config layer lives in a file with this name. */
+export declare const CONFIG_FILE_NAME = "config.json";
+/** The Project Config directory inside a Program Directory. */
+export declare const PROJECT_CONFIG_DIR = ".yaag";
+/**
+ * Resolves the Global Config path: `YAAG_CONFIG_DIR`, then an absolute
+ * `XDG_CONFIG_HOME`, then `$HOME/.config`. A relative `XDG_CONFIG_HOME` is
+ * ignored (XDG spec), exactly as in `resolveCheckpointDirectory`.
+ */
+export declare function resolveGlobalConfigPath(env?: ConfigEnvironment): string;
+/**
+ * Resolves the Project Config path under a Program Directory. The Program
+ * Directory is an input: this module never walks upward looking for `.yaag/`.
+ */
+export declare function projectConfigPath(programDirectory: string): string;

package/assets/types/runtime/config/config-schema.d.ts

@@ -0,0 +1,17 @@
+import { type Static, Type } from "typebox";
+/**
+ * The config document of one layer (spec rule 1): plain JSON, namespaced as
+ * `{ "agents": { "extensions": ["..."] } }`.
+ *
+ * Every node sets `additionalProperties: false` on purpose (spec rule 2) — the
+ * opposite choice from `cassette-schema.ts`, which tolerates unknown fields so
+ * a newer artifact still loads. A config file is hand-written, so an unknown
+ * key is a typo the author wants named, not forward compatibility.
+ */
+export declare const YaagConfigSchema: Type.TObject<{
+    agents: Type.TOptional<Type.TObject<{
+        extensions: Type.TOptional<Type.TArray<Type.TString>>;
+    }>>;
+}>;
+/** The validated shape of one config file. */
+export type YaagConfigDocument = Static<typeof YaagConfigSchema>;

package/assets/types/runtime/config/effective-config.d.ts

@@ -0,0 +1,42 @@
+import { type ConfigEnvironment } 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 declare const EMPTY_EFFECTIVE_CONFIG: EffectiveConfig;
+/**
+ * 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 declare function loadEffectiveConfig(request?: EffectiveConfigRequest): Promise<EffectiveConfig>;

package/assets/types/runtime/config/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/assets/types/runtime/errors.d.ts

@@ -5,7 +5,9 @@ export interface AskLimitOutcome {
     readonly kind: AskLimitKind;
     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`. */
 export interface AskStalledOutcome {
@@ -23,8 +25,12 @@ export interface AskInvalidOutputOutcome {
     /** Final extraction or TypeBox diagnostics, localized to JSON paths. */
     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" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "SPAWN_FAILED";
+export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "CONFIG_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "MODEL_RESOLUTION_FAILED" | "SPAWN_FAILED";
 /** The single error class of the runtime (ADR-0003). */
 export declare class YaagError extends Error {
     readonly code: YaagErrorCode;
@@ -44,7 +50,13 @@ export declare class YaagError extends Error {
     readonly steeringEfforts?: number;
     /** Localized extraction or schema errors, present only for `ASK_INVALID_OUTPUT`. */
     readonly errors?: readonly string[];
-    constructor(code: YaagErrorCode, message: string, agent?: string, options?: AskLimitOutcome | AskStalledOutcome | AskInvalidOutputOutcome);
+    /**
+     * 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 | ModelResolutionOutcome);
 }
 /** Builds the runtime's uniform agent-scoped error message. */
 export declare function agentError(agent: string, code: YaagErrorCode, message: string): YaagError;
@@ -52,5 +64,7 @@ export declare function agentError(agent: string, code: YaagErrorCode, message:
 export declare function askLimitError(agent: string, outcome: AskLimitOutcome): YaagError;
 /** The ASK_STALLED rejection for one tripped idle watch. */
 export declare function askStalledError(agent: string, outcome: AskStalledOutcome): YaagError;
+/** The MODEL_RESOLUTION_FAILED rejection for an exhausted or self-repeating resolver. */
+export declare function modelResolutionError(agent: string, errors: readonly ModelError[], refusedCandidate?: string): YaagError;
 /** Narrows an unknown rejection reason to a YaagError. */
 export declare function isYaagError(value: unknown): value is YaagError;

package/assets/types/runtime/events.d.ts

@@ -7,8 +7,10 @@
  * 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.
  * `interrupted` is not terminal: only an in-flight Checkpoint carries it, and a
@@ -112,6 +114,22 @@ export type LifecycleEventBody = {
      * Watchdog settled it from observed state, so its usage is an undercount.
      */
     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/assets/types/runtime/extension/extension-paths.d.ts

@@ -3,14 +3,22 @@ import { type ExtensionInstallRoots } from "./extension-package.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 declare function resolveExtensionPaths(declarations: readonly string[], options?: ExtensionResolutionOptions): Promise<readonly string[]>;

package/assets/types/runtime/index.d.ts

@@ -2,7 +2,9 @@ export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
 export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./agent/index.ts";
 export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette/index.ts";
 export { assertReplayable, CASSETTE_VERSION, loadCassette, recordingTransport, replayTransport, resumeTransport, } from "./cassette/index.ts";
-export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, YaagErrorCode, } from "./errors.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";
 export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, StampedEventSink, } from "./events.ts";
 export type { ModelError, ModelErrorReason, ModelResolver, ModelSelection, ModelSpec, ThinkingResolver, ThinkingSpec, } from "./model/index.ts";
@@ -11,7 +13,7 @@ export { agentAskPath, childPath, DEFAULT_NODE_DECODERS, NodeTracker, sanitizeNo
 export { prompt, promptGist } from "./prompt/index.ts";
 export type { OrchestrationProgram, ProgramDefinition, RunContext, RunOptions, } from "./run/index.ts";
 export { defineRun, executeRun, isOrchestrationProgram, programDefinition } from "./run/index.ts";
-export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary/index.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary/index.ts";
 export { applyEvent, initialSummary } from "./summary/index.ts";
 export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, DiscoveredSkill, Frame, ReapPath, ReapTarget, SkillProbeFactory, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport/index.ts";
 export { readSystemPromptSidecar, reap, worktreeTransport } from "./transport/index.ts";

package/assets/types/runtime/model/index.d.ts

@@ -2,5 +2,12 @@
  * Public surface of the `model/` module: model resolution.
  * Files inside this directory import each other directly.
  */
-export { type ModelError, type ModelErrorReason, type ModelResolver, type ModelSelection, type ModelSpec, normalizeModelResolution, type ThinkingResolver, type ThinkingSpec, } from "./model-resolution.ts";
+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, normalizeModelResolution, 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/assets/types/runtime/model/model-error-history.d.ts

@@ -0,0 +1,20 @@
+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 declare class ModelErrorHistory {
+    #private;
+    /** Every failed attempt so far, oldest first. */
+    get errors(): readonly ModelError[];
+    /**
+     * Appends one failed attempt and returns it; the attempt number is the
+     * history length before the push.
+     */
+    record(reason: ModelErrorReason, failedModel: string): ModelError;
+    /** True when this candidate already failed for a reason a retry cannot fix. */
+    failedPermanently(candidate: string): boolean;
+}

package/assets/types/runtime/model/model-failure.d.ts

@@ -0,0 +1,18 @@
+import type { ModelErrorReason } from "./model-resolution.ts";
+/**
+ * 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 declare function classifyModelFailure(error: unknown): ModelErrorReason | 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 declare function classifyAskFailure(error: unknown): ModelErrorReason | undefined;