@elliotsystems/eai 0.1.7 → 0.1.14

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

@@ -24,6 +24,25 @@ 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,
+  liveCompactionEnabled,
+  liveJevOutputValidationEnabled,
+  liveJevPolicyEnabled,
+  OUTPUT_VALIDATION_GUARDRAIL_NAME,
+} from "./guardrail-sync.js"
+import { stampSessionAffinity, type CompactionTelemetry } from "./session-affinity.js"
+import { stripBlockedTurns } from "./blocked-turns.js"
+import { readElliotConfig } from "./elliot-auth.js"
+import {
+  compactMessages,
+  type AskerAnswer,
+  type AskerContext,
+  type CompactionMessage,
+  type ContentBlock,
+  type MessageRole,
+} from "./compaction.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
@@ -72,10 +91,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>
@@ -83,6 +135,256 @@ export interface Hooks {
 
 export type Plugin = (input: PluginInput, options?: Record<string, unknown>) => Promise<Hooks>
 
+// ---------------------------------------------------- compaction adapter --
+//
+// Fast Jev Compaction pilot (spec: `specs/2026-10-29-fast-jev-compaction-
+// pilot.md`, task T7). `compaction.ts` (T6) is deliberately transport- and
+// host-shape-agnostic: it only knows its own `CompactionMessage`/
+// `ContentBlock` shape. Everything below adapts OpenCode's native history
+// entry shape (`{ info, parts }`, the same one `blocked-turns.ts` reads) to
+// and from that shape, and supplies the `asker` that calls the T3 backend
+// proxy. None of this runs unless `liveCompactionEnabled` resolves `true`,
+// and the whole attempt is wrapped in a single try/catch in the hook below
+// so a bad response, a network failure, or a bug in this adapter can never
+// break or delay a chat turn -- it only ever falls back to whatever
+// `stripBlockedTurns` already produced.
+
+/** Per-request timeout for one `keepCall`/`keepResult` judge call. Several
+ *  of these may run per turn (one per candidate tool round trip); kept
+ *  short so a hung backend cannot meaningfully delay a chat turn even
+ *  before the outer try/catch gives up on compaction entirely. */
+const COMPACTION_ASKER_TIMEOUT_MS = 5_000
+
+interface NativeToolPartState {
+  status?: unknown
+  input?: unknown
+  output?: unknown
+  error?: unknown
+  [k: string]: unknown
+}
+
+interface NativeToolPart {
+  type: "tool"
+  tool?: unknown
+  callID?: unknown
+  state?: NativeToolPartState
+  [k: string]: unknown
+}
+
+type NativePart = { type?: unknown; text?: unknown } & Record<string, unknown>
+
+interface NativeMessage {
+  info?: Record<string, unknown>
+  parts?: unknown[]
+}
+
+function nativeMessageRole(info: Record<string, unknown> | undefined): MessageRole {
+  if (info?.["role"] === "assistant") return "assistant"
+  if (info?.["role"] === "system") return "system"
+  return "user"
+}
+
+interface CompactionAdapterState {
+  readonly compactionMessages: CompactionMessage[]
+  /** Original native tool part per `callID`, used on the way back to
+   *  restore everything compaction never needed to know about (metadata,
+   *  attachments, timing) rather than rebuilding it from scratch. */
+  readonly toolPartsByCallId: Map<string, NativeToolPart>
+  /** Parts compaction has no vocabulary for (reasoning, step-start, etc.),
+   *  keyed by the message's own `info` object reference -- `compaction.ts`
+   *  carries `info` through unchanged on every surviving `CompactionMessage`
+   *  (see its own module docstring), so looking it back up by identity is
+   *  reliable regardless of what compaction dropped or kept. */
+  readonly passthroughPartsByInfo: Map<object, unknown[]>
+}
+
+/** Converts OpenCode's native `{ info, parts }` history entries into T6's
+ *  `CompactionMessage` shape. A native "tool" part (OpenCode pairs the call
+ *  and its result into ONE part, unlike Claude-style `tool_use`/
+ *  `tool_result` content blocks) becomes a `tool_use` block immediately
+ *  followed, in the SAME message, by a `tool_result` block once the call has
+ *  actually completed or errored -- `compaction.ts`'s pairing logic matches
+ *  blocks by id regardless of which message(s) they live in, so this is a
+ *  faithful, simpler-than-splitting-messages encoding. */
+function toCompactionMessages(nativeMessages: readonly NativeMessage[]): CompactionAdapterState {
+  const compactionMessages: CompactionMessage[] = []
+  const toolPartsByCallId = new Map<string, NativeToolPart>()
+  const passthroughPartsByInfo = new Map<object, unknown[]>()
+
+  for (const native of nativeMessages) {
+    const info = native.info
+    const role = nativeMessageRole(info)
+    const blocks: ContentBlock[] = []
+    const passthrough: unknown[] = []
+
+    for (const rawPart of native.parts ?? []) {
+      const part = rawPart as NativePart
+      if (part.type === "text" && typeof part.text === "string") {
+        blocks.push({ type: "text", text: part.text })
+        continue
+      }
+      if (part.type === "tool" && typeof part.callID === "string") {
+        const toolPart = part as NativeToolPart
+        const callId = part.callID
+        toolPartsByCallId.set(callId, toolPart)
+        blocks.push({
+          type: "tool_use",
+          id: callId,
+          name: typeof toolPart.tool === "string" ? toolPart.tool : "unknown",
+          input: toolPart.state?.input,
+        })
+        const status = toolPart.state?.status
+        if (status === "completed" || status === "error") {
+          const output = toolPart.state?.output
+          const errorValue = toolPart.state?.error
+          const content =
+            typeof output === "string"
+              ? output
+              : typeof errorValue === "string"
+                ? errorValue
+                : JSON.stringify(output ?? errorValue ?? "")
+          blocks.push({ type: "tool_result", tool_use_id: callId, content })
+        }
+        continue
+      }
+      passthrough.push(rawPart)
+    }
+
+    if (passthrough.length > 0 && info) passthroughPartsByInfo.set(info, passthrough)
+    compactionMessages.push({ role, content: blocks, info: info as CompactionMessage["info"] })
+  }
+
+  return { compactionMessages, toolPartsByCallId, passthroughPartsByInfo }
+}
+
+/** Reverses `toCompactionMessages`, rebuilding native `{ info, parts }`
+ *  entries from T6's output. A kept pair's native tool part is reused
+ *  verbatim (preserving fields compaction never touched); a truncated
+ *  pair's part is cloned with only `state.output` replaced by the short
+ *  "omitted" note `compaction.ts` already produced; a dropped pair simply
+ *  never gets a part emitted. */
+function fromCompactionMessages(
+  compactionMessages: readonly CompactionMessage[],
+  toolPartsByCallId: ReadonlyMap<string, NativeToolPart>,
+  passthroughPartsByInfo: ReadonlyMap<object, unknown[]>,
+): NativeMessage[] {
+  return compactionMessages.map((message) => {
+    const parts: unknown[] = []
+
+    if (typeof message.content === "string") {
+      if (message.content) parts.push({ type: "text", text: message.content })
+    } else {
+      for (const block of message.content) {
+        if (block.type === "text") {
+          parts.push({ type: "text", text: block.text })
+          continue
+        }
+        if (block.type === "tool_use") {
+          const original = toolPartsByCallId.get(block.id)
+          if (original) {
+            parts.push({
+              ...original,
+              state: original.state ? { ...original.state, input: block.input } : original.state,
+            })
+          }
+          continue
+        }
+        if (block.type === "tool_result") {
+          // Merge into the tool part this same loop just pushed for the
+          // matching `tool_use` -- `compaction.ts` always keeps a call's
+          // block immediately before its result's within one message (see
+          // `toCompactionMessages`), so it is always the last entry here.
+          const lastIndex = parts.length - 1
+          const last = parts[lastIndex] as NativeToolPart | undefined
+          if (last && last.type === "tool" && last.callID === block.tool_use_id) {
+            parts[lastIndex] = { ...last, state: { ...last.state, output: block.content } }
+          }
+          continue
+        }
+      }
+    }
+
+    const passthrough = message.info ? passthroughPartsByInfo.get(message.info) : undefined
+    if (passthrough) parts.push(...passthrough)
+
+    return { info: message.info as Record<string, unknown> | undefined, parts }
+  })
+}
+
+/**
+ * The T3 proxy's own request/response contract, independent of whatever
+ * OpenRouter's Decisions API itself returns -- T3 treats both `state` and
+ * `questions` as opaque and passes `body` straight through, so this plugin
+ * (the only side that understands the payload) defines the convention: one
+ * question per `asker` call, answered as `{ answers: [{ keepCall,
+ * keepResult }] }`. Any other shape is treated as "could not get an answer"
+ * and throws, which the outer try/catch in the hook below turns into
+ * "skip compaction entirely for this turn" -- never a partial, wrongly-
+ * judged compaction.
+ */
+function parseDecisionAnswer(body: unknown): AskerAnswer {
+  const record = body && typeof body === "object" ? (body as Record<string, unknown>) : null
+  const answers = record && Array.isArray(record["answers"]) ? record["answers"] : null
+  const first = answers && answers.length > 0 ? answers[0] : null
+  const firstRecord = first && typeof first === "object" ? (first as Record<string, unknown>) : null
+  const keepCall = firstRecord ? Number(firstRecord["keepCall"]) : NaN
+  const keepResult = firstRecord ? Number(firstRecord["keepResult"]) : NaN
+  if (!Number.isFinite(keepCall) || !Number.isFinite(keepResult)) {
+    throw new Error("compaction decisions response did not contain a usable answer")
+  }
+  return { keepCall, keepResult }
+}
+
+/** Builds the `Asker` the T7 wiring passes to `compactMessages`: one POST to
+ *  the T3 endpoint (`POST /opencode/teams/{team_id}/compaction/decisions`)
+ *  per candidate tool round trip, reusing the exact fetch/auth pattern
+ *  `guardrail-sync.ts` already uses for its own backend call (bearer JWT,
+ *  `~/.elliot/config.json`'s `backend_url`/`team_id`, an `AbortController`-
+ *  based timeout). Throws on ANY failure -- offline, non-2xx, `available:
+ *  false`, or an unparseable body -- by design: the caller (the hook below)
+ *  wraps the whole compaction attempt in one try/catch, so a single bad
+ *  answer here safely aborts compaction for this turn rather than risking a
+ *  wrongly-judged partial result. */
+function makeCompactionAsker(config: {
+  backendUrl: string
+  teamId: string
+  jwtToken: string
+  fetchImpl?: typeof fetch
+}): (context: AskerContext) => Promise<AskerAnswer> {
+  const fetchImpl = config.fetchImpl ?? fetch
+  const base = config.backendUrl.replace(/\/+$/, "")
+
+  return async (context: AskerContext): Promise<AskerAnswer> => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), COMPACTION_ASKER_TIMEOUT_MS)
+    try {
+      const res = await fetchImpl(`${base}/opencode/teams/${encodeURIComponent(config.teamId)}/compaction/decisions`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${config.jwtToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          state: context.state,
+          questions: [
+            { id: context.id, toolName: context.toolName, input: context.input, resultSummary: context.resultSummary },
+          ],
+        }),
+        signal: controller.signal,
+      })
+      if (!res.ok) throw new Error(`backend returned ${res.status}`)
+      const payload: unknown = await res.json()
+      const record = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {}
+      if (record["available"] !== true) {
+        throw new Error(typeof record["reason"] === "string" ? record["reason"] : "compaction decisions unavailable")
+      }
+      return parseDecisionAnswer(record["body"])
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}
+
 export const ElliotPlugin: Plugin = async (input, rawOptions) => {
   // Fail loudly at load on bad options — a plugin that limps with a typo'd
   // config is worse than one that says why it refused to start.
@@ -92,6 +394,47 @@ export const ElliotPlugin: Plugin = async (input, rawOptions) => {
   // the one source the model cannot influence.
   const worktree = input.worktree || input.directory
 
+  // Fast Jev Compaction pilot (spec: `specs/2026-10-29-fast-jev-compaction-
+  // pilot.md`, task T9). `experimental.chat.messages.transform` is triggered
+  // with an EMPTY `hookInput` (session/prompt.ts), so the compaction outcome
+  // it produces can't be correlated to a session id from inside that hook.
+  // `chat.params` -- which DOES get `hookInput.sessionID` and already stamps
+  // `metadata.session_id` via `stampSessionAffinity` -- fires immediately
+  // after, for the SAME turn (session/llm/request.ts builds `chat.params`
+  // from the same `msgs` the transform hook just finished mutating).
+  //
+  // A FIFO QUEUE, not a single mutable slot (code-review finding, post-T9):
+  // this plugin instance is a process-wide singleton, and both hooks are
+  // `async` -- if two sessions' turns are ever in flight concurrently (very
+  // plausible once a turn's compaction attempt awaits a live-flag check plus
+  // one network round trip per stale tool-call candidate), a single shared
+  // slot lets a slower session A's `transform` overwrite what a faster
+  // session B's `transform` just set, before B's own `chat.params` reads it
+  // -- silently mislabeling B's `LiteLLM_SpendLogs` row with A's telemetry
+  // (or vice versa), which directly undermines the before/after cost
+  // comparison T9 exists for. A FIFO queue fixes this without needing a
+  // session id in the transform hook at all: each session's own
+  // `transform`-then-`params` pair is internally ordered (params always
+  // fires after that same turn's transform), so across interleaved
+  // sessions the order in which `transform` calls finish and push still
+  // matches the order in which the corresponding `chat.params` calls fire
+  // and shift -- unlike a single slot, this doesn't require the two calls
+  // to be adjacent in time, only in queue order.
+  const pendingCompactionTelemetryQueue: CompactionTelemetry[] = []
+
+  // Wall-clock budget for the ENTIRE compaction attempt (code-review
+  // finding, post-T7): `compactMessages` awaits one `asker` call per
+  // non-pinned tool-call candidate, sequentially, each already bounded by
+  // `COMPACTION_ASKER_TIMEOUT_MS` -- but nothing previously bounded the
+  // SUM across many candidates. A turn with N stale candidates could add up
+  // to N * COMPACTION_ASKER_TIMEOUT_MS of latency before the outer
+  // try/catch below ever got a chance to fail open (that catch only fires
+  // on a thrown error, not on cumulative slowness), undercutting "this
+  // feature must never be able to break or delay a chat turn." This budget
+  // is enforced by racing the whole `compactMessages` call against a timer
+  // below, not by changing `compactMessages` itself.
+  const COMPACTION_TURN_BUDGET_MS = 15_000
+
   return {
     /**
      * One handler, two jobs — a JS object literal may carry only one
@@ -163,6 +506,94 @@ 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) {
+        output.messages.length = 0
+        output.messages.push(...filtered)
+      }
+
+      // Fast Jev Compaction pilot (spec: `specs/2026-10-29-fast-jev-
+      // compaction-pilot.md`, task T7). Runs strictly AFTER `stripBlockedTurns`
+      // above -- compaction must never see a message that was already known
+      // to be a blocked turn `stripBlockedTurns` would otherwise have
+      // removed. Opt-in (`liveCompactionEnabled`) and entirely fail-open: a
+      // `null`/`false` decision, or ANY error/timeout from the live check,
+      // the adapter, or the backend call the `asker` makes, leaves
+      // `output.messages` exactly as `stripBlockedTurns` left them above --
+      // this feature must never be able to break or delay a chat turn,
+      // mirroring guardrail-sync.ts's own fail-open posture (see its module
+      // docstring) rather than the Jev guardrails' own fail-closed one,
+      // since this flag only decides whether a token-reduction pass runs at
+      // all, not a security boundary.
+      // This turn's own outcome, pushed onto the FIFO queue (see its
+      // declaration above) exactly once below -- every path (flag off,
+      // missing config, success, timeout, or the catch's fail-open) pushes
+      // before returning, so `chat.params` always has exactly one entry per
+      // turn to shift, in the same relative order these pushes happened.
+      let telemetry: CompactionTelemetry = { applied: false }
+      try {
+        const compactionDecision = await liveCompactionEnabled()
+        if (compactionDecision !== true) return
+
+        const config = readElliotConfig()
+        if (!config?.backend_url || !config.team_id || !config.jwt_token) return
+
+        const { compactionMessages, toolPartsByCallId, passthroughPartsByInfo } = toCompactionMessages(
+          output.messages as unknown as NativeMessage[],
+        )
+
+        const asker = makeCompactionAsker({
+          backendUrl: config.backend_url,
+          teamId: config.team_id,
+          jwtToken: config.jwt_token,
+        })
+
+        // Raced against COMPACTION_TURN_BUDGET_MS (see its declaration
+        // above) -- a turn with many stale candidates can't accumulate
+        // unbounded latency across sequential asker calls. A timeout here
+        // throws into the same catch below as any other failure, so the
+        // fail-open behavior is identical either way.
+        const result = await Promise.race([
+          compactMessages(compactionMessages, { asker }),
+          new Promise<never>((_resolve, reject) => {
+            setTimeout(() => reject(new Error("compaction turn budget exceeded")), COMPACTION_TURN_BUDGET_MS)
+          }),
+        ])
+        const rebuilt = fromCompactionMessages(result.messages, toolPartsByCallId, passthroughPartsByInfo)
+
+        output.messages.length = 0
+        output.messages.push(...(rebuilt as typeof output.messages))
+
+        // T9 telemetry: surface T6's own already-computed stats verbatim --
+        // no new computation -- for `chat.params` to stamp into
+        // `metadata.compaction_applied`/`compaction_state_tokens`/
+        // `compaction_reduction_ratio` via `stampSessionAffinity`.
+        telemetry = {
+          applied: true,
+          stateTokens: result.stats.stateTokens,
+          reductionRatio: result.stats.reductionRatio,
+        }
+      } catch {
+        // Any failure anywhere in the attempt above (live-flag check,
+        // adapter, the asker's HTTP call, compactMessages itself, or the
+        // turn-budget timeout) -- do nothing. `output.messages` already
+        // reflects whatever `stripBlockedTurns` produced; leave it exactly
+        // as is. `telemetry` stays `{ applied: false }` (T9).
+      } finally {
+        pendingCompactionTelemetryQueue.push(telemetry)
+      }
+    },
+
     /**
      * Per-message LiteLLM `end_user` override for a TEAM-shared runtime. See
      * ./identity-headers.ts for the full rationale. A no-op (static header
@@ -175,6 +606,51 @@ export const ElliotPlugin: Plugin = async (input, rawOptions) => {
       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) => {
+      // T9: shift this turn's entry off the FIFO queue `experimental.chat.
+      // messages.transform` pushed for it (see the queue's declaration
+      // above). `shift()` on an empty queue (a turn that skipped the
+      // transform hook entirely) yields `undefined`, defaulted below --
+      // never a stale value from a different turn.
+      const compactionTelemetry = pendingCompactionTelemetryQueue.shift() ?? { applied: false }
+      stampSessionAffinity(output.options, hookInput.sessionID, compactionTelemetry)
+      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"]

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

@@ -0,0 +1,73 @@
+/**
+ * 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).
+ */
+
+/**
+ * Fast Jev Compaction pilot (spec: `specs/2026-10-29-fast-jev-compaction-
+ * pilot.md`, task T9) telemetry handed to `stampSessionAffinity` alongside
+ * the session id, so a before/after cost comparison can later be built
+ * purely from `LiteLLM_SpendLogs` metadata filtered by `session_id` and
+ * `compaction_applied` (see `litellm_spend.py`'s existing per-request
+ * `prompt_tokens`/`completion_tokens` fields) -- no new computation here,
+ * these are T6's own `CompactionStats` fields, surfaced as-is.
+ */
+export interface CompactionTelemetry {
+  readonly applied: boolean
+  readonly stateTokens?: number
+  readonly reductionRatio?: number
+}
+
+/**
+ * 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.
+ *
+ * Also stamps `metadata.compaction_applied` (T9) -- `false`, with
+ * `compaction_state_tokens`/`compaction_reduction_ratio` absent, whenever
+ * `compaction` is omitted or `compaction.applied` is `false` (flag off, or
+ * the compaction attempt in `experimental.chat.messages.transform` failed
+ * open); `true` plus both numeric fields when it actually ran and produced
+ * a result.
+ */
+export function stampSessionAffinity(
+  options: Record<string, unknown> | null | undefined,
+  sessionID: string | undefined,
+  compaction?: CompactionTelemetry,
+): 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
+
+  metadata["compaction_applied"] = compaction?.applied ?? false
+  if (compaction?.applied) {
+    metadata["compaction_state_tokens"] = compaction.stateTokens
+    metadata["compaction_reduction_ratio"] = compaction.reductionRatio
+  } else {
+    delete metadata["compaction_state_tokens"]
+    delete metadata["compaction_reduction_ratio"]
+  }
+}