armin-opencode 0.1.4 → 0.1.6

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

@@ -97,6 +97,7 @@ function buildFromSource() {
 let pendingTypesafeKey = null;
 let pendingOpenrouterKey = null;
 let pendingJevProvider = null; // "openrouter" | "skip" | null (typesafe needs no config entry)
+let pendingPort = null; // fixed engine port, or null for OS auto-assign
 
 /** 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).
@@ -132,6 +133,30 @@ async function askForExtractionSetup() {
   }
 }
 
+/** Ask for an optional fixed engine port (TTY only; ARMIN_PORT in the
+ * environment is the runtime escape hatch and skips the prompt). A pinned
+ * port is written to the opencode config; the sidecar auto-falls back to a
+ * free port when it is busy. */
+async function askForPort() {
+  if (!process.stdin.isTTY) return;
+  if (process.env.ARMIN_PORT) 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 {
+    const answer = ((await ask("\nFixed engine port (Enter = auto-assign per session): ")) || "").trim();
+    if (!answer) return;
+    const port = Number(answer);
+    if (Number.isInteger(port) && port >= 1024 && port <= 65535) {
+      pendingPort = port;
+    } else {
+      console.log(`invalid port "${answer}" (need 1024-65535) — engine port: auto-assign`);
+    }
+  } 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}`);
@@ -148,8 +173,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;
@@ -160,6 +185,12 @@ 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;
@@ -175,11 +206,16 @@ function registerPlugin() {
     data.armin = { ...(data.armin || {}), jevProvider: "openrouter" };
     changed = true;
   }
+  if (pendingPort && data.armin.port !== pendingPort) {
+    data.armin = { ...(data.armin || {}), port: pendingPort };
+    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() {
@@ -202,7 +238,8 @@ async function install() {
     }
   }
   await askForExtractionSetup();
-  registerPlugin();
+  await askForPort();
+  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;
@@ -228,11 +265,14 @@ async function install() {
   }
   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:
+Optional overrides (env wins over config):
+    ARMIN_ENABLED=1                force-enable without the config entry
+    ARMIN_PORT=<port>              fixed engine port (default: OS auto-assign;
+                                   a busy pinned port auto-falls back)
     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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "armin-opencode",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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

@@ -31,12 +31,15 @@
  *       "dbDir": "~/.opencode/armin"      // per-project graph databases
  *                                         // (keyed by git origin remote; path
  *                                         // fallback for non-git dirs)
+ *       "port": 4545,                     // optional fixed engine port (default:
+ *                                         // OS auto-assign; auto-falls back when
+ *                                         // the port is busy); env wins
  *     }
  *   }
  *
  * Precedence: engine defaults < config files (global < project) < env vars
  * (ARMIN_MODEL, ARMIN_BATCH_MS, ARMIN_BATCH_EVENTS, ARMIN_DB_DIR,
- * ARMIN_ENGINE_BIN, ARMIN_DEBUG) — env is the escape hatch.
+ * ARMIN_PORT, ARMIN_ENGINE_BIN, ARMIN_DEBUG) — env is the escape hatch.
  *
  * Note: opencode's auth store (OAuth logins) is not exposed to plugins, so
  * extraction uses `apiKey`/environment API keys; the session *model* can
@@ -207,6 +210,8 @@ class Sidecar {
   private readonly _token = crypto.randomUUID().replace(/-/g, "")
   private starts = 0
   private disposed = false
+  /** Set after a pinned port failed to start; later starts auto-assign. */
+  private pinnedPortFailed = false
   port: number | null = null
 
   get token(): string {
@@ -217,6 +222,7 @@ class Sidecar {
     private engineBin: string,
     private dbFile: string,
     private spawnEnv: Record<string, string> = {},
+    private pinnedPort?: number,
   ) {}
 
   /** Start the engine and wait for the port handshake + health check. */
@@ -229,9 +235,12 @@ class Sidecar {
     }
     this.starts++
 
+    // With a pinned port (armin.port / ARMIN_PORT) the engine binds that
+    // exact port; once it has failed once, later starts auto-assign again.
+    const usePinned = this.pinnedPort !== undefined && !this.pinnedPortFailed
     const args = [
       this.engineBin,
-      "--port", "0",
+      "--port", usePinned ? String(this.pinnedPort) : "0",
       "--db-path", this.dbFile,
       "--auth-token", this.token,
     ]
@@ -263,15 +272,22 @@ class Sidecar {
 
     const port = await this.readPort(proc, 5_000)
     if (!port) {
-      log("sidecar did not report ARMIN_PORT in time")
       proc.kill()
+      if (usePinned) {
+        // The engine exited without a handshake — the pinned port is
+        // almost certainly busy. Fall back to OS auto-assign and retry.
+        log(`sidecar could not bind pinned port ${this.pinnedPort}; falling back to auto-assign`)
+        this.pinnedPortFailed = true
+        return this.start()
+      }
+      log("sidecar did not report ARMIN_PORT in time")
       return false
     }
     this.port = port
 
     for (let i = 0; i < 50; i++) {
       if (await this.healthy()) {
-        log(`sidecar ready on 127.0.0.1:${port}`)
+        log(`sidecar ready on 127.0.0.1:${port}${usePinned ? " (pinned)" : ""}`)
         return true
       }
       if (this.disposed) return false
@@ -321,6 +337,7 @@ class Sidecar {
         break
       }
       if (!chunk) break
+      if (chunk.done) break // engine exited (e.g. bind failure) — stop waiting
       buf += new TextDecoder().decode(chunk.value ?? new Uint8Array())
       const m = buf.match(/ARMIN_PORT=(\d+)/)
       if (m) {
@@ -523,7 +540,20 @@ const ArminPlugin: Plugin = async (ctx) => {
     (typeof armin.batchEvents === "number" ? String(armin.batchEvents) : undefined)
   if (batchEvents) spawnEnv.ARMIN_BATCH_EVENTS = batchEvents
 
-  const sidecar = new Sidecar(engineBin, dbFile, spawnEnv)
+  // Optional fixed engine port: ARMIN_PORT env > armin.port config. Invalid
+  // values (non-integer, 0, out of range) are ignored → OS auto-assign; a
+  // busy pinned port falls back to auto-assign when the sidecar starts.
+  const portEnv = Number(process.env.ARMIN_PORT)
+  const portCfg = typeof armin.port === "number" ? armin.port : Number.NaN
+  const pinnedPort =
+    Number.isInteger(portEnv) && portEnv >= 1 && portEnv <= 65535
+      ? portEnv
+      : Number.isInteger(portCfg) && portCfg >= 1 && portCfg <= 65535
+        ? portCfg
+        : undefined
+  if (pinnedPort) log("fixed engine port:", pinnedPort)
+
+  const sidecar = new Sidecar(engineBin, dbFile, spawnEnv, pinnedPort)
   const started = await sidecar.start()
   if (!started) {
     log("sidecar unavailable — plugin inert")