From 9d83719e85ddfe1ac1e78db9716f01053f27e79b Mon Sep 17 00:00:00 2001 From: Ondrej Drapalik Date: Tue, 8 Sep 2026 22:28:07 +0200 Subject: [PATCH 1/2] feat: pin model and reasoning per template --- src/config.js | 16 +++- src/model-pin.js | 122 +++++++++++++++++++++++++++ src/provision.js | 15 ++++ test/config.test.js | 42 ++++++++++ test/model-pin.test.js | 184 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 378 insertions(+), 1 deletion(-) create mode 100644 src/model-pin.js create mode 100644 test/model-pin.test.js diff --git a/src/config.js b/src/config.js index fe54b56..003ed64 100644 --- a/src/config.js +++ b/src/config.js @@ -4,6 +4,7 @@ import os from "node:os" import TOML from "@iarna/toml" import { HARNESSES, readHarnessFile } from "./harnesses.js" +import { modelEnv, normalizePin } from "./model-pin.js" import { AUTH_PATH, CONFIG_PATH, CONNECTIONS_DIR } from "./config-paths.js" import { applyConnection, readConnections, selectConnection } from "./connections.js" export { AUTH_PATH, CONFIG_PATH } from "./config-paths.js" @@ -264,12 +265,18 @@ function nameTable(raw) { export function resolveEnvConfig({ sandbox = {}, templates = {} } = {}) { const byTemplate = {} const prefer = {} + const models = {} if (templates && typeof templates === "object" && !Array.isArray(templates)) { for (const [template, section] of Object.entries(templates)) { const name = String(template).trim() if (!name) continue const env = envTable(section?.env) if (Object.keys(env).length) byTemplate[name] = env + // `model` / `reasoning`: which model that template's agent uses and how hard it + // thinks, for every box booted from it. Free strings, each harness has its own + // vocabulary; src/model-pin.js knows where each harness reads them from. + const pin = normalizePin(section) + if (pin) models[name] = pin // `prefer = "env"` — the documented way to take back the precedence a // discovered SESSION otherwise wins (ADR 0010). Only that one value means // anything; anything else is left unset rather than guessed at, so a typo @@ -277,7 +284,7 @@ export function resolveEnvConfig({ sandbox = {}, templates = {} } = {}) { if (String(section?.prefer ?? "").trim() === "env") prefer[name] = "env" } } - return { envShared: envTable(sandbox?.env), envByTemplate: byTemplate, templatePrefer: prefer } + return { envShared: envTable(sandbox?.env), envByTemplate: byTemplate, templatePrefer: prefer, templateModels: models } } /** @@ -418,6 +425,11 @@ export function resolveEnv(cfg, template, env = {}, now = Date.now(), readFile = const session = sessionValue(cfg, template, now, readFile) const merged = { ...(cfg?.templateEnvDefaults?.[template] || {}), + // The model pin (`[templates.] model` / `reasoning`), as the variables the + // harness reads plus the two shared ones the file-route pin command reads + // (src/model-pin.js). Below the user's own `env` table, so a hand-written + // ANTHROPIC_MODEL still wins over the pin. + ...modelEnv(template, cfg?.templateModels?.[template]), // The discovered rung has two halves, and forwarding wins between them: a name // resolves from THIS run's environment, while a stored value is a copy taken // whenever `e2b-box auth` last ran. When both name the same box variable the @@ -908,6 +920,8 @@ export function loadConfig() { // hand-written value — and `templatePrefer` is how the user takes that back. envSession: auth.envSession, templatePrefer: env.templatePrefer, + // `[templates.] model` / `reasoning` → {model, reasoning} per template. + templateModels: env.templateModels, // Shipped per-template env (behaviour, never credentials). Carried through // from DEFAULTS rather than read from the file: nothing in config.toml sets // it, and resolveEnv puts the user's own tables OVER it. diff --git a/src/model-pin.js b/src/model-pin.js new file mode 100644 index 0000000..4f3f9b7 --- /dev/null +++ b/src/model-pin.js @@ -0,0 +1,122 @@ +// Which model a box's agent uses, and how hard it thinks: `[templates.] +// model = "…"` and `reasoning = "…"` in config.toml, applied to EVERY box booted +// from that template, whether `open`, `fleet` or `run` booted it. +// +// Every harness has a default model and a default effort, and every harness lets a +// human change them in the TUI. A box has no human. Left alone, an agent picks +// whatever its vendor or its provider ranks first, which is how an opencode member +// on an OpenRouter key came up on an image model with no tool use (observed live, +// 2026-09-08). Pinning it in the launch command works for one verb at a time and +// has to be repeated in `[fleet.agents]` and `[run.agents]`; a plain `e2b-box open` +// followed by typing `opencode` gets neither. So the pin goes where the agent reads +// its defaults from, and the launch commands stay as they are. +// +// Two routes, one per harness, chosen by what that harness documents: +// · ENV the harness reads a variable at start (claude, opencode). Set on the +// box at create time, beside the credential. +// · FILE the harness reads its own config file (codex, grok, droid, prime, +// muse). A one-line command, run over the SDK right after the first-run +// seed (src/fleet-seed.js), writes the keys into that file. +// Both routes read the SAME two variables, `HERDR_E2B_MODEL` and +// `HERDR_E2B_REASONING`, which are injected into every box whose template has a +// pin. That is also the hook for a user's own `[fleet.agents]` / `[run.agents]` +// command: `--model "$HERDR_E2B_MODEL"` works for any CLI the table below does not +// cover. +// +// THE RULES EVERY FILE COMMAND KEEPS, the same as the seeds: one line; POSIX sh +// plus `node -e` (every shipped agent template has Node); never clobber a key that +// is already set (a resumed box's file is the user's); a missing variable means +// "leave the default alone", never an empty string written into a config. +// +// Keys verified against each vendor's own docs or a file the CLI wrote itself: +// claude ANTHROPIC_MODEL, CLAUDE_CODE_EFFORT_LEVEL (code.claude.com/docs/en/model-config) +// opencode OPENCODE_CONFIG_CONTENT, inline JSON, "model" (opencode.ai/docs/config; reasoning is per-model +// variants there, so it is not pinned) +// codex ~/.codex/config.toml model, model_reasoning_effort (codex-rs config) +// grok ~/.grok/config.toml [models] default, default_reasoning_effort (docs.x.ai/build/settings/reference) +// droid ~/.factory/settings.json model, reasoningEffort (docs.factory.ai/droid-cli/settings) +// prime ~/.prime/agent/settings.json defaultProvider, defaultModel, defaultThinkingLevel +// (settings-manager.js, 0.9.3; model is written as `/`, split at the first `/`) +// muse ~/.config/muse/settings.json reasoning_effort (a file muse 1.0.3 wrote itself; no verified +// model key, so `model` is reported and not written) +// amp nothing: amp has no model setting, only `--mode low|medium|high|ultra` + +/** The two variables both routes read. Exported so tests and docs name the same strings. */ +export const MODEL_VAR = "HERDR_E2B_MODEL" +export const REASONING_VAR = "HERDR_E2B_REASONING" + +/** Templates whose harness reads the pin from the environment, and the variables it reads. */ +const ENV_ROUTES = { + claude: (model, reasoning) => ({ + ...(model ? { ANTHROPIC_MODEL: model } : {}), + ...(reasoning ? { CLAUDE_CODE_EFFORT_LEVEL: reasoning } : {}), + }), + // "inject inline JSON as a final local-scope merge" (opencode's own description of + // the variable), so it wins over the seeded ~/.config/opencode/opencode.json. + opencode: (model) => (model ? { OPENCODE_CONFIG_CONTENT: JSON.stringify({ model }) } : {}), +} + +// The file route. `M`/`R` are read inside the box; nothing here interpolates a value. +const NODE = "node -e" +const FILE_ROUTES = { + codex: + `mkdir -p "$HOME/.codex"; ${NODE} 'const fs=require("fs"),f=process.env.HOME+"/.codex/config.toml",NL=String.fromCharCode(10),m=process.env.${MODEL_VAR},r=process.env.${REASONING_VAR};let t="";try{t=fs.readFileSync(f,"utf8")}catch{}let add="";if(m&&!/^model *=/m.test(t))add+="model = "+JSON.stringify(m)+NL;if(r&&!/^model_reasoning_effort *=/m.test(t))add+="model_reasoning_effort = "+JSON.stringify(r)+NL;if(add){fs.writeFileSync(f,add+t);console.log("herdr-e2b: codex pinned"+(m?" to "+m:"")+(r?" at "+r+" effort":""))}else console.log("herdr-e2b: codex model/effort already set - leaving it alone")'`, + // Top-level keys go BEFORE any [table] in TOML, hence prepend. The [models] + // section is only created when absent: editing inside an existing one is not a + // one-liner worth trusting, and a box that already has one was configured by hand. + grok: + `mkdir -p "$HOME/.grok"; ${NODE} 'const fs=require("fs"),f=process.env.HOME+"/.grok/config.toml",NL=String.fromCharCode(10),m=process.env.${MODEL_VAR},r=process.env.${REASONING_VAR};let t="";try{t=fs.readFileSync(f,"utf8")}catch{}if(!m&&!r)process.exit(0);if(t.includes("[models]")){console.log("herdr-e2b: grok already has a [models] section - leaving it alone");process.exit(0)}let s=(t&&!t.endsWith(NL)?NL:"")+"[models]"+NL;if(m)s+="default = "+JSON.stringify(m)+NL;if(r)s+="default_reasoning_effort = "+JSON.stringify(r)+NL;fs.writeFileSync(f,t+s);console.log("herdr-e2b: grok pinned"+(m?" to "+m:"")+(r?" at "+r+" effort":""))'`, + droid: + `mkdir -p "$HOME/.factory"; ${NODE} 'const fs=require("fs"),f=process.env.HOME+"/.factory/settings.json",m=process.env.${MODEL_VAR},r=process.env.${REASONING_VAR};let c={};try{c=JSON.parse(fs.readFileSync(f,"utf8"))}catch{}let w=false;if(m&&c.model===undefined){c.model=m;w=true}if(r&&c.reasoningEffort===undefined){c.reasoningEffort=r;w=true}if(w){fs.writeFileSync(f,JSON.stringify(c,null,2));console.log("herdr-e2b: droid pinned"+(m?" to "+m:"")+(r?" at "+r+" effort":""))}else if(m||r)console.log("herdr-e2b: droid model/effort already set - leaving it alone")'`, + // prime keeps provider and model apart and its ids are bare (`gpt-6-astra`, + // `z-ai/glm-5.2`), so the pin is spelled `/` and split at the + // FIRST slash: `prime-inference/z-ai/glm-5.2` is provider `prime-inference`. + prime: + `mkdir -p "$HOME/.prime/agent"; ${NODE} 'const fs=require("fs"),f=process.env.HOME+"/.prime/agent/settings.json",m=process.env.${MODEL_VAR},r=process.env.${REASONING_VAR};let c={};try{c=JSON.parse(fs.readFileSync(f,"utf8"))}catch{}let w=false;if(m&&c.defaultModel===undefined){const i=m.indexOf("/");if(i>0){c.defaultProvider=m.slice(0,i);c.defaultModel=m.slice(i+1)}else c.defaultModel=m;w=true}if(r&&c.defaultThinkingLevel===undefined){c.defaultThinkingLevel=r;w=true}if(w){fs.writeFileSync(f,JSON.stringify(c,null,2));console.log("herdr-e2b: prime pinned"+(m?" to "+m:"")+(r?" at "+r+" thinking":""))}else if(m||r)console.log("herdr-e2b: prime model/thinking already set - leaving it alone")'`, + muse: + `mkdir -p "$HOME/.config/muse"; ${NODE} 'const fs=require("fs"),f=process.env.HOME+"/.config/muse/settings.json",m=process.env.${MODEL_VAR},r=process.env.${REASONING_VAR};let c={};try{c=JSON.parse(fs.readFileSync(f,"utf8"))}catch{}if(m)console.log("herdr-e2b: muse has no verified settings key for a model - pass --model to it yourself");if(r&&c.reasoning_effort===undefined){if(c.schema_version===undefined)c.schema_version=1;c.reasoning_effort=r;fs.writeFileSync(f,JSON.stringify(c,null,2));console.log("herdr-e2b: muse pinned at "+r+" effort")}else if(r)console.log("herdr-e2b: muse reasoning_effort already set - leaving it alone")'`, +} + +/** Normalize one `[templates.]` section's pin. `null` when it pins nothing. */ +export function normalizePin(section) { + const model = String(section?.model ?? "").trim() + const reasoning = String(section?.reasoning ?? "").trim() + if (!model && !reasoning) return null + return { ...(model ? { model } : {}), ...(reasoning ? { reasoning } : {}) } +} + +/** + * The environment a pinned template's box is created with: the two shared + * variables plus the harness's own, when it reads one. `{}` for no pin. + */ +export function modelEnv(template, pin) { + if (!pin) return {} + const { model = "", reasoning = "" } = pin + const own = ENV_ROUTES[template]?.(model, reasoning) || {} + return { + ...(model ? { [MODEL_VAR]: model } : {}), + ...(reasoning ? { [REASONING_VAR]: reasoning } : {}), + ...own, + } +} + +/** + * The one-line command that writes the pin into the harness's config file inside + * the box, or "" when the template has no file route (env-only, `amp`, `base`, a + * user's own template) or nothing is pinned. The command reads the variables + * `modelEnv` set, so it is only useful on a box created with them. + */ +export function pinCommand(template, pin) { + if (!pin) return "" + return FILE_ROUTES[String(template ?? "")] ?? "" +} + +/** For docs, the picker and the refusal message: what a pin can do per template. */ +export function pinSupport(template) { + const t = String(template ?? "") + if (t === "claude") return { model: true, reasoning: true, route: "env" } + if (t === "opencode") return { model: true, reasoning: false, route: "env" } + if (t === "muse") return { model: false, reasoning: true, route: "file" } + if (t in FILE_ROUTES) return { model: true, reasoning: true, route: "file" } + return { model: false, reasoning: false, route: null } +} diff --git a/src/provision.js b/src/provision.js index 7329a2b..0dc0073 100644 --- a/src/provision.js +++ b/src/provision.js @@ -26,6 +26,7 @@ import { CONFIG_PATH, } from "./config.js" import { seedCommand } from "./fleet-seed.js" +import { pinCommand } from "./model-pin.js" import { selectConnection } from "./connections.js" import { requireApiKey, @@ -347,6 +348,20 @@ async function main() { .catch(() => {}) } + // The model pin (`[templates.] model` / `reasoning`), for the harnesses that + // read it from their own config file. After the seed, because the seed may have + // created that file, and it only ever adds keys the file does not have. The values + // arrive as HERDR_E2B_MODEL / HERDR_E2B_REASONING in the box's environment (set at + // create time by resolveEnv), so this command carries no value and does nothing on + // a box created before the pin was configured. Best-effort like the seed. + const pin = pinCommand(boxTemplate, cfg.templateModels?.[boxTemplate]) + if (pin) { + await sandbox.files.write("/home/user/.herdr-e2b-model.sh", `${pin}\n`) + await sandbox.commands + .run('bash "$HOME/.herdr-e2b-model.sh"', { cwd: projectPath }) + .catch(() => {}) + } + const url = `https://${sandbox.getHost(cfg.serverPort)}` await writeRecord(key, { status: "ready", diff --git a/test/config.test.js b/test/config.test.js index f5d23b8..9c31784 100644 --- a/test/config.test.js +++ b/test/config.test.js @@ -1169,3 +1169,45 @@ test("resolveRun: [run.agents] keeps strings, trimmed, including the empty one", const r = resolveRun({ agents: { claude: "", muse: ' muse --yolo "$(cat $HOME/.herdr-e2b-task.md)" ', droid: 7 } }) assert.deepEqual(r.agents, { claude: "", muse: 'muse --yolo "$(cat $HOME/.herdr-e2b-task.md)"' }) }) + +// --- [templates.] model / reasoning ------------------------------------------ +// One knob per template, applied to every box booted from it. The pin arrives in +// the box as environment (src/model-pin.js), below the user's own `env` table. + +test("resolveEnvConfig: model and reasoning are read per template, trimmed, blanks dropped", () => { + const r = resolveEnvConfig({ + templates: { + opencode: { model: " openrouter/qwen/qwen3.8-max-0902 " }, + codex: { model: "gpt-5.4", reasoning: "high", env: { A: "b" } }, + claude: { reasoning: " " }, + amp: {}, + }, + }) + assert.deepEqual(r.templateModels, { + opencode: { model: "openrouter/qwen/qwen3.8-max-0902" }, + codex: { model: "gpt-5.4", reasoning: "high" }, + }) + assert.deepEqual(r.envByTemplate, { codex: { A: "b" } }) + assert.deepEqual(resolveEnvConfig().templateModels, {}) +}) + +test("resolveEnv: a pin becomes the harness's variables plus the two shared ones", () => { + const cfg = { templateModels: { claude: { model: "claude-opus-5", reasoning: "high" }, codex: { model: "gpt-5.4" } } } + assert.deepEqual(resolveEnv(cfg, "claude"), { + HERDR_E2B_MODEL: "claude-opus-5", + HERDR_E2B_REASONING: "high", + ANTHROPIC_MODEL: "claude-opus-5", + CLAUDE_CODE_EFFORT_LEVEL: "high", + }) + assert.deepEqual(resolveEnv(cfg, "codex"), { HERDR_E2B_MODEL: "gpt-5.4" }) + assert.equal(resolveEnv(cfg, "grok"), undefined) +}) + +test("resolveEnv: the user's own env table beats the pin", () => { + const cfg = { + templateModels: { claude: { model: "claude-opus-5" } }, + envByTemplate: { claude: { ANTHROPIC_MODEL: "claude-sonnet-5" } }, + } + assert.equal(resolveEnv(cfg, "claude").ANTHROPIC_MODEL, "claude-sonnet-5") + assert.equal(resolveEnv(cfg, "claude").HERDR_E2B_MODEL, "claude-opus-5") +}) diff --git a/test/model-pin.test.js b/test/model-pin.test.js new file mode 100644 index 0000000..59884d3 --- /dev/null +++ b/test/model-pin.test.js @@ -0,0 +1,184 @@ +import test from "node:test" +import assert from "node:assert/strict" +import { execFileSync } from "node:child_process" +import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs" +import os from "node:os" +import path from "node:path" + +import { MODEL_VAR, REASONING_VAR, modelEnv, normalizePin, pinCommand, pinSupport } from "../src/model-pin.js" + +// --- the config shape ----------------------------------------------------------- + +test("normalizePin: trims, drops blanks, and is null when nothing is pinned", () => { + assert.deepEqual(normalizePin({ model: " openrouter/qwen/qwen3.8-max-0902 " }), { model: "openrouter/qwen/qwen3.8-max-0902" }) + assert.deepEqual(normalizePin({ reasoning: "high" }), { reasoning: "high" }) + assert.deepEqual(normalizePin({ model: "m", reasoning: "r" }), { model: "m", reasoning: "r" }) + for (const s of [undefined, null, {}, { model: " " }, { model: "", reasoning: "" }, { env: { A: "b" } }]) { + assert.equal(normalizePin(s), null, JSON.stringify(s)) + } +}) + +// --- the env route -------------------------------------------------------------- + +test("modelEnv: every pinned template gets the two shared variables", () => { + for (const t of ["claude", "codex", "opencode", "amp", "grok", "droid", "muse", "prime", "base", "mine/own"]) { + const env = modelEnv(t, { model: "m", reasoning: "r" }) + assert.equal(env[MODEL_VAR], "m", t) + assert.equal(env[REASONING_VAR], "r", t) + } + assert.deepEqual(modelEnv("codex", { model: "gpt-5.4" }), { [MODEL_VAR]: "gpt-5.4" }) + assert.deepEqual(modelEnv("codex", { reasoning: "high" }), { [REASONING_VAR]: "high" }) +}) + +test("modelEnv: claude reads its own variables", () => { + assert.deepEqual(modelEnv("claude", { model: "claude-opus-5", reasoning: "high" }), { + [MODEL_VAR]: "claude-opus-5", + [REASONING_VAR]: "high", + ANTHROPIC_MODEL: "claude-opus-5", + CLAUDE_CODE_EFFORT_LEVEL: "high", + }) + assert.equal(modelEnv("claude", { reasoning: "low" }).ANTHROPIC_MODEL, undefined) +}) + +test("modelEnv: opencode reads inline JSON config, model only", () => { + const env = modelEnv("opencode", { model: "openrouter/qwen/qwen3.8-max-0902", reasoning: "high" }) + assert.deepEqual(JSON.parse(env.OPENCODE_CONFIG_CONTENT), { model: "openrouter/qwen/qwen3.8-max-0902" }) + // Reasoning is per-model variants in opencode, so a reasoning-only pin sets no + // opencode variable at all rather than an empty config. + assert.equal(modelEnv("opencode", { reasoning: "high" }).OPENCODE_CONFIG_CONTENT, undefined) +}) + +test("modelEnv: no pin, no variables", () => { + assert.deepEqual(modelEnv("claude", null), {}) + assert.deepEqual(modelEnv("claude", undefined), {}) +}) + +// --- the file route ------------------------------------------------------------- + +test("pinCommand: file-route harnesses get a command, env-only and unknown ones do not", () => { + const pin = { model: "m", reasoning: "r" } + for (const t of ["codex", "grok", "droid", "prime", "muse"]) assert.ok(pinCommand(t, pin), t) + for (const t of ["claude", "opencode", "amp", "base", "mine/own", "", undefined]) assert.equal(pinCommand(t, pin), "", String(t)) + assert.equal(pinCommand("codex", null), "") +}) + +test("every file-route command is one line, names the variables, carries no value", () => { + for (const t of ["codex", "grok", "droid", "prime", "muse"]) { + const cmd = pinCommand(t, { model: "SECRET-LOOKING-VALUE", reasoning: "xhigh" }) + assert.ok(!cmd.includes("\n"), `${t}: newline`) + assert.ok(!cmd.includes("\\"), `${t}: backslash`) + assert.ok(cmd.includes(MODEL_VAR) && cmd.includes(REASONING_VAR), `${t}: does not read the variables`) + assert.ok(!cmd.includes("SECRET-LOOKING-VALUE") && !cmd.includes("xhigh"), `${t}: interpolates a value`) + } +}) + +test("pinSupport: says what each template can pin", () => { + assert.deepEqual(pinSupport("claude"), { model: true, reasoning: true, route: "env" }) + assert.deepEqual(pinSupport("opencode"), { model: true, reasoning: false, route: "env" }) + assert.deepEqual(pinSupport("codex"), { model: true, reasoning: true, route: "file" }) + assert.deepEqual(pinSupport("muse"), { model: false, reasoning: true, route: "file" }) + assert.deepEqual(pinSupport("amp"), { model: false, reasoning: false, route: null }) + assert.deepEqual(pinSupport("base"), { model: false, reasoning: false, route: null }) +}) + +// --- the file-route commands, actually executed --------------------------------- +// Each runs against a fake HOME under the OS temp dir with the two variables set, +// exactly the way provision.js runs it in a box. This is the one place the shell +// is exercised rather than read, so a quoting slip fails here and not in a fleet. + +function runPin(template, env, home = mkdtempSync(path.join(os.tmpdir(), "herdr-pin-"))) { + const out = execFileSync("bash", ["-c", pinCommand(template, { model: "x", reasoning: "y" })], { + env: { PATH: process.env.PATH, HOME: home, ...env }, + encoding: "utf8", + }) + return { home, out } +} + +test("codex: prepends model and effort to config.toml, once", () => { + const { home, out } = runPin("codex", { [MODEL_VAR]: "gpt-5.4", [REASONING_VAR]: "high" }) + const f = path.join(home, ".codex/config.toml") + assert.equal(readFileSync(f, "utf8"), 'model = "gpt-5.4"\nmodel_reasoning_effort = "high"\n') + assert.match(out, /pinned to gpt-5.4 at high effort/) + // Second run: nothing to add, nothing rewritten. + const again = runPin("codex", { [MODEL_VAR]: "other", [REASONING_VAR]: "low" }, home) + assert.equal(readFileSync(f, "utf8"), 'model = "gpt-5.4"\nmodel_reasoning_effort = "high"\n') + assert.match(again.out, /leaving it alone/) +}) + +test("codex: keys land ABOVE an existing table, and a set key is not touched", () => { + const home = mkdtempSync(path.join(os.tmpdir(), "herdr-pin-")) + mkdirSync(path.join(home, ".codex")) + writeFileSync(path.join(home, ".codex/config.toml"), 'model_reasoning_effort = "low"\n[projects."/p"]\ntrust_level = "trusted"\n') + runPin("codex", { [MODEL_VAR]: "gpt-5.4", [REASONING_VAR]: "high" }, home) + assert.equal( + readFileSync(path.join(home, ".codex/config.toml"), "utf8"), + 'model = "gpt-5.4"\nmodel_reasoning_effort = "low"\n[projects."/p"]\ntrust_level = "trusted"\n', + ) +}) + +test("grok: creates a [models] section, and leaves an existing one alone", () => { + const { home } = runPin("grok", { [MODEL_VAR]: "grok-build", [REASONING_VAR]: "high" }) + const f = path.join(home, ".grok/config.toml") + assert.equal(readFileSync(f, "utf8"), '[models]\ndefault = "grok-build"\ndefault_reasoning_effort = "high"\n') + const again = runPin("grok", { [MODEL_VAR]: "grok-4.5" }, home) + assert.equal(readFileSync(f, "utf8"), '[models]\ndefault = "grok-build"\ndefault_reasoning_effort = "high"\n') + assert.match(again.out, /leaving it alone/) +}) + +test("grok: appends after existing unrelated sections", () => { + const home = mkdtempSync(path.join(os.tmpdir(), "herdr-pin-")) + mkdirSync(path.join(home, ".grok")) + writeFileSync(path.join(home, ".grok/config.toml"), "[cli]\nauto_update = false") + runPin("grok", { [MODEL_VAR]: "grok-build" }, home) + assert.equal(readFileSync(path.join(home, ".grok/config.toml"), "utf8"), '[cli]\nauto_update = false\n[models]\ndefault = "grok-build"\n') +}) + +test("droid: merges into settings.json without clobbering", () => { + const home = mkdtempSync(path.join(os.tmpdir(), "herdr-pin-")) + mkdirSync(path.join(home, ".factory")) + writeFileSync(path.join(home, ".factory/settings.json"), JSON.stringify({ hooks: {}, reasoningEffort: "off" })) + runPin("droid", { [MODEL_VAR]: "glm-5.2", [REASONING_VAR]: "max" }, home) + assert.deepEqual(JSON.parse(readFileSync(path.join(home, ".factory/settings.json"), "utf8")), { + hooks: {}, + reasoningEffort: "off", + model: "glm-5.2", + }) +}) + +test("prime: splits provider/model at the first slash, keeps a provider-less id whole", () => { + const a = runPin("prime", { [MODEL_VAR]: "prime-inference/z-ai/glm-5.2", [REASONING_VAR]: "high" }) + assert.deepEqual(JSON.parse(readFileSync(path.join(a.home, ".prime/agent/settings.json"), "utf8")), { + defaultProvider: "prime-inference", + defaultModel: "z-ai/glm-5.2", + defaultThinkingLevel: "high", + }) + const b = runPin("prime", { [MODEL_VAR]: "gpt-6-astra" }) + assert.deepEqual(JSON.parse(readFileSync(path.join(b.home, ".prime/agent/settings.json"), "utf8")), { defaultModel: "gpt-6-astra" }) +}) + +test("muse: pins reasoning, and says a model cannot be pinned", () => { + const { home, out } = runPin("muse", { [MODEL_VAR]: "spark", [REASONING_VAR]: "high" }) + assert.deepEqual(JSON.parse(readFileSync(path.join(home, ".config/muse/settings.json"), "utf8")), { + schema_version: 1, + reasoning_effort: "high", + }) + assert.match(out, /no verified settings key for a model/) + assert.match(out, /pinned at high effort/) +}) + +test("a pin with neither variable set writes nothing", () => { + for (const t of ["codex", "grok", "droid", "prime", "muse"]) { + const { home } = runPin(t, {}) + const files = ["codex/config.toml", ".codex/config.toml", ".grok/config.toml", ".factory/settings.json", ".prime/agent/settings.json", ".config/muse/settings.json"] + .map((f) => path.join(home, f)) + .filter((f) => { + try { + readFileSync(f) + return true + } catch { + return false + } + }) + assert.deepEqual(files, [], `${t}: wrote ${files.join(", ")}`) + } +}) From 23366fe82a9f3e9463d63eaa58b7432055c4b7e8 Mon Sep 17 00:00:00 2001 From: Ondrej Drapalik Date: Tue, 8 Sep 2026 22:28:07 +0200 Subject: [PATCH 2/2] docs: [templates.] model and reasoning --- ARCHITECTURE.md | 1 + CHANGELOG.md | 10 ++++++++++ README.md | 13 +++++++++++++ config/config.example.toml | 40 ++++++++++++++++++++++++++++++++++++++ docs/headless-run.md | 19 ++++++++++++++++++ 5 files changed, 83 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7dff169..2ef23fb 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -227,6 +227,7 @@ guide, with a CI example, is [docs/headless-run.md](docs/headless-run.md). | `harness-probe.js` | The impure half of the above: spawns the probes for all eight harnesses concurrently with a 5s ceiling, `shell: false` (so a shell function cannot answer for the binary) and stdin on `/dev/null` (one harness with no key opens a browser and blocks forever), then formats one row per harness. Read-only — it never writes. | | `harness-auth.js` | `e2b-box auth` itself: probe, show, ask **once** for the whole batch, write. `buildPlan` turns probe rows into what will be kept and is pure given its file reader; `renderAuthToml` and `formatPlan` are pure; only `writeAuthFile` touches disk. It writes a GENERATED `auth.toml` beside `config.toml` at mode `0600`, regenerated whole on every run, and never touches `config.toml` — one writer each is what makes "hand-written always wins" true. ADR 0009's split lives here: a value read out of a **file** is stored, a value seen only in the **shell** records the variable's NAME and nothing else. Missing credentials are reported and never prompted for; `--yes` skips the question, and no terminal plus no flag writes nothing. It also warns when a variable it recorded by NAME is invisible to a login shell (`invisibleToLoginShell`, one `bash -lc` for the whole batch, names only in both directions) — herdr launches plugin commands from one, so a key exported from a zsh rc is found here and absent at create time. Two entry points, one implementation: the verb a user types, and `install.sh`'s `harness_discovery` on first run — the installer shells out to the very same subcommand with `--yes` (a build step has no TTY), indents its report, and treats any failure as a report rather than a failed install. | | `run-agent.js` | The headless agent table `e2b-box run` drives a box with: `DEFAULT_RUN_AGENTS` (template → that vendor's verified **non-interactive** command, `claude -p`, `codex exec`, `opencode run`, `amp -x`, each with its skip-approvals flag, each reading the task from `TASK_FILE` inside the box, never from argv) and `runCommand` (`[run.agents]` over those, by key presence, so `""` means "no headless agent"). Kept apart from `fleetAgents` on purpose: the interactive command for a template is not a flag away from its headless one. A template with no verified headless mode has no default and `run` refuses it by name. Also the CLI bash calls (`