@elliotsystems/eai 0.1.4 → 0.1.7

package/lib/setup.js

@@ -34,7 +34,8 @@ const os = require("os")
 const path = require("path")
 
 const PROVIDER_ID = "elliot"
-const MODEL_ID = "elliot-governed"
+const GENERAL_MODEL_ID = "elliot-general"
+const CODER_MODEL_ID = "elliot-coder"
 
 /** Matches OpenCode's own resolution (xdg-basedir, whose fallback is ~/.config everywhere). */
 function opencodeConfigDir(env = process.env) {
@@ -69,22 +70,254 @@ function decodeJwtPayload(token) {
 /**
  * The `provider.elliot` block.
  *
- * `baseURL` ends in `/v1` on purpose: @ai-sdk/anthropic appends `/messages`,
- * and the route is `/llm-proxy/v1/messages`. Dropping the `/v1` yields a 404.
+ * `baseURL` ends in `/v1` because LiteLLM's own OpenAI-compatible endpoint is
+ * at `/v1/chat/completions`. `litellmBaseUrl` is the PUBLIC url the backend's
+ * onboarding config returns (`{backend_url}/litellm`, proxied by nginx) — not
+ * an internal Docker address, since this runs on the developer's own machine.
  *
- * `apiKey` is the literal string `{env:ELLIOT_TOKEN}`, not the token. OpenCode
- * substitutes it at config-load time and the launcher sets ELLIOT_TOKEN from
- * ~/.elliot/config.json on every run, which keeps that file the single source
- * of truth for an hourly-expiring credential — a refresh there is picked up
- * without rewriting this one.
+ * `apiKey` is the literal string `{env:ELLIOT_TOKEN}`, not the token itself.
+ * OpenCode substitutes it at config-load time, and the launcher
+ * (`token-env.js`) sets ELLIOT_TOKEN from `~/.elliot/config.json`'s
+ * `litellm_master_key` on every run — ONE shared secret for the whole
+ * gateway now, not a per-user credential (LiteLLM is deliberately DB-less;
+ * there is no per-tenant key without one). Two models are offered
+ * (`elliot-general`/`elliot-coder` — LiteLLM's own configured aliases,
+ * never a literal vendor id); OpenCode's own model-switcher picks between
+ * them.
+ *
+ * `identity` (Phase 1 governance) bakes static LiteLLM spend-log attribution
+ * headers into `options.headers` — `eai setup` runs once per DEVELOPER, so
+ * unlike OpenCode's shared team runtime, this can carry full identity:
+ * `x-litellm-end-user-id` = the real user, `x-litellm-spend-logs-metadata` =
+ * `{tenant_id, team_id, source: "eai"}`. All three come straight out of the
+ * `/onboarding/config/{tenant_id}` response `runSetup` already fetches
+ * (`user_id`/`team_id`/`tenant_id` — see that endpoint in
+ * `app/routers/onboarding.py`), never invented here. Omitted entirely (no
+ * `headers` key) when no identity was resolved, matching the backend's own
+ * `_identity_headers`/`_litellm_identity_headers` "don't invent identity"
+ * rule.
+ *
+ * `allowedModels` (Phase 4 governance, docs/LITELLM_GATEWAY.md §14) — the
+ * opened team's own model restriction, straight from the same onboarding
+ * response's `allowed_models` field. LiteLLM was always the real
+ * enforcement point regardless of what this function offers (LiteLLM
+ * gateway audit finding #5, mirrors the identical fix already made to
+ * `app/services/opencode/teamconfig.py::build_opencode_config` on the
+ * backend side for OpenCode's own web runtimes) — this only stops the menu
+ * from OFFERING a model that will be rejected. Falsy (undefined/null/[]) —
+ * every team until an admin restricts it — offers both, unchanged from
+ * before this parameter existed.
+ */
+function elliotProvider(litellmBaseUrl, identity = undefined, allowedModels = undefined) {
+  const base = String(litellmBaseUrl).replace(/\/+$/, "")
+  const options = { baseURL: `${base}/v1`, apiKey: "{env:ELLIOT_TOKEN}" }
+  const headers = litellmIdentityHeaders(identity)
+  if (headers) options.headers = headers
+  return {
+    npm: "@ai-sdk/openai-compatible",
+    // User-facing (the TUI's own provider/model picker shows this verbatim)
+    // — EAI branding only, never the gateway's own vendor name.
+    name: "EAI Gateway",
+    options,
+    models: offeredModels(allowedModels),
+  }
+}
+
+/**
+ * The `models` block for `elliotProvider`, filtered to `allowedModels` —
+ * see that function's own docstring. A team restricted to ONLY
+ * elliot-classifier (never offered here — internal-only, deploy/litellm/
+ * config.yaml §5) would otherwise get an empty, unusable menu; this
+ * degrades to offering both for that listing only, exactly like the
+ * backend's own fallback — LiteLLM still rejects any actual request the
+ * team isn't allowed to make either way.
+ */
+function offeredModels(allowedModels) {
+  const all = { [GENERAL_MODEL_ID]: { name: "EAI General" }, [CODER_MODEL_ID]: { name: "EAI Coder" } }
+  if (!allowedModels || allowedModels.length === 0) return all
+
+  const allowed = new Set(allowedModels)
+  const offered = Object.keys(all).filter((id) => allowed.has(id))
+  if (offered.length === 0) return all
+
+  const filtered = {}
+  for (const id of offered) filtered[id] = all[id]
+  return filtered
+}
+
+/** The default `model` field, given whatever `models` ended up offered —
+ *  always General when it's offered (unchanged default), otherwise
+ *  whichever one alias remains. */
+function defaultModelId(models) {
+  return GENERAL_MODEL_ID in models ? GENERAL_MODEL_ID : Object.keys(models)[0]
+}
+
+/**
+ * `{ "x-litellm-end-user-id": ..., "x-litellm-spend-logs-metadata": ... }`,
+ * or undefined when `identity` carries nothing usable — see `elliotProvider`.
+ */
+function litellmIdentityHeaders(identity) {
+  if (!identity) return undefined
+  const headers = {}
+  if (identity.userId) headers["x-litellm-end-user-id"] = String(identity.userId)
+  const metadata = {}
+  if (identity.tenantId) metadata.tenant_id = String(identity.tenantId)
+  if (identity.teamId) metadata.team_id = String(identity.teamId)
+  if (Object.keys(metadata).length > 0) {
+    metadata.source = "eai"
+    headers["x-litellm-spend-logs-metadata"] = JSON.stringify(metadata)
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined
+}
+
+/**
+ * The `mcp` block: the MCP servers this org's CLI should talk to.
+ *
+ * Comes from the backend (`mcp_servers`) so the list can grow without an npm
+ * release — adding a connector is a backend change, and the next `eai setup`
+ * picks it up. There is no longer a literal fallback below; see why.
+ *
+ * ONE server carries every connector. Elliot's own MCP endpoint exposes
+ * `knowledge_search`, `search_codebase`, `search_symbols`, `search_jira`,
+ * `search_slack`, `search_clickup`, `graph_query` and the rest, all governed
+ * and all authenticated as the user against this backend. Wiring Slack, Jira
+ * and ClickUp as separate third-party MCP servers instead would mean an OAuth
+ * app registered per workspace and a client secret distributed to every
+ * machine, for tools this backend already serves.
+ *
+ * THIS FALLBACK NO LONGER GUESSES AN ENDPOINT.
+ *
+ * It used to compose `{backendUrl}/mcp/v1` — Elliot MCP, dialled directly.
+ * Runtimes now reach Elliot through the LiteLLM MCP gateway, and the address
+ * of that gateway is the backend's to decide (`services/mcp_gateway.py`,
+ * derived from `litellm_base_url`), not something this launcher can infer from
+ * a backend URL. The two credentials the gateway needs are equally not
+ * inferable here.
+ *
+ * So a backend that does not serve `mcp_servers` gets NO MCP configuration
+ * rather than a direct one. That is the honest degradation: the CLI works
+ * without tools and says nothing false, where the old fallback would have
+ * quietly configured the bypass this cutover exists to remove. A backend old
+ * enough to lack the key is also old enough to lack the gateway.
+ *
+ * Returning nothing is NOT the same as leaving whatever is there. See
+ * `writeOpencodeConfig`: the `elliot` key is ours, so it is removed before the
+ * merge whether or not we have a replacement. Without that, a machine set up
+ * before this change keeps its stale entry forever — which is the one failure
+ * the old fallback was quietly preventing.
+ */
+function elliotMcpServers() {
+  return {}
+}
+
+/**
+ * The `/usage` command: a compact "Personal Usage & Limits" view inside the
+ * CLI — today's budget (spend, limit, percentage, reset time), rate limits,
+ * and this week's spend/requests/tokens with a daily breakdown — via the
+ * SAME `get_eai_usage` MCP tool the `elliot` server exposes as
+ * `elliot-get_eai_usage` — never a second usage implementation, and never
+ * fake/static data: the tool wraps `GET /usage/litellm/{tenant_id}/me`
+ * directly, the SAME endpoint and the SAME numbers the Member/User Web
+ * Chat Settings -> Usage screen shows — always THIS person's own usage,
+ * since that endpoint takes no scope parameter at all.
+ *
+ * That server is no longer defined in this file — it is SERVED, from the
+ * backend's own catalogue (`services/mcp_catalog.py`), so the command and
+ * the server it calls are configured from different places. The name is the
+ * join between them, and the join character is a HYPHEN, not an underscore:
+ * LiteLLM's MCP gateway namespaces every tool it proxies as `<alias>-<tool>`
+ * (live-verified against the real gateway, and pinned on the backend side by
+ * `tests/test_litellm_mcp_alias.py` — see that file's own docstring for the
+ * silent-failure mode an underscore here would reproduce). So
+ * `elliot-get_eai_usage` resolves only while the served entry is still
+ * called `elliot`, which `mcp_catalog.ELLIOT_SERVER` fixes.
+ *
+ * OpenCode's own config-driven custom-command mechanism (`cfg.command` in
+ * `command/index.ts`) is what makes this possible with no vendored-source
+ * change: any `command.<name>` entry here becomes a real, registered slash
+ * command, the identical mechanism the built-in `/init`/`/review` use.
+ *
+ * The template tells the agent to relay the tool's OWN pre-formatted text
+ * verbatim, inside a fenced code block, rather than re-summarizing it — the
+ * formatting (the progress bar, compact spend, DD Mon YYYY dates, EAI
+ * branding, never "LiteLLM") is computed once, on the backend, so it reads
+ * identically to Web Chat regardless of which model is answering; the code
+ * block is what keeps the progress bar's characters and spacing intact
+ * rather than a model reflowing them as prose.
  */
-function elliotProvider(backendUrl) {
-  const base = String(backendUrl).replace(/\/+$/, "")
+function elliotCommands() {
   return {
-    npm: "@ai-sdk/anthropic",
-    name: "Elliot (LightLLM proxy)",
-    options: { baseURL: `${base}/llm-proxy/v1`, apiKey: "{env:ELLIOT_TOKEN}" },
-    models: { [MODEL_ID]: { name: "Elliot Governed" } },
+    usage: {
+      description: "Show your EAI Personal Usage & Limits — spend, limits, reset time",
+      template:
+        "Call the elliot-get_eai_usage tool with no arguments. If it is not " +
+        "available yet (the elliot MCP server can still be connecting in a " +
+        "brand-new session), run `sleep 3` and try the tool call once more " +
+        "before concluding it is unavailable — do not report a failure after " +
+        "only one attempt. Once it succeeds, reply with ONLY its `summary` " +
+        "text, inside a fenced code block, exactly as returned — do not " +
+        "re-summarize, re-total, reformat, or add commentary beyond what it " +
+        "says.",
+    },
+    eai: {
+      description: "EAI project commands. /eai init writes AGENTS.md",
+      template:
+        "The subcommand is: $ARGUMENTS\n\n" +
+        "If it is not \"init\", reply with only:\n" +
+        "\"Usage: /eai init\n\n" +
+        "To update the Elliot CLI itself, exit this chat and run `eai update` " +
+        "in your terminal. That is a shell command, not a chat command — this " +
+        "slash command only writes AGENTS.md.\" — then stop.\n\n" +
+        "For \"init\", create or update `AGENTS.md` in the project root. " +
+        "AGENTS.md is the instruction file OpenCode already loads for this " +
+        "project; this command writes that file rather than introducing a " +
+        "second one.\n\n" +
+        "The goal is a compact instruction file that helps future sessions " +
+        "avoid mistakes and ramp up quickly. Every line should answer: " +
+        "\"Would an agent likely miss this without help?\" If not, leave it " +
+        "out.\n\n" +
+        "Investigate before writing: README and root manifests, lockfiles, " +
+        "build/test/lint/typecheck config, CI workflows, existing instruction " +
+        "files, and the real entrypoints. Prefer executable sources over " +
+        "prose; where they disagree, trust the executable one.\n\n" +
+        "Extract the highest-signal facts: exact developer commands including " +
+        "non-obvious ones, how to run a single test, required command order " +
+        "where it matters, package boundaries and real entrypoints, toolchain " +
+        "quirks (codegen, migrations, build artifacts, env loading), and " +
+        "conventions that differ from language or framework defaults.\n\n" +
+        "Exclude generic software advice, tutorials, exhaustive file trees, " +
+        "obvious language conventions, and anything you could not verify. " +
+        "When in doubt, omit.\n\n" +
+        "If AGENTS.md already exists, improve it IN PLACE rather than " +
+        "rewriting blindly: preserve verified useful guidance, delete stale " +
+        "claims, and reconcile it with the current codebase.\n\n" +
+        "NEVER copy a secret into AGENTS.md: no API keys, tokens, passwords, " +
+        "connection strings or any value from a .env or credentials file. " +
+        "Where such a file matters, name it and say values are omitted — for " +
+        "example \"`.env` holds runtime configuration and credentials; values " +
+        "intentionally omitted\".\n\n" +
+        "Do not list individual skills here; SKILLS.md is the skill index and " +
+        "`/eai-skills` generates it.\n\n" +
+        "When done, report the file written and the key facts you detected.",
+    },
+    "eai-skills": {
+      description: "Synchronize this project's EAI skill catalogue and write SKILLS.md",
+      template:
+        "Call the elliot_eai_skills_document tool with no arguments.\n\n" +
+        "Write its `markdown` value VERBATIM to the file named by `filename` " +
+        "in the project root, replacing that file entirely — it is a generated " +
+        "catalogue index and carries no hand-written content.\n\n" +
+        "Then report, as a short plain-text summary and nothing else:\n" +
+        "- the total number of skills in the document\n" +
+        "- each agent and its skill count, from the document's Agents " +
+        "section\n" +
+        "- the catalogue revision and last-synchronized time if present\n" +
+        "- any `unassigned_disciplines` entries, as a warning that those " +
+        "skills are not reachable through any agent\n\n" +
+        "Do NOT read, summarize or load the body of any individual skill. The " +
+        "document is an index; skill content is fetched per task with " +
+        "elliot_skills_content.",
+    },
   }
 }
 
@@ -92,10 +325,21 @@ function elliotProvider(backendUrl) {
  * Merge the provider into the user's opencode.json, preserving every other key.
  *
  * `enabled_providers` pins OpenCode to this one provider: `eai` is
- * governed-only, so there must be no direct-to-vendor path. `model` is only set
+ * gateway-only, so there must be no direct-to-vendor path. `model` is only set
  * when absent, so a user who picked a model keeps it.
+ *
+ * `backendUrl` and `litellmBaseUrl` are deliberately separate: the MCP server
+ * still talks to Elliot's own backend, while the LLM provider now talks to
+ * LiteLLM directly (no more `/llm-proxy` hop in between).
  */
-function writeOpencodeConfig(backendUrl, env = process.env) {
+function writeOpencodeConfig(
+  backendUrl,
+  litellmBaseUrl,
+  env = process.env,
+  servers = undefined,
+  identity = undefined,
+  allowedModels = undefined,
+) {
   const dir = opencodeConfigDir(env)
   const file = path.join(dir, "opencode.json")
   let existing = {}
@@ -105,18 +349,215 @@ function writeOpencodeConfig(backendUrl, env = process.env) {
     // Absent or unparseable. Overwriting unparseable JSON is the lesser evil:
     // OpenCode would refuse to start on it anyway.
   }
+  // Org servers are spread LAST so they win on a name collision. That is what
+  // repairs a stale entry rather than preserving it: a machine set up before
+  // this carries an `elliot` server pointing at a local process from an
+  // older, now-retired CLI package, which serves a subset of the tools and
+  // requires that package to be installed. The user's own unrelated servers
+  // are untouched.
+  // OURS TO REPLACE, THEIRS TO KEEP. The `elliot` key is this launcher's, so
+  // any existing one is dropped before the merge: a machine configured before
+  // the gateway carries either a local `elliot-cli` server or a direct
+  // `/mcp/v1` one, and both must go even when the backend supplies no
+  // replacement. Every other key is the user's own and survives untouched.
+  const { [PROVIDER_ID]: _ours, ...theirs } = existing.mcp || {}
+  const mcp = { ...theirs, ...(servers || elliotMcpServers()) }
+  const provider = elliotProvider(litellmBaseUrl, identity, allowedModels)
+  // Org commands are spread LAST, same rule as `mcp` above: this repairs a
+  // stale `/usage` from an older package rather than leaving it, while a
+  // user's own unrelated custom commands are untouched.
+  const command = { ...(existing.command || {}), ...elliotCommands() }
+  // `/eai init` writes AGENTS.md, which OpenCode already discovers through its
+  // own AGENTS.md/CLAUDE.md/CONTEXT.md lookup (`session/instruction.ts`). So
+  // there is nothing for this launcher to register: adding it to
+  // `config.instructions` as well would load the same file twice.
+  //
+  // A machine set up by an older package carries `EAI.md` here, pointing at a
+  // file nothing writes any more. Dropped on the next setup — OURS TO REPLACE,
+  // same rule the `mcp` and `command` merges above follow. Every other entry is
+  // the user's own and survives untouched.
+  const instructions = (
+    Array.isArray(existing.instructions) ? existing.instructions : []
+  ).filter((entry) => entry !== "EAI.md")
   const next = {
     ...existing,
     $schema: existing.$schema || "https://opencode.ai/config.json",
-    provider: { ...(existing.provider || {}), [PROVIDER_ID]: elliotProvider(backendUrl) },
+    provider: {
+      ...(existing.provider || {}),
+      [PROVIDER_ID]: provider,
+    },
     enabled_providers: [PROVIDER_ID],
-    model: existing.model || `${PROVIDER_ID}/${MODEL_ID}`,
+    // Follows the restriction, not always General — a team restricted to
+    // Coder-only must not default to a model its own menu just excluded.
+    model: existing.model || `${PROVIDER_ID}/${defaultModelId(provider.models)}`,
+    mcp,
+    command,
   }
+  if (instructions.length) next.instructions = instructions
+  else delete next.instructions
   fs.mkdirSync(dir, { recursive: true })
   fs.writeFileSync(file, JSON.stringify(next, null, 2) + "\n")
   return file
 }
 
+/**
+ * One entry per row in `eai_agents` (migration 086) -- `key` is the DB's own
+ * identity (case-folded by `resolve()`), and `description`/`responsibilities`
+ * are this launcher's, written for what OpenCode shows as a real agent.
+ *
+ * These files ARE the agent mechanism now. The `/eais <key>` command that
+ * used to activate an agent for a session is gone: OpenCode already selects
+ * a primary agent with Tab and reaches a subagent by `@mention`, and a second
+ * Elliot-specific activation path could only disagree with it.
+ *
+ * `mode` is a deliberate per-agent product choice, not derived from anything
+ * -- `dev`/`qa`/`devops`/`security` are `primary` (selectable with Tab, like
+ * `build`/`plan`); `governance`/`architecture`/`data`/`ai`/`product` are
+ * `subagent` (reachable by `@mention` or the `task` tool, like the built-in
+ * `general`/`explore`). Both are equally native; `agentMarkdown` just writes
+ * whichever this entry names.
+ *
+ * NOT fetched from the backend at setup time. The agent CATALOGUE (these nine
+ * rows) changes on the order of a migration, not a sync -- unlike skill
+ * MEMBERSHIP, which `eai_agent_disciplines` resolves fresh on every read
+ * specifically because it changes on every sync. Hardcoding the skill LIST
+ * each agent would reach is exactly what this file must never do (see
+ * agent_skills()'s own docstring); hardcoding which NINE agent roles exist is
+ * not that -- it is the same kind of static authorship as `dev`'s own prompt
+ * body, which this list simply extends to the other eight.
+ *
+ * `key` here must keep matching `eai_agents.key`, or `opencode agent
+ * list`/Tab-cycle and SKILLS.md would name the same agent differently --
+ * confusing rather than merely wrong.
+ *
+ * NOTHING ABOUT THE CATALOGUE IS HARDCODED HERE. The first cut of this
+ * feature put the nine keys, their descriptions AND their primary/subagent
+ * split in a JS list in this file -- repeating, in the launcher, the exact
+ * mistake migration 086 exists to stop for skill MEMBERSHIP: a second, stored
+ * copy of a fact that drifts from its own source of truth the moment either
+ * side changes without the other. `eai_agents` (`mode` added by migration
+ * 087) already owns all of it. `/onboarding/config/{tenant_id}` now returns
+ * it as `eai_agents` -- the exact rows `services/skills_catalogue/agents.py
+ * ::list_agents` resolves, the same call `eai_agents_list` makes -- and this
+ * file only turns whatever that response says into Markdown. An admin
+ * disabling an agent, moving one between primary and subagent, or a future
+ * tenth agent all take effect on the next `eai setup`, no launcher release.
+ */
+
+//: Verbatim shared constraints, identical across every EAI agent regardless
+//: of mode or catalogue state -- these are not discipline-specific, and a
+//: copy that drifted per agent (one devops agent allowed to push commits,
+//: say, because someone forgot this block) would be a worse failure than a
+//: single shared block repeated into every file.
+const EAI_AGENT_CONSTRAINTS = [
+  "Inspect the existing configuration before changing it; preserve the project's current provider, model, MCP, permission, instruction and command settings.",
+  "Never write a secret or a credential into a file you create or edit.",
+  "Do not bypass this project's own authorization, approval or review workflow for a change -- including one already in flight for a skill, a PR, or a config value.",
+  "Do not push a commit or open a pull request unless asked to.",
+  "Do not build a second, parallel execution path for something this project already does one way.",
+]
+
+/**
+ * One EAI agent's Markdown definition, from one row of the backend's live
+ * `eai_agents` response (`{key, name, description, mode, skill_count}`).
+ *
+ * OpenCode discovers a primary agent three ways: a built-in (`build`, `plan`,
+ * `general`), an `agent.<name>` entry in opencode.json, or a Markdown file
+ * under `agent/` or `agents/` in any directory it scans for config — which
+ * INCLUDES the global config directory (`~/.config/opencode`, the same one
+ * `writeOpencodeConfig` already writes into) alongside any per-project
+ * `.opencode/`. `opencode agent create --global` writes exactly here, so this
+ * is the sanctioned location, not a guess: `~/.config/opencode/agents/<key>.md`.
+ *
+ * `agent.mode` decides WHICH of two native mechanisms an agent uses, not
+ * whether it is native: `primary` is what makes it show up next to
+ * `build`/`plan` in the TUI's own agent list and Tab-cycle (`agent.cycle` in
+ * opencode/packages/tui/src/config/keybind.ts); `subagent` is what makes it
+ * reachable by `@mention` and the `task` tool instead, the same way the
+ * built-in `general`/`explore` subagents are -- still a real, natively
+ * discovered agent, just invoked rather than switched to. This file writes
+ * whichever the backend says for this agent; it does not decide.
+ *
+ * No `model` field, regardless of mode. The schema (`ConfigAgentV1.Info`)
+ * makes it optional for exactly this case: an agent with no model inherits
+ * whatever the session's own default is, so this file never pins a
+ * vendor-specific model id that would drift from `provider.elliot`'s own
+ * configured models.
+ *
+ * The body is ONE generic template, parameterised by `agent.name`/
+ * `agent.description` -- not nine hand-written prompts. Authoring nine
+ * separate bodies would mean the one EAI-specific thing about them (which
+ * role each performs) living only in this file, invisible to and unverified
+ * against the backend's own `description` for that same agent; the generic
+ * template keeps that single fact in one place.
+ */
+function agentMarkdown(agent) {
+  const lines = (items) => items.map((s) => `- ${s}\n`).join("")
+  return (
+    "---\n" +
+    `description: Elliot's ${agent.name} agent -- ${agent.description}.\n` +
+    `mode: ${agent.mode}\n` +
+    "---\n" +
+    `You are Elliot's ${agent.name} agent: ${agent.description}.\n` +
+    "\n" +
+    "## Responsibilities\n" +
+    "\n" +
+    lines([
+      "Understand the repository's architecture and existing conventions in this area before changing anything.",
+      "Do the work within that architecture -- do not introduce a parallel one.",
+      "For a defect, find the root cause before writing a fix; a fix for a symptom that leaves the cause in place is not done.",
+      "Verify a claim against a real run, a real test, or a real read of the code -- never report success without having checked.",
+      "Explain what changed, the decisions that mattered, the real outcome of any check you ran, and any risk left outstanding.",
+      "Avoid unrelated changes, unnecessary new dependencies, and a second implementation of something that already exists in this codebase.",
+    ]) +
+    "\n" +
+    "## Constraints\n" +
+    "\n" +
+    lines(EAI_AGENT_CONSTRAINTS) +
+    "\n" +
+    "If this project has an `AGENTS.md`, it is read automatically and is the project's context reference; `SKILLS.md`, if present, indexes the skill catalogue by agent and is regenerated by `/eai-skills` -- use them when a task calls for a convention or a skill this file does not already cover. Load a skill body with the skills_content tool, one at a time, only when the task needs it.\n"
+  )
+}
+
+/**
+ * Write one EAI agent's file into the global OpenCode config directory.
+ *
+ * Unconditional overwrite, same rule as `elliotCommands()` above ("OURS TO
+ * REPLACE"): this file is entirely EAI-generated, so re-running setup must
+ * repair a stale copy from an older package rather than leave it, exactly
+ * like the `elliot` MCP server and the `/eai` commands already do.
+ * There is nothing here for a user to have hand-edited -- unlike
+ * opencode.json, which merges around a user's own unrelated keys, this file
+ * has exactly one owner.
+ */
+function writeAgentFile(agent, env = process.env) {
+  const dir = path.join(opencodeConfigDir(env), "agents")
+  const file = path.join(dir, `${agent.key}.md`)
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(file, agentMarkdown(agent))
+  return file
+}
+
+/**
+ * Every agent the backend's `eai_agents` response named, in one pass.
+ *
+ * `agents` is exactly the `eai_agents` array `fetchOnboardingConfig`'s
+ * response carries (or `[]`/undefined for a backend that predates it, which
+ * this treats as "nothing to write" rather than an error -- a CLI update
+ * must not need a backend update released in lockstep, the same tolerance
+ * `writeOpencodeConfig`'s own `servers` fallback already extends to
+ * `mcp_servers`).
+ *
+ * Stale-file cleanup is deliberately NOT done here: deleting a file this
+ * launcher did not just enumerate would mean trusting a naming convention to
+ * tell an EAI-generated agent apart from one the user wrote themselves under
+ * the same directory, which is exactly the kind of guess `elliotCommands()`'s
+ * "OURS TO REPLACE, THEIRS TO KEEP" rule exists to avoid making.
+ */
+function writeAllAgentFiles(agents, env = process.env) {
+  return (agents || []).map((agent) => writeAgentFile(agent, env))
+}
+
 /** Owner-only: this file holds a bearer token and a refresh token. */
 function writeElliotConfig(config) {
   const file = elliotConfigPath()
@@ -151,8 +592,22 @@ async function exchangeForCliToken(backendUrl, token) {
   }
 }
 
-async function fetchOnboardingConfig(backendUrl, tenantId, token) {
-  const res = await fetch(`${backendUrl}/onboarding/config/${tenantId}`, {
+/**
+ * `team_id` is OPTIONAL and, when given, is appended as a query param — the
+ * same way `terminal/src/CliSetup.tsx` already scopes its own call to
+ * `/onboarding/config/{tenantId}?team_id=...`. Without it, `get_onboarding_
+ * config` resolves no team at all and its LiteLLM key falls back to a
+ * shared/personal credential rather than this team's own — the team-CLI
+ * half of the LiteLLM credential-routing audit: the browser resolves team_id
+ * correctly when it mints the setup command, but this re-fetch used to drop
+ * it, so `eai setup --token <jwt minted with team context>` still came back
+ * scoped to no team at all.
+ */
+async function fetchOnboardingConfig(backendUrl, tenantId, token, teamId) {
+  const url = teamId
+    ? `${backendUrl}/onboarding/config/${tenantId}?team_id=${encodeURIComponent(teamId)}`
+    : `${backendUrl}/onboarding/config/${tenantId}`
+  const res = await fetch(url, {
     headers: { Authorization: `Bearer ${token}` },
   })
   if (!res.ok) {
@@ -175,6 +630,13 @@ async function runSetup(opts) {
   if (!tenantId) {
     throw new Error("no tenant_id in the token; pass --tenant-id, or copy a fresh command from the portal")
   }
+  // The pasted token is minted by `terminal/src/CliSetup.tsx` from the
+  // project card the user opened, and already carries that team in its own
+  // `team_id` claim (withheld only for an owner/admin, whose setup is
+  // deliberately tenant-wide — see `get_onboarding_config`'s own comment on
+  // `tenant_wide`). `--team-id` is an explicit override for a caller who
+  // wants to force a different scope than the token names.
+  const teamId = opts.teamId || claims.team_id
 
   const exchanged = await exchangeForCliToken(backendUrl, opts.token)
   if (!exchanged) {
@@ -183,26 +645,65 @@ async function runSetup(opts) {
   const bearer = exchanged ? exchanged.access_token : opts.token
 
   log("Fetching configuration from backend...")
-  const orgConfig = await fetchOnboardingConfig(backendUrl, tenantId, bearer)
+  const orgConfig = await fetchOnboardingConfig(backendUrl, tenantId, bearer, teamId)
 
   const elliotConfig = {
     ...orgConfig,
     backend_url: orgConfig.backend_url || backendUrl,
     tenant_id: tenantId,
     jwt_token: bearer,
+    // The CLI's ELLIOT MCP credential, minted by the same onboarding request
+    // that minted `jwt_token` and carrying the same identity with the MCP
+    // audience. `token-env.js` exports it as ELLIOT_MCP_TOKEN, which is what
+    // the `{env:ELLIOT_MCP_TOKEN}` placeholder in the generated opencode.json
+    // resolves to.
+    //
+    // Spread from the response rather than assigned unconditionally: a backend
+    // that predates this does not send it, and writing `undefined` would
+    // overwrite a working value from a previous setup with nothing.
+    ...(typeof orgConfig.mcp_token === "string" && orgConfig.mcp_token
+      ? { mcp_token: orgConfig.mcp_token }
+      : {}),
     ...(exchanged && exchanged.refresh_token ? { refresh_token: exchanged.refresh_token } : {}),
     ...(exchanged && exchanged.expires_at ? { access_token_expires_at: exchanged.expires_at } : {}),
     configured_at: new Date().toISOString(),
   }
 
   const elliotFile = writeElliotConfig(elliotConfig)
-  const opencodeFile = writeOpencodeConfig(elliotConfig.backend_url)
+  // `mcp_servers` arrives in OpenCode's own config shape, so it is written
+  // through unchanged. Validated only for shape — a backend that sends garbage
+  // must not leave the user with an unparseable config, and an older backend
+  // that sends nothing falls back to the built-in server list.
+  const servers =
+    orgConfig.mcp_servers && typeof orgConfig.mcp_servers === "object" && !Array.isArray(orgConfig.mcp_servers)
+      ? orgConfig.mcp_servers
+      : undefined
+  // litellm_base_url is a PUBLIC url (backend's onboarding response derives
+  // it as `{backend_url}/litellm`) — fall back to the backend url itself only
+  // for a backend that predates this field, which would then 404 rather than
+  // silently pointing nowhere.
+  const litellmBaseUrl = orgConfig.litellm_base_url || elliotConfig.backend_url
+  // Phase 1 governance: full identity is available here (eai setup runs once
+  // per developer) — straight from the onboarding response, never invented.
+  // See elliotProvider's docstring above.
+  const identity = { tenantId: tenantId, userId: orgConfig.user_id, teamId: orgConfig.team_id }
+  const opencodeFile = writeOpencodeConfig(
+    elliotConfig.backend_url,
+    litellmBaseUrl,
+    process.env,
+    servers,
+    identity,
+    orgConfig.allowed_models,
+  )
+
+  const agentFiles = writeAllAgentFiles(orgConfig.eai_agents, process.env)
 
   log(`Wrote ${elliotFile}`)
   log(`Wrote ${opencodeFile}`)
+  for (const file of agentFiles) log(`Wrote ${file}`)
   log("")
   log("Setup complete. Run `eai` from any directory.")
-  return { elliotFile, opencodeFile, tenantId, exchanged: Boolean(exchanged) }
+  return { elliotFile, opencodeFile, agentFiles, tenantId, exchanged: Boolean(exchanged) }
 }
 
 /** Minimal `--flag value` parsing; the launcher has no dependencies by design. */
@@ -213,6 +714,7 @@ function parseArgs(argv) {
     if (arg === "--token") out.token = argv[++i]
     else if (arg === "--backend-url") out.backendUrl = argv[++i]
     else if (arg === "--tenant-id") out.tenantId = argv[++i]
+    else if (arg === "--team-id") out.teamId = argv[++i]
   }
   return out
 }
@@ -221,11 +723,19 @@ module.exports = {
   runSetup,
   parseArgs,
   decodeJwtPayload,
+  fetchOnboardingConfig,
   elliotProvider,
+  litellmIdentityHeaders,
+  elliotMcpServers,
+  elliotCommands,
   writeOpencodeConfig,
   writeElliotConfig,
+  agentMarkdown,
+  writeAgentFile,
+  writeAllAgentFiles,
   opencodeConfigDir,
   elliotConfigPath,
   PROVIDER_ID,
-  MODEL_ID,
+  GENERAL_MODEL_ID,
+  CODER_MODEL_ID,
 }