@elliotsystems/eai 0.1.5 → 0.1.9

package/plugin/opencode-plugin/src/guardrail-sync.ts

@@ -0,0 +1,330 @@
+/**
+ * Keeps the Jev guardrail's per-request activation current with the team's
+ * REAL, live `Team.jev_policy_enabled` — instead of the one-shot snapshot
+ * `eai setup` bakes into `opencode.json`'s static `options.metadata.
+ * guardrails` (see elliot-launcher/lib/setup.js's own `elliotProvider`).
+ *
+ * ## The gap this closes (CLI session-recovery)
+ *
+ * Web Chat's equivalent bug (terminal/src/opencode/useOpencodeChat.ts) was:
+ * an admin's `jev_policy_enabled` change doesn't reach an already-running
+ * OpenCode instance until that instance is torn down and rebuilt — fixed on
+ * the Web Chat side by (a) checking team-level drift on every request
+ * (backend `_reconcile`) and (b) transparently starting a fresh session when
+ * the old one's instance is gone.
+ *
+ * NEITHER half of that fix has a real analogue for the EAI CLI, and this
+ * module exists because of that, not in spite of it:
+ *
+ *   - There is no "OpenCode server instance" to replace. Web Chat's
+ *     OpenCode runtimes are backend-hosted containers/subprocesses, keyed by
+ *     team, with their own lifecycle (services/opencode/manager.py). The
+ *     CLI's OpenCode process is the user's own local machine running the
+ *     real upstream `opencode` binary (elliot-launcher/bin/eai just
+ *     `spawn`s it with `stdio: "inherit"`) — nothing on Elliot's backend
+ *     ever tears it down or replaces it. A "replaced instance" literally
+ *     cannot happen to it.
+ *   - `elliot-launcher`'s `eai` has zero visibility into the TUI's traffic
+ *     once spawned (inherited stdio, a real full-screen terminal app) and
+ *     the OpenCode plugin API (opencode/packages/plugin/src/index.ts) has NO
+ *     hook that observes a chat response or error — `tool.execute.after`
+ *     only covers TOOL calls, not the chat completion itself. So "detect
+ *     this message got blocked, then resend it" is not implementable from
+ *     either layer available to this integration: there is no hook to
+ *     detect it from.
+ *
+ * What IS real, and what this fixes: the CLI's guardrail activation is a
+ * STATIC snapshot, taken once at `eai setup` and never touched again for the
+ * life of that file. An admin flipping the toggle after that leaves the CLI
+ * silently wrong in BOTH directions until the user re-runs `eai setup`:
+ *   - turned ON after setup  -> the CLI never guards anything (a real
+ *     enforcement gap, not just a UX one);
+ *   - turned OFF after setup -> the CLI keeps blocking every single prompt
+ *     forever (the exact behavior reported: "for every prompts... fix it").
+ *
+ * `chat.params` (opencode/packages/plugin/src/index.ts) is the one hook that
+ * runs on EVERY outgoing request, before it is sent, with write access to
+ * the exact `options` object that becomes the request body (traced through
+ * session/llm/request.ts: `options = mergeOptions(base, model.options, ...)`
+ * is passed into `chat.params`'s `output.options`, and `model.options` is
+ * precisely where `eai setup` wrote `metadata.guardrails`). Using it here
+ * means the correct, CURRENT guardrail state is used on the message's one
+ * and only attempt — there is no failure to recover from, no retry, and
+ * therefore none of the duplicate-request/duplicate-tool-execution risk a
+ * retry-based design would carry.
+ *
+ * ## Fail-safe direction
+ *
+ * A live check that cannot complete (offline, backend down, expired token)
+ * returns `null` and changes NOTHING — the request goes out with whatever
+ * the static config already had, exactly as it did before this module
+ * existed. This can under-protect (an admin's brand-new enable is missed
+ * while offline) but never over-blocks and never throws, which is the
+ * right trade for a CLI tool that must keep working offline: this was never
+ * the enforcement boundary (LiteLLM's own guardrail is, and it fails CLOSED
+ * on its own uncertainty — see jev_decisions_logic.py's CONFIDENCE_THRESHOLD
+ * — because THAT failure is security-load-bearing). This module only
+ * decides which flag to send; a transport failure here is an availability
+ * question, not a security one.
+ */
+import { readElliotConfig, type ElliotConfig } from "./elliot-auth.js"
+
+export const JEV_GUARDRAIL_NAME = "jev-policy"
+
+/**
+ * Jev audit (2026-10, G2): the POST-CALL counterpart to `JEV_GUARDRAIL_NAME`
+ * — must match `Team.jev_output_validation_enabled`'s own LiteLLM guardrail
+ * name (`deploy/litellm/config.yaml`'s `"jev-output-validation"` entry,
+ * `backend/app/services/jev_guardrail_names.py`'s `POST_CALL_GUARDRAIL_NAME`).
+ * Before this constant/the functions below existed, this file only ever
+ * live-synced `jev-policy` — an admin enabling or disabling
+ * `jev_output_validation_enabled` had ZERO effect on an already-`eai setup`
+ * CLI session until the user re-ran setup, the exact bug this whole module
+ * exists to prevent for the pre-call flag (see this file's own top docstring)
+ * but silently left unfixed for the post-call one.
+ */
+export const OUTPUT_VALIDATION_GUARDRAIL_NAME = "jev-output-validation"
+
+/** How long a live answer is trusted before the next request re-checks.
+ *  Short enough that an admin's change reaches the CLI within one coffee
+ *  break of it taking effect; long enough that a user typing several
+ *  messages in a row does not turn every one into a network round trip. */
+const CACHE_TTL_MS = 15_000
+
+/** Per-request timeout for the live check itself. A hung connection must
+ *  not add a user-visible stall to every single message. */
+const CHECK_TIMEOUT_MS = 3_000
+
+interface CacheEntry {
+  jevPolicyEnabled: boolean
+  /** Jev audit (2026-10, G2). */
+  jevOutputValidationEnabled: boolean
+  teamId: string
+  expiresAt: number
+}
+
+let cache: CacheEntry | null = null
+
+/** Test-only: forget whatever the last live check learned, so a test does
+ *  not inherit state another test left behind (module-level cache is
+ *  otherwise invisible from outside this file). */
+export function resetGuardrailSyncCache(): void {
+  cache = null
+}
+
+export interface LiveCheckDeps {
+  /** Overridable for tests — never the real network in a unit test. */
+  fetchImpl?: typeof fetch
+  now?: () => number
+  /** Overridable so a test does not have to write a real file to disk for
+   *  every case; defaults to the real `~/.elliot/config.json` reader. */
+  readConfig?: () => ElliotConfig | null
+  /**
+   * The team THIS OUTGOING REQUEST is actually scoped to — the ground
+   * truth already baked into `options.headers["x-litellm-spend-logs-
+   * metadata"]` by `teamconfig.py`'s own `_litellm_identity_headers` at
+   * provisioning time (see `extractInstanceTeamId` below, which the
+   * `chat.params` hook uses to derive this). NOT read from `~/.elliot/
+   * config.json` — that file is per-MACHINE, written once by `eai setup`
+   * for one specific person/team/backend.
+   *
+   * Required to trust the live check at all: a backend-hosted Web Chat
+   * OpenCode runtime, in this project's local-dev mode (`OPENCODE_
+   * RUNTIME_SUBPROCESS` — same user, same filesystem, no isolation), can
+   * end up running under a real developer's OWN `eai setup` login for a
+   * completely different team, tenant, or even backend (e.g. staging)
+   * than the one THIS request belongs to. Live-confirmed this session: a
+   * local "Test" team's guardrail toggle was silently overridden by a
+   * staging account's config for an unrelated team, because nothing here
+   * had ever checked that the two team ids agreed before trusting the
+   * live answer.
+   *
+   * `undefined` (the default) skips this check entirely — an existing
+   * caller with no way to know its own instance team id (there isn't one
+   * for the real EAI CLI, which never shares a filesystem with anyone
+   * else's session) keeps working exactly as before. Only an EXPLICIT,
+   * KNOWN mismatch (both ids present and different) suppresses the live
+   * check; this narrows an unsafe case, it does not add a new
+   * requirement for callers that already work correctly.
+   */
+  instanceTeamId?: string | null
+}
+
+/**
+ * Both guardrail toggles' current, live values from the backend — fetched
+ * and cached TOGETHER from the one `GET /teams/{id}` call that already
+ * returns both `jev_policy_enabled` and `jev_output_validation_enabled`
+ * (Jev audit, 2026-10, G2: previously only the pre-call flag was ever
+ * fetched/cached here, so the post-call one had no live-sync mechanism at
+ * all). Returns `null` under the exact same conditions `liveJevPolicyEnabled`
+ * always has (see its own docstring, preserved below) — no team context, an
+ * instance/request team-id mismatch, or a failed check with no usable cache.
+ */
+async function liveJevGuardrailFlags(
+  deps: LiveCheckDeps = {},
+): Promise<{ jevPolicyEnabled: boolean; jevOutputValidationEnabled: boolean } | null> {
+  const now = deps.now ?? Date.now
+  const fetchImpl = deps.fetchImpl ?? fetch
+  const readConfig = deps.readConfig ?? readElliotConfig
+  const config = readConfig()
+
+  // No team context at all -- a tenant-wide (owner/admin) setup, or a
+  // config predating team scoping. Nothing team-level to check live;
+  // genuinely unknown rather than "disabled."
+  if (!config?.backend_url || !config.tenant_id || !config.team_id || !config.jwt_token) {
+    return null
+  }
+
+  // The local machine's own login config is for a DIFFERENT team than the
+  // one this specific request is scoped to -- trusting it would silently
+  // apply (or strip) a guardrail based on someone else's team/tenant/
+  // backend. Treat exactly like every other "cannot determine" case above
+  // rather than guessing. Only fires when BOTH ids are actually known;
+  // `undefined`/`null` here (the default for every existing caller) never
+  // triggers it.
+  if (
+    deps.instanceTeamId !== undefined &&
+    deps.instanceTeamId !== null &&
+    deps.instanceTeamId !== config.team_id
+  ) {
+    return null
+  }
+
+  if (cache && cache.teamId === config.team_id && now() < cache.expiresAt) {
+    return { jevPolicyEnabled: cache.jevPolicyEnabled, jevOutputValidationEnabled: cache.jevOutputValidationEnabled }
+  }
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS)
+  try {
+    const base = config.backend_url.replace(/\/+$/, "")
+    const res = await fetchImpl(`${base}/teams/${encodeURIComponent(config.team_id)}`, {
+      headers: { Authorization: `Bearer ${config.jwt_token}` },
+      signal: controller.signal,
+    })
+    if (!res.ok) throw new Error(`backend returned ${res.status}`)
+    const body: unknown = await res.json()
+    const record = body && typeof body === "object" ? (body as Record<string, unknown>) : {}
+    const jevPolicyEnabled = Boolean(record.jev_policy_enabled)
+    const jevOutputValidationEnabled = Boolean(record.jev_output_validation_enabled)
+    cache = {
+      jevPolicyEnabled,
+      jevOutputValidationEnabled,
+      teamId: config.team_id,
+      expiresAt: now() + CACHE_TTL_MS,
+    }
+    return { jevPolicyEnabled, jevOutputValidationEnabled }
+  } catch {
+    // Offline, backend unreachable, expired token, or a malformed response.
+    // Never throw into the chat.params hook over this -- a CLI message must
+    // still be sendable without a network round trip succeeding. Fall back
+    // to a still-fresh cached value for this same team if one exists;
+    // otherwise genuinely unknown.
+    return cache && cache.teamId === config.team_id && now() < cache.expiresAt
+      ? { jevPolicyEnabled: cache.jevPolicyEnabled, jevOutputValidationEnabled: cache.jevOutputValidationEnabled }
+      : null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * The team's current `jev_policy_enabled`, live from the backend — or
+ * `null` when it cannot be determined (no team context, not logged in, the
+ * check itself failed, or the local config belongs to a DIFFERENT team than
+ * this request — see `instanceTeamId`), which callers must read as "use
+ * whatever is already configured," never as "disabled."
+ */
+export async function liveJevPolicyEnabled(deps: LiveCheckDeps = {}): Promise<boolean | null> {
+  const flags = await liveJevGuardrailFlags(deps)
+  return flags ? flags.jevPolicyEnabled : null
+}
+
+/**
+ * The POST-CALL counterpart to `liveJevPolicyEnabled` — the team's current
+ * `jev_output_validation_enabled`, live from the backend, with the exact
+ * same `null`-means-"leave it alone" contract (Jev audit, 2026-10, G2).
+ * Shares `liveJevPolicyEnabled`'s own cache/fetch under the hood (one
+ * `GET /teams/{id}` call answers both), so calling both on the same request
+ * costs at most one network round trip, not two.
+ */
+export async function liveJevOutputValidationEnabled(deps: LiveCheckDeps = {}): Promise<boolean | null> {
+  const flags = await liveJevGuardrailFlags(deps)
+  return flags ? flags.jevOutputValidationEnabled : null
+}
+
+/**
+ * Applies a live guardrail decision to the outgoing request's `options`,
+ * mutating `metadata.guardrails` to match exactly — adding `guardrailName`
+ * when live-enabled, removing it (even if the STATIC config baked it in at
+ * `eai setup` time) when live-disabled. A `null` decision (see
+ * `liveJevPolicyEnabled`'s own docstring) changes nothing, leaving whatever
+ * the static config/an earlier plugin already set untouched.
+ *
+ * `guardrailName` defaults to `JEV_GUARDRAIL_NAME` (pre-call) so every
+ * existing 2-argument call site is unaffected; pass
+ * `OUTPUT_VALIDATION_GUARDRAIL_NAME` for the post-call decision (Jev audit,
+ * 2026-10, G2). Two calls targeting different names compose safely — each
+ * only ever adds/removes its OWN name from the shared `guardrails` array,
+ * never touching the other's entry, so calling this once for each flag (as
+ * `index.ts`'s `chat.params` hook now does) correctly reflects both toggles
+ * independently on the same request.
+ *
+ * Pure and synchronous on purpose: the async live-check already happened by
+ * the time this runs, so applying its result cannot itself introduce a
+ * second network call, a retry, or any other source of a duplicate request.
+ */
+export function applyGuardrailDecision(
+  options: Record<string, unknown>,
+  decision: boolean | null,
+  guardrailName: string = JEV_GUARDRAIL_NAME,
+): void {
+  if (decision === null) return
+
+  const metadata =
+    options.metadata && typeof options.metadata === "object" && !Array.isArray(options.metadata)
+      ? (options.metadata as Record<string, unknown>)
+      : (options.metadata = {} as Record<string, unknown>)
+
+  const existing = Array.isArray(metadata.guardrails)
+    ? (metadata.guardrails as unknown[]).filter((g): g is string => typeof g === "string")
+    : []
+  const withoutThisName = existing.filter((g) => g !== guardrailName)
+
+  metadata.guardrails = decision ? [...withoutThisName, guardrailName] : withoutThisName
+}
+
+/**
+ * The team id THIS specific outgoing request is scoped to, read from the
+ * SAME static header `teamconfig.py`'s `_litellm_identity_headers` already
+ * baked into `options.headers["x-litellm-spend-logs-metadata"]` at
+ * provisioning time — e.g. `{"tenant_id":"...","team_id":"...",
+ * "source":"opencode"}`. This is ground truth about the request regardless
+ * of which real person's OS login happens to be running the process, which
+ * is exactly why it is the right thing to compare `~/.elliot/config.json`'s
+ * own `team_id` against (see `LiveCheckDeps.instanceTeamId`'s own
+ * docstring).
+ *
+ * Returns `undefined` (not `null`) for "could not determine" — `undefined`
+ * is `LiveCheckDeps.instanceTeamId`'s own "skip this check" value, so a
+ * request shape this function does not recognize degrades to the EXACT
+ * pre-existing behavior (trust whatever `~/.elliot/config.json` says) rather
+ * than a new, stricter failure mode nobody asked for.
+ */
+export function extractInstanceTeamId(options: Record<string, unknown> | null | undefined): string | undefined {
+  const headers = options?.["headers"]
+  if (!headers || typeof headers !== "object") return undefined
+  const raw = (headers as Record<string, unknown>)["x-litellm-spend-logs-metadata"]
+  if (typeof raw !== "string") return undefined
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    const teamId =
+      parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>)["team_id"] : undefined
+    return typeof teamId === "string" && teamId ? teamId : undefined
+  } catch {
+    // Malformed/unexpected header shape -- "could not determine" (see this
+    // function's own docstring), never a thrown error over a header this
+    // module merely reads and does not own the shape of.
+    return undefined
+  }
+}

package/plugin/opencode-plugin/src/identity-headers.ts

@@ -0,0 +1,81 @@
+/**
+ * Per-message LiteLLM `end_user` attribution for a TEAM-shared runtime.
+ *
+ * A team instance's LiteLLM provider options carry exactly ONE static
+ * `x-litellm-end-user-id` header (`teamconfig.py::_litellm_identity_headers`),
+ * baked in once at config-generation time as the shared runtime's own
+ * instance id — correct for "which runtime", never "which person", because
+ * every authorized team member sends messages through that same instance.
+ * Confirmed live: two different people chatting through the same team
+ * runtime produced identical `end_user` values in LiteLLM's own spend logs.
+ *
+ * This corrects it per REQUEST via OpenCode's own `chat.headers` hook, which
+ * fires once per chat turn with that turn's live session id — late enough to
+ * win: `session/llm/request.ts` spreads this hook's returned headers LAST,
+ * after the static `options.headers` from `opencode.json`. The real
+ * sender's id is read back from that session's own metadata, stamped there
+ * by the Elliot backend right after creating the session
+ * (`opencode_chat.py::create_session`, `PATCH /session/:id`) — never
+ * invented here, never derived from the message content.
+ *
+ * A session with no such metadata — every session that predates this
+ * feature, a generic/personal instance (which already attributes correctly
+ * via its own static `owner_user_id` header and has no need of this), or a
+ * lookup that fails for any reason — is left alone: the static header keeps
+ * doing its job, exactly as before this hook existed.
+ */
+
+/** The key the backend stamps on a session's own metadata. Mirrors the
+ *  literal `opencode_chat.py::create_session` writes — not independently
+ *  configurable, since a drift here would silently stop the handoff. */
+const USER_ID_METADATA_KEY = "elliot_user_id"
+
+/** The backend always stamps a real UUID (`User.id`). Anything else reaching
+ *  here — a typo, a future metadata shape, a stale/foreign value — is not
+ *  trustworthy as an identity and is left unresolved rather than forwarded
+ *  verbatim to LiteLLM. */
+const LOOKS_LIKE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** Structural mirror of the one SDK method this module calls — the host's
+ *  real client has many more, declared here only to the extent used (same
+ *  reasoning `index.ts`'s own `PluginInput` mirror gives). */
+export interface SessionClient {
+  session?: {
+    get?: (input: { path: { id: string } }) => Promise<unknown>
+  }
+}
+
+/** Pulls the session object out of whatever envelope the client returns —
+ *  tolerant of an openapi-fetch-style `{data, error}` wrapper or a bare
+ *  object, since both have been seen across this SDK's own generated
+ *  methods. */
+function unwrapSession(result: unknown): Record<string, unknown> | undefined {
+  if (!result || typeof result !== "object") return undefined
+  const withData = (result as { data?: unknown }).data
+  if (withData && typeof withData === "object") return withData as Record<string, unknown>
+  return result as Record<string, unknown>
+}
+
+/**
+ * The real sender's user id for `sessionID`, or `undefined` when it cannot
+ * be determined — never throws, never fabricates.
+ */
+export async function resolveEndUserId(
+  client: SessionClient | undefined,
+  sessionID: string,
+): Promise<string | undefined> {
+  if (!client?.session?.get || !sessionID) return undefined
+  try {
+    const result = await client.session.get({ path: { id: sessionID } })
+    const session = unwrapSession(result)
+    const metadata = session?.["metadata"]
+    if (!metadata || typeof metadata !== "object") return undefined
+    const value = (metadata as Record<string, unknown>)[USER_ID_METADATA_KEY]
+    if (typeof value !== "string") return undefined
+    const trimmed = value.trim()
+    return LOOKS_LIKE_UUID.test(trimmed) ? trimmed : undefined
+  } catch {
+    // Best-effort only. An identity lookup must never break a chat turn.
+    return undefined
+  }
+}

package/plugin/opencode-plugin/src/index.ts

@@ -23,6 +23,16 @@ import { isElliotKnowledgeTool, parseOptions, shellVerdict } from "./policy.js"
 import { configHook } from "./proxy-provider.js"
 import { formatScope, scopeForWorktree } from "./scope.js"
 import { applyElliotIdentity } from "./identity.js"
+import { resolveEndUserId, type SessionClient } from "./identity-headers.js"
+import {
+  applyGuardrailDecision,
+  extractInstanceTeamId,
+  liveJevOutputValidationEnabled,
+  liveJevPolicyEnabled,
+  OUTPUT_VALIDATION_GUARDRAIL_NAME,
+} from "./guardrail-sync.js"
+import { stampSessionAffinity } from "./session-affinity.js"
+import { stripBlockedTurns } from "./blocked-turns.js"
 
 // Structural mirrors of the host types (packages/plugin/src/index.ts @
 // v1.18.19). Declared locally so this package type-checks and unit-tests
@@ -37,6 +47,7 @@ export interface PluginInput {
     auth?: {
       set: (input: { path: { id: string }; body: Record<string, unknown> }) => Promise<unknown>
     }
+    session?: SessionClient["session"]
     [k: string]: unknown
   }
   serverUrl?: URL
@@ -70,6 +81,43 @@ export interface Hooks {
     input: { sessionID?: string; model: unknown },
     output: { system: string[] },
   ) => Promise<void>
+  /**
+   * Runs right before the session's message history is converted to the
+   * provider's wire format (session/prompt.ts, immediately before
+   * `MessageV2.toModelMessagesEffect`) — the one hook that sees, and can
+   * edit, exactly what the MODEL is about to be shown as this conversation's
+   * history. `output.messages` is the SAME array the caller goes on to use
+   * (session/plugin/index.ts's `trigger` never reassigns it), so a hook
+   * must mutate it in place; see blocked-turns.ts's own `stripBlockedTurns`.
+   */
+  "experimental.chat.messages.transform"?: (
+    input: Record<string, never>,
+    output: { messages: Array<{ info?: Record<string, unknown>; parts?: unknown[] }> },
+  ) => Promise<void>
+  "chat.headers"?: (
+    input: { sessionID: string; agent: unknown; model: unknown; provider: unknown; message: unknown },
+    output: { headers: Record<string, string> },
+  ) => Promise<void>
+  /**
+   * Runs on every outgoing request, before it is sent — the one hook with
+   * write access to `options`, the object `eai setup`'s static `metadata.
+   * guardrails` lands in (opencode/packages/opencode/src/session/llm/
+   * request.ts: `options = mergeOptions(base, model.options, ...)` is what
+   * this hook receives as `output.options`). See guardrail-sync.ts for why
+   * this is the CLI's real session-recovery mechanism: there is no response/
+   * error hook to retry FROM, so the fix is making the one attempt correct
+   * instead.
+   */
+  "chat.params"?: (
+    input: { sessionID: string; agent: unknown; model: unknown; provider: unknown; message: unknown },
+    output: {
+      temperature?: number
+      topP?: number
+      topK?: number
+      maxOutputTokens?: number
+      options: Record<string, unknown>
+    },
+  ) => Promise<void>
   config?: (input: any) => Promise<void>
   auth?: AuthHook
   dispose?: () => Promise<void>
@@ -157,6 +205,73 @@ export const ElliotPlugin: Plugin = async (input, rawOptions) => {
       applyElliotIdentity(output.system)
     },
 
+    /**
+     * Keeps a Jev-blocked prompt from leaking into the MODEL's own view of
+     * this conversation's history on every LATER turn (see blocked-turns.ts's
+     * own module docstring for the full "why" — a benign follow-up was
+     * getting answered alongside an unprompted refusal about the earlier,
+     * never-actually-sent request). Purely a context-shaping step: the
+     * stored session history (what the UI's own transcript reads) is
+     * untouched, only what gets sent to the model next.
+     */
+    "experimental.chat.messages.transform": async (_hookInput, output) => {
+      const filtered = stripBlockedTurns(output.messages)
+      if (filtered === output.messages) return
+      output.messages.length = 0
+      output.messages.push(...filtered)
+    },
+
+    /**
+     * Per-message LiteLLM `end_user` override for a TEAM-shared runtime. See
+     * ./identity-headers.ts for the full rationale. A no-op (static header
+     * untouched) when the session carries no stamped identity — a generic
+     * instance, a pre-existing session, or a client that doesn't expose
+     * `session.get` at all.
+     */
+    "chat.headers": async (hookInput, output) => {
+      const userId = await resolveEndUserId(input.client as SessionClient | undefined, hookInput.sessionID)
+      if (userId) output.headers["x-litellm-end-user-id"] = userId
+    },
+
+    /**
+     * The CLI's Jev guardrail session-recovery fix (see guardrail-sync.ts's
+     * own module docstring for the full "why this hook, not a retry" case).
+     * A `null` live decision (no team context, or the check itself failed —
+     * offline, backend down) changes nothing: whatever `eai setup` baked
+     * into this model's static `options.metadata.guardrails` is left
+     * exactly as it was, so this can only ever make a stale CLI config
+     * MORE correct, never less available.
+     *
+     * Also stamps `metadata.session_id` (see session-affinity.ts) so
+     * LiteLLM's `session_affinity` pre-call check can pin every turn of
+     * this session to the same upstream deployment — the mechanism that
+     * keeps DeepSeek's implicit prefix cache warm across a long agent
+     * session (deploy/litellm/config.yaml, `optional_pre_call_checks`).
+     *
+     * `instanceTeamId` (see guardrail-sync.ts's own docstring on
+     * `LiveCheckDeps`) is extracted from THIS request's own `options`
+     * rather than trusted from `~/.elliot/config.json` — on a shared-
+     * filesystem local-dev backend runtime, those two can disagree (a real
+     * person's own CLI login vs. the team this Web Chat request actually
+     * belongs to), and the live check must not apply one team's setting to
+     * another's request.
+     *
+     * Jev audit (2026-10, G2): both the pre-call (`jev-policy`) AND
+     * post-call (`jev-output-validation`) toggles are now live-synced here
+     * — previously only the pre-call flag was. `liveJevPolicyEnabled`/
+     * `liveJevOutputValidationEnabled` share one cached `GET /teams/{id}`
+     * fetch under the hood (see guardrail-sync.ts), so checking both here
+     * costs at most one network round trip, not two.
+     */
+    "chat.params": async (hookInput, output) => {
+      stampSessionAffinity(output.options, hookInput.sessionID)
+      const instanceTeamId = extractInstanceTeamId(output.options)
+      const preCallDecision = await liveJevPolicyEnabled({ instanceTeamId })
+      applyGuardrailDecision(output.options, preCallDecision)
+      const outputValidationDecision = await liveJevOutputValidationEnabled({ instanceTeamId })
+      applyGuardrailDecision(output.options, outputValidationDecision, OUTPUT_VALIDATION_GUARDRAIL_NAME)
+    },
+
     "permission.ask": async (permInput, output) => {
       if (permInput.type !== "bash") return
       const command = permInput.metadata?.["command"]
@@ -168,9 +283,9 @@ export const ElliotPlugin: Plugin = async (input, rawOptions) => {
     },
 
     /**
-     * Registers the `elliot` provider (proxy baseURL) and defaults the
-     * model to it — no-op when the user isn't logged into Elliot. See
-     * `proxy-provider.ts`.
+     * Registers the `elliot` provider (LiteLLM gateway baseURL + static
+     * gateway key) and defaults the model to it — no-op when the user isn't
+     * logged into Elliot. See `proxy-provider.ts`.
      */
     config: async (c) => {
       configHook(c)

package/plugin/opencode-plugin/src/mcp-keys.ts

@@ -24,6 +24,10 @@ export function sanitizeKey(value: string): string {
 /** The backend tool behind every Elliot knowledge lookup. */
 export const KNOWLEDGE_TOOL = "knowledge_search"
 
+/** The backend tool behind "my own real EAI Gateway spend" (`/usage`, and the
+ *  sidebar's real-spend section -- see `tui/usage.ts`). */
+export const USAGE_TOOL = "get_eai_usage"
+
 /** The agent-visible key for `KNOWLEDGE_TOOL` on a given MCP server.
  *
  * Still the PRE-GATEWAY spelling, and still correct for a runtime wired

package/plugin/opencode-plugin/src/proxy-provider.ts

@@ -21,9 +21,38 @@ export const ELLIOT_PROVIDER_ID = "elliot"
 export const ELLIOT_GENERAL_MODEL_ID = "elliot-general"
 export const ELLIOT_CODER_MODEL_ID = "elliot-coder"
 
+// `limit`/`cost` are what the OpenCode TUI's own sidebar ("Context ... %
+// used ... spent") computes the context-window percentage and per-session
+// dollar cost from (opencode/packages/tui/src/feature-plugins/sidebar/
+// context.tsx) — without them it always shows "0% used"/"$0.00 spent"
+// regardless of real usage, since there is nothing to divide/multiply by.
+//
+// Neither LiteLLM nor its own cost map has this data for either model
+// (confirmed live: `GET /model/info` on the local gateway returns
+// `max_tokens`/`max_input_tokens`/`input_cost_per_token`/
+// `output_cost_per_token` as null/0 for both elliot-general and
+// elliot-coder) — both route to the same OpenRouter deployment,
+// `openrouter/deepseek/deepseek-v4-flash-0731` (deploy/litellm/
+// config.yaml), so the figures below are OpenRouter's own published model
+// data for that exact slug (`GET https://openrouter.ai/api/v1/models`,
+// confirmed live 2026-10-14: context_length 1048576, top_provider.
+// max_completion_tokens 943718, pricing.prompt $0.000000016/token,
+// pricing.completion $0.00000064/token) — not a guess, and not a figure
+// for a different/similar-sounding model. `cost` is $-per-MILLION-tokens,
+// matching this schema's own convention elsewhere (e.g. opencode/packages/
+// opencode/test/provider/transform.test.ts's real-model fixtures), so the
+// per-token prices above are multiplied by 1e6.
 const ALL_MODELS = {
-  [ELLIOT_GENERAL_MODEL_ID]: { name: "Elliot General" },
-  [ELLIOT_CODER_MODEL_ID]: { name: "Elliot Coder" },
+  [ELLIOT_GENERAL_MODEL_ID]: {
+    name: "EAI General",
+    limit: { context: 1_048_576, output: 943_718 },
+    cost: { input: 0.016, output: 0.64 },
+  },
+  [ELLIOT_CODER_MODEL_ID]: {
+    name: "EAI Coder",
+    limit: { context: 1_048_576, output: 943_718 },
+    cost: { input: 0.016, output: 0.64 },
+  },
 }
 
 /**

package/plugin/opencode-plugin/src/session-affinity.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-request LiteLLM session-affinity stamping.
+ *
+ * LiteLLM v1.101.0's `DeploymentAffinityCheck` — switched on by
+ * `optional_pre_call_checks: ["session_affinity"]` in
+ * deploy/litellm/config.yaml — pins consecutive turns of one conversation to
+ * the SAME upstream deployment, so DeepSeek's implicit prefix cache stays on
+ * the warm node. Verified in the v1.101.0 source
+ * (`deployment_affinity_check.py::_get_session_id_from_metadata_dict`): it
+ * keys on `metadata.session_id` in the REQUEST METADATA, NOT on the
+ * `x-session-affinity` / `x-opencode-session-id` HEADERS OpenCode already
+ * sends on every turn (session/llm/request.ts) — those are ignored for
+ * affinity in this version. Without this stamp, `session_affinity` in the
+ * router config would be dead config.
+ *
+ * This hook writes the id into `options.metadata.session_id` — the exact
+ * metadata channel the existing `metadata.guardrails` mechanism
+ * (guardrail-sync.ts) already proves reaches LiteLLM's request metadata end
+ * to end. Never throws, never fabricates: a missing session id or a
+ * non-object `metadata` simply leaves the request unstamped (the static,
+ * unchanged pre-existing request still goes out).
+ */
+
+/**
+ * Stamp the OpenCode session id into a request's `metadata.session_id` so
+ * LiteLLM can route every turn of the same session to the same deployment.
+ * `options` is the same merged options object `chat.params` hands the caller
+ * (`opencode/.../session/llm/request.ts`), the one `metadata.guardrails`
+ * already travels in.
+ */
+export function stampSessionAffinity(
+  options: Record<string, unknown> | null | undefined,
+  sessionID: string | undefined,
+): void {
+  if (!options || typeof options !== "object" || !sessionID) return
+  const metadata =
+    options.metadata && typeof options.metadata === "object" && !Array.isArray(options.metadata)
+      ? (options.metadata as Record<string, unknown>)
+      : (options.metadata = {} as Record<string, unknown>)
+  metadata["session_id"] = sessionID
+}