@elliotsystems/eai 0.1.4 → 0.1.7

package/lib/update.js

@@ -0,0 +1,303 @@
+"use strict"
+
+/**
+ * `eai update` — move this machine onto the current published CLI.
+ *
+ * ## Why this exists rather than "just run npm i -g"
+ *
+ * Because the user does not necessarily know how `eai` got onto their machine,
+ * and the right command differs: a global npm install, a pnpm or bun global, or
+ * a `node_modules` inside a project are four different updates, and running the
+ * wrong one either fails confusingly or installs a SECOND copy that shadows the
+ * first. Onboarding is one `npm i -g @elliotsystems/eai`, so the common case is
+ * easy; the point of this command is that the uncommon cases say what to do
+ * instead of failing.
+ *
+ * ## It updates the CLI, which brings the runtime with it
+ *
+ * `opencode-ai` is a dependency of this package, pinned to an exact version.
+ * So the OpenCode runtime a user has is decided by the EAI version they have,
+ * and npm fetches the matching runtime as part of the install. There is
+ * deliberately no separate "update OpenCode" path: the two moving
+ * independently on a user's machine is the drift this whole mechanism exists
+ * to prevent, and `check_opencode_versions.mjs` enforces the same pairing in
+ * CI.
+ *
+ * ## Nothing here hardcodes a version
+ *
+ * The published version is asked of the registry, and the installed one is read
+ * from the package. A literal in this file would be a third source of truth
+ * that goes stale on the next release and keeps looking authoritative.
+ */
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+
+const PACKAGE_NAME = "@elliotsystems/eai"
+
+/** The npm registry's own metadata endpoint for the published version. */
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
+
+/**
+ * Run a package-manager command, portably and without a deprecation warning.
+ *
+ * Windows needs a shell: npm, pnpm and bun are all `.cmd` shims there, and
+ * execFile cannot run a `.cmd` directly — it throws ENOENT, which silently
+ * made every Windows user's global install look like "not a global install".
+ *
+ * But `shell: true` TOGETHER WITH an args array triggers Node 24's DEP0190
+ * ("arguments are not escaped, only concatenated"), which printed a security
+ * warning on every `eai update` run. Passing one pre-joined command string
+ * instead does the same work without the warning, because the concatenation
+ * is then explicitly ours rather than something Node did behind our back.
+ *
+ * That is only safe because every command and argument here is a literal from
+ * the table in detectInstall. Nothing user-supplied is ever interpolated, and
+ * nothing in this file should start doing so.
+ */
+function runTool(bin, args, options) {
+  if (process.platform === "win32") {
+    return childProcess.execSync([bin, ...args].join(" "), { ...options, shell: undefined })
+  }
+  return childProcess.execFileSync(bin, args, options)
+}
+
+/**
+ * How was this copy installed?
+ *
+ * Decided from the path the package actually sits at, not from a guess: an
+ * `npm root -g` that matches means a global install, and anything else is
+ * reported rather than acted on. Updating the wrong tree is how a user ends up
+ * with two `eai` binaries and no idea which one runs.
+ */
+function detectInstall(packageRoot) {
+  const managers = [
+    { name: "npm", probe: ["npm", ["root", "-g"]], update: "npm install -g " + PACKAGE_NAME + "@latest" },
+    { name: "pnpm", probe: ["pnpm", ["root", "-g"]], update: "pnpm add -g " + PACKAGE_NAME + "@latest" },
+    { name: "bun", probe: ["bun", ["pm", "bin", "-g"]], update: "bun add -g " + PACKAGE_NAME + "@latest" },
+  ]
+  const resolved = (() => {
+    try {
+      return fs.realpathSync(packageRoot)
+    } catch {
+      return packageRoot
+    }
+  })()
+
+  for (const m of managers) {
+    let root
+    try {
+      root = runTool(m.probe[0], m.probe[1], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 15000,
+          // REQUIRED on Windows, and its absence is not a degraded probe — it is
+          // a total one. `npm`, `pnpm` and `bun` are all `.cmd` shims there, and
+          // execFileSync cannot execute a `.cmd` without a shell: it throws
+          // ENOENT, the catch below skips the manager, every manager is skipped,
+          // and `eai update` tells every Windows user their global install is
+          // "not a global install" and refuses. Windows is the platform
+          // publish-eai.yml validates on.
+          //
+        }).trim()
+    } catch {
+      continue // manager not installed; not an error, just not this one
+    }
+    if (!root) continue
+    let realRoot
+    try {
+      realRoot = fs.realpathSync(root)
+    } catch {
+      realRoot = root
+    }
+    if (resolved.startsWith(realRoot + path.sep) || resolved.startsWith(root + path.sep)) {
+      return { kind: "global", manager: m.name, command: m.update }
+    }
+  }
+  return { kind: "unknown", manager: null, command: null }
+}
+
+/**
+ * The published version, or null.
+ *
+ * Deliberately quiet on failure. An offline machine, a proxy or a registry
+ * blip must not turn `eai update` into an error — and must REALLY not turn a
+ * background check (see maybeNotify) into one.
+ */
+async function latestPublished(timeoutMs = 5000) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(REGISTRY_URL, {
+      signal: controller.signal,
+      // `application/vnd.npm.install-v1+json` returns an abbreviated document.
+      // Smaller and, more to the point, it is the contract npm itself uses, so
+      // it is the least likely shape to change under us.
+      headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
+    })
+    if (!response.ok) return null
+    const body = await response.json()
+    return typeof body?.version === "string" ? body.version : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function compareSemver(a, b) {
+  const parse = (v) => String(v).split("-")[0].split(".").map((n) => Number(n) || 0)
+  const [x, y] = [parse(a), parse(b)]
+  return x[0] - y[0] || x[1] - y[1] || x[2] - y[2]
+}
+
+/** `eai update`. */
+async function runUpdate({ packageRoot, version, argv = [] } = {}) {
+  const check = argv.includes("--check")
+  const latest = await latestPublished()
+
+  if (!latest) {
+    process.stderr.write(
+      "eai update: could not reach the npm registry.\n" +
+        "Nothing was changed. Check your connection or proxy and try again.\n",
+    )
+    return 1
+  }
+
+  process.stdout.write(`installed: ${version}\npublished: ${latest}\n`)
+
+  if (compareSemver(latest, version) <= 0) {
+    process.stdout.write("\nAlready up to date.\n")
+    return 0
+  }
+
+  const install = detectInstall(packageRoot)
+  if (check) {
+    process.stdout.write(`\nUpdate available. Run: ${install.command || "eai update"}\n`)
+    return 0
+  }
+
+  if (install.kind !== "global") {
+    // Not a failure — a refusal to guess. Installing globally over a local
+    // checkout or a project dependency would leave two copies and no signal
+    // about which one the shell resolves.
+    process.stderr.write(
+      `\neai update: this copy of ${PACKAGE_NAME} is not a global install.\n` +
+        `It is at: ${packageRoot}\n` +
+        "Update it the way it was installed — or install globally with:\n" +
+        `  npm install -g ${PACKAGE_NAME}@latest\n`,
+    )
+    return 1
+  }
+
+  process.stdout.write(`\nUpdating via ${install.manager}: ${install.command}\n\n`)
+  // One command string, not (bin, args) — see runTool above for why the args
+  // form prints a DEP0190 security warning on every Windows run.
+  const result = process.platform === "win32"
+    ? childProcess.spawnSync(install.command, { stdio: "inherit", shell: true })
+    : childProcess.spawnSync(install.command.split(" ")[0], install.command.split(" ").slice(1), { stdio: "inherit" })
+  if (result.status !== 0) {
+    process.stderr.write(
+      `\neai update: ${install.manager} exited ${result.status}.\n` +
+        "On a permissions error, either re-run with the privileges that install needs,\n" +
+        "or point npm at a user-writable prefix (`npm config set prefix`).\n",
+    )
+    return result.status || 1
+  }
+  process.stdout.write(`\nUpdated to ${latest}. Run \`eai --version\` to confirm.\n`)
+  return 0
+}
+
+// ── update notification ────────────────────────────────────────────────────
+//
+// A CLI that silently goes stale is a CLI whose users report bugs that were
+// fixed months ago. But a version check on the hot path is worse than the
+// problem: it adds latency to every launch, it fails on an offline machine,
+// and a nag on every single run gets ignored and then resented.
+//
+// So the notice is: throttled to once a day, written to STDERR so it can never
+// corrupt piped output, never blocking (the check runs against a cached answer
+// from a PREVIOUS run, never a live request on this one), and switchable off.
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+function stateFile() {
+  return path.join(os.homedir(), ".elliot", "update-check.json")
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile(), "utf8")) || {}
+  } catch {
+    return {}
+  }
+}
+
+function writeState(state) {
+  try {
+    fs.mkdirSync(path.dirname(stateFile()), { recursive: true })
+    fs.writeFileSync(stateFile(), JSON.stringify(state))
+  } catch {
+    // A read-only or full home directory must not break the CLI over a
+    // convenience feature. Losing the throttle means re-checking tomorrow.
+  }
+}
+
+function notificationsDisabled(env) {
+  // Two switches on purpose. ELLIOT_NO_UPDATE_CHECK is ours and explicit;
+  // CI is honoured because a version nag in build logs is pure noise and
+  // nobody sets a flag they do not know exists.
+  return Boolean(env.ELLIOT_NO_UPDATE_CHECK || env.CI || env.NO_UPDATE_NOTIFIER)
+}
+
+/**
+ * Print a notice if a newer version was seen EARLIER, then refresh the cache in
+ * the background.
+ *
+ * The ordering is the whole design. This run reports what the last run already
+ * learned, so the common path does no network I/O at all and costs a file read.
+ * The refresh is detached and unref'd, so the process exits without waiting on
+ * it, and a hung registry delays nothing.
+ */
+function maybeNotify({ version, env = process.env, now = Date.now() } = {}) {
+  if (notificationsDisabled(env)) return
+  const state = readState()
+
+  if (state.latest && compareSemver(state.latest, version) > 0) {
+    process.stderr.write(
+      `\nA newer Elliot CLI is available: ${version} → ${state.latest}\n` +
+        "Run `eai update` to upgrade. (`ELLIOT_NO_UPDATE_CHECK=1` silences this.)\n\n",
+    )
+  }
+
+  if (now - (state.checkedAt || 0) < CHECK_INTERVAL_MS) return
+  // Stamp BEFORE spawning. If the check fails or the machine is offline, the
+  // throttle still holds and we do not spawn a doomed probe on every run.
+  writeState({ ...state, checkedAt: now })
+  try {
+    const child = childProcess.spawn(
+      process.execPath,
+      [path.join(__dirname, "update-check.js")],
+      { detached: true, stdio: "ignore", env },
+    )
+    child.unref()
+  } catch {
+    // Best effort, always.
+  }
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  runUpdate,
+  latestPublished,
+  compareSemver,
+  detectInstall,
+  maybeNotify,
+  notificationsDisabled,
+  stateFile,
+  readState,
+  writeState,
+  CHECK_INTERVAL_MS,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliotsystems/eai",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Elliot AI CLI entry point (eai) - launches the Elliot runtime with arguments forwarded verbatim.",
   "bin": {
     "eai": "./bin/eai"
@@ -13,6 +13,7 @@
     "README.md"
   ],
   "scripts": {
+    "pretest": "node scripts/bundle.js",
     "test": "node --test test/*.test.js",
     "publish:npm": "node scripts/publish.js",
     "bundle": "node scripts/bundle.js",
@@ -26,6 +27,6 @@
     "access": "public"
   },
   "dependencies": {
-    "opencode-ai": "1.18.30"
+    "opencode-ai": "1.19.0"
   }
 }

package/plugin/opencode-plugin/package.json

@@ -24,7 +24,7 @@
     "node": ">=18"
   },
   "elliot": {
-    "opencodeRange": ">=1.18.19 <1.19.0"
+    "opencodeRange": ">=1.18.19 <1.20.0"
   },
   "oc-themes": [
     "themes/elliot.json"

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

@@ -1,7 +1,8 @@
 /**
  * Shell-command classification — the policy intelligence glob patterns cannot express.
  *
- * Ported (adapted, not copied wholesale) from `elliot-cli/src/tools/bash-policy.ts`,
+ * Ported (adapted, not copied wholesale) from the retired elliot-ai CLI's
+ * `src/tools/bash-policy.ts`,
  * which is pure and dependency-free. Three things here are beyond what OpenCode's
  * native `permission.bash` globs can represent, which is exactly why this file exists:
  *

package/plugin/opencode-plugin/src/elliot-auth.ts

@@ -1,27 +1,70 @@
 /**
- * Elliot token read + refresh — the credential half of the proxy provider.
+ * Reads `~/.elliot/config.json` — written by `eai setup`/`elliot-ai setup`.
  *
- * Ported (trimmed, not imported) from `elliot-cli/src/auth/refresh.ts` and
- * `elliot-cli/src/config.ts`: same `~/.elliot/config.json` shape, same
- * refresh endpoint contract (`POST {backend_url}/auth/refresh` ->
- * `{access_token, expires_in_seconds}`), same "never throw" discipline. This
- * file exists inside `opencode-plugin` rather than importing the CLI package
- * because the plugin ships and is loaded independently of `elliot-cli` — see
- * `docs/superpowers/plans/2026-09-03-eai-proxy-auth.md`.
+ * Used two ways: `readElliotConfig() !== null` is "is the user logged in at
+ * all" (the proxy-provider config hook is a no-op otherwise); and its
+ * `litellm_base_url`/`litellm_master_key` fields are the LLM provider's
+ * connection info directly.
  *
- * `freshToken` is the only export the proxy provider's `auth.loader`/`fetch`
- * needs: it never throws, so a stale/missing/corrupt config degrades to "no
- * token" (the proxy 401s) rather than crashing OpenCode's model call.
+ * Formerly also home to `freshToken`/`isExpired` — a self-refreshing JWT
+ * mechanism for the per-instance credential `/llm-proxy` used to validate.
+ * Removed along with `/llm-proxy`: the LiteLLM gateway this now points at
+ * authenticates with ONE static, shared `litellm_master_key` (LiteLLM is
+ * deliberately DB-less — no per-tenant/per-instance credential is possible
+ * without one), which never expires and so never needs refreshing.
  */
 import * as fs from "node:fs"
 import * as os from "node:os"
 import * as path from "node:path"
 
+/**
+ * One LiteLLM credential this person can use from OpenCode — their own
+ * personal key, or a team's shared key (Phase 4, docs/LITELLM_GATEWAY.md
+ * §14 / PRD PO-4/4.3/4.4). `provider_id` is the OpenCode provider id
+ * `configHook` registers it under directly (e.g. `elliot` for the personal
+ * default, `elliot-team-<slug>` per team) — computed backend-side
+ * (`onboarding.py`), not derived here, so naming stays in one place.
+ */
+export interface ElliotCredential {
+  provider_id: string
+  /** Shown in OpenCode's own model picker, e.g. "Elliot (Personal)" or
+   *  "Elliot — Team Platform". */
+  label: string
+  api_key: string
+  /** Present for a team credential, absent for the personal one. */
+  team_id?: string
+  /**
+   * This credential's own team's Phase 4 model restriction
+   * (docs/LITELLM_GATEWAY.md §14), or absent/null for unrestricted — always
+   * absent on the personal credential, which has no team and so no
+   * restriction concept. LiteLLM gateway audit finding #5: each provider
+   * `configHook` registers must be filtered by ITS OWN credential's
+   * restriction, not a shared list — a user on both a restricted and an
+   * unrestricted team must not have one leak into the other.
+   */
+  allowed_models?: string[] | null
+}
+
 export interface ElliotConfig {
   jwt_token?: string
-  refresh_token?: string
   backend_url?: string
-  access_token_expires_at?: string
+  litellm_base_url?: string
+  litellm_master_key?: string
+  /**
+   * Every credential this person can use, personal key first (Phase 4).
+   * Absent on a config written by an older `eai setup` (or a backend that
+   * predates this field) — `configHook` falls back to the single
+   * `litellm_master_key` provider in that case, so an old config keeps
+   * working unchanged rather than losing LLM access outright.
+   */
+  credentials?: ElliotCredential[]
+  /**
+   * The single scoped team's own Phase 4 model restriction, when
+   * `credentials` is absent and the legacy `litellm_master_key` fallback
+   * provider is registered instead — same field, same meaning as
+   * `ElliotCredential.allowed_models`, just for the one-provider path.
+   */
+  allowed_models?: string[] | null
   [k: string]: unknown
 }
 
@@ -40,94 +83,3 @@ export function readElliotConfig(): ElliotConfig | null {
     return null
   }
 }
-
-/**
- * Persist the config, owner-only (0600) — this file holds a live bearer
- * token. Creates `~/.elliot` (0700) if it doesn't exist yet.
- */
-export function writeElliotConfig(cfg: ElliotConfig): void {
-  const configPath = elliotConfigPath()
-  const configDir = path.dirname(configPath)
-  if (!fs.existsSync(configDir)) {
-    fs.mkdirSync(configDir, { recursive: true, mode: 0o700 })
-  }
-  fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2), { mode: 0o600 })
-  fs.chmodSync(configPath, 0o600)
-}
-
-/** `exp` (seconds since epoch) from a JWT's middle segment, or null. */
-function decodeJwtExp(token: string): number | null {
-  try {
-    const parts = token.split(".")
-    if (parts.length < 2) return null
-    const payload = JSON.parse(Buffer.from(parts[1], "base64").toString("utf-8"))
-    return typeof payload?.exp === "number" ? payload.exp : null
-  } catch {
-    return null
-  }
-}
-
-const REFRESH_SKEW_MS = 60_000
-
-/**
- * True if the access token is expired or within `REFRESH_SKEW_MS` of
- * expiring. Prefers the stored `access_token_expires_at`; falls back to
- * decoding `jwt_token`'s `exp` claim; true (treat as expired -> refresh) when
- * neither is decodable.
- */
-export function isExpired(cfg: ElliotConfig, nowMs = Date.now()): boolean {
-  if (cfg.access_token_expires_at) {
-    const expiresAtMs = new Date(cfg.access_token_expires_at).getTime()
-    if (Number.isFinite(expiresAtMs)) {
-      return expiresAtMs - REFRESH_SKEW_MS <= nowMs
-    }
-  }
-  const exp = cfg.jwt_token ? decodeJwtExp(cfg.jwt_token) : null
-  if (exp === null) return true
-  return exp * 1000 - REFRESH_SKEW_MS <= nowMs
-}
-
-interface RefreshResponse {
-  access_token: string
-  expires_in_seconds: number
-}
-
-interface FreshTokenDeps {
-  fetchImpl?: typeof fetch
-  write?: (cfg: ElliotConfig) => void
-}
-
-/**
- * A valid access token, refreshing + persisting when expired and a
- * `refresh_token`/`backend_url` are present. NEVER throws: any failure
- * (network, non-2xx, malformed response) falls back to the existing
- * `jwt_token` — the proxy 401s on a stale token rather than this crashing the
- * model call.
- */
-export async function freshToken(
-  cfg: ElliotConfig,
-  deps?: FreshTokenDeps,
-): Promise<string | null> {
-  try {
-    if (cfg.jwt_token && !isExpired(cfg)) return cfg.jwt_token
-    if (!cfg.refresh_token || !cfg.backend_url) return cfg.jwt_token ?? null
-
-    const fetchImpl = deps?.fetchImpl ?? fetch
-    const write = deps?.write ?? writeElliotConfig
-
-    const response = await fetchImpl(`${cfg.backend_url}/auth/refresh`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refresh_token: cfg.refresh_token }),
-    })
-    if (!response.ok) return cfg.jwt_token ?? null
-
-    const data = (await response.json()) as RefreshResponse
-    cfg.jwt_token = data.access_token
-    cfg.access_token_expires_at = new Date(Date.now() + data.expires_in_seconds * 1000).toISOString()
-    write(cfg)
-    return data.access_token
-  } catch {
-    return cfg.jwt_token ?? null
-  }
-}

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
+  }
+}