@dylanrussell/agent-router 1.0.6 → 1.0.7

package/README.md

@@ -29,28 +29,29 @@ opencode agents are markdown files (`~/.config/opencode/agents/*.md`) whose YAML
 ---
 description: High-reasoning review, debugging, and architecture counsel
 mode: subagent
-model: anthropic/claude-opus-4-8        # ← the ONLY line agent-router touches
+model: anthropic/claude-opus-4-8        # ← agent-router rewrites this
+reasoningEffort: high                   # ← and any option keys a stack names
 temperature: 0.1
 tools: { write: false, edit: false }
 ---
 <prompt body — owned by you, never touched by agent-router>
 ```
 
-`agent-router` keeps named **stacks** — JSON files mapping agent names to models — and applies them to those `model:` lines on demand. Premium models for the workday, cheap ones for bulk chores, one command to swap the whole crew:
+`agent-router` keeps named **stacks** — JSON files mapping agent names to models (and optionally to provider options) — and applies them to those frontmatter lines on demand. Premium models for the workday, cheap ones for bulk chores, one command to swap the whole crew:
 
 ```json
 {
   "agents": {
     "Omni":      { "model": "anthropic/claude-fable-5" },
-    "oracle":    { "model": "openai/gpt-5.5" },
+    "oracle":    { "model": "openai/gpt-5.5", "reasoningEffort": "high" },
     "explorer":  { "model": "openai/gpt-5.4-mini" },
     "librarian": { "model": "openai/gpt-5.4-mini" },
-    "fixer":     { "model": "openai/gpt-5.5" }
+    "fixer":     { "model": "openai/gpt-5.5", "thinking": { "effort": "low" } }
   }
 }
 ```
 
-The prompt body and every other frontmatter key are yours; agent-router rewrites exactly one line per agent, atomically, through symlinks (dotfile-manager setups survive intact).
+The prompt body and opencode framework keys (`description`, `mode`, `permission`, `tools`, …) are yours; agent-router rewrites only the `model:` line and the option keys a stack entry names, atomically, through symlinks (dotfile-manager setups survive intact).
 
 ```
 ~/.config/opencode/
@@ -104,11 +105,27 @@ The everyday loop: tune your agents until you like them → `capture <name>` →
 
 ## Stacks
 
-A stack file needs one thing: an `agents` record whose entries carry a `model` string. Agent names are the `.md` basenames in your agents dir (`Omni` ↔ `Omni.md`). Unknown keys are preserved round-trip.
+A stack file needs one thing: an `agents` record whose entries carry a `model` string. Agent names are the `.md` basenames in your agents dir (`Omni` ↔ `Omni.md`). Any **other key** on an entry is a provider pass-through option (`reasoningEffort`, `thinking`, `temperature`, `topP`, `maxOutputTokens`, …) that opencode forwards to the model — agent-router transcribes these to the agent's frontmatter alongside `model:` and captures them back. Unknown keys are preserved round-trip.
+
+```json
+{
+  "agents": {
+    "oracle": {
+      "model": "openai/gpt-5.5",
+      "reasoningEffort": "high",
+      "thinking": { "effort": "low" }
+    }
+  }
+}
+```
+
+- **Apply** writes/updates only the option keys a stack entry names; options the stack omits are left in place. To **clear** an option, set it to `null` in the stack entry.
+- Reserved opencode framework keys (`description`, `mode`, `permission`, `tools`, `prompt`, `steps`, `color`, `name`) are never transcribed — a stack entry can't clobber them.
+- Option values serialize to a single frontmatter line: scalars bare (quoted only when needed), objects/arrays as JSON flow. Block-style values an apply replaces are collapsed to flow; `capture` parses them back into typed JSON.
 
 `use` is strict by design: if a stack references an agent file that doesn't exist, or one without a `model:` line, the switch fails **before anything is written** — your suite is never left half-switched. It also validates every model ID against `opencode models` first (skip with `--no-validate`, override with `--force-invalid`).
 
-`capture` is the inverse: it reads the current `model:` line of every agent file (files without one are skipped) and writes a stack. There are no bundled seed stacks — your real setup is the seed.
+`capture` is the inverse: it reads the current `model:` line and option keys of every agent file (files without a `model:` line are skipped) and writes a stack. There are no bundled seed stacks — your real setup is the seed.
 
 ## Inside opencode
 
@@ -167,12 +184,12 @@ Paths resolve in this order: explicit option → `config.json` → env var → d
 ## ⚠ Things to know
 
 - **Restart required.** opencode reads agent files once at startup. After every `agent-router use`, restart opencode for the new models to take effect. The CLI reminds you.
-- **Hand-edits to frontmatter are not auto-saved into stacks.** If you hand-tune a model and want to keep it, `capture` it (or `capture <active> --force`). The next `use` that touches that agent overwrites the hand-edit.
+- **Hand-edits to frontmatter are not auto-saved into stacks.** If you hand-tune a model or option and want to keep it, `capture` it (or `capture <active> --force`). The next `use` that touches that agent overwrites the hand-edit for keys the stack names; keys the stack omits are preserved (set an option to `null` in a stack entry to clear it).
 - **Validation is auth-state-dependent.** `agent-router validate` runs `opencode models`, which only lists models reachable through your current auth. If you revoke a key, previously-valid stacks may suddenly be invalid.
 
 ## FAQ
 
-**Why no variants/fallback models?** Native agent frontmatter has a single `model:` line. If you want a fallback, make it a stack (`cheap`, `free`) and switch to it.
+**Why no variants/fallback models?** Native agent frontmatter has a single `model:` line. If you want a fallback, make it a stack (`cheap`, `free`) and switch to it. For per-stack *behavior* variants (reasoning effort, thinking budget, temperature, …), add the option as a sibling key on the stack entry — it transcribes to frontmatter on `use`.
 
 **Can I have per-project stacks?** Point `AGENT_ROUTER_STACKS_DIR` at a project-local directory in that project's shell env.
 

package/dist/cli.js

@@ -16086,8 +16086,300 @@ init_errors();
 import { existsSync as existsSync3 } from "fs";
 import { readFile as readFile2, readdir } from "fs/promises";
 import path4 from "path";
+
+// src/core/yaml-lite.ts
+var RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "null",
+  "true",
+  "false",
+  "yes",
+  "no",
+  "on",
+  "off",
+  "~",
+  // YAML 1.1 nulls
+  "Null",
+  "NULL",
+  "True",
+  "False",
+  "Yes",
+  "No",
+  "On",
+  "Off"
+]);
+var BARE_STRING_RE = /^[A-Za-z0-9._\-\/+@$%^&()~]+$/;
+function needsQuoting(s) {
+  if (s === "") return true;
+  if (RESERVED_WORDS.has(s)) return true;
+  if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s)) return true;
+  if (/^0x[0-9A-Fa-f]+$/.test(s)) return true;
+  if (/^[+-]?\.(inf|Inf|INF|nan|NaN|NAN)$/.test(s)) return true;
+  if (!BARE_STRING_RE.test(s)) return true;
+  return false;
+}
+function serializeOptionValue(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return String(value);
+    return JSON.stringify(value);
+  }
+  if (typeof value === "bigint") return String(value);
+  if (typeof value === "string") return needsQuoting(value) ? JSON.stringify(value) : value;
+  return JSON.stringify(value);
+}
+function stripComment(line) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === "#" && !inSingle && !inDouble) {
+      if (i === 0 || /\s/.test(line[i - 1] ?? "")) return line.slice(0, i);
+    }
+  }
+  return line;
+}
+function tokenize(block) {
+  const out = [];
+  for (const raw of block.split(/\r?\n/)) {
+    if (raw.trim() === "") continue;
+    const indentMatch = /^( *)/.exec(raw);
+    const indent = indentMatch?.[1]?.length ?? 0;
+    const content = stripComment(raw.slice(indent));
+    if (content.trim() === "") continue;
+    out.push({ indent, text: content.trimEnd(), raw });
+  }
+  return out;
+}
+function coerceScalar(raw) {
+  const v = raw.trim();
+  if (v === "" || v === "null" || v === "~" || v === "Null" || v === "NULL") return null;
+  if (v === "true" || v === "True" || v === "TRUE") return true;
+  if (v === "false" || v === "False" || v === "FALSE") return false;
+  if (v === "yes" || v === "Yes" || v === "YES") return true;
+  if (v === "no" || v === "No" || v === "NO") return false;
+  if (v === "on" || v === "On" || v === "ON") return true;
+  if (v === "off" || v === "Off" || v === "OFF") return false;
+  if (/^[+-]?\d+$/.test(v)) return Number.parseInt(v, 10);
+  if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(v)) return Number.parseFloat(v);
+  if (/^0x[0-9A-Fa-f]+$/.test(v)) return Number.parseInt(v, 16);
+  return v;
+}
+function parseQuoted(s) {
+  const quote = s[0] ?? "";
+  if (quote !== '"' && quote !== "'") return null;
+  if (quote === '"') {
+    let out2 = "";
+    for (let i = 1; i < s.length; i++) {
+      const ch = s[i] ?? "";
+      if (ch === "\\" && i + 1 < s.length) {
+        const next = s[i + 1] ?? "";
+        const map2 = {
+          n: "\n",
+          t: "	",
+          r: "\r",
+          '"': '"',
+          "\\": "\\",
+          "/": "/",
+          b: "\b",
+          f: "\f"
+        };
+        out2 += map2[next] ?? next;
+        i++;
+      } else if (ch === '"') {
+        return { value: out2, rest: s.slice(i + 1) };
+      } else {
+        out2 += ch;
+      }
+    }
+    return null;
+  }
+  let out = "";
+  for (let i = 1; i < s.length; i++) {
+    const ch = s[i] ?? "";
+    if (ch === "'") {
+      if (s[i + 1] === "'") {
+        out += "'";
+        i++;
+      } else {
+        return { value: out, rest: s.slice(i + 1) };
+      }
+    } else {
+      out += ch;
+    }
+  }
+  return null;
+}
+function splitFlow(raw) {
+  const parts = [];
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let start = 0;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (!inSingle && !inDouble) {
+      if (ch === "{" || ch === "[") depth++;
+      else if (ch === "}" || ch === "]") depth--;
+      else if (ch === "," && depth === 0) {
+        parts.push(raw.slice(start, i));
+        start = i + 1;
+      }
+    }
+  }
+  parts.push(raw.slice(start));
+  return parts;
+}
+function parseFlowValue(raw) {
+  const s = raw.trim();
+  if (s === "") return null;
+  const first = s[0] ?? "";
+  if (first === "{") {
+    const inner = s.slice(1, s.length - 1);
+    const obj = {};
+    for (const part of splitFlow(inner)) {
+      const t = part.trim();
+      if (t === "") continue;
+      const colon = findColon(t);
+      if (colon < 0) {
+        obj[t] = null;
+      } else {
+        const k = t.slice(0, colon).trim();
+        const v = t.slice(colon + 1).trim();
+        obj[stripKeyQuotes(k)] = parseFlowValue(v);
+      }
+    }
+    return obj;
+  }
+  if (first === "[") {
+    const inner = s.slice(1, s.length - 1);
+    return splitFlow(inner).filter((p) => p.trim() !== "").map((p) => parseFlowValue(p));
+  }
+  if (first === '"' || first === "'") {
+    const q = parseQuoted(s);
+    return q ? q.value : s;
+  }
+  return coerceScalar(s);
+}
+function findColon(s) {
+  let inSingle = false;
+  let inDouble = false;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (!inSingle && !inDouble) {
+      if (ch === "{" || ch === "[") depth++;
+      else if (ch === "}" || ch === "]") depth--;
+      else if (ch === ":" && depth === 0) return i;
+    }
+  }
+  return -1;
+}
+function stripKeyQuotes(k) {
+  if (k.length >= 2 && (k[0] === '"' && k.at(-1) === '"' || k[0] === "'" && k.at(-1) === "'")) {
+    return k.slice(1, -1);
+  }
+  return k;
+}
+function parseMapping(lines, startIdx, indent) {
+  const out = {};
+  let i = startIdx;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line) break;
+    if (line.indent < indent) break;
+    if (line.indent > indent) {
+      i++;
+      continue;
+    }
+    const colon = findColon(line.text);
+    if (colon < 0) {
+      i++;
+      continue;
+    }
+    const key = stripKeyQuotes(line.text.slice(0, colon).trim());
+    if (key === "") {
+      i++;
+      continue;
+    }
+    const rest = line.text.slice(colon + 1).trim();
+    if (rest !== "") {
+      out[key] = parseFlowValue(rest);
+      i++;
+    } else {
+      const childIndent = lines[i + 1]?.indent ?? line.indent + 1;
+      let j = i + 1;
+      while (j < lines.length && (lines[j]?.indent ?? -1) >= childIndent) j++;
+      if (j === i + 1) {
+        out[key] = null;
+        i++;
+      } else {
+        const childBlock = lines.slice(i + 1, j);
+        const firstChild = childBlock[0];
+        if (firstChild?.text.trimStart().startsWith("- ")) {
+          out[key] = parseSequence(childBlock, childIndent);
+        } else {
+          out[key] = parseMapping(childBlock, 0, childIndent).value;
+        }
+        i = j;
+      }
+    }
+  }
+  return { value: out, next: i };
+}
+function parseSequence(lines, indent) {
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line) break;
+    if (line.indent < indent) break;
+    const t = line.text.trimStart();
+    if (!t.startsWith("- ")) {
+      i++;
+      continue;
+    }
+    const item = t.slice(2).trim();
+    if (item === "") {
+      const childIndent = lines[i + 1]?.indent ?? line.indent + 1;
+      let j = i + 1;
+      while (j < lines.length && (lines[j]?.indent ?? -1) >= childIndent) j++;
+      out.push(parseMapping(lines.slice(i + 1, j), 0, childIndent).value);
+      i = j;
+    } else {
+      out.push(parseFlowValue(item));
+      i++;
+    }
+  }
+  return out;
+}
+function parseFrontmatterBlock(block) {
+  const lines = tokenize(block);
+  if (lines.length === 0) return null;
+  const { value } = parseMapping(lines, 0, 0);
+  return value;
+}
+
+// src/core/frontmatter.ts
 var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 var MODEL_LINE_RE = /^model:[ \t]*(.*)$/m;
+var RESERVED_AGENT_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "mode",
+  "description",
+  "permission",
+  "color",
+  "tools",
+  "prompt",
+  "steps",
+  "maxSteps"
+]);
 function cleanModelValue(raw) {
   let v = raw;
   const hash2 = v.search(/[ \t]#/);
@@ -16116,6 +16408,55 @@ function setFrontmatterModel(content, model) {
   const nextFm = fm[0].slice(0, blockStart) + nextBlock + fm[0].slice(blockStart + block.length);
   return nextFm + content.slice(fm[0].length);
 }
+function getFrontmatterOptions(content) {
+  const fm = FRONTMATTER_RE.exec(content);
+  if (!fm?.[1]) return {};
+  const parsed = parseFrontmatterBlock(fm[1]);
+  if (!parsed) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(parsed)) {
+    if (k === "model" || RESERVED_AGENT_KEYS.has(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+function setFrontmatterOptions(content, options) {
+  const fm = FRONTMATTER_RE.exec(content);
+  if (!fm?.[1]) throw new Error("no frontmatter block");
+  const block = fm[1];
+  const keys = Object.keys(options);
+  if (keys.length === 0) return content;
+  const eol = block.includes("\r\n") ? "\r\n" : "\n";
+  const lines = block.split(/\r?\n/);
+  const handled = /* @__PURE__ */ new Set();
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([A-Za-z0-9_-]+):[ \t]*(.*)$/.exec(lines[i] ?? "");
+    if (!m) continue;
+    const key = m[1] ?? "";
+    if (!(key in options)) continue;
+    handled.add(key);
+    let end = i + 1;
+    while (end < lines.length && /^[ \t]+/.test(lines[end] ?? "")) end++;
+    const value = options[key];
+    if (value === null || value === void 0) {
+      lines.splice(i, end - i);
+      i--;
+    } else {
+      lines.splice(i, end - i, `${key}: ${serializeOptionValue(value)}`);
+    }
+  }
+  const appended = [];
+  for (const [key, value] of Object.entries(options)) {
+    if (handled.has(key)) continue;
+    if (value === null || value === void 0) continue;
+    appended.push(`${key}: ${serializeOptionValue(value)}`);
+  }
+  const nextBlock = appended.length > 0 ? lines.join(eol) + eol + appended.join(eol) : lines.join(eol);
+  if (nextBlock === block) return content;
+  const blockStart = fm[0].indexOf(block);
+  const nextFm = fm[0].slice(0, blockStart) + nextBlock + fm[0].slice(blockStart + block.length);
+  return nextFm + content.slice(fm[0].length);
+}
 function agentFilePath(agentsDir, name) {
   return path4.join(agentsDir, `${name}.md`);
 }
@@ -16129,7 +16470,7 @@ async function listAgentFiles(agentsDir) {
   }
   return names.filter((n) => n.endsWith(".md")).map((n) => n.slice(0, -".md".length)).sort();
 }
-async function readAgentModels(agentsDir) {
+async function readAgentEntries(agentsDir) {
   const out = {};
   for (const name of await listAgentFiles(agentsDir)) {
     const filePath = agentFilePath(agentsDir, name);
@@ -16140,10 +16481,17 @@ async function readAgentModels(agentsDir) {
       throw new IOError(`Failed to read ${filePath}: ${cause.message}`, cause);
     }
     const model = getFrontmatterModel(content);
-    if (model !== null) out[name] = model;
+    if (model === null) continue;
+    out[name] = { model, options: getFrontmatterOptions(content) };
   }
   return out;
 }
+async function readAgentModels(agentsDir) {
+  const entries = await readAgentEntries(agentsDir);
+  const out = {};
+  for (const [name, entry] of Object.entries(entries)) out[name] = entry.model;
+  return out;
+}
 async function readAgentFileStrict(agentsDir, name) {
   const filePath = agentFilePath(agentsDir, name);
   if (!existsSync3(filePath)) {
@@ -16159,7 +16507,7 @@ async function readAgentFileStrict(agentsDir, name) {
   if (model === null) {
     throw new AgentFileError(name, filePath, "no frontmatter `model:` line to rewrite");
   }
-  return { filePath, content, model };
+  return { filePath, content, model, options: getFrontmatterOptions(content) };
 }
 
 // src/core/history.ts
@@ -16428,15 +16776,14 @@ async function applyStack(paths, name, options = {}) {
   const pending = [];
   for (const [agent, entry] of Object.entries(target.agents)) {
     const { filePath, content, model } = await readAgentFileStrict(paths.agentsDir, agent);
-    pending.push({
-      agent,
-      filePath,
-      next: model === entry.model ? null : setFrontmatterModel(content, entry.model)
-    });
+    const wantOptions = entryOptions(entry);
+    const afterOptions = setFrontmatterOptions(content, wantOptions);
+    const nextContent = entry.model === model ? afterOptions : setFrontmatterModel(afterOptions, entry.model);
+    pending.push({ agent, filePath, next: nextContent === content ? null : nextContent });
   }
   const prevState = await readState(paths.statePath);
   const prevActive = prevState?.active ?? null;
-  const displaced = { agents: modelsToStackAgents(await readAgentModels(paths.agentsDir)) };
+  const displaced = { agents: entriesToStackAgents(await readAgentEntries(paths.agentsDir)) };
   const historyId = await appendHistory(
     paths.historyDir,
     prevActive ?? "(none)",
@@ -16466,11 +16813,24 @@ async function applyStack(paths, name, options = {}) {
     restartRequired: true
   };
 }
-function modelsToStackAgents(models) {
+function entryOptions(entry) {
+  const rec = entry;
   const out = {};
-  for (const k of Object.keys(models).sort()) {
-    const model = models[k];
-    if (model !== void 0) out[k] = { model };
+  for (const [k, v] of Object.entries(rec)) {
+    if (k === "model" || RESERVED_AGENT_KEYS.has(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+function entriesToStackAgents(entries) {
+  const out = {};
+  for (const name of Object.keys(entries).sort()) {
+    const entry = entries[name];
+    if (!entry) continue;
+    const { model, options } = entry;
+    const stackEntry = { model };
+    for (const [k, v] of Object.entries(options)) stackEntry[k] = v;
+    out[name] = stackEntry;
   }
   return out;
 }
@@ -16507,8 +16867,8 @@ async function captureStack(paths, name, options = {}) {
   if (existsSync6(dest) && !options.force) {
     throw new UserError(`Stack "${name}" already exists. Use --force to overwrite.`);
   }
-  const models = await readAgentModels(paths.agentsDir);
-  const agents = modelsToStackAgents(models);
+  const entries = await readAgentEntries(paths.agentsDir);
+  const agents = entriesToStackAgents(entries);
   if (Object.keys(agents).length === 0) {
     throw new UserError(
       `No agent .md files with a frontmatter \`model:\` line found in ${paths.agentsDir}.`
@@ -16551,7 +16911,7 @@ async function exportStack(paths, name, toFile) {
 }
 
 // src/version.ts
-var VERSION = "1.0.6";
+var VERSION = "1.0.7";
 
 // src/cli.ts
 var log = (...args) => console.log(...args);