codex-model-router 2.0.0 → 2.1.0

package/README.md

@@ -10,7 +10,7 @@ The normal installation uses free mode:
 
 - The user-selected primary model handles conversation, clarification, follow-ups, final replies, and trivial work.
 - Terra/high investigates, produces implementation-ready plans, verifies results, debugs, and replans.
-- Luna/max performs most clear, bounded, repetitive, or independently verifiable implementation work.
+- Luna/xhigh performs most clear, bounded, repetitive, or independently verifiable implementation work.
 - Sol/medium is read-only and used only when Terra still cannot resolve core logic after focused investigation and one materially revised plan, or when the user explicitly requests Sol.
 - Existing built-in and custom agents remain available and take precedence when they are a better match.
 
@@ -49,6 +49,17 @@ codex-model-router install --set-default
 
 Running a later plain `install` returns package-managed default settings to free mode. User-modified model settings are preserved.
 
+## Agent reasoning
+
+The managed agent defaults are Terra/high, Luna/xhigh, and Sol/medium. Override all agents or individual agents during installation:
+
+```sh
+codex-model-router install --agent-reasoning high
+codex-model-router install --terra-reasoning xhigh --luna-reasoning low --sol-reasoning max
+```
+
+Supported values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`. Per-agent options override `--agent-reasoning`. Later installs preserve unchanged package-managed reasoning choices; manually edited agent files remain protected.
+
 ## Install
 
 Run from npm:
@@ -69,7 +80,7 @@ Installing the CLI globally only makes the command available system-wide. Use `i
 Install a specific GitHub release:
 
 ```sh
-npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v2.0.0.tar.gz
+npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v2.1.0.tar.gz
 codex-model-router install
 ```
 
@@ -119,6 +130,8 @@ Terra verifies separately whether implementation matches the plan and whether th
 
 ```text
 codex-model-router install [--global] [--set-default] [--dry-run]
+  [--agent-reasoning <effort>]
+  [--terra-reasoning <effort>] [--luna-reasoning <effort>] [--sol-reasoning <effort>]
 codex-model-router uninstall [--global] [--dry-run]
 codex-model-router doctor [--global]
 codex-model-router --version

package/bin/codex-model-router.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { run } from "../lib/router.js";
+import { runCli } from "../lib/agent-reasoning-cli.js";
 
-process.exitCode = await run(process.argv.slice(2), { output: console.log });
+process.exitCode = await runCli(process.argv.slice(2), { output: console.log });

package/lib/agent-reasoning-cli.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  AGENT_NAMES,
+  configureAgentReasoning,
+  DEFAULT_AGENT_REASONING,
+  REASONING_EFFORTS,
+  VERSION
+} from "./manifest.js";
+import { run as runCore } from "./router.js";
+
+const OPTION_TO_AGENT = Object.freeze({
+  "--terra-reasoning": "terra",
+  "--luna-reasoning": "luna",
+  "--sol-reasoning": "sol"
+});
+
+function usage() {
+  return `codex-model-router ${VERSION}
+
+Usage:
+  codex-model-router install [--global] [--set-default] [--dry-run]
+    [--agent-reasoning <effort>]
+    [--terra-reasoning <effort>]
+    [--luna-reasoning <effort>]
+    [--sol-reasoning <effort>]
+  codex-model-router uninstall [--global] [--dry-run]
+  codex-model-router doctor [--global]
+  codex-model-router --version
+
+Reasoning efforts: ${REASONING_EFFORTS.join(", ")}
+Defaults: Terra=${DEFAULT_AGENT_REASONING.terra}, Luna=${DEFAULT_AGENT_REASONING.luna}, Sol=${DEFAULT_AGENT_REASONING.sol}`;
+}
+
+function optionValue(argv, index, option) {
+  const token = argv[index];
+  if (token.startsWith(`${option}=`)) return { value: token.slice(option.length + 1), consumed: 1 };
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) return { error: `missing value for ${option}` };
+  return { value, consumed: 2 };
+}
+
+function parseReasoningOptions(argv) {
+  const command = argv[0];
+  const cleaned = command ? [command] : [];
+  const overrides = {};
+  let all;
+
+  for (let index = 1; index < argv.length;) {
+    const token = argv[index];
+    const option = token.split("=", 1)[0];
+    const agent = OPTION_TO_AGENT[option];
+    if (option !== "--agent-reasoning" && !agent) {
+      cleaned.push(token);
+      index += 1;
+      continue;
+    }
+    if (command !== "install") return { error: `${option} is supported only for install` };
+    const parsed = optionValue(argv, index, option);
+    if (parsed.error) return parsed;
+    const reasoning = parsed.value.toLowerCase();
+    if (!REASONING_EFFORTS.includes(reasoning)) {
+      return { error: `unsupported reasoning effort: ${parsed.value}` };
+    }
+    if (agent) overrides[agent] = reasoning;
+    else all = reasoning;
+    index += parsed.consumed;
+  }
+  return { cleaned, overrides, all };
+}
+
+function digest(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function readRegularText(path) {
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink()) return null;
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function activeReasoning(content) {
+  const match = content.match(/^\s*model_reasoning_effort\s*=\s*"([^"\r\n]+)"\s*(?:#.*)?$/m);
+  return match && REASONING_EFFORTS.includes(match[1]) ? match[1] : null;
+}
+
+function versionAtLeast(version, minimum) {
+  const parse = (value) => String(value || "0").split(".").slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  const left = parse(version);
+  const right = parse(minimum);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return true;
+}
+
+async function installedReasoning(argv, options) {
+  const global = argv.includes("--global");
+  const home = resolve(options.home ?? homedir());
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const env = options.env ?? process.env;
+  const codexHome = global
+    ? resolve(env.CODEX_HOME || join(home, ".codex"))
+    : join(cwd, ".codex");
+  const stateText = await readRegularText(join(codexHome, "model-router-state.json"));
+  if (!stateText) return { reasoning: {}, content: {}, packageVersion: null };
+
+  let state;
+  try {
+    state = JSON.parse(stateText);
+  } catch {
+    return { reasoning: {}, content: {}, packageVersion: null };
+  }
+
+  const physicalCodexHome = await realpath(codexHome);
+  const reasoning = {};
+  const content = {};
+  for (const name of AGENT_NAMES) {
+    const path = join(physicalCodexHome, "agents", `${name}.toml`);
+    const tracked = state.files?.[name];
+    const current = await readRegularText(path);
+    if (!tracked || !current || resolve(tracked.path) !== resolve(path) || digest(current) !== tracked.hash) continue;
+    const effort = activeReasoning(current);
+    if (!effort) continue;
+    reasoning[name] = effort;
+    content[name] = current;
+  }
+  return { reasoning, content, packageVersion: state.packageVersion };
+}
+
+export async function runCli(argv, options = {}) {
+  const output = options.output ?? console.log;
+  if (!argv.length || argv.includes("--help") || argv.includes("-h")) {
+    output(usage());
+    return 0;
+  }
+
+  const parsed = parseReasoningOptions(argv);
+  if (parsed.error) {
+    output(`${parsed.error}\n\n${usage()}`);
+    return 1;
+  }
+
+  const installed = await installedReasoning(parsed.cleaned, options);
+  const selected = { ...DEFAULT_AGENT_REASONING };
+  if (versionAtLeast(installed.packageVersion, "2.1.0")) Object.assign(selected, installed.reasoning);
+  if (parsed.all) {
+    for (const name of AGENT_NAMES) selected[name] = parsed.all;
+  }
+  Object.assign(selected, parsed.overrides);
+  configureAgentReasoning(selected, installed.content);
+  return runCore(parsed.cleaned, options);
+}

package/lib/manifest.js

@@ -87,7 +87,7 @@ Return only the artifact required by the current stage.
 const luna = `name = "luna"
 description = "Implements clear, bounded work from an approved plan."
 model = "gpt-5.6-luna"
-model_reasoning_effort = "max"
+model_reasoning_effort = "xhigh"
 sandbox_mode = "workspace-write"
 developer_instructions = """
 Implement the current approved plan with the smallest coherent change.
@@ -155,45 +155,91 @@ Omit irrelevant fields and vague instructions. Preserve verified work, revise on
 Verification answers separately: did implementation match the plan, and did the plan plus implementation satisfy the request? Use PASS, IMPLEMENTATION_FIX, PLAN_REVISION, EVIDENCE_GAP, or REQUIREMENT_CLARIFICATION.
 `;
 
-export const TEMPLATES = Object.freeze({
-  terra: Object.freeze({ relative: ["agents", "terra.toml"], content: terra }),
-  luna: Object.freeze({ relative: ["agents", "luna.toml"], content: luna }),
-  sol: Object.freeze({ relative: ["agents", "sol.toml"], content: sol }),
-  skill: Object.freeze({ relative: ["model-router", "SKILL.md"], content: skill }),
-  planning: Object.freeze({ relative: ["implementation-planning", "SKILL.md"], content: planning })
+export const REASONING_EFFORTS = Object.freeze([
+  "none",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+]);
+
+export const DEFAULT_AGENT_REASONING = Object.freeze({
+  terra: "high",
+  luna: "xhigh",
+  sol: "medium"
 });
 
-export const MANAGED_FILE_NAMES = Object.freeze(["terra", "luna", "sol", "skill", "planning"]);
 export const AGENT_NAMES = Object.freeze(["terra", "luna", "sol"]);
 
-export const LEGACY_TEMPLATES = Object.freeze({
-  terra: Object.freeze([]),
-  luna: Object.freeze([legacyLunaV12]),
-  sol: Object.freeze([legacySolWorkspaceWrite, legacySolReadOnly]),
-  skill: Object.freeze([legacySkillWorkspaceWrite, legacySkillReadOnly]),
-  planning: Object.freeze([])
-});
+const AGENT_BASE_TEMPLATES = Object.freeze({ terra, luna, sol });
+
+function withReasoning(content, reasoning) {
+  const pattern = /^model_reasoning_effort = "[^"]+"$/m;
+  if (!pattern.test(content)) throw new Error("agent template is missing model_reasoning_effort");
+  return content.replace(pattern, `model_reasoning_effort = "${reasoning}"`);
+}
+
+export const TEMPLATES = {
+  terra: { relative: Object.freeze(["agents", "terra.toml"]), content: terra },
+  luna: { relative: Object.freeze(["agents", "luna.toml"]), content: luna },
+  sol: { relative: Object.freeze(["agents", "sol.toml"]), content: sol },
+  skill: { relative: Object.freeze(["model-router", "SKILL.md"]), content: skill },
+  planning: { relative: Object.freeze(["implementation-planning", "SKILL.md"]), content: planning }
+};
+
+export const MANAGED_FILE_NAMES = Object.freeze(["terra", "luna", "sol", "skill", "planning"]);
 
-export const AGENT_EXPECTATIONS = Object.freeze({
-  terra: Object.freeze({
+export const LEGACY_TEMPLATES = {
+  terra: [],
+  luna: [legacyLunaV12, withReasoning(luna, "max")],
+  sol: [legacySolWorkspaceWrite, legacySolReadOnly],
+  skill: [legacySkillWorkspaceWrite, legacySkillReadOnly],
+  planning: []
+};
+
+export const AGENT_EXPECTATIONS = {
+  terra: {
     name: "terra",
     model: "gpt-5.6-terra",
     model_reasoning_effort: "high",
     sandbox_mode: "read-only"
-  }),
-  luna: Object.freeze({
+  },
+  luna: {
     name: "luna",
     model: "gpt-5.6-luna",
-    model_reasoning_effort: "max",
+    model_reasoning_effort: "xhigh",
     sandbox_mode: "workspace-write"
-  }),
-  sol: Object.freeze({
+  },
+  sol: {
     name: "sol",
     model: "gpt-5.6-sol",
     model_reasoning_effort: "medium",
     sandbox_mode: "read-only"
-  })
-});
+  }
+};
+
+export function configureAgentReasoning(overrides = {}, migrateFrom = {}) {
+  const selected = { ...DEFAULT_AGENT_REASONING, ...overrides };
+  for (const [name, reasoning] of Object.entries(selected)) {
+    if (!AGENT_NAMES.includes(name)) throw new Error(`unknown agent: ${name}`);
+    if (!REASONING_EFFORTS.includes(reasoning)) {
+      throw new Error(`unsupported reasoning effort for ${name}: ${reasoning}`);
+    }
+  }
+
+  for (const name of AGENT_NAMES) {
+    const previous = migrateFrom[name];
+    if (typeof previous === "string" && !LEGACY_TEMPLATES[name].includes(previous)) {
+      LEGACY_TEMPLATES[name].push(previous);
+    }
+    TEMPLATES[name].content = withReasoning(AGENT_BASE_TEMPLATES[name], selected[name]);
+    AGENT_EXPECTATIONS[name].model_reasoning_effort = selected[name];
+  }
+  return Object.freeze({ ...selected });
+}
+
+configureAgentReasoning();
 
 export const SKILL_EXPECTATIONS = Object.freeze({
   skill: Object.freeze({

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "codex-model-router",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Safely install adaptive free-mode Codex routing for Terra, Luna, and Sol.",
   "type": "module",
   "bin": {
     "codex-model-router": "./bin/codex-model-router.js"
   },
   "scripts": {
-    "check": "node --check bin/codex-model-router.js && node --check lib/manifest.js && node --check lib/router.js && node --check lib/router-core.js && node --check lib/toml.js && node --check scripts/release-metadata.js && node --check scripts/verify-published.js",
+    "check": "node --check bin/codex-model-router.js && node --check lib/agent-reasoning-cli.js && node --check lib/manifest.js && node --check lib/router.js && node --check lib/router-core.js && node --check lib/toml.js && node --check scripts/release-metadata.js && node --check scripts/verify-published.js",
     "test": "node --test",
     "test:package": "node scripts/package-smoke.js"
   },