@ast-ai-model-router/cli 1.0.0 → 2.0.0

package/README.md

@@ -69,6 +69,18 @@ Launch Claude Code with the selected alias:
 ast-ai-model-router run claude --task "plan a cross-module database migration" -- --permission-mode plan
 ```
 
+Route each prompt through a gateway session:
+
+```bash
+ast-ai-model-router gateway codex -- --sandbox workspace-write
+```
+
+Preview one gateway turn without launching an agent:
+
+```bash
+ast-ai-model-router gateway claude --once --task "write docs for this repo" --dry-run -- --permission-mode plan
+```
+
 ## CI And Team Policy
 
 Fail if a task would exceed the allowed tier:
@@ -97,6 +109,30 @@ ast-ai-model-router analyze --agent codex --task "write tests" --json
 
 The JSON includes `selectedModel`, `tier`, `confidence`, `signals`, `rationale`, `warnings`, `costEstimate`, `policy`, and `commandPreview`.
 
+## Per-Turn Gateway
+
+`run` chooses one model before launching a Claude Code or Codex session. `gateway` is different: it keeps a small router prompt open, scores every message you type, then invokes the selected agent model for that turn.
+
+```bash
+ast-ai-model-router gateway claude -- --permission-mode plan
+ast-ai-model-router gateway codex -- --sandbox workspace-write
+```
+
+Inside the gateway, type a prompt and press Enter. Use `/exit` or `/quit` to stop.
+
+For single-turn automation or CI smoke tests:
+
+```bash
+ast-ai-model-router gateway codex --once --task "add regression tests for parser errors" --dry-run
+```
+
+The gateway uses non-interactive agent execution:
+
+- Claude Code: `claude --print --model <selected-model> ... <prompt>`
+- Codex: `codex exec --model <selected-model> ... <prompt>`
+
+This is not an invisible hook inside an already-running Claude Code or Codex TUI. To route every turn, enter prompts through `ast-ai-model-router gateway ...`.
+
 ## How Routing Works
 
 The router scores four groups of signals:

package/bin/ast-ai-model-router.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { CONFIG_TEMPLATE, loadConfig, validateTier } from "../lib/config.js";
 import { createDecision, maybeLogDecision } from "../lib/decision.js";
+import { runGateway } from "../lib/gateway.js";
 import { formatUsd } from "../lib/policy.js";
 
 const HELP = `ast-ai-model-router
@@ -15,6 +16,7 @@ Usage:
   ast-ai-model-router ci --agent claude|codex --task "deploy change" [--max-tier complex]
   ast-ai-model-router run claude --task "refactor parser" -- [extra claude args]
   ast-ai-model-router run codex --task "write tests" -- [extra codex args]
+  ast-ai-model-router gateway claude|codex [--once --task "write docs"] -- [extra agent args]
   ast-ai-model-router init [--cwd <path>] [--force]
 
 Options:
@@ -26,6 +28,7 @@ Options:
   --max-cost-usd <n>   Policy ceiling when cost estimate is available
   --log                Append a local JSONL decision record
   --dry-run            For run: print the command instead of launching
+  --once               For gateway: route one --task prompt and exit
   --refresh-models     Refresh Codex model catalog cache
 `;
 
@@ -137,6 +140,39 @@ async function main() {
     return;
   }
 
+  if (command === "gateway" || command === "intercept") {
+    const agent = assertAgent(maybeAgent);
+    const split = rest.indexOf("--");
+    const optionArgs = split === -1 ? rest : rest.slice(0, split);
+    const passthrough = split === -1 ? [] : rest.slice(split + 1);
+    const { values } = parseArgs({
+      args: optionArgs,
+      options: {
+        task: { type: "string" },
+        cwd: { type: "string" },
+        log: { type: "boolean" },
+        once: { type: "boolean" },
+        "max-tier": { type: "string" },
+        "max-cost-usd": { type: "string" },
+        "dry-run": { type: "boolean" },
+        "refresh-models": { type: "boolean" }
+      }
+    });
+    if (values.once && !values.task) throw new Error("--task is required with --once.");
+    const exitCode = await runGateway({
+      agent,
+      cwd: values.cwd ?? process.cwd(),
+      log: Boolean(values.log),
+      dryRun: Boolean(values["dry-run"]),
+      refreshModels: Boolean(values["refresh-models"]),
+      maxTier: values["max-tier"] ? validateTier(values["max-tier"], "--max-tier") : undefined,
+      maxCostUsd: parseOptionalNumber(values["max-cost-usd"], "--max-cost-usd"),
+      passthrough,
+      onceTask: values.once ? values.task : undefined
+    });
+    process.exit(exitCode);
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }
 

package/lib/adapters.js

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+
+export function buildAgentCommand({ agent, model, prompt, passthrough = [] }) {
+  if (agent === "claude") {
+    return {
+      command: "claude",
+      args: ["--print", "--model", model, ...passthrough, prompt]
+    };
+  }
+  if (agent === "codex") {
+    return {
+      command: "codex",
+      args: ["exec", "--model", model, ...passthrough, prompt]
+    };
+  }
+  throw new Error("Expected agent to be 'claude' or 'codex'.");
+}
+
+export function formatAgentCommand(request) {
+  const { command, args } = buildAgentCommand(request);
+  return `${command} ${args.map(shellQuote).join(" ")}`;
+}
+
+export async function executeAgent({ agent, model, prompt, cwd, passthrough = [] }) {
+  const { command, args } = buildAgentCommand({ agent, model, prompt, passthrough });
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      resolve({ exitCode: 1, stdout, stderr, error });
+    });
+    child.on("exit", (code, signal) => {
+      resolve({ exitCode: code ?? 1, signal, stdout, stderr });
+    });
+  });
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:=@-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/lib/gateway.js

@@ -0,0 +1,143 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { loadConfig } from "./config.js";
+import { createDecision, maybeLogDecision } from "./decision.js";
+import { executeAgent as defaultExecuteAgent, formatAgentCommand } from "./adapters.js";
+
+export async function runGatewayTurn({
+  agent,
+  prompt,
+  cwd,
+  config,
+  refreshModels = false,
+  maxTier,
+  maxCostUsd,
+  log = false,
+  dryRun = false,
+  passthrough = [],
+  executeAgent = defaultExecuteAgent
+}) {
+  const decision = await createDecision({
+    agent,
+    task: prompt,
+    cwd,
+    config,
+    refreshModels,
+    maxTier,
+    maxCostUsd
+  });
+  await maybeLogDecision(decision, config, log);
+  if (!decision.policy.passed) {
+    return {
+      decision,
+      output: "",
+      exitCode: 3,
+      error: new Error(`Policy failed: ${decision.policy.failures.join("; ")}`)
+    };
+  }
+  if (dryRun) {
+    const commandPreview = formatAgentCommand({
+      agent,
+      model: decision.selectedModel,
+      prompt,
+      passthrough
+    });
+    return {
+      decision,
+      output: `${commandPreview}\n`,
+      exitCode: 0,
+      dryRun: true
+    };
+  }
+
+  const result = await executeAgent({
+    agent,
+    model: decision.selectedModel,
+    prompt,
+    cwd: decision.cwd,
+    passthrough
+  });
+  return {
+    decision,
+    output: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    exitCode: result.exitCode ?? 1,
+    signal: result.signal,
+    error: result.error
+  };
+}
+
+export async function runGateway({
+  agent,
+  cwd = process.cwd(),
+  log = false,
+  refreshModels = false,
+  maxTier,
+  maxCostUsd,
+  dryRun = false,
+  passthrough = [],
+  onceTask
+}) {
+  const config = await loadConfig(cwd);
+  if (onceTask !== undefined) {
+    const result = await runGatewayTurn({
+      agent,
+      prompt: onceTask,
+      cwd,
+      config,
+      log,
+      dryRun,
+      refreshModels,
+      maxTier,
+      maxCostUsd,
+      passthrough
+    });
+    printGatewayTurn(result);
+    return result.exitCode;
+  }
+
+  const rl = createInterface({ input, output });
+  process.stdout.write(`[model-router] gateway for ${agent}. Type /exit or /quit to stop.\n`);
+  try {
+    for (;;) {
+      const prompt = await rl.question("> ");
+      const trimmed = prompt.trim();
+      if (!trimmed) continue;
+      if (trimmed === "/exit" || trimmed === "/quit") return 0;
+      const result = await runGatewayTurn({
+        agent,
+        prompt,
+        cwd,
+        config,
+        log,
+        dryRun,
+        refreshModels,
+        maxTier,
+        maxCostUsd,
+        passthrough
+      });
+      printGatewayTurn(result);
+    }
+  } catch (error) {
+    if (error?.code === "ERR_USE_AFTER_CLOSE") return 0;
+    throw error;
+  } finally {
+    rl.close();
+  }
+}
+
+export function printGatewayTurn(result) {
+  const { decision } = result;
+  process.stderr.write(`[model-router] ${decision.agent}: ${decision.selectedModel} (${decision.tier}, confidence ${decision.confidence.toFixed(2)})\n`);
+  if (!decision.policy.passed) {
+    process.stderr.write(`[model-router] policy failed: ${decision.policy.failures.join("; ")}\n`);
+    return;
+  }
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error) {
+    process.stderr.write(`[model-router] failed to launch ${decision.agent}: ${result.error.message}\n`);
+    return;
+  }
+  if (result.output) process.stdout.write(result.output);
+  if (result.exitCode !== 0) process.stderr.write(`[model-router] ${decision.agent} exited with code ${result.exitCode}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ast-ai-model-router/cli",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "AST-based Claude Code and Codex model router with token-cost estimates, CI policy checks, and explainable AI coding-agent model selection.",
   "type": "module",
   "bin": {
@@ -66,6 +66,6 @@
     "@changesets/cli": "^2.31.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=26"
   }
 }

package/skills/model-router/SKILL.md

@@ -43,7 +43,23 @@ ast-ai-model-router run codex --task "<task>" -- <codex args>
 ast-ai-model-router run claude --task "<task>" -- <claude args>
 ```
 
-5. Explain the selected model in token-economics terms: simple tasks should use faster/cheaper models; complex migrations, security-sensitive work, and architecture planning should use stronger models.
+5. If the user wants every new prompt routed independently, use the gateway:
+
+```bash
+ast-ai-model-router gateway codex -- <codex args>
+```
+
+```bash
+ast-ai-model-router gateway claude -- <claude args>
+```
+
+For a single routed turn:
+
+```bash
+ast-ai-model-router gateway codex --once --task "<task>" -- <codex args>
+```
+
+6. Explain the selected model in token-economics terms: simple tasks should use faster/cheaper models; complex migrations, security-sensitive work, and architecture planning should use stronger models.
 
 ## Notes
 
@@ -51,3 +67,4 @@ ast-ai-model-router run claude --task "<task>" -- <claude args>
 - Claude model names use aliases: `haiku`, `sonnet`, `opus`, and `opusplan`.
 - Token-cost estimates use Tokenometer when a selected model maps cleanly to a known provider model.
 - The router analyzes JavaScript/TypeScript with Babel ASTs and Python with stdlib `ast`.
+- Gateway mode routes prompts entered through `ast-ai-model-router gateway`; it does not invisibly intercept an already-running Claude Code or Codex TUI.