@yaag/runtime 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },

package/src/agent/define-agent.ts

@@ -35,6 +35,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;
 }

package/src/agent/spawn-extensions.ts

@@ -0,0 +1,97 @@
+import type { ConfigExtension } from "../config/index.ts";
+import { resolveExtensionPaths } from "../extension/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 async function resolveSpawnExtensions(
+  request: SpawnExtensionRequest,
+): Promise<SpawnExtensions | undefined> {
+  const entries = request.useConfigExtensions ? request.configExtensions : [];
+  if (request.declared === undefined && entries.length === 0) return undefined;
+  const resolved: { declaration: string; paths: readonly string[] }[] = [];
+  for (const entry of entries) {
+    resolved.push({
+      declaration: entry.declaration,
+      paths: await resolveConfigEntry(entry, request.projectRoot),
+    });
+  }
+  for (const declaration of request.declared ?? []) {
+    resolved.push({
+      declaration,
+      // One declaration per call: `resolveExtensionPaths` keeps no cross-entry
+      // state, so the loop preserves its order and its error messages.
+      paths: await resolveExtensionPaths([declaration], {
+        ...(request.programFile === undefined ? {} : { programFile: request.programFile }),
+        projectRoot: request.projectRoot,
+      }),
+    });
+  }
+  const seen = new Set<string>();
+  const resolvedPaths: string[] = [];
+  const declared: string[] = [];
+  for (const { declaration, paths } of resolved) {
+    let contributed = false;
+    for (const path of paths) {
+      if (seen.has(path)) continue;
+      seen.add(path);
+      resolvedPaths.push(path);
+      contributed = true;
+    }
+    if (contributed) declared.push(declaration);
+  }
+  return { resolvedPaths, declared };
+}
+
+/** Names the declaring config file, so a bad entry points at its own source. */
+async function resolveConfigEntry(
+  entry: ConfigExtension,
+  projectRoot: string,
+): Promise<readonly string[]> {
+  try {
+    return await resolveExtensionPaths([entry.declaration], {
+      baseDirectory: entry.baseDirectory,
+      projectRoot,
+    });
+  } catch (error) {
+    throw new Error(
+      `config "${entry.file}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/agent/spawn-request.ts

@@ -8,6 +8,7 @@ export interface OpenRequestOptions {
   readonly cwd: string;
   readonly spawnOptions: SpawnOptions;
   readonly resolvedExtensionPaths?: readonly string[];
+  readonly declaredExtensions?: readonly string[];
   readonly sessionDir: string | undefined;
 }
 
@@ -45,6 +46,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
     ...(options.resolvedExtensionPaths === undefined
       ? {}
       : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+    // An empty list means the same as no list at all, so it stays absent and an
+    // extension-free spawn keeps its recorded identity.
+    ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
+      ? {}
+      : { declaredExtensions: options.declaredExtensions }),
     ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
     ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
   };

package/src/agent/spawn.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
+import type { ConfigExtension } from "../config/index.ts";
 import { YaagError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
-import { resolveExtensionPaths } from "../extension/index.ts";
 import {
   ModelErrorHistory,
   type ModelSelection,
@@ -21,6 +21,7 @@ import type {
 import { Agent } from "./agent.ts";
 import { uniqueAgentName } from "./agent-names.ts";
 import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
+import { resolveSpawnExtensions } from "./spawn-extensions.ts";
 import { openRequest, withSelection } from "./spawn-request.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
@@ -30,6 +31,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. */
@@ -61,16 +64,25 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
     const history = new ModelErrorHistory();
     try {
       // Extension paths do not vary per candidate, so a bad path fails once, generically.
-      const resolvedExtensionPaths =
-        request.spawnOptions.extensions === undefined
-          ? undefined
-          : await resolveExtensionPaths(request.spawnOptions.extensions, {
-              ...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
-              projectRoot: cwd,
-            }).catch((error: unknown) => {
-              if (error instanceof YaagError) throw error;
-              throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
-            });
+      const extensions = await resolveSpawnExtensions({
+        configExtensions: deps.configExtensions,
+        declared: request.spawnOptions.extensions,
+        useConfigExtensions: request.spawnOptions.configExtensions !== false,
+        ...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
+        projectRoot: cwd,
+      }).catch((error: unknown) => {
+        if (error instanceof YaagError) throw error;
+        throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
+      });
+      // One local for both open sites, so the launch arguments and the recorded
+      // identity cannot drift apart.
+      const extensionFields =
+        extensions === undefined
+          ? {}
+          : {
+              resolvedExtensionPaths: extensions.resolvedPaths,
+              declaredExtensions: extensions.declared,
+            };
       const attempt = async (
         selection: ModelSelection,
       ): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
@@ -81,7 +93,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
             name,
             cwd,
             spawnOptions: settled,
-            ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
+            ...extensionFields,
             sessionDir: deps.sessionDir,
           }),
           spawnOptions: settled,
@@ -94,7 +106,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
           name,
           cwd,
           spawnOptions: request.spawnOptions,
-          ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
+          ...extensionFields,
           sessionDir: deps.sessionDir,
         }),
       );
@@ -194,6 +206,9 @@ function resolveRequest(
       ...(config.tools === undefined ? {} : { tools: config.tools }),
       ...(config.disallowedTools === undefined ? {} : { disallowedTools: config.disallowedTools }),
       ...(config.skills === undefined ? {} : { skills: config.skills }),
+      ...(config.configExtensions === undefined
+        ? {}
+        : { configExtensions: config.configExtensions }),
       ...(config.disallowedSkills === undefined
         ? {}
         : { disallowedSkills: config.disallowedSkills }),
@@ -256,6 +271,7 @@ interface OpenTransportOptions {
   readonly cwd: string;
   readonly spawnOptions: ResolvedSpawnOptions;
   readonly resolvedExtensionPaths?: readonly string[];
+  readonly declaredExtensions?: readonly string[];
   readonly sessionDir: string | undefined;
 }
 
@@ -275,6 +291,9 @@ async function openTransport(options: OpenTransportOptions): Promise<OpenedTrans
         ...(options.resolvedExtensionPaths === undefined
           ? {}
           : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+        ...(options.declaredExtensions === undefined
+          ? {}
+          : { declaredExtensions: options.declaredExtensions }),
         sessionDir: options.sessionDir,
       }),
       (report) => Object.assign(startup, report),

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-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/replay-divergence.ts

@@ -73,13 +73,16 @@ 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,
     );
   }
@@ -90,7 +93,7 @@ export function strictReplay(mismatch: ReplayMismatch): never {
       : "";
   throw new YaagError(
     "REPLAY_DIVERGED",
-    `replay diverged for agent "${mismatch.agent}" at ${at}:${changed} 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,
   );
 }
@@ -123,7 +126,11 @@ export function recordedSpawnSelection(
   };
 }
 
-/** The spawn fields both Divergence reports compare, so the two cannot drift apart. */
+/**
+ * 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",
@@ -138,7 +145,7 @@ const SPAWN_IDENTITY_FIELDS = [
 ] as const;
 
 /** The spawn identity fields plus the Agent name, which only an open request carries. */
-const SPAWN_OPEN_FIELDS = ["name", ...SPAWN_IDENTITY_FIELDS] as const;
+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>(
@@ -206,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/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>;

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

@@ -46,6 +46,7 @@ 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

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,6 +18,18 @@ 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,

package/src/run/run.ts

@@ -24,6 +24,7 @@ import {
   resumeTransport,
   writeRecordingDiagnostic,
 } from "../cassette/index.ts";
+import { type EffectiveConfig, EMPTY_EFFECTIVE_CONFIG } from "../config/index.ts";
 import { isYaagError, YaagError } from "../errors.ts";
 import type { EventSink, LifecycleEvent, RunOutcome, StampedEventSink } from "../events.ts";
 import { applyEvent, initialSummary, type RunSummary } from "../summary/index.ts";
@@ -69,6 +70,12 @@ export interface RunOptions {
   readonly signal?: AbortSignal;
   /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
   readonly checkpointDir?: string;
+  /**
+   * Effective Config for this Run, read once by the launcher (ADR-0040). The
+   * Run never loads it itself: omission runs config-free, so no Run picks up a
+   * config it was not given, and every test stays hermetic.
+   */
+  readonly config?: EffectiveConfig;
 }
 
 /**
@@ -152,6 +159,7 @@ export async function executeRun<Args, Result>(
     emit,
     sessionDir: options.sessionDir,
     programFile: options.programFile,
+    configExtensions: options.config?.extensions ?? EMPTY_EFFECTIVE_CONFIG.extensions,
   });
 
   const ctx: RunContext<Args> = { args, spawn: spawnGate.spawn };

package/src/transport/transport.ts

@@ -186,6 +186,11 @@ export interface OpenOptions {
   readonly resolvedSkillPaths?: readonly string[];
   /** Absolute launch-ready extension paths resolved above the seam, emitted as repeated `-e` flags. */
   readonly resolvedExtensionPaths?: readonly string[];
+  /**
+   * Declared extensions in final concatenation order, unresolved (ADR-0040).
+   * Spawn identity only: it never becomes argv, and it is absent when empty.
+   */
+  readonly declaredExtensions?: readonly string[];
   /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
   readonly sessionDir?: string;
   /** Resumes an existing pi session, translated to `--session <path>`. */

package/src/types.ts

@@ -38,6 +38,11 @@ export interface SpawnOptions {
    * resolve from the Orchestration Program file; each becomes `pi -e <path>`.
    */
   readonly extensions?: readonly string[];
+  /**
+   * Load the Effective Config's `agents.extensions` for this Agent. Default
+   * true; false spawns with only the extensions this call declares (ADR-0040).
+   */
+  readonly configExtensions?: boolean;
   /**
    * Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
    * `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;