@yaag/extension 0.6.2 → 0.8.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@yaag/extension",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "src",
+    "docs",
     "!src/**/*.test.ts"
   ],
   "type": "module",
@@ -24,9 +25,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.6.2",
-    "@yaag/runtime": "0.6.2",
-    "@yaag/tui": "0.6.2",
+    "@yaag/cli": "0.8.0",
+    "@yaag/runtime": "0.8.0",
+    "@yaag/tui": "0.8.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/docs/doc-embed.ts

@@ -0,0 +1,127 @@
+/**
+ * The drift guard behind every doc page: a fenced block must be a verbatim
+ * region of a real source file, and every block must name that file with an
+ * `<!-- embed: <source> -->` marker.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { docPath } from "./docs-root.ts";
+
+/** One fenced block of a page, with the marker that precedes it. */
+export interface DocBlock {
+  /** The page the block came from, relative to the docs root. */
+  readonly page: string;
+  /** The marker payload, e.g. `docs/examples/01-minimal.ts` or `@yaag/cli/src/argv.ts#USAGE`. */
+  readonly source: string | null;
+  /** The block body, without the fences and without a trailing newline. */
+  readonly body: string;
+  /** 1-based line of the opening fence, for a self-explaining failure. */
+  readonly line: number;
+}
+
+const MARKER = /^<!--\s*embed:\s*(.+?)\s*-->$/;
+
+/** Reads every fenced block of a page, together with its preceding marker. */
+export function readBlocks(page: string): DocBlock[] {
+  const lines = readFileSync(docPath(page), "utf8").split("\n");
+  const blocks: DocBlock[] = [];
+  let marker: string | null = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    const found = MARKER.exec(line.trim());
+    if (found?.[1] !== undefined) {
+      marker = found[1];
+      continue;
+    }
+    if (!line.startsWith("```")) continue;
+    const body: string[] = [];
+    index += 1;
+    const open = index;
+    while (index < lines.length && !(lines[index] ?? "").startsWith("```")) {
+      body.push(lines[index] ?? "");
+      index += 1;
+    }
+    blocks.push({ page, source: marker, body: body.join("\n"), line: open });
+    marker = null;
+  }
+  return blocks;
+}
+
+/** Resolves a marker payload to the text it must match. */
+export function resolveSource(spec: string): string {
+  const [path, constant] = spec.split("#");
+  const text = readFileSync(resolvePath(path ?? ""), "utf8");
+  return constant === undefined ? text : exportedString(text, constant, spec);
+}
+
+function resolvePath(path: string): string {
+  if (path.startsWith("docs/")) return docPath(path.slice("docs/".length));
+  if (path.startsWith("src/")) return fileURLToPath(new URL(`../../${path}`, import.meta.url));
+  const require = createRequire(import.meta.url);
+  const packaged = /^(@yaag\/[a-z]+)\/(src\/.+)$/.exec(path);
+  if (packaged?.[1] === "@yaag/runtime" && packaged[2] !== undefined) {
+    // @yaag/runtime publishes one entry point, so reach its files through it.
+    const entry = require.resolve("@yaag/runtime");
+    return join(entry.slice(0, entry.lastIndexOf("/src/")), packaged[2]);
+  }
+  return require.resolve(path);
+}
+
+/** Reads the body of `export const NAME = \`…\`;` out of a source file. */
+function exportedString(text: string, name: string, spec: string): string {
+  const start = text.indexOf(`export const ${name} = \``);
+  if (start === -1) throw new Error(`${spec}: no exported template string named ${name}`);
+  const from = text.indexOf("`", start) + 1;
+  const to = text.indexOf("`;", from);
+  if (to === -1) throw new Error(`${spec}: ${name} is not terminated`);
+  return text.slice(from, to);
+}
+
+/** One quoted message of a page, with the source it is guarded against. */
+export interface DocQuote {
+  readonly source: string;
+  readonly text: string;
+}
+
+const QUOTE_MARKER = /^<!--\s*quote:\s*(.+?)\s*-->$/;
+
+/**
+ * Reads every `> quoted` line of a markdown text with the
+ * `<!-- quote: <source> -->` marker that precedes it.
+ *
+ * One marker guards one quote: the marker is consumed, so a quote can never be
+ * compared with the file of the entry above it. Throws when a quote line has no
+ * marker of its own.
+ */
+export function readQuotes(markdown: string): DocQuote[] {
+  const found: DocQuote[] = [];
+  let source: string | null = null;
+  for (const line of markdown.split("\n")) {
+    const marker = QUOTE_MARKER.exec(line.trim());
+    if (marker?.[1] !== undefined) {
+      source = marker[1];
+      continue;
+    }
+    if (!line.startsWith("> ")) continue;
+    if (source === null) throw new Error(`quoted message with no marker: ${line}`);
+    found.push({ source, text: line.slice(2).trim() });
+    source = null;
+  }
+  return found;
+}
+
+/** Fails unless the block body appears line for line inside its source. */
+export function assertVerbatim(block: DocBlock): void {
+  if (block.source === null) throw new Error(describe(block, "carries no embed marker"));
+  const source = resolveSource(block.source);
+  const body = block.body.replace(/\s+$/, "");
+  if (source.replace(/\r/g, "").includes(body)) return;
+  throw new Error(describe(block, `is not verbatim in ${block.source}`));
+}
+
+function describe(block: DocBlock, what: string): string {
+  const first = block.body.split("\n")[0] ?? "";
+  return `${block.page}:${block.line} (\`${first}\`) ${what}`;
+}

package/src/docs/docs-root.ts

@@ -0,0 +1,32 @@
+/**
+ * The shipped docs folder. The repo path is the tarball path, so one constant
+ * serves the system prompt, the error messages, and the drift guards.
+ */
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Absolute path of the shipped `docs/` folder, with no trailing separator. */
+export const DOCS_ROOT = fileURLToPath(new URL("../../docs", import.meta.url));
+
+/** The five shipped pages, in reading order. */
+export const DOC_PAGES = [
+  "getting-started.md",
+  "authoring.md",
+  "examples.md",
+  "cli.md",
+  "troubleshooting.md",
+] as const;
+
+/** The five shipped example programs, in reading order. */
+export const EXAMPLE_FILES = [
+  "01-minimal.ts",
+  "02-args.ts",
+  "03-fan-out.ts",
+  "04-controlled-ask.ts",
+  "05-record-resume.ts",
+] as const;
+
+/** Absolute path of one shipped doc file, named relative to the docs root. */
+export function docPath(name: string): string {
+  return join(DOCS_ROOT, name);
+}

package/src/docs/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Public surface of the `docs/` module: where the shipped docs are, and the
+ * drift guard that keeps them true.
+ */
+export {
+  assertVerbatim,
+  type DocBlock,
+  type DocQuote,
+  readBlocks,
+  readQuotes,
+  resolveSource,
+} from "./doc-embed.ts";
+export { DOC_PAGES, DOCS_ROOT, docPath, EXAMPLE_FILES } from "./docs-root.ts";

package/src/process/run-argv.ts

@@ -15,6 +15,10 @@ export interface RunArgvOptions {
   readonly record?: string;
   /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
   readonly resume?: string;
+  /** Run Config path, forwarded as `--config` (ADR-0040). */
+  readonly config?: string;
+  /** Suppresses the discovered config layers, forwarded as `--no-config` (ADR-0040). */
+  readonly noConfig?: boolean;
 }
 
 /**
@@ -35,5 +39,7 @@ export function runArgv(options: RunArgvOptions): readonly string[] {
     ...(options.args === undefined ? [] : ["--args", options.args]),
     ...(options.record === undefined ? [] : ["--record", options.record]),
     ...(options.resume === undefined ? [] : ["--resume", options.resume]),
+    ...(options.config === undefined ? [] : ["--config", options.config]),
+    ...(options.noConfig === true ? ["--no-config"] : []),
   ];
 }

package/src/process/spawn-run.ts

@@ -26,6 +26,10 @@ export interface StartRunOptions {
   readonly record?: string;
   /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
   readonly resume?: string;
+  /** Run Config path, forwarded as `--config` (ADR-0040). */
+  readonly config?: string;
+  /** Suppresses the discovered config layers, forwarded as `--no-config` (ADR-0040). */
+  readonly noConfig?: boolean;
   /**
    * Called after each event is folded. `sequence` identifies this fd 3 stream
    * occurrence, not an event value or timestamp; it makes renderer observation
@@ -60,6 +64,8 @@ export function startRun(options: StartRunOptions): RunHandle {
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),
+    ...(options.config === undefined ? {} : { config: options.config }),
+    ...(options.noConfig === true ? { noConfig: true } : {}),
   });
   const child = startCliChild({
     bun: options.bun,

package/src/process/status.ts

@@ -2,11 +2,14 @@
  * The one message the extension has to say about itself: either the bridge to
  * the Bun CLI is in place, or exactly what is missing and how to install it.
  */
+import { docPath } from "../docs/index.ts";
+
 export function statusReport(bun: string | null, cli: string): string {
   if (bun === null) {
     return (
       "yaag needs Bun and could not find it on PATH or in ~/.bun/bin. " +
-      "Install it with: curl -fsSL https://bun.sh/install | bash"
+      "Install it with: curl -fsSL https://bun.sh/install | bash. " +
+      `See ${docPath("troubleshooting.md#bun-is-missing")}`
     );
   }
   return `yaag ready — bun: ${bun}, cli: ${cli}`;

package/src/record/index.ts

@@ -2,7 +2,7 @@
  * Public surface of the `record/` module: the Run record registry, store, restore, and resume.
  * Files inside this directory import each other directly.
  */
-export { resolveProgramParams } from "./resume-source.ts";
+export { resolveLaunchConfig, resolveProgramParams } from "./resume-source.ts";
 export { mintRunId } from "./run-id.ts";
 export {
   confirmProgramTarget,

package/src/record/resume-source.ts

@@ -13,10 +13,12 @@ import type { RunRecord } from "./run-record.ts";
  * source it sees is byte-identical to the recorded one.
  */
 
-/** The stored Runs a resume lookup reads; a structural type, so a test needs no store. */
-export interface InlineSourceLookup {
+/** The stored Runs a resume reads back; a structural type, so a test needs no store. */
+export interface ResumeRecordLookup {
   /** The Inline Program source whose Run published `artifact`, or null. */
   inlineSourceFor(artifact: string): Promise<string | null>;
+  /** The Run Config path of the Run that published `artifact`, or null. */
+  resumeConfigFor(artifact: string): Promise<string | null>;
 }
 
 /**
@@ -32,18 +34,36 @@ export function pickInlineResumeSource(
 ): string | null {
   let found: string | null = null;
   for (const record of records) {
-    const { launch } = record;
-    if (launch.kind !== "inline") continue;
-    const { script, record: recorded } = launch;
-    const published = record.summary.artifact;
-    const matches =
-      (published !== null && published !== undefined && resolve(published) === artifact) ||
-      (recorded !== undefined && resolve(recorded) === artifact);
-    if (matches) found = script;
+    if (record.launch.kind !== "inline") continue;
+    if (publishes(record, artifact)) found = record.launch.script;
   }
   return found;
 }
 
+/**
+ * The stored Run Config path of the Run that published `artifact`, or null.
+ *
+ * Pure, and blind to the launch kind: a file Run and an inline Run both carry
+ * their Run Config path. The newest match wins, as above.
+ */
+export function pickResumeConfig(records: readonly RunRecord[], artifact: string): string | null {
+  let found: string | null = null;
+  for (const record of records) {
+    if (publishes(record, artifact)) found = record.launch.config ?? null;
+  }
+  return found;
+}
+
+/** Whether the Run of this record published, or wrote, the given Checkpoint. */
+function publishes(record: RunRecord, artifact: string): boolean {
+  const published = record.summary.artifact;
+  const recorded = record.launch.record;
+  return (
+    (published !== null && published !== undefined && resolve(published) === artifact) ||
+    (recorded !== undefined && resolve(recorded) === artifact)
+  );
+}
+
 /** What the tool says when no record holds the source of the given Checkpoint. */
 export function noStoredSourceMessage(artifact: string): string {
   return [
@@ -66,7 +86,7 @@ export function noStoredSourceMessage(artifact: string): string {
  */
 export async function resolveProgramParams(
   params: ProgramParams,
-  lookup: InlineSourceLookup,
+  lookup: ResumeRecordLookup,
 ): Promise<ProgramParams> {
   if (params.file !== undefined || params.script !== undefined) return params;
   if (params.resume === undefined) return params;
@@ -75,3 +95,28 @@ export async function resolveProgramParams(
   if (source === null) throw new Error(noStoredSourceMessage(artifact));
   return { ...params, script: source };
 }
+
+/** The launch parameters a resume needs, with the stored Run Config supplied. */
+export interface LaunchParams {
+  readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
+}
+
+/**
+ * The Run Config path a resume inherits from its Run record.
+ *
+ * A call that gives `config`, or `noConfig: true`, states its own layers, so it
+ * passes through untouched. `noConfig: false` states nothing: it is the default,
+ * and it emits no `--no-config`, so it must not drop the stored path either. A call that gives `resume` alone repeats the layers of the
+ * Run it resumes: the path is stored, and every layer is read again now.
+ */
+export async function resolveLaunchConfig<T extends LaunchParams>(
+  params: T,
+  lookup: ResumeRecordLookup,
+): Promise<T & LaunchParams> {
+  if (params.config !== undefined || params.noConfig === true) return params;
+  if (params.resume === undefined) return params;
+  const config = await lookup.resumeConfigFor(resolve(params.resume));
+  return config === null ? params : { ...params, config };
+}

package/src/record/run-record.ts

@@ -22,6 +22,11 @@ export interface RunLaunchContext {
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
+  /**
+   * The Run Config path the launch gave, never its contents: a resume reads
+   * every layer again at resume time (ADR-0040).
+   */
+  readonly config?: string;
 }
 
 /**
@@ -144,6 +149,7 @@ function launchContext(stored: Record<string, unknown>): RunLaunchContext {
     ...(typeof stored.args === "string" ? { args: stored.args } : {}),
     ...(typeof stored.record === "string" ? { record: stored.record } : {}),
     ...(typeof stored.resume === "string" ? { resume: stored.resume } : {}),
+    ...(typeof stored.config === "string" ? { config: stored.config } : {}),
   };
 }
 

package/src/record/run-registry.ts

@@ -1,6 +1,6 @@
 import type { RunSummary, RunOutcome as SummaryOutcome } from "@yaag/runtime";
 import type { ProcessIdentity, RunOutcome } from "../process/index.ts";
-import { pickInlineResumeSource } from "./resume-source.ts";
+import { pickInlineResumeSource, pickResumeConfig } from "./resume-source.ts";
 import { type RunLaunch, type RunRecord, startedRecord } from "./run-record.ts";
 import { restoreRecords } from "./run-restore.ts";
 import { failedSummary, settledRecord } from "./run-settle-record.ts";
@@ -229,6 +229,16 @@ export class RunRegistry {
     return pickInlineResumeSource(await this.#store.load(), artifact);
   }
 
+  /**
+   * The Run Config path a Checkpoint resumes with, read back from the durable
+   * records (ADR-0040). Null when no record holds one. Same wait as above.
+   */
+  async resumeConfigFor(artifact: string): Promise<string | null> {
+    if (this.#store === undefined) return null;
+    await this.#store.settled();
+    return pickResumeConfig(await this.#store.load(), artifact);
+  }
+
   /** Reads a Run this session never started back from the store, by id. */
   async recall(id: string): Promise<RunStatus> {
     const known = this.lookup(id);

package/src/record/run-summary-parse.ts

@@ -2,6 +2,7 @@ import type {
   AgentActivity,
   AgentInfo,
   AgentState,
+  ModelFallbackInfo,
   NodeInfo,
   NodeState,
   RunOutcome,
@@ -56,6 +57,7 @@ interface SummaryBase {
   readonly incomplete: boolean;
   readonly durationMs: number;
   readonly worstFrameGapMs: number;
+  readonly modelFallbacks: number;
 }
 
 function parseBase(stored: Record<string, unknown>): SummaryBase | null {
@@ -88,6 +90,9 @@ function parseBase(stored: Record<string, unknown>): SummaryBase | null {
     incomplete: stored.incomplete,
     durationMs: stored.durationMs,
     worstFrameGapMs: stored.worstFrameGapMs,
+    // Tolerant, unlike the strict fields above: a record written before the
+    // fallback counter existed must still load instead of disappearing.
+    modelFallbacks: typeof stored.modelFallbacks === "number" ? stored.modelFallbacks : 0,
   };
 }
 
@@ -110,7 +115,9 @@ function parseAgent(value: unknown): AgentInfo | null {
   const nodes = parseNodes(stored.nodes);
   const tokens = parseTokens(stored.tokens);
   const activity = parseActivity(stored.activity);
+  const fallbacks = parseFallbacks(stored.modelFallbacks);
   if (
+    fallbacks === null ||
     nodes === null ||
     tokens === undefined ||
     activity === undefined ||
@@ -142,6 +149,10 @@ function parseAgent(value: unknown): AgentInfo | null {
     askStartedAt: stored.askStartedAt,
     nodes,
     finishedNodesPruned: stored.finishedNodesPruned,
+    modelFallbacks: fallbacks,
+    // Tolerant for the same reason as the Run-level counter.
+    modelFallbacksPruned:
+      typeof stored.modelFallbacksPruned === "number" ? stored.modelFallbacksPruned : 0,
   };
   if (state === "asking") {
     if (typeof stored.askIndex !== "number") return null;
@@ -189,6 +200,37 @@ function parseNodes(value: unknown): NodeInfo[] | null {
   return nodes;
 }
 
+/**
+ * The per-Agent fallback table: `[]` when a record predates it, `null` when the
+ * stored value is malformed.
+ */
+function parseFallbacks(value: unknown): ModelFallbackInfo[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return null;
+  const fallbacks: ModelFallbackInfo[] = [];
+  for (const entry of value) {
+    const stored = asRecord(entry);
+    if (
+      stored === null ||
+      typeof stored.failedModel !== "string" ||
+      typeof stored.resolvedModel !== "string" ||
+      typeof stored.attempt !== "number" ||
+      !isReason(stored.reason) ||
+      !isNullableNumber(stored.at)
+    ) {
+      return null;
+    }
+    fallbacks.push({
+      failedModel: stored.failedModel,
+      resolvedModel: stored.resolvedModel,
+      attempt: stored.attempt,
+      reason: stored.reason,
+      at: stored.at,
+    });
+  }
+  return fallbacks;
+}
+
 /**
  * `undefined` means the stored value is malformed or missing; a stored `null`
  * is an Agent or Node whose usage was never reported.
@@ -250,6 +292,10 @@ function isAgentState(value: unknown): value is AgentState {
   return value === "idle" || value === "asking" || value === "exited";
 }
 
+function isReason(value: unknown): value is ModelFallbackInfo["reason"] {
+  return value === "not_found" || value === "auth" || value === "rate_limited";
+}
+
 function isNodeState(value: unknown): value is NodeState {
   return value === "running" || value === "exited" || value === "failed";
 }

package/src/testing/run-call-render.ts

@@ -16,6 +16,8 @@ export interface RunParams {
   readonly background?: boolean;
   readonly record?: string;
   readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
 }
 
 function renderCallComponent(params: RunParams, expanded: boolean) {

package/src/tool/describe-tool.ts

@@ -20,6 +20,12 @@ const DESCRIPTION = [
   "handle.ask supports maxTurns, maxToolCalls, maxDurationMs, and wrapUpPrompt as recoverable",
   "ASK_LIMIT controls. These differ from timeoutMs, the destructive Agent-killing fallback.",
   "",
+  "model takes one pattern, an ordered list of patterns, or a function of the failures so far;",
+  "thinking takes a level or a function of the settled model. A pattern can end with a thinking",
+  'suffix ("opus-5:medium"), which wins over thinking. yaag falls back only on not_found, auth,',
+  "and rate_limited, at spawn and inside an Ask. Exhausted candidates fail with",
+  "MODEL_RESOLUTION_FAILED.",
+  "",
   "Describing imports the program and executes its module top level. Programs should keep",
   "module top level side-effect free; use this only for reviewed, user-authored files.",
 ].join("\n");

package/src/tool/run-tool.ts

@@ -35,6 +35,7 @@ import {
   mintRunId,
   observedSettlement,
   programTarget,
+  resolveLaunchConfig,
   resolveProgramParams,
 } from "../record/index.ts";
 
@@ -65,6 +66,12 @@ const parameters = Type.Object({
         "Resume from this Cassette: matching Asks replay free, then the Run continues live. For an inline Run, give resume with no file and no script, and yaag reuses the stored source",
     }),
   ),
+  config: Type.Optional(Type.String({ description: "Path to one more config file for this Run" })),
+  noConfig: Type.Optional(
+    Type.Boolean({
+      description: "Ignore the global config and the project config for this Run",
+    }),
+  ),
 });
 
 /** pi's own message channel, narrowed to what a background Run needs. */
@@ -121,6 +128,12 @@ const DESCRIPTION = [
   "pass its artifact as `resume` on the retry: Asks that already succeeded",
   "replay instantly and free, and the Run goes live where it diverges. Record",
   "the retry too (to a different path) to keep every attempt resumable.",
+  "",
+  "`config` gives one more config file to this Run. yaag reads it after the",
+  "global config and after the project config. `noConfig: true` tells yaag to",
+  "ignore the global config and the project config. It does not ignore `config`,",
+  "so `config` with `noConfig: true` gives the Run one known config. A config",
+  "file that is not there stops the Run at the start.",
 ].join("\n");
 
 /**
@@ -169,6 +182,9 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       // A resume with no file and no script takes its source from the Run
       // record, before the shape check, so the shape it produces is valid.
       const target = programTarget(await resolveProgramParams(params, registry));
+      // A resume that states no layers of its own repeats the layers of the Run
+      // it resumes; every layer is read again now, at resume time (ADR-0040).
+      const launch = await resolveLaunchConfig(params, registry);
       if (bun === null) throw new Error(statusReport(null, cli));
       const program = await confirmProgramTarget(target);
 
@@ -183,7 +199,7 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
         cli,
         program,
         args: params.args,
-        ...cassetteOptions(params),
+        ...launchOptions(launch),
         id,
         registry,
         start,
@@ -217,16 +233,26 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
 }
 
 /**
- * Cassette paths are `resolve`d here; the CLI owns every rule about them —
- * combinations, validation, refusals — and its own message surfaces on failure.
+ * Cassette and config paths are `resolve`d here; the CLI owns every rule about
+ * them — combinations, validation, refusals — and its own message surfaces on
+ * failure.
  */
-function cassetteOptions(params: { readonly record?: string; readonly resume?: string }): {
+function launchOptions(params: {
+  readonly record?: string;
+  readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
+}): {
   record?: string;
   resume?: string;
+  config?: string;
+  noConfig?: boolean;
 } {
   return {
     ...(params.record === undefined ? {} : { record: resolve(params.record) }),
     ...(params.resume === undefined ? {} : { resume: resolve(params.resume) }),
+    ...(params.config === undefined ? {} : { config: resolve(params.config) }),
+    ...(params.noConfig === true ? { noConfig: true } : {}),
   };
 }
 
@@ -259,6 +285,8 @@ function registeredRun(options: {
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
   readonly id: string;
   readonly registry: RunRegistry;
   readonly start: (options: StartRunOptions) => RunHandle;
@@ -273,6 +301,8 @@ function registeredRun(options: {
     args: options.args,
     record: options.record,
     resume: options.resume,
+    config: options.config,
+    noConfig: options.noConfig,
     onProgress: (summary, event, sequence) => {
       options.registry.progress(options.id, summary);
       options.store.ingest(options.id, { summary, event, sequence, id: options.id });
@@ -289,6 +319,10 @@ function registeredRun(options: {
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),
+    // The record stores the Run Config path, never its contents; a resume
+    // re-resolves every layer at resume time (ADR-0040). `noConfig` is not
+    // stored: it is a property of one launch, not of the Run's program.
+    ...(options.config === undefined ? {} : { config: options.config }),
   };
   const launch: RunLaunch =
     options.program.kind === "file"

package/src/tool/system-prompt-append.ts

@@ -1,3 +1,5 @@
+import { DOCS_ROOT } from "../docs/index.ts";
+
 /** Builds the host-visible yaag block appended to pi's system prompt. */
 export function yaagPromptBlock(directories: readonly string[]): string {
   const list = directories.join(", ");
@@ -24,8 +26,9 @@ export function yaagPromptBlock(directories: readonly string[]): string {
     "});",
     "```",
     "",
-    "Full authoring surface (defineAgent, args schemas, ask limits, worktrees):",
+    "Full authoring surface (defineAgent, args schemas, ask limits, worktrees, model fallback):",
     "read `<program dir>/.yaag/types/runtime/index.d.ts`.",
+    `Shipped docs (${DOCS_ROOT}): getting-started.md, authoring.md, examples.md, cli.md, troubleshooting.md.`,
   ].join("\n");
 }