@elliotsystems/eai 0.1.7 → 0.1.14

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

@@ -0,0 +1,370 @@
+/**
+ * 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
+  /** Fast Jev Compaction pilot (spec: `specs/2026-10-29-fast-jev-
+   *  compaction-pilot.md`, task T7) -- `Team.eai_compaction_enabled`, read
+   *  from this SAME `GET /teams/{id}` response, never a second round trip. */
+  compactionEnabled: 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.
+ *
+ * Fast Jev Compaction pilot (T7): also reads `eai_compaction_enabled` from
+ * this same response/cache entry -- one more field off a call this module
+ * already makes, not a second network round trip.
+ */
+async function liveJevGuardrailFlags(
+  deps: LiveCheckDeps = {},
+): Promise<{ jevPolicyEnabled: boolean; jevOutputValidationEnabled: boolean; compactionEnabled: 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,
+      compactionEnabled: cache.compactionEnabled,
+    }
+  }
+
+  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)
+    const compactionEnabled = Boolean(record.eai_compaction_enabled)
+    cache = {
+      jevPolicyEnabled,
+      jevOutputValidationEnabled,
+      compactionEnabled,
+      teamId: config.team_id,
+      expiresAt: now() + CACHE_TTL_MS,
+    }
+    return { jevPolicyEnabled, jevOutputValidationEnabled, compactionEnabled }
+  } 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,
+          compactionEnabled: cache.compactionEnabled,
+        }
+      : 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
+}
+
+/**
+ * Fast Jev Compaction pilot (spec: `specs/2026-10-29-fast-jev-compaction-
+ * pilot.md`, task T7) — the team's current `Team.eai_compaction_enabled`,
+ * live from the backend, with the exact same `null`-means-"leave it alone"
+ * contract as `liveJevPolicyEnabled`/`liveJevOutputValidationEnabled`.
+ * Shares the same cached `GET /teams/{id}` call under the hood, so calling
+ * this alongside either (or both) of the other two costs at most one
+ * network round trip, not two or three.
+ *
+ * Callers (index.ts's `experimental.chat.messages.transform` hook) must
+ * treat `null` and `false` identically here: skip compaction and leave
+ * `output.messages` exactly as `stripBlockedTurns` left them. Unlike the
+ * Jev guardrails, there is no security-load-bearing reason to fail closed
+ * on uncertainty -- this flag only decides whether a token-reduction pass
+ * runs at all, so "do nothing" is always the safe default when the answer
+ * is not confidently known.
+ */
+export async function liveCompactionEnabled(deps: LiveCheckDeps = {}): Promise<boolean | null> {
+  const flags = await liveJevGuardrailFlags(deps)
+  return flags ? flags.compactionEnabled : 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
+  }
+}