opencode-adaptive-routing 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# Architecture
+
+## Phase 0 Decision
+
+The MVP is a command/custom-tool recommendation package with a thin adapter
+boundary. It does not mutate an OpenCode request. The user receives a
+recommendation and copyable model-variant settings, then chooses what to do in
+their normal OpenCode flow.
+
+## Compatibility Findings
+
+- OpenCode plugins can register custom tools through `@opencode-ai/plugin`.
+- The documented plugin hooks include `chat.message`, `chat.params`,
+  `command.execute.before`, and `permission.ask`.
+- OpenCode configuration supports named model variants with options such as
+  `reasoningEffort`.
+- The documented APIs do not define a safe, user-confirmed mutation of the
+  next request's model and variant from a custom command or tool.
+- `chat.params` is a request-parameter hook, not an approved next-request
+  selection mechanism. This project will not use it for routing.
+
+## Compatibility Range
+
+The package targets OpenCode plugin APIs available from `@opencode-ai/plugin`
+1.18.25 or newer. Runtime mutation remains disabled unless a future documented
+API is explicitly reviewed and approved.
+
+## Boundaries
+
+`policy.ts`, `recommendation.ts`, and `metrics.ts` are pure or filesystem-only
+TypeScript. `command.ts` adapts task input and user decisions to the pure core.
+`plugin.ts` is the thin documented OpenCode custom-tool bridge and exports the
+default plugin entry point used by npm installation.
+
+## Safety Invariants
+
+- No task text leaves the local process.
+- No model or effort setting is changed automatically.
+- `max`, Sol, and all classifier-generated recommendations require explicit
+  confirmation.
+- Metrics are disabled unless the caller opts in.
+- Unsupported runtime application returns manual instructions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files, to deal in the Software
+without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# OpenCode Adaptive Routing
+
+An opt-in, local, recommendation-only extension for choosing a GPT-5.6 model
+variant and reasoning effort before a task starts.
+
+The MVP never silently changes settings, sends task content to a service, or
+collects telemetry. It prints manual selection instructions when runtime
+mutation is unavailable.
+
+## Status
+
+The package is ready to publish and install as an OpenCode server plugin. It is
+not published or installed into an active OpenCode profile by this repository.
+
+## OpenCode Installation
+
+After publication, add the npm package to your OpenCode configuration, usually
+`.opencode/opencode.jsonc` or `opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-adaptive-routing"],
+}
+```
+
+Restart OpenCode. The plugin registers a custom tool named `route_task`. Ask
+OpenCode to use `route_task` for a task, or invoke the tool from a workflow
+that supplies these arguments:
+
+```json
+{
+  "task": "Debug a database connection issue.",
+  "action": "recommend"
+}
+```
+
+The tool returns a model, effort, confidence, rationale, tradeoffs, risk, and
+confirmation requirement. To act on the result, make a second explicit call:
+
+```json
+{
+  "task": "Debug a database connection issue.",
+  "action": "accept"
+}
+```
+
+For an edited selection, use `action: "edit"` with `model` (`Luna`, `Terra`,
+or `Sol`) and `effort` (`none`, `low`, `medium`, `high`, `xhigh`, or `max`).
+Use `action: "cancel"` to make no change. The plugin only returns manual
+selection instructions; it never changes OpenCode's native model or effort.
+
+## Optional `/route` Command
+
+OpenCode slash commands are configured separately from plugins. Copy the
+`command.route` entry from `opencode.example.jsonc` into the same configuration
+file as the plugin:
+
+```jsonc
+{
+  "command": {
+    "route": {
+      "description": "Recommend a model and reasoning effort for a task",
+      "template": "Use the route_task tool with task `$ARGUMENTS` and action `recommend`. Do not perform the task. Show the recommendation and wait for confirmation.",
+    },
+  },
+}
+```
+
+Restart OpenCode, then use:
+
+```text
+/route Debug a database connection issue.
+```
+
+The command asks the plugin's `route_task` tool for a recommendation without
+starting the task. `/route` is not created by the npm plugin automatically;
+the command configuration is required.
+
+Pin a release for reproducible installation:
+
+```jsonc
+{
+  "plugin": ["opencode-adaptive-routing@0.1.0"],
+}
+```
+
+## Development
+
+```text
+npm install
+npm run check
+npm run lint
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## Privacy and Consent
+
+Task classification is deterministic and local. Metrics are off by default and
+must be explicitly enabled by the caller. Metrics contain only sanitized
+outcome metadata, never prompts, responses, paths, identifiers, credentials,
+or tool arguments.
+
+The user can accept, edit, or cancel every recommendation. Cancellation has no
+side effects. Automatic routing is intentionally out of scope.
+
+## Rollback
+
+Remove the command/tool registration from the OpenCode profile. Because this
+package does not mutate native request settings, ordinary OpenCode model and
+effort selection remains available at all times.
+
+## Publishing
+
+Publication is intentionally manual and requires npm authentication:
+
+```text
+npm publish --access public
+```
+
+Do not run this command unless publication has been explicitly approved.

package/dist/index.js

@@ -0,0 +1,308 @@
+// src/types.ts
+var MODELS = ["Luna", "Terra", "Sol"];
+var EFFORTS = [
+  "none",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+];
+
+// src/policy.ts
+var rules = [
+  {
+    name: "long-task",
+    pattern: /\b.{240,}\b/s,
+    score: 2,
+    reason: "The task contains substantial context."
+  },
+  {
+    name: "multi-step",
+    pattern: /\b(first|then|next|finally|step\s+\d|and then)\b/gi,
+    score: 2,
+    reason: "The task contains multiple ordered steps."
+  },
+  {
+    name: "external-tools",
+    pattern: /\b(api|browser|deploy|database|terminal|shell|tool|github|railway)\b/gi,
+    score: 2,
+    reason: "The task likely requires external tools or integrations."
+  },
+  {
+    name: "security",
+    pattern: /\b(security|credential|secret|auth|vulnerability|threat|permission|exploit)\b/gi,
+    score: 4,
+    reason: "The task includes security-sensitive language."
+  },
+  {
+    name: "research",
+    pattern: /\b(research|compare|evaluate|sources|literature|investigate)\b/gi,
+    score: 3,
+    reason: "The task requires research or evidence gathering."
+  },
+  {
+    name: "long-horizon",
+    pattern: /\b(roadmap|migration|refactor|large-scale|end-to-end|long-running|implement.*all)\b/gi,
+    score: 4,
+    reason: "The task suggests long-horizon or broad work."
+  },
+  {
+    name: "imperative",
+    pattern: /\b(build|create|implement|fix|debug|design|review|write|add|remove|update)\b/gi,
+    score: 1,
+    reason: "The task contains an actionable request."
+  },
+  {
+    name: "simple",
+    pattern: /\b(hello|format|extract|summarize|classify|quick|simple|latency)\b/gi,
+    score: -2,
+    reason: "The task includes a simple or latency-sensitive signal."
+  }
+];
+function matches(pattern, task) {
+  pattern.lastIndex = 0;
+  return pattern.test(task);
+}
+function riskFor(score) {
+  if (score >= 8) return "critical";
+  if (score >= 5) return "high";
+  if (score >= 2) return "medium";
+  return "low";
+}
+function classifyTask(task) {
+  const normalized = task.trim();
+  const signals = rules.filter((rule) => matches(rule.pattern, normalized)).map(({ name, score: score2, reason }) => ({ name, score: score2, reason }));
+  const score = signals.reduce((total, signal) => total + signal.score, 0);
+  const hasConflictingSignals = signals.some((signal) => signal.name === "simple") && score >= 5;
+  const unknown = normalized.length === 0 || signals.length === 0;
+  if (unknown || hasConflictingSignals) {
+    return {
+      model: "Terra",
+      effort: "medium",
+      confidence: 0.35,
+      risk: "medium",
+      signals,
+      requiresConfirmation: true
+    };
+  }
+  let model = "Luna";
+  let effort = "low";
+  if (score >= 2) {
+    model = "Terra";
+    effort = "medium";
+  }
+  if (score >= 5) {
+    model = signals.some(
+      (signal) => signal.name === "security" || signal.name === "research"
+    ) ? "Sol" : "Terra";
+    effort = "high";
+  }
+  if (score >= 8 && signals.some(
+    (signal) => signal.name === "research" || signal.name === "long-horizon"
+  )) {
+    model = "Sol";
+    effort = "xhigh";
+  }
+  return {
+    model,
+    effort,
+    confidence: Math.min(0.95, 0.55 + Math.min(5, Math.abs(score)) * 0.07),
+    risk: riskFor(score),
+    signals,
+    requiresConfirmation: true
+  };
+}
+
+// src/recommendation.ts
+function recommend(task) {
+  const result = classifyTask(task);
+  const rationale = result.signals.length > 0 ? result.signals.map((signal) => signal.reason).join(" ") : "No reliable task signals were found, so the conservative baseline was selected.";
+  const tradeoffs = result.model === "Sol" ? "Higher quality and reasoning depth, with higher latency and cost." : result.model === "Terra" ? "Balanced quality, latency, and cost for general work." : "Lowest latency and cost; use only when the task is straightforward.";
+  return {
+    ...result,
+    rationale,
+    tradeoffs,
+    manualSettings: `Select model ${result.model} and reasoning effort ${result.effort} for the next task.`
+  };
+}
+
+// src/command.ts
+function isModel(value) {
+  return typeof value === "string" && MODELS.includes(value);
+}
+function isEffort(value) {
+  return typeof value === "string" && EFFORTS.includes(value);
+}
+function routeTask(task, decision) {
+  const recommendation = recommend(task);
+  if (!decision)
+    return {
+      status: "recommendation",
+      recommendation,
+      message: formatRecommendation(recommendation)
+    };
+  if (decision.type === "cancel")
+    return {
+      status: "cancelled",
+      recommendation,
+      message: "Routing cancelled. No model or effort setting was changed."
+    };
+  const model = decision.type === "edit" && decision.model !== void 0 ? decision.model : recommendation.model;
+  const effort = decision.type === "edit" && decision.effort !== void 0 ? decision.effort : recommendation.effort;
+  if (!isModel(model) || !isEffort(effort))
+    throw new Error("Invalid model or effort selection.");
+  const selected = { model, effort };
+  const status = decision.type === "edit" ? "edited" : "accepted";
+  return {
+    status,
+    recommendation,
+    selected,
+    message: `Confirmed ${model} with ${effort} effort. ${manualSettings(model, effort)}`
+  };
+}
+function formatRecommendation(recommendation) {
+  return [
+    `Recommendation: ${recommendation.model} / ${recommendation.effort}`,
+    `Confidence: ${Math.round(recommendation.confidence * 100)}% | Risk: ${recommendation.risk}`,
+    `Why: ${recommendation.rationale}`,
+    `Tradeoffs: ${recommendation.tradeoffs}`,
+    `Confirmation required: ${recommendation.requiresConfirmation ? "yes" : "no"}`,
+    "Choose accept, edit model, edit effort, or cancel."
+  ].join("\n");
+}
+function manualSettings(model, effort) {
+  return `Open your normal model selector and choose model ${model} with reasoning effort ${effort}; this adapter does not change native settings.`;
+}
+
+// src/tui.ts
+function renderRecommendation(recommendation) {
+  return formatRecommendation(recommendation);
+}
+function confirmRoute(task, decision) {
+  return routeTask(task, decision);
+}
+
+// src/metrics.ts
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+var MAX_METRICS = 1e3;
+var models = /* @__PURE__ */ new Set(["Luna", "Terra", "Sol"]);
+var efforts = /* @__PURE__ */ new Set([
+  "none",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+]);
+function optionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function sanitizeMetric(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("Metric must be an object.");
+  const input = value;
+  if (typeof input.timestamp !== "string" || !models.has(input.model) || !efforts.has(input.effort)) {
+    throw new Error("Metric has invalid required fields.");
+  }
+  const metric = {
+    timestamp: input.timestamp,
+    model: input.model,
+    effort: input.effort,
+    confidence: optionalNumber(input.confidence) ?? 0,
+    overridden: input.overridden === true
+  };
+  for (const key of [
+    "latencyMs",
+    "inputTokens",
+    "outputTokens",
+    "reasoningTokens",
+    "cost"
+  ]) {
+    const number = optionalNumber(input[key]);
+    if (number !== void 0) metric[key] = number;
+  }
+  if (typeof input.success === "boolean") metric.success = input.success;
+  if (typeof input.reworked === "boolean") metric.reworked = input.reworked;
+  return metric;
+}
+async function recordMetric(config, metric) {
+  if (!config.enabled) return false;
+  const clean = sanitizeMetric(metric);
+  let entries = [];
+  try {
+    const parsed = JSON.parse(await readFile(config.filePath, "utf8"));
+    if (Array.isArray(parsed))
+      entries = parsed.flatMap((entry) => {
+        try {
+          return [sanitizeMetric(entry)];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+  }
+  entries.push(clean);
+  entries = entries.slice(-MAX_METRICS);
+  await mkdir(dirname(config.filePath), { recursive: true });
+  const temporary = `${config.filePath}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(entries)}
+`, { mode: 384 });
+  await rename(temporary, config.filePath);
+  return true;
+}
+
+// src/plugin.ts
+import { tool } from "@opencode-ai/plugin";
+function decisionFor(action, model, effort) {
+  if (action === "recommend") return void 0;
+  if (action === "accept") return { type: "accept" };
+  if (action === "cancel") return { type: "cancel" };
+  if (action === "edit") {
+    const decision = { type: "edit" };
+    if (model !== void 0) decision.model = model;
+    if (effort !== void 0) decision.effort = effort;
+    return decision;
+  }
+  throw new Error("action must be recommend, accept, edit, or cancel");
+}
+var AdaptiveRoutingPlugin = async () => ({
+  tool: {
+    route_task: tool({
+      description: "Recommend a local OpenCode model and reasoning effort. This tool never changes native settings.",
+      args: {
+        task: tool.schema.string().describe("The task to classify locally."),
+        action: tool.schema.string().describe("One of: recommend, accept, edit, cancel."),
+        model: tool.schema.string().optional().describe("Edited model: Luna, Terra, or Sol."),
+        effort: tool.schema.string().optional().describe("Edited effort: none, low, medium, high, xhigh, or max.")
+      },
+      async execute(args) {
+        return routeTask(
+          args.task,
+          decisionFor(args.action, args.model, args.effort)
+        ).message;
+      }
+    })
+  }
+});
+var plugin = {
+  id: "adaptive-routing",
+  server: AdaptiveRoutingPlugin
+};
+var plugin_default = plugin;
+export {
+  plugin_default as AdaptiveRoutingPlugin,
+  EFFORTS,
+  MAX_METRICS,
+  MODELS,
+  classifyTask,
+  confirmRoute,
+  plugin_default as default,
+  formatRecommendation,
+  recommend,
+  recordMetric,
+  renderRecommendation,
+  routeTask,
+  sanitizeMetric
+};

package/opencode.example.jsonc

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-adaptive-routing"],
+  "command": {
+    "route": {
+      "description": "Recommend a model and reasoning effort for a task",
+      "template": "Use the route_task tool with task `$ARGUMENTS` and action `recommend`. Do not perform the task. Show the recommendation and wait for confirmation.",
+    },
+  },
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "opencode-adaptive-routing",
+  "version": "0.1.0",
+  "description": "Opt-in, local, recommendation-only model routing for OpenCode",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "ARCHITECTURE.md",
+    "opencode.example.jsonc"
+  ],
+  "engines": {
+    "node": ">=20",
+    "opencode": ">=1.18.25 <2"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.25 <2"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --format=esm --platform=node --packages=external --outfile=dist/index.js",
+    "check": "prettier --check src tests scripts fixtures package.json tsconfig.json README.md ARCHITECTURE.md EVALUATION.md opencode.example.jsonc",
+    "format": "prettier --write src tests scripts fixtures package.json tsconfig.json README.md ARCHITECTURE.md EVALUATION.md opencode.example.jsonc",
+    "lint": "tsc --noEmit",
+    "evaluate": "tsx scripts/evaluate.ts",
+    "test": "tsx --test tests/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@opencode-ai/plugin": "^1.18.25",
+    "esbuild": "^0.25.9",
+    "prettier": "^3.6.2",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.2"
+  }
+}