oc-agent-router 0.1.0

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 (the "Software"), 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,78 @@
+# oc-agent-router
+
+An OpenCode plugin that routes each new `task` subagent to one of your configured models. It asks [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) for a structured choice immediately before OpenCode creates the child session.
+
+## Install
+
+```sh
+opencode plugin add oc-agent-router
+```
+
+Set `TYPESAFE_API_KEY` in the environment that starts OpenCode, then configure the plugin in `~/.config/opencode/opencode.json` or your project `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "oc-agent-router",
+      {
+        "models": [
+          "openai/gpt-5.4",
+          "anthropic/claude-sonnet-4-6",
+          "google/gemini-3-pro"
+        ],
+        "fallbackModel": "anthropic/claude-sonnet-4-6"
+      }
+    ]
+  ]
+}
+```
+
+All configured models must already be available in OpenCode. Restart OpenCode after installing or changing its configuration.
+
+`TYPESAFE_API_KEY` is read only from the environment of the OpenCode process. Do not put it in `opencode.json`.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `models` | Required | Non-empty allowed model list in `provider/model` form. |
+| `fallbackModel` | First model | Used when the API key is missing, Jev errors, times out, or returns an invalid choice. Must be in `models`. |
+| `jevModel` | `jev-latest` | TypeSafe model ID. Pin a version if routing behavior must be stable. |
+| `apiKeyEnv` | `TYPESAFE_API_KEY` | Environment variable containing the TypeSafe API key. |
+| `timeoutMs` | `5000` | Jev request deadline, from 100 to 30,000 ms. |
+
+## How It Works
+
+OpenCode's `task` tool does not accept a per-call model override. The plugin uses the documented `tool.execute.before` hook, calls `POST https://api.typesafe.ai/v1/systemone` with a Choice question whose only choices are your allowed models, then rewrites `subagent_type` to a hidden, model-bound copy of the requested subagent.
+
+Task resumes (`task_id`) are deliberately not rerouted, so a resumed session keeps its original model. API failures never expand the configured model allowlist and use `fallbackModel` instead.
+
+The routing request sends only the subagent type, short task description, and task prompt. It does not send session history, tool outputs, or API credentials.
+
+For example, a task that asks `general` to implement a parser sends the following payload. Its `Authorization` header is `Bearer $TYPESAFE_API_KEY`, which comes from the process environment rather than any config file.
+
+```json
+{
+  "model": "jev-latest",
+  "state": {
+    "task": "Implement the parser for the new configuration format.",
+    "description": "Implement parser",
+    "requested_agent": "general"
+  },
+  "questions": {
+    "model": {
+      "type": "choice",
+      "instructions": "Choose the configured model most suitable for completing this OpenCode subagent task. Prefer a capable model for implementation, debugging, and complex reasoning; prefer an efficient model for focused exploration or simple tasks.",
+      "criteria": {
+        "openai/gpt-5.4": "Use the configured OpenCode model openai/gpt-5.4.",
+        "anthropic/claude-sonnet-4-6": "Use the configured OpenCode model anthropic/claude-sonnet-4-6.",
+        "google/gemini-3-pro": "Use the configured OpenCode model google/gemini-3-pro."
+      }
+    }
+  }
+}
+```
+
+The plugin routes the built-in `general` and `explore` agents plus subagents declared in `opencode.json` under `agent`. Markdown-only subagents are left unchanged because OpenCode's plugin hook does not expose their resolved definitions for safe cloning.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { Plugin } from '@opencode-ai/plugin';
+
+interface RouterOptions {
+    /** Models eligible to receive subagent tasks, in OpenCode provider/model form. */
+    models: string[];
+    /** TypeSafe model ID used for routing. Defaults to jev-latest. */
+    jevModel?: string;
+    /** Environment variable containing the TypeSafe API key. Defaults to TYPESAFE_API_KEY. */
+    apiKeyEnv?: string;
+    /** Maximum time to wait for a route decision. Defaults to 5000. */
+    timeoutMs?: number;
+    /** Model to use when Jev is unavailable or returns an invalid answer. Defaults to the first model. */
+    fallbackModel?: string;
+}
+interface TaskArgs {
+    description?: unknown;
+    prompt?: unknown;
+    subagent_type?: unknown;
+    task_id?: unknown;
+}
+interface FetchResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+type Fetcher = (input: string, init: RequestInit) => Promise<FetchResponse>;
+declare function parseOptions(value: unknown): Required<RouterOptions>;
+declare function routedAgentName(agent: string, model: string): string;
+declare function selectModel(options: Required<RouterOptions>, args: TaskArgs, apiKey: string | undefined, fetcher?: Fetcher): Promise<string>;
+
+declare const plugin: Plugin;
+
+export { type RouterOptions, plugin as default, parseOptions, routedAgentName, selectModel };

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/router.ts
+function parseOptions(value) {
+  if (!isRecord(value) || !Array.isArray(value.models)) {
+    throw new Error("oc-agent-router requires a non-empty models array");
+  }
+  const models = value.models.filter((model) => typeof model === "string" && isModel(model));
+  if (models.length !== value.models.length || models.length === 0) {
+    throw new Error("oc-agent-router models must be provider/model strings");
+  }
+  const fallbackModel = typeof value.fallbackModel === "string" ? value.fallbackModel : models[0];
+  if (!models.includes(fallbackModel)) throw new Error("oc-agent-router fallbackModel must appear in models");
+  return {
+    models,
+    jevModel: typeof value.jevModel === "string" ? value.jevModel : "jev-latest",
+    apiKeyEnv: typeof value.apiKeyEnv === "string" ? value.apiKeyEnv : "TYPESAFE_API_KEY",
+    timeoutMs: typeof value.timeoutMs === "number" && value.timeoutMs >= 100 && value.timeoutMs <= 3e4 ? value.timeoutMs : 5e3,
+    fallbackModel
+  };
+}
+function routedAgentName(agent, model) {
+  return `oc-agent-router-${encode(agent)}-${encode(model)}`;
+}
+async function selectModel(options, args, apiKey, fetcher = fetch) {
+  if (!apiKey) return options.fallbackModel;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const response = await fetcher("https://api.typesafe.ai/v1/systemone", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: options.jevModel,
+        state: {
+          task: typeof args.prompt === "string" ? args.prompt : "",
+          description: typeof args.description === "string" ? args.description : "",
+          requested_agent: typeof args.subagent_type === "string" ? args.subagent_type : ""
+        },
+        questions: {
+          model: {
+            type: "choice",
+            instructions: "Choose the configured model most suitable for completing this OpenCode subagent task. Prefer a capable model for implementation, debugging, and complex reasoning; prefer an efficient model for focused exploration or simple tasks.",
+            criteria: Object.fromEntries(options.models.map((model) => [model, `Use the configured OpenCode model ${model}.`]))
+          }
+        }
+      }),
+      signal: controller.signal
+    });
+    if (!response.ok) return options.fallbackModel;
+    const body = await response.json();
+    const choice = isRecord(body) && isRecord(body.answers) && isRecord(body.answers.model) ? body.answers.model.choice : void 0;
+    return typeof choice === "string" && options.models.includes(choice) ? choice : options.fallbackModel;
+  } catch {
+    return options.fallbackModel;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function encode(value) {
+  return Array.from(value, (character) => character.codePointAt(0).toString(36)).join("-");
+}
+function isModel(value) {
+  const separator = value.indexOf("/");
+  return separator > 0 && separator < value.length - 1;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/index.ts
+var plugin = async (_input, rawOptions) => {
+  const options = parseOptions(rawOptions);
+  const routeableAgents = /* @__PURE__ */ new Set();
+  return {
+    async config(config) {
+      config.agent ??= {};
+      const agents = config.agent;
+      const sourceAgents = {
+        general: agents.general ?? { mode: "subagent" },
+        explore: agents.explore ?? { mode: "subagent" },
+        ...Object.fromEntries(
+          Object.entries(agents).filter(
+            (entry) => Boolean(entry[1]) && entry[0] !== "build" && entry[0] !== "plan" && entry[1]?.mode !== "primary"
+          )
+        )
+      };
+      for (const [name, agent] of Object.entries(sourceAgents)) {
+        if (name.startsWith("oc-agent-router-")) continue;
+        routeableAgents.add(name);
+        for (const model of options.models) {
+          const routeName = routedAgentName(name, model);
+          if (agents[routeName]) continue;
+          agents[routeName] = { ...agent, model, mode: "subagent", hidden: true };
+        }
+      }
+    },
+    "tool.execute.before": async (input, output) => {
+      if (input.tool !== "task") return;
+      const args = output.args;
+      if (typeof args.subagent_type !== "string" || typeof args.prompt !== "string" || args.task_id) return;
+      if (args.subagent_type.startsWith("oc-agent-router-")) return;
+      if (!routeableAgents.has(args.subagent_type)) return;
+      const model = await selectModel(options, args, process.env[options.apiKeyEnv]);
+      args.subagent_type = routedAgentName(args.subagent_type, model);
+    }
+  };
+};
+var index_default = plugin;
+export {
+  index_default as default,
+  parseOptions,
+  routedAgentName,
+  selectModel
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "oc-agent-router",
+  "version": "0.1.0",
+  "description": "Route OpenCode subagent tasks to configured models with Jev.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maharshi365/oc-agent-router.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/**/*.test.ts",
+    "verify": "npm run check && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.31",
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "subagent",
+    "model-routing",
+    "jev"
+  ]
+}