@yaag/runtime 0.6.2 → 0.8.0

package/src/ask/ask-exchange.ts

@@ -17,6 +17,7 @@ import {
   askStalledError,
   isYaagError,
 } from "../errors.ts";
+import { retryOnModelFailure, swapModel } from "../model/index.ts";
 import { NodeTracker } from "../node/index.ts";
 import type { AskPlayback } from "../transport/index.ts";
 import { FrameGapTracker } from "../transport/index.ts";
@@ -43,7 +44,7 @@ export async function exchangeAsk(options: AskExchangeOptions): Promise<unknown>
 }
 class AskExchange {
   readonly #options: AskExchangeOptions;
-  readonly #turn = new AskTurn();
+  #turn = new AskTurn();
   readonly #events: AskEvents;
   #limit: AskLimit | null = null;
   #idle: IdleWatch | null = null;
@@ -73,16 +74,48 @@ class AskExchange {
 
   async run(): Promise<unknown> {
     const startedAt = Date.now();
+    this.#openEnvelope();
     try {
-      const result = await this.#exchange();
+      const result = await this.#attempts();
       this.#events.end(this.#endOutcome(startedAt, true));
       return result;
     } catch (error) {
       if (this.#began) this.#events.end(this.#endOutcome(startedAt, false));
       throw error;
+    } finally {
+      this.#finish();
     }
   }
 
+  /**
+   * Runs the Ask, retrying it on a swapped-in model when a model failure ends an
+   * attempt. Every attempt stays inside one Ask envelope, so one Ask still emits
+   * exactly one `ask_start`, one `ask_end` and one recorded Cassette Ask.
+   */
+  async #attempts(): Promise<unknown> {
+    const fallback = this.#options.modelFallback;
+    if (fallback === undefined) return await this.#exchange();
+    return await retryOnModelFailure({
+      resolution: fallback.resolution,
+      agent: this.#options.agent,
+      history: fallback.history,
+      onFallback: this.#events.fallback,
+      currentModel: () => fallback.currentModel(),
+      attempt: async () => await this.#exchange(),
+      swap: async (selection) => {
+        // Replay re-runs this loop and re-sends the recorded swap frames, which
+        // CassetteReplay matches as ordinary frames (ADR-0039). The Ask keeps its
+        // spawn-time identity, so the retry records under the same hash.
+        const swapped = await swapModel({
+          agent: this.#options.agent,
+          command: async (frame) => await this.#options.connection.command(frame),
+          selection,
+        });
+        fallback.onSwapped(selection.model ?? swapped.model, swapped.model);
+      },
+    });
+  }
+
   #endOutcome(startedAt: number, ok: boolean): AskEndOutcome {
     return {
       durationMs: Date.now() - startedAt,
@@ -94,8 +127,7 @@ class AskExchange {
 
   async #exchange(): Promise<unknown> {
     try {
-      this.#begin();
-      this.#timeoutDeadline = this.#deadline();
+      this.#armAttempt();
       // The schema command is answered without a turn, so settlement tracking
       // starts after it: nothing it could emit may settle this Ask (ADR-0032).
       await this.#deliverSchema();
@@ -119,11 +151,12 @@ class AskExchange {
       this.#recordInvalidOutput(error);
       throw error;
     } finally {
-      this.#cleanup();
+      this.#cleanupAttempt();
     }
   }
 
-  #begin(): void {
+  /** Opens the Ask envelope: identity, recording and the Ask-scoped events. Once per Ask. */
+  #openEnvelope(): void {
     this.#legacyExtraction = this.#recordedLegacyPolicy();
     const outputContract = structuredOutputContract(
       this.#options.ask,
@@ -147,7 +180,27 @@ class AskExchange {
     });
     this.#began = true;
     this.#playback = playback;
+    // `timeoutMs` is the Ask's hard ceiling and kills the Agent (ADR-0003), so
+    // it is Ask-scoped: retries share one deadline, unlike the soft limits.
+    this.#timeoutDeadline = this.#deadline();
     this.#events.start(this.#options.prompt, playback !== undefined);
+  }
+
+  /**
+   * Arms one attempt: fresh turn tracking, limits, watches and report_result
+   * state, so a retry starts from nothing — the failed attempt's work died with
+   * its model error, and its stale reported result cannot settle the retry.
+   */
+  #armAttempt(): void {
+    const playback = this.#playback;
+    this.#turn = new AskTurn();
+    this.#outcome = undefined;
+    this.#stalled = undefined;
+    // A failed attempt's stall recovery and invalid output describe work that
+    // died with it, so neither may reach the Ask's single `ask_end` or its one
+    // recorded completion when a later attempt settles cleanly.
+    this.#cause = "normal";
+    this.#invalidOutput = undefined;
     this.#gap = playback === undefined ? new FrameGapTracker() : null;
     this.#activity = playback === undefined ? new AskActivityTracker(this.#events.activity) : null;
     this.#output =
@@ -443,15 +496,23 @@ class AskExchange {
       this.#invalidOutput = { kind: "invalid_output", steeringEfforts: error.steeringEfforts ?? 0 };
   }
 
-  #cleanup(): void {
-    this.#maxFrameGapMs = this.#gap?.maxGapMs;
+  /** Ends one attempt; the envelope stays open, so a retry can arm the next one. */
+  #cleanupAttempt(): void {
+    this.#maxFrameGapMs = maxGap(this.#maxFrameGapMs, this.#gap?.maxGapMs);
     this.#stalled ??= this.#idle?.result ?? this.#stall?.result ?? undefined;
     this.#limit?.cleanup();
     this.#idle?.cleanup();
     this.#stall?.cleanup();
     this.#output?.close();
+    if (this.#drainStaleFrames) {
+      this.#options.connection.drainStaleTurn();
+      this.#drainStaleFrames = false;
+    }
+  }
+
+  /** Closes the Ask envelope: one `finishAsk` for the whole Ask, retries included. */
+  #finish(): void {
     this.#options.connection.observe(null);
-    if (this.#drainStaleFrames) this.#options.connection.drainStaleTurn();
     if (!this.#began) return;
     try {
       this.#options.transport.finishAsk({
@@ -465,3 +526,10 @@ class AskExchange {
     }
   }
 }
+
+/** The widest frame gap seen across an Ask's attempts. */
+function maxGap(left: number | undefined, right: number | undefined): number | undefined {
+  if (left === undefined) return right;
+  if (right === undefined) return left;
+  return Math.max(left, right);
+}

package/src/ask/index.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/src/cassette/cassette-publish.ts

@@ -21,7 +21,11 @@ export async function publishCassette(path: string, cassette: Cassette): Promise
     await syncDirectory(directory);
   } catch (error) {
     await discard(temp);
-    throw new Error(`failed to publish cassette ${path}: ${String(error)}`, { cause: error });
+    throw new Error(
+      `failed to publish cassette ${path}: ${String(error)}; ` +
+        "see @yaag/extension docs/troubleshooting.md#failed-to-publish-cassette",
+      { cause: error },
+    );
   }
 }
 

package/src/cassette/cassette-replay.ts

@@ -48,6 +48,11 @@ export class CassetteReplay {
         this.#releaseOneResponse();
         return;
       }
+      // A recorded swap ends one Ask attempt (ADR-0038): the prompt that
+      // follows is the retry, not an ADR-0027 correction, so the floor moves.
+      if (expected.type === "set_model" || expected.type === "set_thinking_level") {
+        this.#openAttempt(this.#sentCursor);
+      }
       this.#releaseFor(frame.type);
       this.#consumeControls();
       return;
@@ -72,10 +77,7 @@ export class CassetteReplay {
     this.#receivedCursor = 0;
     this.#sent = ask.sentFrames;
     this.#received = ask.receivedFrames;
-    // A schema-bearing Ask opens with the report_result schema command, so the
-    // Ask's own prompt is the second sent frame, not the first (ADR-0032).
-    const first = ask.sentFrames[0];
-    this.#promptFloor = first !== undefined && isReportResultCommandFrame(first) ? 1 : 0;
+    this.#openAttempt(0);
     const awaitsAbortSettlement = abortSettlementFollowsFinalText(ask);
     const settles = ask.receivedFrames.some((frame) => frame.type === "agent_settled");
     const reported = recordedReportedResult(ask);
@@ -95,6 +97,19 @@ export class CassetteReplay {
     this.#queue.end();
   }
 
+  /**
+   * Opens one Ask attempt at `cursor`: the first prompt at or after it is the
+   * attempt's own prompt, and every later prompt is a recorded correction.
+   *
+   * A schema-bearing attempt opens with the report_result schema command, so
+   * its own prompt is the second sent frame, not the first (ADR-0032).
+   */
+  #openAttempt(cursor: number): void {
+    const first = this.#sent[cursor];
+    this.#promptFloor =
+      first !== undefined && isReportResultCommandFrame(first) ? cursor + 1 : cursor;
+  }
+
   #consumeControls(): void {
     for (;;) {
       const expected = this.#sent[this.#sentCursor];
@@ -110,6 +125,10 @@ export class CassetteReplay {
    * amendment). A recorded `get_state` is a Stall Watchdog probe: replay is
    * never silent, so it never probes, and the recorded exchange is consumed
    * here instead of blocking the frames that follow it (ADR-0029).
+   *
+   * A recorded `get_available_models`/`set_model` pair is deliberately not a
+   * control: replay re-runs the mid-Ask Model Resolution and sends those
+   * commands itself, so `send()` matches them like any other frame (ADR-0039).
    */
   #isRecordedControl(frame: Frame): boolean {
     if (frame.type === "steer" || frame.type === "abort" || frame.type === "get_state") return true;

package/src/cassette/cassette-schema.ts

@@ -37,6 +37,7 @@ const CassetteSpawnSchema = Type.Object({
   cwd: Type.String(),
   ...spawnPolicyFields,
   worktree: Type.Optional(Type.Literal(true)),
+  declaredExtensions: Type.Optional(StringArray),
 });
 
 const ContextSpawnSchema = Type.Object({

package/src/cassette/cassette.ts

@@ -83,6 +83,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. */
@@ -264,6 +269,9 @@ function spawnIdentity(options: OpenOptions): CassetteSpawn {
     ...(options.disallowedSkills === undefined
       ? {}
       : { disallowedSkills: [...options.disallowedSkills] }),
+    ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
+      ? {}
+      : { declaredExtensions: [...options.declaredExtensions] }),
     ...(options.worktree === true ? { worktree: true } : {}),
   };
 }

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 {
@@ -62,24 +73,91 @@ export const replayMismatch = {
   },
 };
 
+/** Where a user reads what a Divergence means and what to do about it. */
+const DOCS_POINTER = "; see @yaag/extension docs/troubleshooting.md#replay-or-resume-mismatch";
+
 /** Converts a detected mismatch into strict replay's public failure. */
 export function strictReplay(mismatch: ReplayMismatch): never {
   if (mismatch.kind === "changed-ask" && mismatch.definitionName !== undefined) {
     const fields = mismatch.changedFields?.join(", ") ?? "hash inputs";
     throw new YaagError(
       "REPLAY_DIVERGED",
-      `replay diverged for agent "${mismatch.agent}" at ask #${mismatch.index}: definition "${mismatch.definitionName}" changed since recording (${fields})`,
+      `replay diverged for agent "${mismatch.agent}" at ask #${mismatch.index}: definition "${mismatch.definitionName}" changed since recording (${fields})${DOCS_POINTER}`,
       mismatch.agent,
     );
   }
   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}${DOCS_POINTER}`,
     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. Extensions are the deliberate exception: they identify the process
+ * start, not an Ask, so they join only the open-request list below.
+ */
+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, "declaredExtensions"] 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 +171,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",
@@ -150,6 +213,9 @@ function spawnHash(options: CassetteSpawn | OpenOptions): string {
       ...(options.appendSystemPrompt === undefined
         ? {}
         : { appendSystemPrompt: options.appendSystemPrompt }),
+      ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
+        ? {}
+        : { declaredExtensions: options.declaredExtensions }),
     }),
   );
   return hasher.digest("hex");

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/config/config-file.ts

@@ -0,0 +1,67 @@
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Value } from "typebox/value";
+import { YaagError } from "../errors.ts";
+import { describeConfigIssues } from "./config-issues.ts";
+import { type YaagConfigDocument, YaagConfigSchema } 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 async function readConfigLayer(
+  path: string,
+  options: ReadConfigOptions,
+): Promise<ConfigLayer | undefined> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissing(error)) {
+      if (!options.required) return undefined;
+      throw invalid(`config file "${path}" does not exist`);
+    }
+    throw invalid(`cannot read config "${path}": ${String(error)}`);
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw invalid(`cannot parse config "${path}": ${String(error)}`);
+  }
+  const errors = Value.Errors(YaagConfigSchema, value);
+  if (errors.length > 0) {
+    throw invalid(`invalid config "${path}": ${describeConfigIssues(value, errors).join("; ")}`);
+  }
+  // Sound: the strict schema above accepted `value`, so it has exactly this shape.
+  const document = value as YaagConfigDocument;
+  return { file: path, directory: dirname(path), document };
+}
+
+function invalid(message: string): YaagError {
+  return new YaagError("CONFIG_INVALID", message);
+}
+
+function isMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  const { code } = error;
+  return code === "ENOENT" || code === "ENOTDIR";
+}

package/src/config/config-issues.ts

@@ -0,0 +1,31 @@
+import type { TLocalizedValidationError } from "typebox/error";
+import { formatValidationErrors } from "../validation-errors.ts";
+
+/**
+ * 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 function describeConfigIssues(
+  value: unknown,
+  errors: Iterable<TLocalizedValidationError>,
+): readonly string[] {
+  return Array.from(errors).flatMap((error) => {
+    if (error.keyword === "additionalProperties") {
+      const [line] = formatValidationErrors(value, [error]);
+      // The formatter renders `<path>: <message>`; the message carries no colon,
+      // so the last one is the separator even for quoted path segments.
+      const prefix = line === undefined ? "$" : line.slice(0, line.lastIndexOf(":"));
+      return error.params.additionalProperties.map(
+        (key) => `${prefix}: unknown key ${JSON.stringify(key)}`,
+      );
+    }
+    if (error.keyword === "boolean") return [];
+    return formatValidationErrors(value, [error]);
+  });
+}

package/src/config/config-paths.ts

@@ -0,0 +1,38 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+/**
+ * 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 const CONFIG_FILE_NAME = "config.json";
+
+/** The Project Config directory inside a Program Directory. */
+export 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 function resolveGlobalConfigPath(env: ConfigEnvironment = process.env): string {
+  const override = env["YAAG_CONFIG_DIR"];
+  if (override !== undefined && override !== "") return join(override, CONFIG_FILE_NAME);
+  const xdg = env["XDG_CONFIG_HOME"];
+  if (xdg !== undefined && isAbsolute(xdg)) return join(xdg, "yaag", CONFIG_FILE_NAME);
+  const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir();
+  return join(home, ".config", "yaag", CONFIG_FILE_NAME);
+}
+
+/**
+ * Resolves the Project Config path under a Program Directory. The Program
+ * Directory is an input: this module never walks upward looking for `.yaag/`.
+ */
+export function projectConfigPath(programDirectory: string): string {
+  return join(programDirectory, PROJECT_CONFIG_DIR, CONFIG_FILE_NAME);
+}

package/src/config/config-schema.ts

@@ -0,0 +1,25 @@
+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 const YaagConfigSchema = Type.Object(
+  {
+    agents: Type.Optional(
+      Type.Object(
+        { extensions: Type.Optional(Type.Array(Type.String())) },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/** The validated shape of one config file. */
+export type YaagConfigDocument = Static<typeof YaagConfigSchema>;