oc-agent-router 0.1.1 → 0.2.0

package/README.md

@@ -22,7 +22,8 @@ Set `TYPESAFE_API_KEY` in the environment that starts OpenCode, then configure t
           "anthropic/claude-sonnet-4-6",
           "google/gemini-3-pro"
         ],
-        "fallbackModel": "anthropic/claude-sonnet-4-6"
+        "agents": ["general", "explore"],
+        "confidenceThreshold": 0.8
       }
     ]
   ]
@@ -33,23 +34,38 @@ All configured models must already be available in OpenCode. Restart OpenCode af
 
 `TYPESAFE_API_KEY` is read only from the environment of the OpenCode process. Do not put it in `opencode.json`.
 
+## Local Testing
+
+This repository includes `.opencode/opencode.json`, which loads the built `dist/` plugin directory. Before starting OpenCode from this directory, build the plugin and update its `models` to model IDs enabled in your OpenCode configuration.
+
+```sh
+npm run build
+TYPESAFE_API_KEY=... opencode
+```
+
+Ask OpenCode to delegate work with a `subagent`. A new child session will receive the model selected by Jev; resumed child sessions and calls with an explicit model are intentionally left unchanged. Restart OpenCode after changing the plugin source, build output, or `.opencode/opencode.json`.
+
+To leave child sessions on their configured or inherited model, omit `TYPESAFE_API_KEY` or set a threshold higher than Jev's returned confidence.
+
 ## 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`. |
+| `agents` | All subagents | Optional list of subagent IDs this plugin may route. An explicit empty list routes none. |
+| `confidenceThreshold` | `0.8` | Minimum Jev choice confidence from 0 to 1 required to override the child model. |
+| `instructions` | Built-in routing guidance | Instructions sent to Jev to guide its model choice. |
 | `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
 
-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 sets the task's `model` field. It leaves the task's original `subagent_type` and description unchanged.
+The plugin calls `POST https://api.typesafe.ai/v1/systemone` with a Choice question whose only choices are your allowed models, then supplies the selected model to OpenCode's native `subagent` tool immediately before it creates the child session. The original agent ID, system prompt, permissions, task, and display name remain unchanged.
 
-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.
+Child-session resumes (`sessionID`) are deliberately not rerouted, so a resumed session keeps its original model. Calls that explicitly select a model are also left unchanged. If Jev is unavailable, returns an invalid choice, or is below `confidenceThreshold`, the plugin leaves the model unset so OpenCode uses the configured agent model or parent session model.
 
-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.
+The routing request sends only the subagent ID, 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.
 
@@ -75,4 +91,4 @@ For example, a task that asks `general` to implement a parser sends the followin
 }
 ```
 
-Every new task is eligible for routing, including configured and Markdown-defined subagents. Task resumes (`task_id`) retain their existing model.
+Every new child session is eligible for routing, including configured and Markdown-defined subagents. Resumes (`sessionID`) retain their existing model.

package/dist/index.d.ts

@@ -1,22 +1,32 @@
-import { Plugin } from '@opencode-ai/plugin';
+import { Plugin } from '@opencode/plugin';
 
 interface RouterOptions {
     /** Models eligible to receive subagent tasks, in OpenCode provider/model form. */
     models: string[];
+    /** Subagent IDs eligible for routing. When omitted, all subagents are eligible. */
+    agents?: string[];
+    /** Minimum Jev choice confidence required to override the child model. Defaults to 0.8. */
+    confidenceThreshold?: number;
+    /** Routing guidance sent to Jev. */
+    instructions?: 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 {
+interface ParsedRouterOptions extends Omit<Required<RouterOptions>, "agents"> {
+    agents?: string[];
+}
+interface SubagentArgs {
     description?: unknown;
     prompt?: unknown;
-    subagent_type?: unknown;
-    task_id?: unknown;
+    agent?: unknown;
+    /** An explicit model is not overridden by the router. */
+    model?: unknown;
+    /** Resumed child sessions keep their existing model. */
+    sessionID?: unknown;
 }
 interface FetchResponse {
     ok: boolean;
@@ -24,9 +34,9 @@ interface FetchResponse {
     json(): Promise<unknown>;
 }
 type Fetcher = (input: string, init: RequestInit) => Promise<FetchResponse>;
-declare function parseOptions(value: unknown): Required<RouterOptions>;
-declare function selectModel(options: Required<RouterOptions>, args: TaskArgs, apiKey: string | undefined, fetcher?: Fetcher): Promise<string>;
+declare function parseOptions(value: unknown): ParsedRouterOptions;
+declare function selectModel(options: ParsedRouterOptions, args: SubagentArgs, apiKey: string | undefined, fetcher?: Fetcher): Promise<string | undefined>;
 
-declare const plugin: Plugin;
+declare const plugin: Plugin.Plugin;
 
 export { type RouterOptions, plugin as default, parseOptions, selectModel };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/index.ts
+import { Plugin } from "@opencode/plugin";
+
 // src/router.ts
 function parseOptions(value) {
   if (!isRecord(value) || !Array.isArray(value.models)) {
@@ -7,47 +10,62 @@ function parseOptions(value) {
   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");
+  const agents = value.agents === void 0 ? void 0 : Array.isArray(value.agents) && value.agents.every((agent) => typeof agent === "string" && agent.trim()) ? value.agents : void 0;
+  if (value.agents !== void 0 && agents === void 0) {
+    throw new Error("oc-agent-router agents must be an array of non-empty agent IDs");
+  }
+  const confidenceThreshold = value.confidenceThreshold === void 0 ? 0.8 : typeof value.confidenceThreshold === "number" && Number.isFinite(value.confidenceThreshold) ? value.confidenceThreshold : void 0;
+  if (confidenceThreshold === void 0 || confidenceThreshold < 0 || confidenceThreshold > 1) {
+    throw new Error("oc-agent-router confidenceThreshold must be a number from 0 to 1");
+  }
   return {
     models,
+    agents,
+    confidenceThreshold,
+    instructions: typeof value.instructions === "string" && value.instructions.trim() ? value.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.",
     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
+    timeoutMs: typeof value.timeoutMs === "number" && value.timeoutMs >= 100 && value.timeoutMs <= 3e4 ? value.timeoutMs : 5e3
   };
 }
 async function selectModel(options, args, apiKey, fetcher = fetch) {
-  if (!apiKey) return options.fallbackModel;
+  if (!apiKey) {
+    return void 0;
+  }
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
   try {
+    const body = {
+      model: options.jevModel,
+      state: {
+        task: typeof args.prompt === "string" ? args.prompt : "",
+        description: typeof args.description === "string" ? args.description : "",
+        requested_agent: typeof args.agent === "string" ? args.agent : ""
+      },
+      questions: {
+        model: {
+          type: "choice",
+          instructions: options.instructions,
+          criteria: Object.fromEntries(options.models.map((model) => [model, `Use the configured OpenCode model ${model}.`]))
+        }
+      }
+    };
     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}.`]))
-          }
-        }
-      }),
+      body: JSON.stringify(body),
       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;
+    const responseBody = await response.json();
+    if (!response.ok) return void 0;
+    const answer = isRecord(responseBody) && isRecord(responseBody.answers) && isRecord(responseBody.answers.model) ? responseBody.answers.model : void 0;
+    const choice = isRecord(answer) ? answer.choice : void 0;
+    const confidence = isRecord(answer) ? answer.confidence : void 0;
+    if (typeof choice !== "string" || !options.models.includes(choice) || typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < options.confidenceThreshold)
+      return void 0;
+    return choice;
   } catch {
-    return options.fallbackModel;
+    return void 0;
   } finally {
     clearTimeout(timeout);
   }
@@ -61,18 +79,20 @@ function isRecord(value) {
 }
 
 // src/index.ts
-var plugin = async (_input, rawOptions) => {
-  const options = parseOptions(rawOptions);
-  return {
-    "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;
-      const model = await selectModel(options, args, process.env[options.apiKeyEnv]);
-      args.model = model;
-    }
-  };
-};
+var plugin = Plugin.define({
+  id: "oc-agent-router",
+  async setup(ctx) {
+    const options = parseOptions(ctx.options);
+    await ctx.tool.hook("execute.before", async (event) => {
+      if (event.tool !== "subagent") return;
+      const input = event.input;
+      if (typeof input.agent !== "string" || typeof input.prompt !== "string" || input.model !== void 0 || input.sessionID !== void 0 || options.agents !== void 0 && !options.agents.includes(input.agent))
+        return;
+      const model = await selectModel(options, input, process.env[options.apiKeyEnv], fetch);
+      if (model !== void 0) input.model = model;
+    });
+  }
+});
 var index_default = plugin;
 export {
   index_default as default,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-agent-router",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Route OpenCode subagent tasks to configured models with Jev.",
   "type": "module",
   "license": "MIT",
@@ -28,10 +28,10 @@
     "verify": "npm run check && npm test && npm run build"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": ">=1.18.0"
+    "@opencode/plugin": "^2.0.0"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.18.31",
+    "@opencode/plugin": "^2.0.15",
     "@types/node": "^24.0.0",
     "tsup": "^8.5.0",
     "tsx": "^4.20.0",