@bluewombat/runtime 0.5.0 → 0.7.0

package/dist/config/agent-shorthand.js

@@ -0,0 +1,256 @@
+import { resolve } from "node:path";
+/**
+ * The short way to write an agent pass: which agent, which prompt, which
+ * plugins — and Host writes the argv a pass has always been.
+ *
+ *   agents:
+ *     cursor: { adapter: cursor, home: ./.mason/agent-home, apiKeyEnv: CURSOR_API_KEY,
+ *               transcripts: ./.mason/transcripts, pluginsOut: ./.mason/plugins }
+ *   builder:
+ *     producer: { agent: cursor, prompt: ./prompts/builder.md,
+ *                 plugins: [./ai-plugins/core/builder], profile: builder, timeoutMs: … }
+ *
+ * expands to
+ *
+ *   node <slots>/builders/producer.mjs --prompt-file <prompt> --
+ *     node <slots>/agents/cursor.mjs --transcript-dir … --agent-home … --api-key-env …
+ *       --plugin-dir <core> --profile builder --plugins-out …
+ *
+ * The expansion is the whole feature: nothing downstream knows a pass was
+ * written short, so `cmd` stays the one shape the rest of Host reads, and a
+ * pass that needs something the short form cannot say still writes `cmd`.
+ */
+/** Where the shipped slots live, next to the config: what `npm install` in a Mason home makes. */
+const SLOTS_PACKAGE = "node_modules/@bluewombat/slots";
+/** The shipped role slot behind each pass that drives an agent. */
+export const ROLE_SCRIPTS = {
+    planner: "planners/producer.mjs",
+    "builder.producer": "builders/producer.mjs",
+    "builder.repair": "builders/repair.mjs",
+    "assembly.fix": "assembly/fix.mjs",
+    "assembly.validate": "assembly/validate.mjs",
+    "authority.describe": "messages/git-producer.mjs",
+};
+const ADAPTERS = new Set(["cursor", "claude"]);
+const AGENT_KEYS = new Set([
+    "adapter",
+    "bin",
+    "model",
+    "home",
+    "apiKeyEnv",
+    "transcripts",
+    "pluginsOut",
+    "args",
+]);
+/** The keys a pass written short may carry, besides its own (`timeoutMs`, `gates`). */
+export const SHORT_PASS_KEYS = new Set(["agent", "prompt", "rules", "plugins", "profile", "args"]);
+export function readAgents(value, configDir) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return { ok: false, reason: 'Config "agents" must be a YAML mapping of agent names.' };
+    }
+    const agents = new Map();
+    for (const [name, raw] of Object.entries(value)) {
+        const key = `agents.${name}`;
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            return { ok: false, reason: `Config "${key}" must be a YAML mapping.` };
+        }
+        const object = raw;
+        for (const field of Object.keys(object)) {
+            if (!AGENT_KEYS.has(field)) {
+                return { ok: false, reason: `Config "${key}" has unknown key "${field}".` };
+            }
+        }
+        const fields = {};
+        for (const field of [
+            "adapter",
+            "bin",
+            "model",
+            "home",
+            "apiKeyEnv",
+            "transcripts",
+            "pluginsOut",
+        ]) {
+            const text = object[field];
+            if (text !== undefined && (typeof text !== "string" || text.trim().length === 0)) {
+                return { ok: false, reason: `Config "${key}.${field}" must be a non-empty string.` };
+            }
+            fields[field] = text;
+        }
+        const adapter = fields.adapter;
+        if (adapter === undefined) {
+            return {
+                ok: false,
+                reason: `Config "${key}" needs an "adapter": cursor, claude, or the path of an agent wrapper.`,
+            };
+        }
+        if ((fields.home === undefined) !== (fields.apiKeyEnv === undefined)) {
+            return {
+                ok: false,
+                reason: `Config "${key}" isolates an agent with "home" and "apiKeyEnv" together, or neither.`,
+            };
+        }
+        const args = stringList(object.args, `${key}.args`);
+        if (args.ok === false) {
+            return args;
+        }
+        const at = (path) => path === undefined ? undefined : resolve(configDir, path);
+        const decl = {
+            adapter: ADAPTERS.has(adapter)
+                ? resolve(configDir, SLOTS_PACKAGE, "agents", `${adapter}.mjs`)
+                : resolve(configDir, adapter),
+            args: args.value,
+        };
+        // A binary named bare is looked up on PATH; one written as a path is next to the config.
+        const bin = fields.bin;
+        if (bin !== undefined) {
+            decl.bin = bin.includes("/") ? resolve(configDir, bin) : bin;
+        }
+        if (fields.model !== undefined) {
+            decl.model = fields.model;
+        }
+        const home = at(fields.home);
+        if (home !== undefined) {
+            decl.home = home;
+        }
+        if (fields.apiKeyEnv !== undefined) {
+            decl.apiKeyEnv = fields.apiKeyEnv;
+        }
+        const transcripts = at(fields.transcripts);
+        if (transcripts !== undefined) {
+            decl.transcripts = transcripts;
+        }
+        const pluginsOut = at(fields.pluginsOut);
+        if (pluginsOut !== undefined) {
+            decl.pluginsOut = pluginsOut;
+        }
+        agents.set(name, decl);
+    }
+    return { ok: true, value: agents };
+}
+/**
+ * The argv a pass written short stands for. `object` is the pass's own
+ * mapping; its keys were checked by the caller.
+ */
+export function expandAgentPass(object, role, agents, configDir, key) {
+    if (object.cmd !== undefined) {
+        return { ok: false, reason: `Config "${key}" names "cmd" and "agent": write one of the two.` };
+    }
+    const name = object.agent;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        return { ok: false, reason: `Config "${key}.agent" must name an agent of "agents".` };
+    }
+    const agent = agents.get(name);
+    if (agent === undefined) {
+        return {
+            ok: false,
+            reason: `Config "${key}.agent" is "${name}", and "agents" declares no such agent.`,
+        };
+    }
+    const prompt = pathField(object, "prompt", key, configDir);
+    if (prompt.ok === false) {
+        return prompt;
+    }
+    const rules = pathField(object, "rules", key, configDir);
+    if (rules.ok === false) {
+        return rules;
+    }
+    const read = pathField(object, "read", key, configDir);
+    if (read.ok === false) {
+        return read;
+    }
+    const plugins = stringList(object.plugins, `${key}.plugins`);
+    if (plugins.ok === false) {
+        return plugins;
+    }
+    const profile = object.profile;
+    if (profile !== undefined && (typeof profile !== "string" || profile.trim().length === 0)) {
+        return { ok: false, reason: `Config "${key}.profile" must be a deck profile name.` };
+    }
+    if (profile !== undefined && agent.pluginsOut === undefined) {
+        return {
+            ok: false,
+            reason: `Config "${key}" names a deck profile, so "agents.${name}.pluginsOut" must say where it is built.`,
+        };
+    }
+    const args = stringList(object.args, `${key}.args`);
+    if (args.ok === false) {
+        return args;
+    }
+    const argv = ["node", resolve(configDir, SLOTS_PACKAGE, ROLE_SCRIPTS[role])];
+    if (prompt.value !== undefined) {
+        argv.push("--prompt-file", prompt.value);
+    }
+    if (rules.value !== undefined) {
+        argv.push("--rules-file", rules.value);
+    }
+    if (read.value !== undefined) {
+        argv.push("--read", read.value);
+    }
+    argv.push("--", "node", agent.adapter);
+    if (agent.bin !== undefined) {
+        argv.push("--bin", agent.bin);
+    }
+    if (agent.model !== undefined) {
+        argv.push("--model", agent.model);
+    }
+    if (agent.transcripts !== undefined) {
+        argv.push("--transcript-dir", agent.transcripts);
+    }
+    if (agent.home !== undefined && agent.apiKeyEnv !== undefined) {
+        argv.push("--agent-home", agent.home, "--api-key-env", agent.apiKeyEnv);
+    }
+    for (const dir of plugins.value) {
+        argv.push("--plugin-dir", resolve(configDir, dir));
+    }
+    if (profile !== undefined && agent.pluginsOut !== undefined) {
+        argv.push("--profile", profile, "--plugins-out", agent.pluginsOut);
+    }
+    for (const arg of [...agent.args, ...args.value]) {
+        argv.push("--agent-arg", arg);
+    }
+    return { ok: true, value: argv };
+}
+/** The agent and profile a pass's argv names, written short or not; for `doctor`. */
+export function agentPartOf(argv) {
+    const split = argv.indexOf("--");
+    const agent = split === -1 ? [] : argv.slice(split + 1);
+    const found = {
+        pluginDirs: [],
+    };
+    agent.forEach((token, at) => {
+        const value = agent[at + 1];
+        if (value === undefined) {
+            return;
+        }
+        if (token === "--profile") {
+            found.profile = value;
+        }
+        else if (token === "--plugins-out") {
+            found.pluginsOut = value;
+        }
+        else if (token === "--plugin-dir") {
+            found.pluginDirs.push(value);
+        }
+    });
+    return found;
+}
+function pathField(object, field, key, configDir) {
+    const value = object[field];
+    if (value === undefined) {
+        return { ok: true, value: undefined };
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return { ok: false, reason: `Config "${key}.${field}" must be a non-empty path.` };
+    }
+    return { ok: true, value: resolve(configDir, value) };
+}
+function stringList(value, key) {
+    if (value === undefined) {
+        return { ok: true, value: [] };
+    }
+    if (!Array.isArray(value) || value.some((token) => typeof token !== "string")) {
+        return { ok: false, reason: `Config "${key}" must be an array of strings.` };
+    }
+    return { ok: true, value: value };
+}
+//# sourceMappingURL=agent-shorthand.js.map

package/dist/config/agent-shorthand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-shorthand.js","sourceRoot":"","sources":["../../src/config/agent-shorthand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,kGAAkG;AAClG,MAAM,aAAa,GAAG,gCAAgC,CAAC;AAEvD,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,uBAAuB;IAChC,kBAAkB,EAAE,uBAAuB;IAC3C,gBAAgB,EAAE,qBAAqB;IACvC,cAAc,EAAE,kBAAkB;IAClC,mBAAmB,EAAE,uBAAuB;IAC5C,oBAAoB,EAAE,2BAA2B;CACzC,CAAC;AAIX,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,SAAS;IACT,KAAK;IACL,OAAO;IACP,MAAM;IACN,WAAW;IACX,aAAa;IACb,YAAY;IACZ,MAAM;CACP,CAAC,CAAC;AAEH,uFAAuF;AACvF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAkBnG,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,SAAiB;IAC1D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wDAAwD,EAAE,CAAC;IACzF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC3E,MAAM,GAAG,GAAG,UAAU,IAAI,EAAE,CAAC;QAC7B,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,2BAA2B,EAAE,CAAC;QAC1E,CAAC;QACD,MAAM,MAAM,GAAG,GAA8B,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,sBAAsB,KAAK,IAAI,EAAE,CAAC;YAC9E,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAuC,EAAE,CAAC;QACtD,KAAK,MAAM,KAAK,IAAI;YAClB,SAAS;YACT,KAAK;YACL,OAAO;YACP,MAAM;YACN,WAAW;YACX,aAAa;YACb,YAAY;SACb,EAAE,CAAC;YACF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;gBACjF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,KAAK,+BAA+B,EAAE,CAAC;YACvF,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,GAAG,IAA0B,CAAC;QAC7C,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,WAAW,GAAG,wEAAwE;aAC/F,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,EAAE,CAAC;YACrE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,WAAW,GAAG,uEAAuE;aAC9F,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;QACpD,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,EAAE,GAAG,CAAC,IAAwB,EAAE,EAAE,CACtC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAc;YACtB,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;gBAC5B,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,OAAO,MAAM,CAAC;gBAC/D,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC;YAC/B,IAAI,EAAE,IAAI,CAAC,KAAK;SACjB,CAAC;QACF,yFAAyF;QACzF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC/D,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC5B,CAAC;QACD,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QACpC,CAAC;QACD,MAAM,WAAW,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC3C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QACjC,CAAC;QACD,MAAM,UAAU,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC/B,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA+B,EAC/B,IAAe,EACf,MAAc,EACd,SAAiB,EACjB,GAAW;IAEX,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,kDAAkD,EAAE,CAAC;IACjG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC;IAC1B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,yCAAyC,EAAE,CAAC;IACxF,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,WAAW,GAAG,eAAe,IAAI,yCAAyC;SACnF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACvD,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,GAAG,UAAU,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAC1F,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,wCAAwC,EAAE,CAAC;IACvF,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAC5D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,WAAW,GAAG,sCAAsC,IAAI,0CAA0C;SAC3G,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7E,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC9D,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1E,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAC5D,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAiB,EAAE,eAAe,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/E,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,WAAW,CAAC,IAAuB;IAKjD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAoE;QAC7E,UAAU,EAAE,EAAE;KACf,CAAC;IACF,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;YAC1B,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC;QACxB,CAAC;aAAM,IAAI,KAAK,KAAK,eAAe,EAAE,CAAC;YACrC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;QAC3B,CAAC;aAAM,IAAI,KAAK,KAAK,cAAc,EAAE,CAAC;YACpC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAChB,MAA+B,EAC/B,KAAa,EACb,GAAW,EACX,SAAiB;IAEjB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,KAAK,6BAA6B,EAAE,CAAC;IACrF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,GAAW;IAC7C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC9E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,gCAAgC,EAAE,CAAC;IAC/E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAiB,EAAE,CAAC;AAChD,CAAC"}

package/dist/config/load-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../../src/config/load-config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAGV,cAAc,EAIf,MAAM,YAAY,CAAC;AA8BpB,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAmKrD"}
+{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../../src/config/load-config.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAIV,cAAc,EAIf,MAAM,YAAY,CAAC;AAgCpB,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA+KrD"}

package/dist/config/load-config.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { expandAgentPass, readAgents, SHORT_PASS_KEYS, } from "./agent-shorthand.js";
 const KNOWN_KEYS = new Set([
     "manager",
     "managerOptions",
@@ -9,6 +10,7 @@ const KNOWN_KEYS = new Set([
     "workspaceRoot",
     "ledger",
     "persist",
+    "agents",
     "planner",
     "builder",
     "assembly",
@@ -18,9 +20,10 @@ const KNOWN_KEYS = new Set([
     "maxRefusals",
     "pollIntervalMs",
 ]);
-const WORK_LINE_KEYS = new Set(["stable", "branch", "isolation", "isolationOptions"]);
+const WORK_LINE_KEYS = new Set(["stable", "branch", "isolation", "isolationOptions", "warm"]);
 const PASS_KEYS = new Set(["cmd", "timeoutMs"]);
-const STAGE_KEYS = new Set(["producer", "repair", "maxAttempts", "gates"]);
+const GATED_PASS_KEYS = new Set(["cmd", "timeoutMs", "gates"]);
+const STAGE_KEYS = new Set(["producer", "repair", "maxAttempts"]);
 const ASSEMBLY_KEYS = new Set(["fix", "validate", "maxAttempts", "gates"]);
 const GATES_KEYS = new Set(["defaultTimeoutMs", "gates"]);
 const AUTHORITY_KEYS = new Set(["enabled", "publish", "refresh", "describe"]);
@@ -97,6 +100,9 @@ export function loadConfig(path) {
         if (workLine.isolationOptions !== undefined) {
             invocation.workLineIsolationOptions = workLine.isolationOptions;
         }
+        if (workLine.warm !== undefined) {
+            invocation.workLineWarm = workLine.warm;
+        }
     }
     const workspaceRoot = stringField(object, "workspaceRoot");
     if (workspaceRoot.ok === false) {
@@ -119,29 +125,37 @@ export function loadConfig(path) {
     if (persist.value !== undefined) {
         invocation.persist = persist.value;
     }
+    let agents = new Map();
+    if (object.agents !== undefined) {
+        const read = readAgents(object.agents, configDir);
+        if (read.ok === false) {
+            return read;
+        }
+        agents = read.value;
+    }
     if (object.planner !== undefined) {
-        const planner = readPass(object.planner, configDir, "planner");
+        const planner = readGatedPass(object.planner, configDir, "planner", agents);
         if (planner.ok === false) {
             return planner;
         }
         invocation.planner = planner.value;
     }
     if (object.builder !== undefined) {
-        const builder = readBuilder(object.builder, configDir);
+        const builder = readBuilder(object.builder, configDir, agents);
         if (builder.ok === false) {
             return builder;
         }
         invocation.builder = builder.value;
     }
     if (object.assembly !== undefined) {
-        const assembly = readAssembly(object.assembly, configDir);
+        const assembly = readAssembly(object.assembly, configDir, agents);
         if (assembly.ok === false) {
             return assembly;
         }
         invocation.assembly = assembly.value;
     }
     if (object.authority !== undefined) {
-        const authority = readAuthority(object.authority, configDir);
+        const authority = readAuthority(object.authority, configDir, agents);
         if (authority.ok === false) {
             return authority;
         }
@@ -243,6 +257,14 @@ function readWorkLine(value, configDir) {
             Array.isArray(isolationOptions))) {
         return { ok: false, reason: 'Config "workLine.isolationOptions" must be a YAML mapping.' };
     }
+    let warm;
+    if (object.warm !== undefined) {
+        const read = readPass(object.warm, configDir, "workLine.warm");
+        if (read.ok === false) {
+            return read;
+        }
+        warm = read.value;
+    }
     return {
         ok: true,
         ...(stable.value === undefined ? {} : { stable: resolve(configDir, stable.value) }),
@@ -251,6 +273,7 @@ function readWorkLine(value, configDir) {
         ...(isolationOptions === undefined
             ? {}
             : { isolationOptions: isolationOptions }),
+        ...(warm === undefined ? {} : { warm }),
     };
 }
 /**
@@ -269,7 +292,7 @@ function readWorkLine(value, configDir) {
  * shared work line and one that keeps every fold local are different products,
  * and neither is the obvious one to assume.
  */
-function readAuthority(value, configDir) {
+function readAuthority(value, configDir, agents) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return { ok: false, reason: 'Config "authority" must be a YAML mapping.' };
     }
@@ -315,13 +338,26 @@ function readAuthority(value, configDir) {
     };
     // Optional: the Project's own words for what it submits.
     const describe = object.describe;
-    if (describe !== undefined) {
+    if (describe !== null && typeof describe === "object" && !Array.isArray(describe)) {
+        const short = describe;
+        for (const name of Object.keys(short)) {
+            if (!SHORT_PASS_KEYS.has(name)) {
+                return { ok: false, reason: `Config "authority.describe" has unknown key "${name}".` };
+            }
+        }
+        const argv = expandAgentPass(short, "authority.describe", agents, configDir, "authority.describe");
+        if (argv.ok === false) {
+            return argv;
+        }
+        spec.describeArgv = argv.value;
+    }
+    else if (describe !== undefined) {
         if (!Array.isArray(describe) ||
             describe.length === 0 ||
             describe.some((token) => typeof token !== "string")) {
             return {
                 ok: false,
-                reason: 'Config "authority.describe" must be a non-empty array of strings.',
+                reason: 'Config "authority.describe" must be a non-empty array of strings, or an agent pass ({ agent: … }).',
             };
         }
         spec.describeArgv = resolveArgv(describe, configDir);
@@ -483,10 +519,67 @@ function readPass(value, configDir, key) {
         value: { cmd: resolveArgv(cmd.value, configDir), timeoutMs: timeoutMs.value },
     };
 }
+/**
+ * A command, and its own Gate sequence — `planner`, `builder.producer`,
+ * `builder.repair`, `assembly.fix`, `assembly.validate`. Deliberately its own
+ * ~10 lines rather than a parameterized `readPass`: each reader's error
+ * messages and key set stay independently legible.
+ */
+function readGatedPass(value, configDir, key, agents) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return {
+            ok: false,
+            reason: `Config "${key}" must be a YAML mapping with "cmd" (or "agent") and "timeoutMs".`,
+        };
+    }
+    const object = value;
+    const short = object.agent !== undefined;
+    for (const name of Object.keys(object)) {
+        const known = GATED_PASS_KEYS.has(name) ||
+            (short && (SHORT_PASS_KEYS.has(name) || (name === "read" && key === "planner")));
+        if (!known) {
+            return { ok: false, reason: `Config "${key}" has unknown key "${name}".` };
+        }
+    }
+    let cmd;
+    if (short) {
+        const expanded = expandAgentPass(object, key, agents, configDir, key);
+        if (expanded.ok === false) {
+            return expanded;
+        }
+        cmd = expanded.value;
+    }
+    else {
+        const written = stringArrayField(object, "cmd");
+        if (written.ok === false || written.value === undefined) {
+            return {
+                ok: false,
+                reason: `Config "${key}.cmd" must be a non-empty array of strings, or "${key}.agent" an agent of "agents".`,
+            };
+        }
+        cmd = resolveArgv(written.value, configDir);
+    }
+    const timeoutMs = positiveIntField(object, "timeoutMs");
+    if (timeoutMs.ok === false || timeoutMs.value === undefined) {
+        return {
+            ok: false,
+            reason: `Config "${key}" needs a positive "timeoutMs": nothing else bounds a command.`,
+        };
+    }
+    let gates = [];
+    if (object.gates !== undefined) {
+        const read = readGates(object.gates, configDir, `${key}.gates`);
+        if (read.ok === false) {
+            return read;
+        }
+        gates = read.value;
+    }
+    return { ok: true, value: { cmd, timeoutMs: timeoutMs.value, gates } };
+}
 /**
  * Making a Subtask: both passes named, neither borrowing the other's command.
  */
-function readBuilder(value, configDir) {
+function readBuilder(value, configDir, agents) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return { ok: false, reason: 'Config "builder" must be a YAML mapping.' };
     }
@@ -502,18 +595,17 @@ function readBuilder(value, configDir) {
     if (object.repair === undefined) {
         return { ok: false, reason: 'Config "builder" needs a "repair".' };
     }
-    const readProducer = readPass(object.producer, configDir, "builder.producer");
+    const readProducer = readGatedPass(object.producer, configDir, "builder.producer", agents);
     if (readProducer.ok === false) {
         return readProducer;
     }
-    const readRepair = readPass(object.repair, configDir, "builder.repair");
+    const readRepair = readGatedPass(object.repair, configDir, "builder.repair", agents);
     if (readRepair.ok === false) {
         return readRepair;
     }
     const spec = {
         producer: readProducer.value,
         repair: readRepair.value,
-        gates: [],
     };
     const maxAttempts = positiveIntField(object, "maxAttempts");
     if (maxAttempts.ok === false) {
@@ -522,20 +614,13 @@ function readBuilder(value, configDir) {
     if (maxAttempts.value !== undefined) {
         spec.maxAttempts = maxAttempts.value;
     }
-    if (object.gates !== undefined) {
-        const gates = readGates(object.gates, configDir, "builder.gates");
-        if (gates.ok === false) {
-            return gates;
-        }
-        spec.gates = gates.value;
-    }
     return { ok: true, value: spec };
 }
 /**
  * Judging the assembled feature. A command here is a fix of what a judgement
  * refused, not a second first-pass of the request.
  */
-function readAssembly(value, configDir) {
+function readAssembly(value, configDir, agents) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return { ok: false, reason: 'Config "assembly" must be a YAML mapping.' };
     }
@@ -554,14 +639,14 @@ function readAssembly(value, configDir) {
     }
     const spec = { gates: [] };
     if (object.fix !== undefined) {
-        const read = readPass(object.fix, configDir, "assembly.fix");
+        const read = readGatedPass(object.fix, configDir, "assembly.fix", agents);
         if (read.ok === false) {
             return read;
         }
         spec.fix = read.value;
     }
     if (object.validate !== undefined) {
-        const read = readPass(object.validate, configDir, "assembly.validate");
+        const read = readGatedPass(object.validate, configDir, "assembly.validate", agents);
         if (read.ok === false) {
             return read;
         }
@@ -592,8 +677,20 @@ function readAssembly(value, configDir) {
  * resolved against the slot's working directory, which is the Task workspace.
  * A workspace is a git worktree that is published and then destroyed: output
  * left there is committed into the work first, and lost after.
+ *
+ * `--transcript-dir` and `--agent-home` are Host-owned write paths (films, and
+ * the vendor's isolated HOME). Both must resolve against the config directory
+ * even before the directory exists. So must `--plugins-out`, where a deck
+ * profile is built. `--plugin-dir` is read, not written, but a relative one
+ * left as a word would be looked up in the Task workspace — never where the
+ * operator's plugin is.
  */
-const WRITTEN_PATH_FLAGS = new Set(["--transcript-dir"]);
+const WRITTEN_PATH_FLAGS = new Set([
+    "--transcript-dir",
+    "--agent-home",
+    "--plugins-out",
+    "--plugin-dir",
+]);
 function resolveArgv(argv, configDir) {
     return argv.map((token, at) => WRITTEN_PATH_FLAGS.has(argv[at - 1] ?? "")
         ? resolve(configDir, token)