armin-opencode 0.1.2 → 0.1.4

package/README.md

@@ -8,6 +8,9 @@ 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
+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

package/bin/armin.js

@@ -94,6 +94,44 @@ function buildFromSource() {
   return true;
 }
 
+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;
+
+  const readline = require("readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  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() {
   const plugin = path.join(PKG_ROOT, "plugins", "armin.ts");
   if (!fs.existsSync(plugin)) throw new Error(`plugin not found at ${plugin}`);
@@ -115,10 +153,29 @@ function registerPlugin() {
     }
   }
   const entry = "file://" + plugin;
+  let changed = false;
   const plugins = Array.isArray(data.plugin) ? data.plugin : [];
   if (!plugins.includes(entry)) {
     plugins.push(entry);
     data.plugin = plugins;
+    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));
   }
@@ -144,7 +201,31 @@ async function install() {
       }
     }
   }
+  await askForExtractionSetup();
   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 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) 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:
@@ -152,7 +233,12 @@ Enable ARMIN per environment:
     export ARMIN_ENABLED=1
 
 Optional:
-    ARMIN_EXTRACTION_MODE=jev      TypeSafe System One extraction
+    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.2",
+  "version": "0.1.4",
   "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

@@ -16,6 +16,13 @@
  *       "enabled": true,
  *       "provider": "anthropic",          // anthropic | openai (default: infer from keys)
  *       "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
@@ -490,6 +497,16 @@ const ArminPlugin: Plugin = async (ctx) => {
   if (provider === "anthropic" || provider === "openai") {
     spawnEnv.LLM_PROVIDER = provider
   }
+  // Typesafe key (jev is the default extraction mode): config value is
+  // 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) {
@@ -519,6 +536,35 @@ const ArminPlugin: Plugin = async (ctx) => {
   if (sidecar.port) {
     log(`reasoning-state UI: http://127.0.0.1:${sidecar.port}/ui`)
   }
+  // Surface the effective extraction mode once — this is the difference
+  // between "memory works" and a silent deterministic downgrade.
+  void (async () => {
+    try {
+      const health = await api.get<{ extraction: string; jev_provider?: string }>("/health")
+      const mode = health?.extraction ?? "unknown"
+      if (mode === "jev") {
+        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 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 OPENROUTER_API_KEY (or ANTHROPIC/OPENAI_API_KEY) ` +
+            `to enable it.`,
+        )
+      }
+    } catch {
+      // best-effort status only
+    }
+  })()
 
   // ── Cold start: import AGENTS.md / CLAUDE.md into an empty graph ──────
   // Deterministic parse on the engine side (content-hash IDs, idempotent).