@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/opencode-subscribe.ts

@@ -0,0 +1,62 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { errMessage, isRecord } from "@humwick/sdk";
+import { logger } from "../logger";
+import type { OpenCodeServerEvent } from "./opencode";
+
+export async function subscribeOpenCodeEvents(request: () => Promise<Response>, signal: AbortSignal, onEvent: (event: OpenCodeServerEvent) => void, retryDelay: (ms: number, signal: AbortSignal) => Promise<unknown> = (ms, abort) => delay(ms, undefined, { signal: abort })): Promise<void> {
+  let failures = 0;
+  while (!signal.aborted) {
+    try {
+      await consumeEvents(request, signal, onEvent, () => { failures = 0; });
+      if (signal.aborted) return;
+      throw new Error("event stream ended");
+    } catch (error) {
+      if (signal.aborted) return;
+      const delayMs = Math.min(30_000, 1_000 * 2 ** Math.min(failures++, 5));
+      logger.error("opencode", `SSE subscription failed: ${errMessage(error)}; reconnecting in ${delayMs}ms`);
+      try {
+        await retryDelay(delayMs, signal);
+      } catch (delayError) {
+        if (signal.aborted) return;
+        throw delayError;
+      }
+    }
+  }
+}
+
+async function consumeEvents(request: () => Promise<Response>, signal: AbortSignal, onEvent: (event: OpenCodeServerEvent) => void, onReceived: () => void): Promise<void> {
+  const response = await request();
+  if (!response.body) throw new Error("event stream has no body");
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  try {
+    while (!signal.aborted) {
+      const read = await reader.read();
+      if (read.done) return;
+      buffered += decoder.decode(read.value, { stream: true });
+      const frames = buffered.split("\n\n");
+      buffered = frames.pop() ?? "";
+      for (const frame of frames) {
+        const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("\n");
+        if (!data) continue;
+        let event: unknown;
+        try {
+          event = JSON.parse(data);
+        } catch {
+          continue; // malformed event is isolated; the stream remains usable
+        }
+        if (isRecord(event) && typeof event.type === "string") {
+          onReceived();
+          try {
+            onEvent({ type: event.type, ...(isRecord(event.properties) ? { properties: event.properties } : {}) });
+          } catch (error) {
+            logger.error("opencode", `SSE event handler failed for ${event.type}: ${errMessage(error)}`);
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  }

package/src/adapters/opencode-token-usage-capture.ts

@@ -0,0 +1,187 @@
+// #2484 — per-turn OpenCode/Zai token-usage capture, reusing the #2482/#2485 spine seam
+// (ProviderTokenUsageReporter + POST /api/agents/:id/token-usage, validated live via Claude's
+// #2491 capture). Unlike Claude, OpenCode never hands the runner a transcript file to tail: the
+// `message.updated` SSE door already carries a structured per-assistant-message `tokens` object
+// once a message finalizes — `{ input, output, reasoning, cache: { read, write } }`, confirmed
+// live against a real captured v1.18.21 session (see opencode-context.ts's #2355 note beside the
+// same wire shape). So there is no incremental-file tail here: this module is a pure decoder from
+// that object to the spine's required breakdown, called straight from the SSE handler.
+//
+// Dedupe: the door fires more than once per message as it streams toward its final total (#2427).
+// Keying on the message id makes every echo collapse onto the SAME spine row via the dedupe_key
+// upsert (`created_at >= existing` replaces) — the row simply refines towards the message's true
+// total rather than posting a new one per frame, exactly like Claude's uuid-keyed entries collapse
+// repeated capture passes onto one row.
+import { OPENAI_API_MODEL, isRecord, stringValue } from "@humwick/sdk";
+import type { ProviderTokenUsageRecord, ProviderTokenUsageReporter } from "../adapter";
+
+export type OpenCodeTokenUsageSpineRecord = ProviderTokenUsageRecord;
+
+function numberOrZero(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Decompose OpenCode's per-message `tokens` object into the spine's required input/output/cache
+ * breakdown. Returns `undefined` when the shape is not the recognised record (absent, a bare
+ * number, or every leaf zero/unreadable) — never fabricating a breakdown it cannot actually read,
+ * mirroring the "only claim what was understood" rule `openCodeCompletion` already applies to this
+ * same wire family.
+ */
+export function openCodeTokenUsageRecord(input: {
+  sessionId: string;
+  provider: string;
+  model: string;
+  messageId: string;
+  tokens: unknown;
+  createdAt?: number;
+  /** #3351 — the message is final, so unreadable counts mean unknown spend, not "not yet". */
+  finished?: boolean;
+}): OpenCodeTokenUsageSpineRecord | undefined {
+  const unknown = (): OpenCodeTokenUsageSpineRecord | undefined => input.finished ? {
+    sessionId: input.sessionId, provider: input.provider, model: input.model,
+    inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
+    dedupeKey: input.messageId, createdAt: input.createdAt ?? Date.now(), usageStatus: "unknown",
+  } : undefined;
+  if (!isRecord(input.tokens)) return unknown();
+  const cache = isRecord(input.tokens.cache) ? input.tokens.cache : undefined;
+  if (input.model === OPENAI_API_MODEL && ![input.tokens.input, input.tokens.output, cache?.read, cache?.write, input.tokens.reasoning === undefined ? 0 : input.tokens.reasoning]
+    .every(n => typeof n === "number" && Number.isSafeInteger(n) && n >= 0)) return unknown();
+  const inputTokens = numberOrZero(input.tokens.input);
+  const outputTokens = numberOrZero(input.tokens.output);
+  const reasoningOutputTokens = numberOrZero(input.tokens.reasoning);
+  const cacheReadTokens = numberOrZero(cache?.read);
+  const cacheWriteTokens = numberOrZero(cache?.write);
+  // A recognised-but-entirely-empty object carries no signal — the same no-signal rule
+  // `openCodeContextState` applies to a `tokensUsed:0` reading of this identical shape (#2355
+  // review MED-1: a genuinely engaged assistant message always has input > 0).
+  if (inputTokens === 0 && outputTokens === 0 && reasoningOutputTokens === 0 && cacheReadTokens === 0 && cacheWriteTokens === 0) return unknown();
+  return {
+    sessionId: input.sessionId,
+    provider: input.provider,
+    model: input.model,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    ...(reasoningOutputTokens > 0 ? { reasoningOutputTokens } : {}),
+    dedupeKey: input.messageId,
+    createdAt: input.createdAt ?? Date.now(),
+  };
+}
+
+/**
+ * #2484 round 1 review (F6) — the message's OWN observed usage time: `time.completed` once
+ * finalized, else `time.created` (present on every AssistantMessage, per opencode-context.ts's
+ * #2355 note on this same wire family). Reading this instead of `Date.now()` at report time
+ * removes the equal-millisecond upsert race for the TERMINAL echo specifically: every
+ * streaming echo of a still-open message shares the SAME `time.created`, and the terminal
+ * echo's own `time.completed` is always `>=` it — so the spine's `created_at >= existing`
+ * upsert can never let a stale reprocessing of an earlier, still-open echo clobber the
+ * terminal, complete read the way a receipt-time `Date.now()` could. (Round 2 review, LOW-1:
+ * two PRE-completion echoes of the same still-open message still share that same
+ * `time.created` and so are not individually ordered against each other by this alone — the
+ * debounced poster's own last-write-wins `schedule()` is what settles that case, since only
+ * the most recently scheduled record ever reaches `flush()`.)
+ */
+export function openCodeMessageObservedAt(info: unknown): number | undefined {
+  if (!isRecord(info) || !isRecord(info.time)) return undefined;
+  const completed = info.time.completed;
+  if (typeof completed === "number" && Number.isFinite(completed)) return completed;
+  const created = info.time.created;
+  return typeof created === "number" && Number.isFinite(created) ? created : undefined;
+}
+
+/** Terminal messages can carry billed usage even when the turn errored or was aborted. */
+export function openCodeMessageFinished(info: unknown): boolean {
+  return isRecord(info) && ((isRecord(info.time) && typeof info.time.completed === "number") || isRecord(info.error));
+}
+
+/**
+ * #2484 round 1 review (F5) — the model the message was actually generated with, read off its own
+ * `providerID`/`modelID` (the same shape `openCodeModelDescriptor` sends on the request) rather
+ * than the session's currently-configured model, which can have moved on (a mid-session
+ * model/provider swap, a #2397 retry re-roll) by the time this echo is processed.
+ */
+export function openCodeMessageModel(info: unknown): string | undefined {
+  if (!isRecord(info)) return undefined;
+  const providerID = stringValue(info.providerID);
+  const modelID = stringValue(info.modelID);
+  return providerID && modelID ? `${providerID}/${modelID}` : undefined;
+}
+
+const TOKEN_USAGE_DEBOUNCE_MS = 300;
+
+/**
+ * #2484 round 1 review (F2/F3) — the `message.updated` door fires repeatedly as one message
+ * streams to completion; posting on every echo means an HTTP POST + SQLite write per frame,
+ * fleet-wide, for a value the very next echo immediately supersedes. Trailing-debounce per
+ * message id: each new echo replaces the pending record and resets the timer, so a whole
+ * streaming burst collapses to ONE post carrying the terminal value. `flush`/`flushAll` let the
+ * adapter force an immediate post at a real turn boundary (turn close, shutdown) rather than
+ * risk losing the last burst's report to a timer that never gets to fire.
+ */
+export class OpenCodeTokenUsagePoster {
+  private readonly pending = new Map<string, { record: OpenCodeTokenUsageSpineRecord; timer: ReturnType<typeof setTimeout> }>();
+
+  constructor(
+    private readonly reporter: () => ProviderTokenUsageReporter | undefined,
+    private readonly debounceMs = TOKEN_USAGE_DEBOUNCE_MS,
+  ) {}
+
+  schedule(record: OpenCodeTokenUsageSpineRecord): void {
+    const prior = this.pending.get(record.dedupeKey);
+    if (prior) clearTimeout(prior.timer);
+    const timer = setTimeout(() => this.flush(record.dedupeKey), this.debounceMs);
+    if (typeof timer.unref === "function") timer.unref();
+    this.pending.set(record.dedupeKey, { record, timer });
+  }
+
+  // #2484 round 2 review (MED-1) — returns the in-flight delivery so a teardown caller can
+  // actually await it (previously fire-and-forget: a caller that returned right after calling
+  // this had no guarantee the POST had even started, let alone landed — the repo's
+  // persisted-is-not-delivered shape). A live turn-boundary call (closeSuppressedTurn/
+  // closeEventTurn/failTurn) still doesn't need to await it: the promise's own `.catch` already
+  // routes failures to `reporter.reportFailure`, so nothing is lost by not awaiting there.
+  flush(dedupeKey: string): Promise<void> {
+    const entry = this.pending.get(dedupeKey);
+    if (!entry) return Promise.resolve();
+    this.pending.delete(dedupeKey);
+    clearTimeout(entry.timer);
+    const reporter = this.reporter();
+    if (!reporter) return Promise.resolve();
+    return reporter
+      .report(entry.record)
+      .then(() => reporter.debug(`token-usage capture: posted ${entry.record.dedupeKey}`))
+      .catch((error) => reporter.reportFailure(error));
+  }
+
+  flushAll(): Promise<void> {
+    return Promise.all([...this.pending.keys()].map((dedupeKey) => this.flush(dedupeKey))).then(() => undefined);
+  }
+}
+
+/**
+ * Decode the `message.updated` door's `info` into a spine record and schedule it through
+ * `poster`. A no-op whenever the session/model is unknown or {@link openCodeTokenUsageRecord}
+ * couldn't decompose the tokens object — never fabricating a report from a shape it didn't
+ * understand, and never throwing when no reporter has been configured yet (the poster itself
+ * absorbs that at flush time).
+ */
+export function scheduleOpenCodeTokenUsage(
+  poster: OpenCodeTokenUsagePoster,
+  input: { provider: string; sessionId: string | undefined; model: string | undefined; messageId: string; tokens: unknown; createdAt: number | undefined; finished?: boolean },
+): void {
+  if (!input.sessionId || !input.model) return;
+  const record = openCodeTokenUsageRecord({
+    sessionId: input.sessionId,
+    provider: input.provider,
+    model: input.model,
+    messageId: input.messageId,
+    tokens: input.tokens,
+    createdAt: input.createdAt,
+    finished: input.finished,
+  });
+  if (!record) return;
+  poster.schedule(record);
+}

package/src/adapters/opencode-tool-events.ts

@@ -0,0 +1,302 @@
+/**
+ * #2354 — decode OpenCode's `message.part.updated` tool parts (v1.18.21 `ToolPart`) into the
+ * provider-neutral tool-step shape the chat/timeline already renders (TraceView `ToolCallRow`).
+ *
+ * `opencode.ts` is near the module-size ceiling, so the wire-decoding lives here as a small,
+ * pure, separately-testable unit; the adapter keeps only the stateful dedup/ordering and the
+ * `sessionEventCb` emit. Modelled on the Codex adapter (stable item-id running/completed upserts),
+ * per the operator's "handle like we do in codex" instruction.
+ *
+ * ToolPart wire shape (pinned v1.18.21):
+ *   { id, callID, tool, state: { status: "pending"|"running"|"completed"|"error", … } }
+ *     - running:   input, title, metadata
+ *     - completed: output, title, metadata, time
+ *     - error:     error, metadata, and an `interrupted` flag when a running tool was aborted
+ */
+
+import { isRecord, stringValue, type ToolCallCategory } from "@humwick/sdk";
+import type { ProviderSessionEvent } from "../adapter";
+import { absoluteToolPaths, clipToolSummary, oneLineText, redactAndCapParams, summarizeToolInput } from "./tool-summary";
+
+/** The provider-neutral tool-step lifecycle status. `cancelled` is an interrupted-before-finished
+ *  tool (ToolPart error state with `interrupted:true`), distinct from `failed` (ran and errored). */
+export type OpenCodeToolStepStatus = "running" | "completed" | "failed" | "cancelled";
+
+export interface OpenCodeToolStep {
+  /** Stable part id → session-step `stepId`, so running→completed upserts one row in place. */
+  stepId: string;
+  /** The raw OpenCode tool name (e.g. "bash", "read", an MCP tool) — short row label. */
+  label: string;
+  category: ToolCallCategory;
+  status: OpenCodeToolStepStatus;
+  /** Safe one-line summary (redacted + clipped) of what the tool is doing. */
+  body: string;
+  /** #2437 — redacted, size-capped tool input. Only present on the "running" state (the ToolPart
+   *  wire shape drops `input` once the tool completes) — undefined here means "not captured on
+   *  THIS decode", not "no params exist"; see `emitToolStep`'s stepId cache for the carry-forward
+   *  onto the terminal state. */
+  params?: unknown;
+  /** #3411 — absolute paths a file tool reads or edits, from the raw input (running state only). */
+  paths?: string[];
+}
+
+/** OpenCode built-in tool name → the provider-independent category taxonomy (#1498). Anything
+ *  not a known built-in (an MCP tool, a future built-in) falls to the mcp/generic default —
+ *  never force-fit, so nothing is hidden from the trace. */
+const OPENCODE_TOOL_CATEGORIES: Record<string, ToolCallCategory> = {
+  bash: "cli-bash",
+  edit: "edit",
+  write: "edit",
+  patch: "edit",
+  multiedit: "edit",
+  read: "read",
+  list: "read",
+  task: "agent-spawn",
+  todowrite: "plan",
+  todoread: "plan",
+};
+
+/** #3411 — OpenCode's file tools; each names its file in `input.filePath`. */
+const OPENCODE_FILE_TOOLS = new Set(["read", "edit", "write", "multiedit"]);
+
+/** Extra input-field names OpenCode's built-in tools use that aren't in the shared candidate
+ *  list — its file tools use camelCase `filePath` (already shared) and `todo`/`glob` shapes. */
+const OPENCODE_INPUT_KEYS = ["filePath", "cwd"] as const;
+
+export function openCodeToolCategory(tool: string): ToolCallCategory {
+  const known = OPENCODE_TOOL_CATEGORIES[tool.toLowerCase()];
+  if (known) return known;
+  // MCP tools surface through OpenCode with a namespaced name; the `__` convention (shared with
+  // Claude's `mcp__server__tool`) is the safe signal. Everything else is generic (#2354 rule:
+  // unknown tool → generic), so a mystery tool still renders rather than vanishing.
+  if (tool.includes("__") || tool.toLowerCase().startsWith("mcp")) return "mcp-tool-call";
+  return "generic";
+}
+
+/**
+ * Map the ToolPart state to the shared lifecycle status. `pending` (queued but not yet started)
+ * collapses to `running` — the trace shows one "in-flight" state, matching Codex, which emits a
+ * single running upsert. An `error` state splits: an interrupted tool is `cancelled` (we/the
+ * operator aborted it — not the model's fault), a non-interrupted error is `failed`. An
+ * unrecognised/missing status is treated as in-flight (`running`) rather than dropped.
+ */
+export function openCodeToolStatus(state: Record<string, unknown> | undefined): OpenCodeToolStepStatus {
+  const rawStatus = stringValue(state?.status);
+  if (rawStatus === "completed") return "completed";
+  if (rawStatus === "error") return state?.interrupted === true ? "cancelled" : "failed";
+  return "running";
+}
+
+/** Lifecycle rank for the adapter's terminal-lock/dedup: a terminal state (2) must never be
+ *  regressed to running (1) by a duplicate/reordered update. Mirrors the server's
+ *  `sessionStepStatusRank`. */
+export function openCodeToolStatusRank(status: OpenCodeToolStepStatus): number {
+  return status === "running" ? 1 : 2;
+}
+
+/** The message the ToolPart error state carries, defensively (string, `{message}`, `{data.message}`,
+ *  or a `{name}` fallback). */
+function openCodeToolErrorText(error: unknown): string {
+  if (typeof error === "string") return oneLineText(error);
+  if (!isRecord(error)) return "";
+  const direct = oneLineText(error.message);
+  if (direct) return direct;
+  const nested = isRecord(error.data) ? oneLineText(error.data.message) : "";
+  if (nested) return nested;
+  return oneLineText(error.name);
+}
+
+/**
+ * The safe body summary for a tool step, in priority order: the input args' most meaningful field
+ * (present while running), then the server-supplied human `title`, then the error text (error
+ * state), then the tool name. Raw tool OUTPUT is deliberately never surfaced — it can be huge and
+ * unbounded (Codex applies the same rule), and `title` already names the result. Everything routes
+ * through `clipToolSummary`, so redaction can't be skipped.
+ */
+function openCodeToolBody(tool: string, state: Record<string, unknown> | undefined): string {
+  if (!state) return tool;
+  const input = isRecord(state.input) ? state.input : undefined;
+  const inputSummary = summarizeToolInput(input, OPENCODE_INPUT_KEYS);
+  if (inputSummary) return inputSummary;
+  const title = oneLineText(state.title);
+  if (title) return title;
+  const error = openCodeToolErrorText(state.error);
+  if (error) return error;
+  return tool;
+}
+
+/**
+ * Decode one `message.part.updated` part into a tool step, or `undefined` when the part is not a
+ * decodable tool part (wrong type, or missing the stable id/name we key the upsert on). Pure — the
+ * adapter owns the dedup/ordering state and the emit.
+ */
+export function decodeOpenCodeToolPart(part: unknown): OpenCodeToolStep | undefined {
+  if (!isRecord(part)) return undefined;
+  if (stringValue(part.type) !== "tool") return undefined;
+  const stepId = stringValue(part.id);
+  const tool = stringValue(part.tool);
+  if (!stepId || !tool) return undefined;
+  const state = isRecord(part.state) ? part.state : undefined;
+  const input = isRecord(state?.input) ? state.input : undefined;
+  const paths = input && OPENCODE_FILE_TOOLS.has(tool) ? absoluteToolPaths([input.filePath]) : undefined;
+  return {
+    stepId,
+    label: tool,
+    category: openCodeToolCategory(tool),
+    status: openCodeToolStatus(state),
+    body: clipToolSummary(openCodeToolBody(tool, state)),
+    ...(input !== undefined ? { params: redactAndCapParams(input) } : {}),
+    ...(paths ? { paths } : {}),
+  };
+}
+
+/** Build the `tool` session event the chat/timeline consumes from a decoded step. `streaming` is
+ *  true only while running; `stepId` drives the server's in-place running→terminal upsert. */
+export function openCodeToolSessionEvent(step: OpenCodeToolStep, turnId: string | undefined): ProviderSessionEvent {
+  return {
+    type: "tool",
+    origin: "provider",
+    body: step.body,
+    label: step.label,
+    category: step.category,
+    status: step.status,
+    streaming: step.status === "running",
+    stepId: step.stepId,
+    ...(turnId ? { turnId } : {}),
+    ...(step.params !== undefined ? { params: step.params } : {}),
+    ...(step.paths ? { paths: step.paths } : {}),
+  };
+}
+
+/**
+ * #2413 — concatenate the terminal assistant message's text parts (wire order) into the turn-final
+ * response text. Non-text parts (tool, step-start/finish, reasoning) are skipped; the `\n\n` join
+ * matches the dashboard's block delimiter, so a multi-part response's leading blocks dedupe against
+ * the streamed narration. `undefined` when there is no assistant text.
+ */
+export function openCodeAssistantText(parts: unknown[] | undefined): string | undefined {
+  if (!parts) return undefined;
+  const blocks: string[] = [];
+  for (const part of parts) {
+    if (!isRecord(part) || stringValue(part.type) !== "text") continue;
+    const text = stringValue(part.text)?.trim();
+    if (text) blocks.push(text);
+  }
+  return blocks.length ? blocks.join("\n\n") : undefined;
+}
+
+/**
+ * #2605 — decode one `message.part.updated` reasoning part (`{ type: "reasoning", text }`,
+ * pinned v1.18.21, live-verified in the provider's own SQLite: opencode/minimax-m2.5-free AND
+ * kimi-for-coding sessions persist `{type:"reasoning",text}` parts) into the provider-neutral
+ * emit fields. Pure — the adapter owns the dedup/emission, exactly like decodeOpenCodeToolPart.
+ * Returns `undefined` for non-reasoning parts or empty text (an empty reasoning row is backend
+ * muzak, not operator signal — e.g. a session's first persisted reasoning part was `""`).
+ */
+export function decodeOpenCodeReasoningPart(part: unknown): { stepId: string; body: string } | undefined {
+  if (!isRecord(part)) return undefined;
+  if (stringValue(part.type) !== "reasoning") return undefined;
+  const stepId = stringValue(part.id);
+  const body = stringValue(part.text)?.trim();
+  if (!stepId || !body) return undefined;
+  return { stepId, body };
+}
+
+/** #2605 — build the `reasoning` session event the chat/timeline consumes (TraceView reasoning
+ *  row): `stepId` = the stable part id, so the server upserts the row in place on growth instead
+ *  of appending a duplicate — the same stable-key shape the Codex adapter flushes with.
+ *  `streaming` stays true while the part is unfinished (`time.end` unset), false on finalize. */
+export function openCodeReasoningSessionEvent(step: { stepId: string; body: string }, turnId: string | undefined, streaming: boolean): ProviderSessionEvent {
+  return {
+    type: "reasoning",
+    origin: "provider",
+    body: step.body,
+    stepId: step.stepId,
+    streaming,
+    ...(turnId ? { turnId } : {}),
+  };
+}
+
+/**
+ * #2605 — one decoded reasoning part with its provider-side identity. The `id` is the wire that
+ * makes the turn-final backstop upsert instead of duplicate: the server keys step rows on
+ * `stepId` ONLY, so every turn-final reasoning row must carry the SAME stepId the live SSE door
+ * already emitted for that part (see openCodeReasoningSessionEvent) — a merged/concatenated
+ * body under a synthetic stepId would land as a second row on every turn whose SSE was
+ * observed. Thread `{id,text}[]` (not a joined string) through the completion for exactly this.
+ */
+export interface OpenCodeReasoningStep {
+  stepId: string;
+  body: string;
+}
+
+/**
+ * #2605 — decode the completed assistant message's reasoning parts (wire order) into
+ * per-part steps. Mirrors openCodeAssistantText's part walk, but keeps identity: one entry per
+ * non-empty reasoning part (empty text is backend muzak — dropped by decodeOpenCodeReasoningPart
+ * — so it never occupies a row). `[]` when the message carried no reasoning.
+ */
+export function openCodeAssistantReasoningSteps(parts: unknown[] | undefined): OpenCodeReasoningStep[] {
+  if (!parts) return [];
+  const steps: OpenCodeReasoningStep[] = [];
+  for (const part of parts) {
+    const step = decodeOpenCodeReasoningPart(part);
+    if (step) steps.push(step);
+  }
+  return steps;
+}
+
+/**
+ * #2605 — concatenate the terminal assistant message's reasoning parts (wire order) into the
+ * turn-final reasoning text. `undefined` when the completed message carried no (non-empty)
+ * reasoning. Kept for the completion log line / describeCompletion only — the EMIT path uses
+ * openCodeAssistantReasoningSteps (per-part identity) so live+final collapse to one row.
+ */
+export function openCodeAssistantReasoning(parts: unknown[] | undefined): string | undefined {
+  const steps = openCodeAssistantReasoningSteps(parts);
+  return steps.length ? steps.map((step) => step.body).join("\n\n") : undefined;
+}
+
+/** #2413 — build the turn-final `response` event (marks it for Final Response capture / auto-forward
+ *  and styles it apart from reasoning). `undefined` when the turn produced no assistant text. */
+export function openCodeTurnFinalResponseEvent(text: string | undefined, turnId: string | undefined): ProviderSessionEvent | undefined {
+  const body = text?.trim();
+  if (!body) return undefined;
+  return { type: "response", origin: "provider", body, final: true, confidence: "definitive", endedBy: "completed", ...(turnId ? { turnId } : {}) };
+}
+
+/**
+ * #2605 — emit the turn-final `reasoning` rows (`completion.reasoningSteps`, read from the SAME
+ * synchronous POST body as the response below) plus that response, in order. Each reasoning row
+ * carries its OWN part id as stepId — the exact key the live SSE door already emitted — so the
+ * server upserts live+final into ONE row instead of storing the turn's thinking twice. Pure
+ * event construction — the caller owns the ledger write + emit, like the tool/response builders.
+ *
+ * The parts are the model's thinking as of turn end — the completed message persists every
+ * reasoning part with its full text — so the backstop covers a POST-only reader, a dropped
+ * subscription, or frames racing the close. A part whose live row already carries this exact
+ * body is skipped here (same-body no-op, matching the SSE door's dedup); a part that GREW
+ * since its last live frame re-emits the current full body under the same stepId (upsert).
+ * The caller passes the per-part bodies it already emitted (or an empty record on the POST-only
+ * path) — comparison is scoped to THOSE part ids, never to a global body pool, so an identical
+ * body in a later turn is never misread as already-seen.
+ *
+ * The text is ground truth per #2389: the POST returning IS the provider-native turn-end edge,
+ * hence `confidence:"definitive"` on the response; `final:true` is what makes it a turn-final
+ * capture downstream. Emits reasoning first so the trace reads thinking-then-answer, the order
+ * the model produced them in. Either half may be absent (reasoning-only or text-only turns).
+ */
+export function openCodeTurnFinalEvents(
+  completion: { text?: string; reasoningSteps?: OpenCodeReasoningStep[] },
+  turnId: string | undefined,
+  emittedBodies: Record<string, string> = {},
+): ProviderSessionEvent[] {
+  const events: ProviderSessionEvent[] = [];
+  for (const step of completion.reasoningSteps ?? []) {
+    if (emittedBodies[step.stepId] === step.body) continue;
+    events.push({ type: "reasoning", origin: "provider", body: step.body, stepId: step.stepId, streaming: false, ...(turnId ? { turnId } : {}) });
+  }
+  const response = openCodeTurnFinalResponseEvent(completion.text, turnId);
+  if (response) events.push(response);
+  return events;
+}

package/src/adapters/opencode-tools-config.ts

@@ -0,0 +1,17 @@
+import { harnessSubagentsEnabled } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "../adapter";
+import { openCodeNativeWebPermissions, openCodeWebToolsConfig } from "../web-tools";
+
+export function openCodeHarnessTools(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">): Record<string, false> {
+  return harnessSubagentsEnabled(config) ? {} : { task: false };
+}
+
+/** The opencode.json `tools` map: harness built-ins plus, with MCP present, the switched-off web tools. */
+export function openCodeToolsConfig(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">, hasMcp: boolean): { tools?: Record<string, false> } {
+  const tools = { ...openCodeHarnessTools(config), ...(hasMcp ? openCodeWebToolsConfig(config).tools : {}) };
+  return Object.keys(tools).length ? { tools } : {};
+}
+
+export function openCodePermissions(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">): Record<string, "allow" | "deny"> {
+  return { "*": "allow", ...openCodeNativeWebPermissions(config) };
+}