oc-agent-router 0.1.0 → 0.1.2

package/README.md

@@ -33,11 +33,27 @@ 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.jsonc`, which loads the built plugin directly from `./dist/index.js`. Before starting OpenCode from this directory, update its `models` and `fallbackModel` to model IDs enabled in your OpenCode configuration.
+
+```sh
+npm run build
+TYPESAFE_API_KEY=... opencode
+```
+
+Ask OpenCode to delegate work with a `task` subagent. A new task will receive the model selected by Jev; resumed tasks are intentionally left unchanged. Restart OpenCode after changing the plugin source, build output, or `opencode.jsonc`.
+
+To exercise the fallback without calling Jev, omit `TYPESAFE_API_KEY`; new tasks will use `fallbackModel`.
+
+Routing diagnostics are appended as JSON lines to `oc-agent-router.log` in the project directory. The log records the request payload, response status and body, selected model, and failures, but never the API key.
+
 ## Options
 
 | Option | Default | Description |
 | --- | --- | --- |
 | `models` | Required | Non-empty allowed model list in `provider/model` form. |
+| `instructions` | Built-in routing guidance | Instructions sent to Jev to guide its model choice. |
 | `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. |
@@ -45,7 +61,7 @@ All configured models must already be available in OpenCode. Restart OpenCode af
 
 ## 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.
+The plugin creates hidden model-specific variants of each subagent, calls `POST https://api.typesafe.ai/v1/systemone` with a Choice question whose only choices are your allowed models, then routes each new task to the matching hidden variant. Each variant retains the original agent's public name, prompt, and permissions, so users continue to see names such as `general` and `explore` rather than an internal routing name.
 
 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.
 
@@ -75,4 +91,4 @@ For example, a task that asks `general` to implement a parser sends the followin
 }
 ```
 
-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.
+Every new task is eligible for routing, including configured and Markdown-defined subagents. Task resumes (`task_id`) retain their existing model.

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { Plugin } from '@opencode-ai/plugin';
 interface RouterOptions {
     /** Models eligible to receive subagent tasks, in OpenCode provider/model form. */
     models: string[];
+    /** 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. */
@@ -24,9 +26,10 @@ interface FetchResponse {
     json(): Promise<unknown>;
 }
 type Fetcher = (input: string, init: RequestInit) => Promise<FetchResponse>;
-declare function parseOptions(value: unknown): Required<RouterOptions>;
+type Logger = (event: string, data?: unknown) => void;
 declare function routedAgentName(agent: string, model: string): string;
-declare function selectModel(options: Required<RouterOptions>, args: TaskArgs, apiKey: string | undefined, fetcher?: Fetcher): Promise<string>;
+declare function parseOptions(value: unknown): Required<RouterOptions>;
+declare function selectModel(options: Required<RouterOptions>, args: TaskArgs, apiKey: string | undefined, fetcher?: Fetcher, log?: Logger): Promise<string>;
 
 declare const plugin: Plugin;
 

package/dist/index.js

@@ -1,4 +1,20 @@
+// src/index.ts
+import { appendFile } from "fs/promises";
+import { join } from "path";
+
 // src/router.ts
+function routedAgentName(agent, model) {
+  return `oc-agent-router-${encode(agent)}-${encode(model)}`;
+}
+function routedAgentConfig(name, agent, model) {
+  return {
+    ...agent,
+    name,
+    model,
+    mode: "subagent",
+    hidden: true
+  };
+}
 function parseOptions(value) {
   if (!isRecord(value) || !Array.isArray(value.models)) {
     throw new Error("oc-agent-router requires a non-empty models array");
@@ -11,65 +27,87 @@ function parseOptions(value) {
   if (!models.includes(fallbackModel)) throw new Error("oc-agent-router fallbackModel must appear in models");
   return {
     models,
+    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
   };
 }
-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;
+async function selectModel(options, args, apiKey, fetcher = fetch, log = () => {
+}) {
+  if (!apiKey) {
+    log("routing.skipped", { reason: "missing_api_key", fallbackModel: options.fallbackModel });
+    return options.fallbackModel;
+  }
   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.subagent_type === "string" ? args.subagent_type : ""
+      },
+      questions: {
+        model: {
+          type: "choice",
+          instructions: options.instructions,
+          criteria: Object.fromEntries(options.models.map((model2) => [model2, `Use the configured OpenCode model ${model2}.`]))
+        }
+      }
+    };
+    log("routing.request", body);
     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
     });
+    log("routing.response.status", { ok: response.ok, status: response.status });
+    const responseBody = await response.json();
+    log("routing.response.body", responseBody);
     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 {
+    const choice = isRecord(responseBody) && isRecord(responseBody.answers) && isRecord(responseBody.answers.model) ? responseBody.answers.model.choice : void 0;
+    const model = typeof choice === "string" && options.models.includes(choice) ? choice : options.fallbackModel;
+    log("routing.selected", { model });
+    return model;
+  } catch (error) {
+    log("routing.error", {
+      error: error instanceof Error ? { name: error.name, message: error.message } : String(error),
+      fallbackModel: options.fallbackModel
+    });
     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 encode(value) {
+  return Array.from(value, (character) => character.codePointAt(0).toString(36)).join("-");
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 
 // src/index.ts
-var plugin = async (_input, rawOptions) => {
+var plugin = async (input, rawOptions) => {
   const options = parseOptions(rawOptions);
+  const logFile = join(input.directory, "oc-agent-router.log");
+  const log = (event, data) => {
+    const entry = JSON.stringify({ timestamp: (/* @__PURE__ */ new Date()).toISOString(), event, data });
+    void appendFile(logFile, `${entry}
+`).catch((error) => {
+      console.error("[oc-agent-router] failed to write log file", error);
+    });
+  };
   const routeableAgents = /* @__PURE__ */ new Set();
+  const routedAgents = /* @__PURE__ */ new Map();
+  log("plugin.initialized", { logFile });
   return {
     async config(config) {
       config.agent ??= {};
@@ -79,28 +117,71 @@ var plugin = async (_input, rawOptions) => {
         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"
+            (entry) => Boolean(entry[1]) && !entry[0].startsWith("oc-agent-router-") && entry[0] !== "build" && entry[0] !== "plan" && entry[1]?.mode !== "primary" && entry[1]?.disable !== true
           )
         )
       };
       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);
+          routedAgents.set(routeName, name);
           if (agents[routeName]) continue;
-          agents[routeName] = { ...agent, model, mode: "subagent", hidden: true };
+          agents[routeName] = routedAgentConfig(name, agent, model);
         }
       }
     },
-    "tool.execute.before": async (input, output) => {
-      if (input.tool !== "task") return;
+    "tool.execute.before": async (input2, output) => {
+      if (input2.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);
+      if (args.subagent_type.startsWith("oc-agent-router-") || !routeableAgents.has(args.subagent_type)) return;
+      const model = await selectModel(options, args, process.env[options.apiKeyEnv], fetch, log);
+      const requestedAgent = args.subagent_type;
+      const routedAgent = routedAgentName(requestedAgent, model);
+      args.subagent_type = routedAgent;
+      log("routing.applied", { requestedAgent, routedAgent, model });
+    },
+    event: async ({ event }) => {
+      if (event.type !== "message.part.updated") return;
+      const part = event.properties.part;
+      if (part.type !== "tool" || part.tool !== "task") return;
+      if (part.state.status !== "completed" && part.state.status !== "error") return;
+      const routedAgent = part.state.input.subagent_type;
+      if (typeof routedAgent !== "string") return;
+      const requestedAgent = routedAgents.get(routedAgent);
+      if (!requestedAgent) return;
+      const client = input.client._client;
+      if (!client) {
+        log("routing.display_restore_failed", { reason: "missing_internal_client", requestedAgent, routedAgent });
+        return;
+      }
+      const restoredPart = {
+        ...part,
+        state: {
+          ...part.state,
+          input: { ...part.state.input, subagent_type: requestedAgent }
+        }
+      };
+      try {
+        const result = await client.patch({
+          url: "/session/{sessionID}/message/{messageID}/part/{partID}",
+          path: { sessionID: part.sessionID, messageID: part.messageID, partID: part.id },
+          body: restoredPart,
+          headers: { "Content-Type": "application/json" }
+        });
+        if (result.error) {
+          log("routing.display_restore_failed", { error: result.error, requestedAgent, routedAgent });
+          return;
+        }
+        log("routing.display_restored", { requestedAgent, routedAgent });
+      } catch (error) {
+        log("routing.display_restore_failed", {
+          error: error instanceof Error ? { name: error.name, message: error.message } : String(error),
+          requestedAgent,
+          routedAgent
+        });
+      }
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-agent-router",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Route OpenCode subagent tasks to configured models with Jev.",
   "type": "module",
   "license": "MIT",