armin-opencode 0.1.3 → 0.1.5

package/README.md

@@ -5,7 +5,6 @@ for AI coding agents — packaged for [opencode](https://opencode.ai).
 
 ```bash
 npx armin-opencode install      # or: npm i -g armin-opencode && armin install
-export ARMIN_ENABLED=1
 ```
 
 Prefer a global install over one-off `npx` runs: the plugin registration
@@ -13,8 +12,9 @@ points at the package's install location, and `npx` caches are evicted.
 
 `armin install` downloads the `armin-engine` sidecar binary for your platform
 from the [GitHub releases](https://github.com/bastian-seifert/armin/releases)
-and registers the plugin in your global opencode config. Enable it per
-environment with `ARMIN_ENABLED=1`.
+and registers + enables the plugin in your global opencode config
+(`"armin": { "enabled": true }`). `ARMIN_ENABLED=1` remains as a
+per-environment escape hatch.
 
 See the [main repo](https://github.com/bastian-seifert/armin) for what the
 agent gets (durable decisions/rules/open items, scoped reasoning-state brief,

package/bin/armin.js

@@ -95,25 +95,41 @@ function buildFromSource() {
 }
 
 let pendingTypesafeKey = null;
+let pendingOpenrouterKey = null;
+let pendingJevProvider = null; // "openrouter" | "skip" | null (typesafe needs no config entry)
+
+/** Ask which relay serves Jev and for the matching key (TTY only; values
+ * go into the opencode config — the plugin passes them to the sidecar).
+ * A provider detected from the environment skips the prompt entirely. */
+async function askForExtractionSetup() {
+  if (!process.stdin.isTTY) return;
+  let provider;
+  if (process.env.ARMIN_JEV_PROVIDER) provider = process.env.ARMIN_JEV_PROVIDER;
+  else if (process.env.TYPESAFE_AI_API_KEY) provider = "typesafe";
+  else if (process.env.OPENROUTER_API_KEY) provider = "openrouter";
+  if (provider) return;
 
-/** Ask for the Typesafe key when nothing is configured (TTY only; the key
- * goes into the opencode config — the plugin passes it to the sidecar). */
-function askForTypesafeKey() {
-  if (process.env.TYPESAFE_AI_API_KEY) return Promise.resolve();
-  if (!process.stdin.isTTY) return Promise.resolve();
   const readline = require("readline");
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(
-      "TypeSafe System One API key (jev extraction is the default) — paste, or Enter to skip: ",
-      (answer) => {
-        rl.close();
-        const key = (answer || "").trim();
-        if (key) pendingTypesafeKey = key;
-        resolve();
-      },
-    );
-  });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  try {
+    console.log("\nExtraction backend (jev is the default — verbatim nodes, no generative LLM):");
+    console.log("  1) TypeSafe System One (typesafe.ai)  [default]");
+    console.log("  2) Jev via OpenRouter (openrouter.ai — same API, OpenRouter billing)");
+    console.log("  3) skip (LLM fallback / deterministic-only)");
+    const choice = ((await ask("Choose [1/2/3, Enter=1]: ")) || "1").trim();
+    if (choice === "3") { pendingJevProvider = "skip"; return; }
+    if (choice === "2") {
+      pendingJevProvider = "openrouter";
+      const key = ((await ask("OpenRouter API key (openrouter.ai/settings/keys) — paste, or Enter to skip: ")) || "").trim();
+      if (key) pendingOpenrouterKey = key;
+    } else {
+      const key = ((await ask("TypeSafe System One API key — paste, or Enter to skip: ")) || "").trim();
+      if (key) pendingTypesafeKey = key;
+    }
+  } finally {
+    rl.close();
+  }
 }
 
 function registerPlugin() {
@@ -132,8 +148,8 @@ function registerPlugin() {
     try {
       data = JSON.parse(text.replace(/^\s*\/\/.*$/gm, ""));
     } catch {
-      console.log(`\nCould not parse ${cfgPath} — register the plugin manually:\n  add "plugin": ["file://${plugin}"] to your opencode config\n`);
-      return;
+      console.log(`\nCould not parse ${cfgPath} — set up manually:\n  add "plugin": ["file://${plugin}"] and "armin": { "enabled": true } to your opencode config\n`);
+      return false;
     }
   }
   const entry = "file://" + plugin;
@@ -144,15 +160,33 @@ function registerPlugin() {
     data.plugin = plugins;
     changed = true;
   }
+  // `armin install` is an explicit opt-in — enable in config so no
+  // per-shell env var is needed (ARMIN_ENABLED stays as escape hatch).
+  if (data.armin?.enabled !== true) {
+    data.armin = { ...(data.armin || {}), enabled: true };
+    changed = true;
+  }
   if (pendingTypesafeKey && !process.env.TYPESAFE_AI_API_KEY) {
     data.armin = { ...(data.armin || {}), typesafeKey: pendingTypesafeKey };
     changed = true;
   }
+  if (pendingOpenrouterKey && !process.env.OPENROUTER_API_KEY) {
+    data.armin = { ...(data.armin || {}), openrouterKey: pendingOpenrouterKey };
+    changed = true;
+  }
+  // Persist the relay choice only when the user explicitly picked
+  // OpenRouter in the prompt (env-detected providers drive the sidecar
+  // via their env vars; writing nothing avoids overriding that later).
+  if (pendingJevProvider === "openrouter" && data.armin.jevProvider !== "openrouter") {
+    data.armin = { ...(data.armin || {}), jevProvider: "openrouter" };
+    changed = true;
+  }
   if (changed) {
     fs.mkdirSync(cfgDir, { recursive: true });
     fs.writeFileSync(cfgPath, JSON.stringify(data, null, 2));
   }
   console.log(`plugin registered in ${cfgPath}`);
+  return true;
 }
 
 async function install() {
@@ -174,34 +208,45 @@ async function install() {
       }
     }
   }
-  await askForTypesafeKey();
-  registerPlugin();
+  await askForExtractionSetup();
+  const registered = registerPlugin();
   const tsKey = process.env.TYPESAFE_AI_API_KEY || pendingTypesafeKey;
+  const orKey = process.env.OPENROUTER_API_KEY || pendingOpenrouterKey;
   const llmKey = process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
   if (tsKey) {
     console.log("extraction: jev (TypeSafe System One) — ready");
+  } else if (orKey) {
+    console.log("extraction: jev via OpenRouter — ready");
   } else if (llmKey) {
     console.log(
-      "extraction: LLM fallback — jev is the default but no Typesafe key is set.\n" +
-        "  Get a key at typesafe.ai and export TYPESAFE_AI_API_KEY (or put\n" +
-        '  "armin": { "typesafeKey": "..." } in your opencode config).',
+      "extraction: LLM fallback — jev is the default but no key for it is set.\n" +
+        "  Set TYPESAFE_AI_API_KEY (typesafe.ai) or OPENROUTER_API_KEY (openrouter.ai),\n" +
+        '  or put "armin": { "typesafeKey": "..." } / { "jevProvider": "openrouter",\n' +
+        '  "openrouterKey": "..." } in your opencode config.',
     );
   } else {
     console.log(
       "extraction: NONE (deterministic-only) — import, capture and unverified-edit\n" +
         "  warnings work; prose extraction does not.\n" +
-        "  Set TYPESAFE_AI_API_KEY (typesafe.ai) for jev extraction — the default —\n" +
-        "  or ANTHROPIC_API_KEY / OPENAI_API_KEY for LLM fallback.",
+        "  Set TYPESAFE_AI_API_KEY (typesafe.ai) or OPENROUTER_API_KEY (openrouter.ai)\n" +
+        "  for jev extraction — the default — or ANTHROPIC_API_KEY / OPENAI_API_KEY\n" +
+        "  for LLM fallback.",
     );
   }
   console.log(`
 ── done ────────────────────────────────────────────────────────
-Enable ARMIN per environment:
-
-    export ARMIN_ENABLED=1
+${registered
+    ? 'ARMIN is enabled in your opencode config ("armin": { "enabled": true }).\nRestart opencode to activate it; remove "enabled" to turn it off.'
+    : "ARMIN is not enabled yet — follow the manual setup steps above."}
 
-Optional:
-    ARMIN_EXTRACTION_MODE=jev      TypeSafe System One extraction
+Optional overrides (env wins over config):
+    ARMIN_ENABLED=1                force-enable without the config entry
+    ARMIN_EXTRACTION_MODE=jev      System One extraction (default; needs
+                                   TYPESAFE_AI_API_KEY or OPENROUTER_API_KEY)
+    ARMIN_JEV_PROVIDER=openrouter  route jev via OpenRouter (auto-detected
+                                   when only that key is set)
+    ARMIN_JEV_MODEL=<model>        jev model override (default jev-1.13.0,
+                                   or jev-latest via OpenRouter)
     ARMIN_MODEL=<model>            extraction model override
     ARMIN_DEBUG=1                  verbose logging + /ui URL
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "armin-opencode",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "ARMIN — queryable decision memory for AI coding agents. Installs the armin-engine sidecar and registers the opencode plugin.",
   "license": "Apache-2.0",
   "author": "Bastian Seifert",

package/plugins/armin.ts

@@ -18,6 +18,11 @@
  *       "apiKey": "sk-...",               // sent to the sidecar only; env key wins if both set
  *       "typesafeKey": "...",             // Typesafe System One key (jev is the
  *                                         // default extraction mode); env wins
+ *       "jevProvider": "typesafe",        // typesafe | openrouter — which relay serves
+ *                                         // the System One API (openrouter bills
+ *                                         // your OpenRouter account); env wins
+ *       "openrouterKey": "sk-or-...",     // OpenRouter key, used when jevProvider is
+ *                                         // "openrouter"; env wins
  *       "model": "session",               // "session" = follow the live session model
  *                                         // "small"  = reuse opencode's small_model setting
  *                                         // any string = fixed extraction model
@@ -496,6 +501,12 @@ const ArminPlugin: Plugin = async (ctx) => {
   // passed to the sidecar only; a key already in the environment wins.
   const typesafeKey = cfgStr("typesafeKey", "TYPESAFE_AI_API_KEY")
   if (typesafeKey) spawnEnv.TYPESAFE_AI_API_KEY = typesafeKey
+  // Jev relay: "typesafe" (api.typesafe.ai, default) or "openrouter"
+  // (openrouter.ai/api — same System One API, OpenRouter billing).
+  const jevProvider = cfgStr("jevProvider", "ARMIN_JEV_PROVIDER")
+  if (jevProvider) spawnEnv.ARMIN_JEV_PROVIDER = jevProvider
+  const openrouterKey = cfgStr("openrouterKey", "OPENROUTER_API_KEY")
+  if (openrouterKey) spawnEnv.OPENROUTER_API_KEY = openrouterKey
   // API key: config value is passed to the sidecar only; a key already in
   // the environment wins (no override).
   if (typeof armin.apiKey === "string" && armin.apiKey) {
@@ -529,21 +540,25 @@ const ArminPlugin: Plugin = async (ctx) => {
   // between "memory works" and a silent deterministic downgrade.
   void (async () => {
     try {
-      const health = await api.get<{ extraction: string }>("/health")
+      const health = await api.get<{ extraction: string; jev_provider?: string }>("/health")
       const mode = health?.extraction ?? "unknown"
       if (mode === "jev") {
-        log(`extraction: jev (TypeSafe System One) — ready`)
+        const via = health?.jev_provider ?? "typesafe"
+        log(`extraction: jev (System One via ${via}) — ready`)
       } else if (mode === "llm") {
         log(
-          `extraction: llm (fallback) — jev is the default but no Typesafe key is ` +
-            `configured. Set TYPESAFE_AI_API_KEY in your environment or ` +
-            `"armin": { "typesafeKey": "..." } in your opencode config.`,
+          `extraction: llm (fallback) — jev is the default but no key is ` +
+            `configured. Set TYPESAFE_AI_API_KEY (typesafe.ai) or OPENROUTER_API_KEY ` +
+            `(openrouter.ai) in your environment, or \`"armin": { "typesafeKey": "..." }\`` +
+            ` / \`{ "jevProvider": "openrouter", "openrouterKey": "..." }\` in your ` +
+            `opencode config.`,
         )
       } else {
         log(
           `extraction: deterministic-only — no API keys found. Import and ` +
             `unverified-edit warnings work; prose extraction does not. Set ` +
-            `TYPESAFE_AI_API_KEY (or ANTHROPIC/OPENAI_API_KEY) to enable it.`,
+            `TYPESAFE_AI_API_KEY or OPENROUTER_API_KEY (or ANTHROPIC/OPENAI_API_KEY) ` +
+            `to enable it.`,
         )
       }
     } catch {