@elliotsystems/eai 0.1.3 → 0.1.5

package/README.md

@@ -31,16 +31,11 @@ In precedence order (`lib/resolve.js`):
 | # | Source | Path |
 |---|---|---|
 | 1 | `ELLIOT_OPENCODE_BIN` | the binary itself |
-| 2 | **stock upstream runtime** | `opencode-ai/bin/opencode.exe`, resolved via `require.resolve` — **this is production** |
-| 3 | Elliot platform package | `@elliotsystems/eai-<os>-<arch>/bin/…` — fork builds, legacy, no longer a dependency |
-| 4 | bundled runtime | `vendor/opencode-<platform>-<arch>/bin/…` |
-| 5 | `ELLIOT_OPENCODE_HOME` | `<home>/packages/opencode/dist/…` or `<home>/opencode-<platform>-<arch>/…` |
-| 6 | in-repo fork checkout | `../opencode/…` — **development only** |
-| 7 | sibling fork checkout | `../../opencode/…` — **development only**, last resort |
-
-Stock sits ahead of the Elliot platform packages deliberately. Those are fork
-builds, and preferring them would quietly reintroduce the patched OpenCode this
-architecture exists to remove.
+| 2 | platform npm package | `@elliotsystems/eai-<platform>-<arch>/bin/opencode[.exe]`, via `require.resolve` -- **this is how an installed `eai` finds its runtime** |
+| 3 | bundled runtime | `vendor/opencode-<platform>-<arch>/bin/opencode[.exe]` |
+| 4 | `ELLIOT_OPENCODE_HOME` | `<home>/packages/opencode/dist/…` or `<home>/opencode-<platform>-<arch>/…` |
+| 5 | in-repo fork checkout | `../opencode/packages/opencode/dist/…` -- **development only** |
+| 6 | sibling fork checkout | `../../opencode/packages/opencode/dist/…` -- **development only**, last resort |
 
 Two deliberate rules:
 
@@ -57,16 +52,100 @@ runtime later is a file copy, not a translation.
 
 Set `ELLIOT_LAUNCHER_DEBUG=1` to print the resolved path to **stderr** (stdout
 stays clean for piping).
+## Slash commands
+
+`eai setup` writes these into `~/.config/opencode/opencode.json` under
+`command`, which is OpenCode's own config-driven command mechanism — the same
+one its built-in `/init` and `/review` use (`command/index.ts`). Nothing in the
+vendored runtime is patched to add them, and a user's own custom commands in
+that file are preserved.
+
+Each one is a prompt that calls an Elliot MCP tool. There is no second
+implementation behind any of them.
+
+| Command | What it does |
+|---|---|
+| `/usage` | Your own gateway spend and limits |
+| `/eai init` | Writes `EAI.md`, this project's context file |
+| `/eai-skills` | Writes `ESKILLS.md`, the project's skill catalogue index |
+| `/eais` | Lists the EAI agents |
+| `/eais <agent>` | Activates one, e.g. `/eais dev` |
+
+### `EAI.md` and `AGENTS.md`
+
+`EAI.md` is added to `instructions` in `opencode.json`, so OpenCode loads it as
+a system instruction. It does **not** replace `AGENTS.md`: OpenCode resolves
+`config.instructions` separately from its `AGENTS.md`/`CLAUDE.md`/`CONTEXT.md`
+lookup, so a project can have both and a team's existing `AGENTS.md` keeps
+working untouched. `eai setup` appends `EAI.md` only when it is absent, so
+re-running it never duplicates the entry.
+
+`/eai init` writes only between `<!-- EAI:GENERATED:START -->` and
+`<!-- EAI:GENERATED:END -->`. Anything you write outside those markers survives
+regeneration.
+
+### Agents
+
+An agent is a set of skill *disciplines*, not a stored list of skills. Its
+members are resolved by joining the catalogue at read time, so a skill added by
+the next sync belongs to its agent immediately and the two can never drift. The
+agent set is seeded by migration `086` and derived from the catalogue's own
+`discipline` values — a discipline with no agent is reported by `/eai-skills`
+rather than hidden.
+
+`/eais dev` does not start a second runtime or change your OpenCode
+configuration. It establishes the agent for the current session: the model is
+told which skills that agent can draw on, and fetches a skill's body with
+`skills_content` only when a task needs it.
+
+### Why `ESKILLS.md` is an index
+
+The catalogue holds every skill's full body. Writing them all into a file that
+OpenCode loads on every turn would spend the context window before any work
+started, so `ESKILLS.md` carries metadata only — name, key, discipline,
+description, version. Skill content is fetched one skill at a time, and that
+fetch is audited; a body pasted into a file is read with neither.
+
+### What `/eai-skills` does and does not do
+
+It synchronizes **this project's view**: it reads the authoritative catalogue,
+regenerates `ESKILLS.md`, and reports the upstream revision and sync time so a
+stale catalogue is visible rather than assumed fresh.
+
+It does **not** fetch from GitHub. That sync is tenant-wide and gated on an
+admin role, and an MCP principal carries no role — so triggering it from a CLI
+command would hand every user a privileged action the HTTP API refuses them.
+Fetching from GitHub stays where its authorization lives: the dashboard's sync
+button and the repository push webhook.
+
+### Scoping
+
+Agents resolve skills through the same authorization predicate as
+`skills_search` and `skills_content`. An agent cannot surface a skill its
+caller could not already read: only `ACTIVE`, MCP-visible skills resolve, and a
+project-scoped skill stays invisible without its project. Newly synced skills
+sit in `REVIEW` until they are governed through, so they are catalogued but not
+yet invocable — `/eais` will show an agent with a count of `0` rather than
+pretend it is empty.
+
+
 
 ## Command name
 
-`eai` is a new, unused command name. It deliberately does **not** collide with
-`elliot-ai`, which is the bin name of the shipped legacy CLI
-(`@elliotsystems/elliot-ai`, currently on PATH). Both can coexist, so the legacy
-CLI keeps working untouched and its retirement stays a separate, later decision.
+`eai` is the only command this project ships. It deliberately does **not** claim
+`elliot-ai`, the bin name of the retired `@elliotsystems/elliot-ai`: that package
+is no longer built or published, but it is still installed on machines that set
+it up before the migration, and taking over its command name would overwrite a
+working install rather than replace it on the user's terms. Everything it did now
+lives here — `setup`, `status`, `logout`, the TUI, and MCP over the backend's
+remote endpoint.
 
 Run it locally, without installing, with `node bin/eai`.
 
+> This section previously said the package was `private: true` and that publishing
+> was out of scope. It has been published as `@elliotsystems/eai` since 0.1.0; the
+> note was left behind and is corrected here.
+
 ## Install
 
 ```
@@ -105,43 +184,3 @@ To publish a new release to npm:
 ```
 npm test        # node --test, no dependencies
 ```
-
-## Architecture
-
-```
-stock upstream OpenCode  (opencode-ai, an npm dependency)
-          |
-   Elliot launcher  (this package)
-     |-- config/            OPENCODE_CONFIG_DIR: theme + plugin registration
-     |-- config/themes/     the Elliot palette
-     |-- plugin/            the bundled Elliot plugin (wordmark, chrome)
-     +-- bin/eai            OSC 0 terminal title
-          |
-        eai  ->  Elliot-branded TUI
-```
-
-**OpenCode core modifications: 0.** Elliot ships no compiled OpenCode. An
-upstream upgrade is a version bump of `opencode-ai` in `package.json`.
-
-Three mechanisms carry the branding, none of which touch OpenCode source:
-
-| Surface | Mechanism |
-|---|---|
-| Wordmark, palette, accent, chrome | the bundled plugin, via `home_logo` (`mode="replace"`) and theme discovery |
-| Theme selection + plugin registration | `OPENCODE_CONFIG_DIR` -> this package's `config/` |
-| Terminal title | `OPENCODE_DISABLE_TERMINAL_TITLE=1`, then the launcher writes OSC 0 |
-
-### Why the plugin is bundled rather than depended on
-
-`@elliotsystems/opencode-plugin` is not published to npm. A config that named it
-by package name would install cleanly and then render as plain OpenCode, which
-is the worst failure mode available -- it looks like it worked. `scripts/bundle.js`
-copies it in from `opencode-plugin/` (the single source of truth) and runs from
-`prepack`, so `npm pack` and `npm publish` cannot forget it.
-
-### Why the theme file is shipped as well
-
-The plugin can install the palette itself via `api.theme.install()`, but that
-WRITES into the config directory, and a global npm install directory is not
-reliably writable. Shipping `config/themes/elliot.json` means the theme resolves
-read-only.

package/bin/eai

@@ -26,6 +26,12 @@ const {
 } = require("../lib/resolve.js")
 const { injectToken } = require("../lib/token-env.js")
 const { stageOverlay } = require("../lib/stage.js")
+const { runSetup, parseArgs } = require("../lib/setup.js")
+const { runStatus } = require("../lib/status.js")
+const { runLogout } = require("../lib/logout.js")
+const { runConnect } = require("../lib/connect.js")
+const { runUpdate, maybeNotify } = require("../lib/update.js")
+const gdrive = require("../lib/gdrive.js")
 
 /**
  * Resolve symlinks before deriving the package root.
@@ -63,6 +69,128 @@ function fail(message) {
   process.exit(127) // conventional "command not found"
 }
 
+/**
+ * End an async command with an exit code, WITHOUT calling `process.exit`.
+ *
+ * Every command here that talks to the network used to end with
+ * `.then((code) => process.exit(code))`, and on Windows that crashes:
+ *
+ *   Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c
+ *
+ * `process.exit` tears the loop down while undici (global `fetch`) still has
+ * handles closing, libuv asserts, and the process dies with **127** — after the
+ * command has already printed its correct output and done its work. So `eai
+ * status` reports the truth and then looks like "command not found" to any
+ * script that checks `$?`. Reproduced on Node 24.19.0 / Windows with a
+ * one-liner: `fetch(url).then(() => process.exit(0))`.
+ *
+ * Setting `process.exitCode` lets the loop drain on its own and exits with the
+ * same code. It is not a Windows-only patch applied conditionally, because the
+ * conditional version is the one nobody tests on the other platform.
+ */
+function finishWith(promise, label) {
+  promise
+    .then((code) => {
+      process.exitCode = typeof code === "number" ? code : 0
+    })
+    .catch((error) => {
+      process.stderr.write(`eai ${label}: ${error.message}\n`)
+      process.exitCode = 1
+    })
+}
+
+// `eai setup` is handled here and never reaches the runtime.
+//
+// It is intercepted BEFORE the runtime is resolved, because setup is what a
+// machine runs when nothing is configured yet -- failing with "could not locate
+// the OpenCode runtime" would be a confusing way to refuse to configure it.
+// `setup` is not an OpenCode command, so nothing is shadowed.
+//
+// This exists so `eai` is the only CLI to install. Onboarding used to hand out
+// a second global package whose whole job was writing two config files, and a
+// user who ran only the first install got a CLI with no backend and no token.
+if (process.argv[2] === "setup") {
+  const options = parseArgs(process.argv.slice(3))
+  runSetup(options).catch((error) => {
+    process.stderr.write(`eai setup: ${error.message}
+`)
+    process.exit(1)
+  })
+  return
+}
+
+// `--version` answers for BOTH layers, because a bug report that says only
+// "1.18.30" names the runtime and not the product — and the two move
+// independently: one is this package, the other is its `opencode-ai`
+// dependency. Forwarded verbatim like every other flag, it reported upstream's
+// version alone and left the EAI version unknowable from a terminal.
+//
+// Both values are READ, never embedded. A literal here would be a second source
+// of truth that goes stale the first time either is bumped.
+if (process.argv[2] === "--version" || process.argv[2] === "-v") {
+  process.stdout.write(`EAI: ${PACKAGE_VERSION}\n`)
+  // Best-effort: an unresolvable dependency manifest is worth reporting as
+  // unknown, not worth failing the one command someone runs to find out what
+  // they have installed.
+  let runtime = "unknown"
+  try {
+    runtime = require("opencode-ai/package.json").version
+  } catch {
+    // Left as "unknown" rather than guessed.
+  }
+  process.stdout.write(`OpenCode: ${runtime}\n`)
+  return
+}
+
+// `eai update` is intercepted alongside setup/status/logout, and for the same
+// reason: it is about this machine's installation rather than a coding session,
+// and it has to work when the runtime cannot be located at all — a broken
+// install is exactly when someone reaches for it. `update` is not an OpenCode
+// command, so nothing is shadowed.
+if (process.argv[2] === "update") {
+  finishWith(
+    runUpdate({ packageRoot: PACKAGE_ROOT, version: PACKAGE_VERSION, argv: process.argv.slice(3) }),
+    "update",
+  )
+  return
+}
+
+// `connect|status|disconnect gdrive` is a GOOGLE connection, not an MCP one,
+// and is intercepted here — before the runtime is even resolved — because it
+// talks only to Elliot's API. `eai connect <mcp-server>` below still hands MCP
+// authentication to the runtime; these two share a verb and nothing else.
+//
+// Placed above the `status` intercept so `eai status gdrive` reaches the Drive
+// status rather than the general one, which knows nothing about personal
+// connectors.
+if (gdrive.isGdrive(process.argv[3])) {
+  const verb = process.argv[2]
+  const run =
+    verb === "connect" ? gdrive.connect
+      : verb === "disconnect" ? gdrive.disconnect
+        : verb === "status" ? gdrive.status
+          : null
+  if (run) {
+    finishWith(run(), `${verb} gdrive`)
+    return
+  }
+}
+
+// `status` and `logout` are intercepted for the same reason as `setup`: they
+// are about this machine's Elliot configuration, not about the coding session,
+// and both must work when the runtime cannot even be located -- "am I set up?"
+// is the question you ask precisely when nothing else is working.
+//
+// Migrated here from the retired `elliot-ai` CLI, which is the only thing that
+// ever answered them. Neither name is an OpenCode command, so nothing is
+// shadowed.
+if (process.argv[2] === "status" || process.argv[2] === "logout") {
+  const command = process.argv[2]
+  const run = command === "status" ? runStatus : () => runLogout({ force: process.argv.includes("--yes") })
+  finishWith(run(), command)
+  return
+}
+
 const resolved = resolveOpencodeBin({ packageRoot: PACKAGE_ROOT })
 
 if (!resolved) {
@@ -82,6 +210,15 @@ if (!resolved) {
   )
 }
 
+// `connect` runs AFTER resolution, unlike setup/status/logout: it hands the
+// actual OAuth to the runtime rather than implementing a second OAuth client.
+// Tokens must be written by one implementation, or a refresh by one silently
+// invalidates the other.
+if (process.argv[2] === "connect") {
+  finishWith(runConnect({ bin: resolved.path, argv: process.argv.slice(3) }), "connect")
+  return
+}
+
 if (process.env.ELLIOT_LAUNCHER_DEBUG) {
   // Opt-in only: the resolved path helps when a launch goes wrong, but it is
   // noise on every normal run, and stdout must stay clean for piped output.
@@ -138,6 +275,23 @@ for (const signal of FORWARDED_SIGNALS) {
 child.on("exit", (code, signal) => {
   for (const s of FORWARDED_SIGNALS) process.removeListener(s, forwarders[s])
 
+  // The update notice goes here, on the way OUT, and that placement is the
+  // whole reason it is visible at all. Printed before the spawn it would be
+  // erased a moment later: the TUI takes the alternate screen buffer and the
+  // notice disappears with everything else that was on screen. On exit the
+  // buffer has been restored, so it lands in the scrollback the user is left
+  // looking at — and after `eai run`, after the output rather than before it.
+  //
+  // TTY-gated, so a piped or CI invocation stays clean, and cheap: it reports
+  // what a PREVIOUS run cached and never waits on the network.
+  if (process.stderr.isTTY) {
+    try {
+      maybeNotify({ version: PACKAGE_VERSION })
+    } catch {
+      // A version notice may never be the reason a session fails to exit.
+    }
+  }
+
   // Re-raise rather than translating to an exit code, so callers can still tell
   // "killed by signal" from "exited non-zero" — scripts and CI depend on that.
   if (signal) {

package/lib/connect.js

@@ -0,0 +1,205 @@
+"use strict"
+
+/**
+ * `eai connect` — see every MCP tool and authenticate the one you pick.
+ *
+ * The runtime can already authenticate a server (`mcp auth <name>`), but only
+ * if you already know the server's exact name, that the command exists, and
+ * which of your servers still needs it. A user who just wants Slack working has
+ * none of those, and the failure they actually meet is a red `✗ failed` line
+ * with no next step in it.
+ *
+ * So this is discovery plus the action, in one place: list what is configured,
+ * say which are already connected, and run the login for the chosen one. The
+ * name is `connect` rather than `auth` because that is what the user is trying
+ * to do; authentication is how it happens, not what they came for.
+ *
+ * It reads the same files the runtime reads and shells out to the runtime to do
+ * the actual OAuth. It does NOT implement a second OAuth client: tokens must
+ * keep living in one place, written by one implementation, or a refresh done by
+ * one of them silently invalidates the other.
+ */
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const readline = require("readline")
+
+/** Where the runtime keeps its config, matching `setup.js`'s resolution. */
+function configDirs(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")
+  return [path.join(base, "opencode")]
+}
+
+/**
+ * Where the runtime stores MCP OAuth credentials.
+ *
+ * The DATA dir, not the config dir — they diverge, and looking in the wrong one
+ * reports every server as unauthenticated, which would send a user through a
+ * login they had already done.
+ */
+function mcpAuthFile(env = process.env) {
+  const base = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
+  return path.join(base, "opencode", "mcp-auth.json")
+}
+
+function readJson(file) {
+  try {
+    const text = fs.readFileSync(file, "utf8")
+    // Strip // and /* */ comments: the runtime accepts .jsonc, and a user's
+    // hand-edited config very often has them.
+    const stripped = text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1")
+    const parsed = JSON.parse(stripped)
+    return parsed && typeof parsed === "object" ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Every MCP server the runtime would load, with the state the user cares about.
+ *
+ * Later files win on a name collision, matching the runtime's own merge, so
+ * what is listed is what will actually run rather than what one file happens to
+ * say.
+ */
+function listServers(env = process.env) {
+  const servers = {}
+  for (const dir of configDirs(env)) {
+    for (const name of ["opencode.json", "opencode.jsonc"]) {
+      const cfg = readJson(path.join(dir, name))
+      if (cfg && cfg.mcp && typeof cfg.mcp === "object") Object.assign(servers, cfg.mcp)
+    }
+  }
+
+  const auth = readJson(mcpAuthFile(env)) || {}
+  return Object.entries(servers).map(([name, def]) => {
+    const remote = def && def.type === "remote"
+    return {
+      name,
+      type: (def && def.type) || "unknown",
+      url: (def && def.url) || null,
+      enabled: !def || def.enabled !== false,
+      authenticated: Boolean(auth[name]),
+      // A server carrying static `headers` authenticates with a token the user
+      // already supplied (GitHub's MCP takes a Bearer token this way). It has
+      // no OAuth step and stores nothing, so judging it by the credential file
+      // reports a working server as "not connected" and sends the user through
+      // a login that does not exist. Only OAuth-capable remotes are offerable.
+      tokenAuth: remote && Boolean(def && def.headers),
+      connectable: remote && !(def && def.headers),
+    }
+  })
+}
+
+function stateLabel(server) {
+  if (!server.enabled) return "disabled"
+  if (server.tokenAuth) return "token"
+  if (!server.connectable) return "local"
+  return server.authenticated ? "connected" : "not connected"
+}
+
+/** Render the table. Returned as lines so tests read them without a TTY. */
+function render(servers) {
+  if (!servers.length) {
+    return [
+      "No MCP servers are configured.",
+      "Run `eai setup` with the command from the Elliot portal — it configures them for you.",
+    ]
+  }
+  const width = Math.max(...servers.map((s) => s.name.length), 4)
+  const lines = ["", "MCP tools", "─────────────────────────────"]
+  for (const s of servers) {
+    lines.push(`  ${s.name.padEnd(width)}  ${stateLabel(s)}`)
+  }
+  lines.push("")
+  const pending = servers.filter((s) => s.connectable && s.enabled && !s.authenticated)
+  if (pending.length) {
+    lines.push(`${pending.length} tool${pending.length === 1 ? "" : "s"} can be connected.`)
+  } else {
+    lines.push("Everything that can be connected is connected.")
+  }
+  return lines
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(String(answer || "").trim())
+    })
+  })
+}
+
+/**
+ * Hand off to the runtime's own OAuth. stdio is inherited so its browser
+ * prompt and its "paste the code" step reach the user unchanged.
+ */
+function authenticate(bin, name, env, spawn = childProcess.spawnSync) {
+  const result = spawn(bin, ["mcp", "auth", name], { stdio: "inherit", env })
+  if (result.error) throw result.error
+  return typeof result.status === "number" ? result.status : 1
+}
+
+/**
+ * @param {{bin: string, argv?: string[], env?: object, log?: Function, ask?: Function, spawn?: Function}} opts
+ * @returns {Promise<number>} the process exit code
+ */
+async function runConnect(opts) {
+  const env = opts.env || process.env
+  const log = opts.log || ((s) => process.stdout.write(s + "\n"))
+  const prompt = opts.ask || ask
+  const servers = listServers(env)
+  const requested = (opts.argv || []).find((a) => !a.startsWith("-"))
+
+  if (requested) {
+    const hit = servers.find((s) => s.name === requested)
+    if (!hit) {
+      log(`No MCP server named "${requested}".`)
+      for (const line of render(servers)) log(line)
+      return 1
+    }
+    if (!hit.connectable) {
+      // Said plainly rather than attempted: `mcp auth` on a local server fails
+      // with an error about the server, which reads as "it is broken".
+      log(
+        hit.tokenAuth
+          ? `"${requested}" authenticates with a token from your config — there is no login to run.`
+          : `"${requested}" is a local server — it runs as a process and needs no login.`,
+      )
+      return 0
+    }
+    return authenticate(opts.bin, requested, env, opts.spawn)
+  }
+
+  for (const line of render(servers)) log(line)
+
+  const pending = servers.filter((s) => s.connectable && s.enabled && !s.authenticated)
+  if (!pending.length) return 0
+
+  // Non-interactive callers (CI, a pipe) get the listing and the command to run
+  // rather than a prompt into a stream nobody is reading.
+  if (!process.stdin.isTTY) {
+    log("")
+    for (const s of pending) log(`  eai connect ${s.name}`)
+    return 0
+  }
+
+  log("")
+  pending.forEach((s, i) => log(`  ${i + 1}) ${s.name}`))
+  const answer = await prompt("Connect which? [number, or Enter to skip] ")
+  if (!answer) {
+    log("Nothing connected.")
+    return 0
+  }
+  const index = Number.parseInt(answer, 10)
+  if (!Number.isInteger(index) || index < 1 || index > pending.length) {
+    log(`"${answer}" is not one of the listed numbers.`)
+    return 1
+  }
+  return authenticate(opts.bin, pending[index - 1].name, env, opts.spawn)
+}
+
+module.exports = { runConnect, listServers, render, stateLabel, mcpAuthFile, configDirs }