@yaag/extension 0.8.0 → 0.8.2

package/docs/cli.md

@@ -40,6 +40,9 @@ Warning: describe imports the module and executes its top level. Keep program mo
 A bad invocation prints this usage text on stderr and exits with code 2. Those
 argv errors have no troubleshooting entry: the usage text is the fix.
 
+The `--config` and `--no-config` flags select the config layers of a Run. See
+[Configuration](configuration.md#locations).
+
 ## Tools
 
 ### yaag_run
@@ -52,7 +55,7 @@ Runs an Orchestration Program. It maps to `yaag run`.
 | `script` | `--eval-fd` | Inline source. It can import `@yaag/runtime` and `typebox` only. |
 | `args` | `--args <json>` | A JSON object string. |
 | `background` | none | Extension only. Starts the Run and returns its Run id. |
-| `record` | `--record <file>` | Writes the Cassette here. |
+| `record` | `--record <file>` | Writes the Cassette here. yaag makes a missing directory of this path, and stops the Run at the start when it cannot. |
 | `resume` | `--resume <file>` | Replays matching Asks, then continues live. |
 | `config` | `--config <file>` | Reads one more config file for this Run. |
 | `noConfig` | `--no-config` | Ignores the global config and the project config. |

package/docs/configuration.md

@@ -0,0 +1,87 @@
+# Configuration
+
+yaag reads up to three config files at the start of a Run. Their merged
+content is the configuration of that Run. yaag reads them one time, at Run
+start. A config edit during a Run changes nothing until the next Run.
+
+## Locations
+
+| Layer | Location |
+|---|---|
+| Global | `$YAAG_CONFIG_DIR/config.json` when `YAAG_CONFIG_DIR` is set. Else `$XDG_CONFIG_HOME/yaag/config.json` when `XDG_CONFIG_HOME` is an absolute path. Else `~/.config/yaag/config.json`. |
+| Project | `.yaag/config.json` in the Program Directory of the Run. |
+| Run | The file that `yaag run --config <file>` or the `config` option of the `yaag_run` tool gives. Give it one time only. |
+
+The Program Directory is the nearest directory that contains `.yaag/`. yaag
+searches upward from the directory of the program file. For an Inline Program,
+the search starts in the working directory.
+
+A global or project file that does not exist is an empty layer. A `--config`
+file that does not exist stops the Run at the start.
+
+## Supported fields
+
+A config file is plain JSON. [`examples/config.json`](examples/config.json)
+shows the full surface:
+
+<!-- embed: docs/examples/config.json -->
+
+```json
+{
+  "agents": {
+    "extensions": ["./extensions/team-conventions.ts", "npm:@acme/pi-guardrails"]
+  }
+}
+```
+
+| Field | Type | Effect |
+|---|---|---|
+| `agents.extensions` | array of strings | Extensions that every Agent of the Run loads, as extra `pi -e` arguments. |
+
+An entry is an extension path or an `npm:`/`git:` specifier. A relative path
+resolves against the directory of the config file that declares it. An `npm:`
+or `git:` specifier installs from the Agent working directory.
+
+Validation is strict. An unknown key, or a value with a wrong type, stops the
+Run at the start.
+
+## How the layers merge
+
+The extension lists concatenate in this order: global, then project, then run,
+then the `extensions` of the spawn call itself. yaag removes duplicates by
+resolved path. The first occurrence keeps its place. The merged list loads on
+top of the extensions a spawn call declares — a config never removes one.
+
+## Opt out
+
+`--no-config` (CLI) or `noConfig: true` (tool) makes the Run ignore the global
+config and the project config. It does not ignore an explicit `--config` file.
+Thus `--no-config --config ./one.json` gives the Run one known config file.
+
+`configExtensions: false` on one spawn call or one Agent Definition opts that
+one Agent out. The Agent then loads only the extensions its own call declares:
+
+<!-- embed: @yaag/runtime/src/types.ts -->
+
+```ts
+  /**
+   * 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;
+```
+
+## Errors
+
+A config file that yaag cannot read or parse, or that fails validation, stops
+the Run at the start with exit code 1. The message names the file. See
+[A config file is missing or invalid](troubleshooting.md#a-config-file-is-missing-or-invalid).
+
+## Record and resume
+
+The Run record stores the `--config` path, never the file content. A
+`yaag_run` call that gives `resume` alone reads the stored path again, and
+yaag reads every layer again at that moment. An extension list that changed
+since the recording is a Divergence at the first spawn it changes: a strict
+replay stops there, and a resume goes live there. See
+[Replay or resume mismatch](troubleshooting.md#replay-or-resume-mismatch).

package/docs/examples/config.json

@@ -0,0 +1,5 @@
+{
+  "agents": {
+    "extensions": ["./extensions/team-conventions.ts", "npm:@acme/pi-guardrails"]
+  }
+}

package/docs/getting-started.md

@@ -50,4 +50,5 @@ argument schema of the program.
 - [Authoring](authoring.md) — how to write a program.
 - [Examples](examples.md) — five programs, from minimal to record and resume.
 - [CLI reference](cli.md) — every flag and every tool parameter.
+- [Configuration](configuration.md#locations) — the three config files a Run reads.
 - [Troubleshooting](troubleshooting.md) — the errors you can meet.

package/docs/troubleshooting.md

@@ -36,11 +36,22 @@ Agent a model the machine can reach. A `model` list falls back on `auth`.
 
 > failed to publish cassette
 
-Cause: yaag could not write the Cassette. Most often the parent directory of
-the `--record` path does not exist, or it is not writable.
+Cause: yaag could not write the Cassette. The destination is not writable, or
+something else occupies the name.
 
-Fix: create the directory first, then run again. The Run keeps its result; only
-the recording failed.
+Fix: give a writable path, then run again.
+
+## cannot create the Cassette directory
+
+<!-- quote: @yaag/runtime/src/cassette/run-checkpoint.ts -->
+
+> cannot create the Cassette directory
+
+Cause: yaag makes a missing directory of the `--record` path, and this one
+could not be made. A name on the path is a file, or a parent refuses a write.
+
+Fix: give a `--record` path yaag can make. The Run stops at the start, before
+the first Agent, so no work is lost.
 
 ## Replay or resume mismatch
 
@@ -126,7 +137,8 @@ file at the start of a Run. A `--config` file that is not there, or any config
 file that yaag cannot read or parse, stops the Run at the start (exit 1).
 
 Fix: correct the path or the file. Give `--no-config` to ignore the global
-config and the project config.
+config and the project config. [Configuration](configuration.md#locations)
+names the three locations and the supported fields.
 
 Plain usage errors of the CLI exit with code 2 and print the usage text. See
 [the CLI reference](cli.md#usage).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "publishConfig": {
     "access": "public"
   },
@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.8.0",
-    "@yaag/runtime": "0.8.0",
-    "@yaag/tui": "0.8.0",
+    "@yaag/cli": "0.8.2",
+    "@yaag/runtime": "0.8.2",
+    "@yaag/tui": "0.8.2",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/docs/docs-root.ts

@@ -8,12 +8,13 @@ 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. */
+/** The shipped pages, in reading order. */
 export const DOC_PAGES = [
   "getting-started.md",
   "authoring.md",
   "examples.md",
   "cli.md",
+  "configuration.md",
   "troubleshooting.md",
 ] as const;
 

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

@@ -28,7 +28,7 @@ export function yaagPromptBlock(directories: readonly string[]): string {
     "",
     "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.`,
+    `Shipped docs (${DOCS_ROOT}): getting-started.md, authoring.md, examples.md, cli.md, configuration.md, troubleshooting.md.`,
   ].join("\n");
 }