@xyagent/cli 0.0.1

package/src-shared/envelope_builder.mjs

@@ -0,0 +1,612 @@
+/**
+ * envelope_builder.mjs — C1.1.2 + C1.1.3
+ *
+ * Builders for unified Agent Protocol envelope objects.
+ * Each builder returns a plain object without `id` (server assigns).
+ *
+ * Protocol reference: docs/protocol/unified-agent-sse.md §5.1
+ */
+
+// ---------------------------------------------------------------------------
+// GAP-16: ID generator — "blk_" prefix + 26 Crockford Base32 chars (ULID format)
+// Crockford alphabet: 0-9 A-H J K M N P-T V-Z (32 chars, no I L O U)
+// ---------------------------------------------------------------------------
+
+const CROCKFORD_CHARS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/**
+ * tool_result.output 里嵌套的每个 Block 都必须独立通过 block.schema 校验
+ * (block.schema.json 要求 id/type/status；text 块要 type/format/text；image
+ * 要 source 等等)。runtime translator 出于人类可读优先，常常只传 {type,
+ * format, text}，需要在这里补齐 schema 必填项。
+ *
+ * 规则：
+ *   - 任意 item 必带 id (auto blk_<ULID>) + status (默认 completed) + type
+ *   - type === "text"      → 默认 format="plain", text=""
+ *   - type === "thinking"  → 默认 text=""
+ *   - type === "tool_use"  → 默认 tool_call_id=id, tool_name="unknown",
+ *                            input={}, input_complete=true
+ *   - 其他 type 透传，由调用方保证 schema 完整
+ *
+ * 非 object item（字符串／null）兜底包成 text 块，避免 server 拒。
+ */
+function normalizeToolResultOutputItem(raw) {
+  if (raw == null) {
+    return { id: newBlockId(), type: "text", status: "completed", format: "plain", text: "" };
+  }
+  if (typeof raw === "string") {
+    return { id: newBlockId(), type: "text", status: "completed", format: "plain", text: raw };
+  }
+  if (typeof raw !== "object") {
+    return { id: newBlockId(), type: "text", status: "completed", format: "plain", text: String(raw) };
+  }
+  const out = { ...raw };
+  if (!out.id) out.id = newBlockId();
+  if (!out.status) out.status = "completed";
+  if (!out.type) out.type = "text";
+  if (out.type === "text") {
+    if (out.format === undefined) out.format = "plain";
+    if (out.text === undefined) out.text = "";
+  } else if (out.type === "thinking") {
+    if (out.text === undefined) out.text = "";
+  } else if (out.type === "tool_use") {
+    if (out.tool_call_id === undefined) out.tool_call_id = out.id;
+    if (out.tool_name === undefined) out.tool_name = "unknown";
+    if (out.input === undefined) out.input = {};
+    if (out.input_complete === undefined) out.input_complete = true;
+  }
+  return out;
+}
+
+function newCrockfordSuffix() {
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    // fallback: Math.random (Node < 22 shouldn't happen, but safe)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  // Encode 128 bits as 26 Crockford Base32 chars (128 / 5 = 25.6 → 26 chars, top 2 bits zero)
+  // Pack bytes into a BigInt then extract 5-bit groups from MSB.
+  let n = BigInt(0);
+  for (const b of bytes) n = (n << BigInt(8)) | BigInt(b);
+  const chars = [];
+  for (let i = 0; i < 26; i++) {
+    chars.unshift(CROCKFORD_CHARS[Number(n & BigInt(31))]);
+    n >>= BigInt(5);
+  }
+  return chars.join("");
+}
+
+export function newBlockId() {
+  return "blk_" + newCrockfordSuffix();
+}
+
+// Mint a fresh `run_<26 Crockford>` id — matches envelope.schema run_id pattern
+// `^run_[0-9A-HJKMNP-TV-Z]{26}$`. Used by hermes bridge when synthesizing a
+// child run for delegate_task (no upstream child session id available).
+export function newRunId() {
+  return "run_" + newCrockfordSuffix();
+}
+
+// ---------------------------------------------------------------------------
+// C1.1.2 — 5 envelope builders
+// ---------------------------------------------------------------------------
+
+/**
+ * run.started
+ * @param {string} runId
+ * @param {{
+ *   model?: string|null,
+ *   options?: object,
+ *   parentRunId?: string,
+ *   spawnToolUseId?: string,
+ *   extensions?: object,
+ * }} [meta]
+ *
+ * parentRunId — top-level envelope field; set when this run is a child run
+ * spawned by a subagent dispatch. Server's subagent_synth correlates child
+ * lifecycle back to the parent's `subagent_ref` block via this field plus
+ * `extensions.openclaw.child_session_key`.
+ *
+ * spawnToolUseId — when provided (non-empty string), written to
+ * `payload.spawn_tool_use_id`. Lets relay subagent_synth SDK mode detect that
+ * the CLI will supply the child run id, so relay skips minting its own ULID.
+ *
+ * Note: `usage` was removed — run_started.schema.json uses additionalProperties:false
+ * and does not list `usage`; it is reported via a separate usage.report envelope.
+ */
+export function buildRunStarted(runId, meta) {
+  const env = {
+    type: "run.started",
+    run_id: runId,
+    payload: {
+      model: meta?.model ?? "",
+      options: meta?.options ?? {},
+    },
+  };
+  if (meta?.parentRunId) env.parent_run_id = meta.parentRunId;
+  if (meta?.spawnToolUseId) env.payload.spawn_tool_use_id = meta.spawnToolUseId;
+  if (meta?.extensions && typeof meta.extensions === "object") {
+    env.extensions = meta.extensions;
+  }
+  return env;
+}
+
+/**
+ * run.completed
+ * @param {string} runId
+ * @param {string} stopReason  e.g. "end_turn" | "max_tokens" | "user_canceled"
+ * @param {{ parentRunId?: string, extensions?: object }} [opts]
+ *
+ * parentRunId + extensions same semantics as buildRunStarted; required for
+ * child run termination so subagent_synth.synthChildRunTerminal can fire
+ * subagent_ref.completed on the parent timeline.
+ */
+export function buildRunCompleted(runId, stopReason, opts) {
+  const env = {
+    type: "run.completed",
+    run_id: runId,
+    payload: { stop_reason: stopReason || "end_turn" },
+  };
+  if (opts?.parentRunId) env.parent_run_id = opts.parentRunId;
+  if (opts?.extensions && typeof opts.extensions === "object") {
+    env.extensions = opts.extensions;
+  }
+  return env;
+}
+
+/**
+ * content_block.started
+ * @param {string} runId
+ * @param {{ id?: string, type: string, [k: string]: any }} block
+ * @param {number} [index=0]  block index within the message (schema required, defaults to 0)
+ *
+ * Automatically fills schema-required fields for known block types:
+ *   - All blocks: `status` defaults to "in_progress"
+ *   - text blocks: `format` defaults to "plain", `text` defaults to "" (filled via deltas, finalized on completed)
+ *   - thinking blocks: `text` defaults to "" (filled via deltas, finalized on completed)
+ */
+export function buildBlockStarted(runId, block, index = 0) {
+  const id = block.id || newBlockId();
+  const enrichedBlock = { ...block, id };
+  if (enrichedBlock.status === undefined) {
+    enrichedBlock.status = "in_progress";
+  }
+  if (enrichedBlock.type === "text") {
+    if (enrichedBlock.format === undefined) enrichedBlock.format = "plain";
+    if (enrichedBlock.text === undefined) enrichedBlock.text = "";
+  }
+  if (enrichedBlock.type === "thinking") {
+    if (enrichedBlock.text === undefined) enrichedBlock.text = "";
+  }
+  // tool_use block — schema requires tool_call_id + tool_name; input defaults
+  // to {} and input_complete defaults to false (app accumulates via deltas).
+  if (enrichedBlock.type === "tool_use") {
+    if (enrichedBlock.tool_call_id === undefined) enrichedBlock.tool_call_id = id;
+    if (enrichedBlock.tool_name === undefined) enrichedBlock.tool_name = "unknown";
+    if (enrichedBlock.input === undefined) enrichedBlock.input = {};
+    if (enrichedBlock.input_complete === undefined) enrichedBlock.input_complete = false;
+  }
+  // tool_result block — schema requires tool_call_id + output (List<Block>).
+  if (enrichedBlock.type === "tool_result") {
+    if (enrichedBlock.tool_call_id === undefined) enrichedBlock.tool_call_id = id;
+    if (enrichedBlock.output === undefined) enrichedBlock.output = [];
+    if (enrichedBlock.is_error === undefined) enrichedBlock.is_error = false;
+  }
+  // subagent_ref — schema requires child_run_id (^run_[0-9A-HJKMNP-TV-Z]{26}$).
+  // fail-fast: blk_ prefix fallback violates schema; caller must supply valid run id.
+  if (enrichedBlock.type === "subagent_ref") {
+    if (enrichedBlock.child_run_id === undefined) throw new Error("subagent_ref block requires child_run_id");
+  }
+  // interrupt block — protocol initial status is "awaiting" (not "in_progress").
+  // Transparently pass through subtype / prompt / options / title / selection_mode.
+  if (enrichedBlock.type === "interrupt") {
+    if (enrichedBlock.status === "in_progress") {
+      // "in_progress" was set by the generic default above — override with "awaiting"
+      // only if the caller did NOT explicitly pass a status.
+      // We detect this by checking if the original block.status was undefined.
+      if (block.status === undefined) {
+        enrichedBlock.status = "awaiting";
+      }
+    }
+  }
+  return {
+    type: "content_block.started",
+    run_id: runId,
+    payload: { index, block: enrichedBlock },
+  };
+}
+
+/**
+ * content_block.delta
+ * @param {string} runId
+ * @param {string} blockId
+ * @param {string|object} delta  If a string is provided it is wrapped into
+ *   { text_append: delta } so app-side consumers (chat_store_unified.dart)
+ *   can read `payload.delta['text_append']` directly.
+ * @param {number} [index=0]  block index within the message (schema required, defaults to 0)
+ */
+export function buildBlockDelta(runId, blockId, delta, index = 0) {
+  const normalizedDelta =
+    typeof delta === "string" ? { text_append: delta } : delta;
+  return {
+    type: "content_block.delta",
+    run_id: runId,
+    payload: { index, block_id: blockId, delta: normalizedDelta },
+  };
+}
+
+/**
+ * content_block.completed
+ * @param {string} runId
+ * @param {{ id: string, type: string, [k: string]: any }} block
+ * @param {number} [index=0]  block index within the message (schema required, defaults to 0)
+ *
+ * Automatically fills schema-required fields for known block types:
+ *   - All blocks: `status` defaults to "completed"
+ *   - text blocks: `format` defaults to "plain"; `text` defaults to "" only as a
+ *     last-resort schema guard. Callers SHOULD pass the full accumulated text
+ *     (protocol §5.3.5: completed payload is the terminal full state).
+ *   - thinking blocks: `text` defaults to "" with the same caveat.
+ */
+export function buildBlockCompleted(runId, block, index = 0) {
+  const enrichedBlock = { ...block };
+  if (enrichedBlock.status === undefined) {
+    enrichedBlock.status = "completed";
+  }
+  if (enrichedBlock.type === "text") {
+    if (enrichedBlock.format === undefined) enrichedBlock.format = "plain";
+    if (enrichedBlock.text === undefined) enrichedBlock.text = "";
+  }
+  if (enrichedBlock.type === "thinking") {
+    if (enrichedBlock.text === undefined) enrichedBlock.text = "";
+  }
+  if (enrichedBlock.type === "tool_use") {
+    if (enrichedBlock.tool_call_id === undefined) enrichedBlock.tool_call_id = enrichedBlock.id;
+    if (enrichedBlock.tool_name === undefined) enrichedBlock.tool_name = "unknown";
+    if (enrichedBlock.input === undefined) enrichedBlock.input = {};
+    if (enrichedBlock.input_complete === undefined) enrichedBlock.input_complete = true;
+  }
+  if (enrichedBlock.type === "tool_result") {
+    if (enrichedBlock.tool_call_id === undefined) enrichedBlock.tool_call_id = enrichedBlock.id;
+    if (enrichedBlock.output === undefined) enrichedBlock.output = [];
+    if (enrichedBlock.is_error === undefined) enrichedBlock.is_error = false;
+  }
+  // subagent_ref — schema requires child_run_id (^run_[0-9A-HJKMNP-TV-Z]{26}$).
+  // fail-fast: blk_ prefix fallback violates schema; caller must supply valid run id.
+  if (enrichedBlock.type === "subagent_ref") {
+    if (enrichedBlock.child_run_id === undefined) throw new Error("subagent_ref block requires child_run_id");
+  }
+  return {
+    type: "content_block.completed",
+    run_id: runId,
+    payload: { index, block: enrichedBlock },
+  };
+}
+
+/**
+ * run.paused
+ * @param {string} runId
+ * @param {string[]} interruptIds  block ids that caused the pause (e.g. ["blk_xxx..."])
+ *
+ * `reason` is always "interrupt" per protocol (RunPausedPayload requires reason: string).
+ * `interrupt_ids` lists the block ids that caused the pause; allowed to be empty.
+ */
+export function buildRunPaused(runId, interruptIds) {
+  return {
+    type: "run.paused",
+    run_id: runId,
+    payload: {
+      reason: "interrupt",
+      interrupt_ids: Array.isArray(interruptIds) ? interruptIds : [],
+    },
+  };
+}
+
+/**
+ * run.failed — GAP-01 + GAP-19:
+ *   - payload includes stop_reason: "error" (spec §5.2, GAP-01)
+ *   - run_id_ref moved to extensions (not top-level, GAP-19)
+ * @param {string} runId
+ * @param {string} code   error code
+ * @param {string} message  error message
+ * @param {object|null} [details]  optional structured details (e.g. { model, missing_modality })
+ */
+export function buildRunFailed(runId, code, message, details = null) {
+  return {
+    type: "run.failed",
+    run_id: runId,
+    extensions: { run_id_ref: runId },
+    payload: {
+      stop_reason: "error",
+      error: { code, message, ...(details ? { details } : {}) },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// C1.1.3 — translateOpenClawChunkToEnvelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Translate a single openclaw stream chunk into zero or more unified envelopes.
+ *
+ * Real openclaw SSE event names:
+ *   - response.output_text.delta           — streaming text delta
+ *   - response.output_text.done            — text segment complete (no-op here)
+ *   - response.reasoning_summary_text.delta — thinking/reasoning delta
+ *   - response.tool_use.start              — tool call begin: chunk carries
+ *                                            { call_id, name, input?, parent_tool_use_id? }
+ *   - response.tool_use.arguments.delta    — incremental input/arguments JSON
+ *                                            (string fragment to append to input_json)
+ *   - response.tool_use.completed          — tool call args complete (input_complete=true)
+ *   - response.tool_result                 — tool result envelope: chunk has
+ *                                            { call_id, output[]: Block[], is_error?, summary? }
+ *   - response.completed / failed / end    — turn finished
+ *   - __envelopes                          — passthrough escape hatch:
+ *                                            chunk.envelopes is appended verbatim
+ *                                            (used by hermes bridge to inject
+ *                                            child-run run.started/run.completed
+ *                                            with parent_run_id + extensions)
+ *
+ * Run-scope override: tool_use / tool_result chunks may carry chunk.run_id;
+ * when present, the produced envelope's run_id uses it instead of the function
+ * arg runId. tool_use.start records the run scope on the call state so
+ * arguments.delta / completed envelopes ride the same run. text / thinking
+ * deltas always use the function arg runId.
+ *
+ * blockState shape:
+ *   {
+ *     text:     { blockId, started },
+ *     thinking: { blockId, started },
+ *     toolUses: Map<call_id, { blockId, started, argsJson }>,
+ *   }
+ *
+ * Multiple tool_use calls can be in flight simultaneously (parallel tool_use),
+ * so we key by call_id. parent_tool_use_id, when present on any envelope,
+ * surfaces in payload extensions so app can render subagent nesting.
+ *
+ * @param {{ event?: string, type?: string, [k: string]: any }} chunk
+ * @param {string} runId
+ * @param {object} blockState
+ * @returns {{ envelopes: any[], blockState: object }}
+ */
+export function translateOpenClawChunkToEnvelope(chunk, runId, blockState) {
+  const event = chunk.event || chunk.type;
+  const envelopes = [];
+  let text = { ...blockState.text };
+  let thinking = { ...blockState.thinking };
+  // Clone the toolUses Map shallowly so callers can detect change.
+  const toolUses = new Map(blockState.toolUses || []);
+
+  // hermes subagent passthrough: bridge mints child-run-scoped envelopes
+  // (run.started / run.completed with parent_run_id + extensions) directly
+  // because the translator only knows about a single (parent) runId per call.
+  // Anything in chunk.envelopes is appended verbatim; this is **not** a hot
+  // path — only used by hermes when delegate_task fires.
+  if (event === "__envelopes") {
+    if (Array.isArray(chunk.envelopes)) {
+      for (const env of chunk.envelopes) {
+        if (env && typeof env === "object") envelopes.push(env);
+      }
+    }
+    return { envelopes, blockState: { text, thinking, toolUses } };
+  }
+
+  // tool_use / tool_result chunks may override the run scope (subagent child
+  // run). text / thinking deltas stay on the caller's runId — child runs in
+  // hermes don't emit text, only tool calls.
+  const toolRunId = (typeof chunk.run_id === "string" && chunk.run_id) || runId;
+
+  if (event === "response.output_text.delta") {
+    const deltaText = chunk.delta ?? chunk.text ?? "";
+
+    if (!text.started) {
+      text.blockId = newBlockId();
+      text.content = "";
+      envelopes.push(buildBlockStarted(runId, { id: text.blockId, type: "text" }));
+      text.started = true;
+    }
+
+    text.content = (text.content || "") + String(deltaText);
+    envelopes.push(buildBlockDelta(runId, text.blockId, deltaText));
+  } else if (event === "response.reasoning_summary_text.delta") {
+    const deltaText = chunk.delta ?? chunk.text ?? "";
+
+    if (!thinking.started) {
+      thinking.blockId = newBlockId();
+      thinking.content = "";
+      envelopes.push(buildBlockStarted(runId, { id: thinking.blockId, type: "thinking" }));
+      thinking.started = true;
+    }
+
+    thinking.content = (thinking.content || "") + String(deltaText);
+    envelopes.push(buildBlockDelta(runId, thinking.blockId, deltaText));
+  } else if (event === "response.tool_use.start") {
+    // Begin a tool_use block. Stamp tool_call_id = call_id (stable across the lifecycle).
+    const callId = String(chunk.call_id || chunk.tool_use_id || newBlockId());
+    const toolName = String(chunk.name || chunk.tool_name || "unknown");
+    const inputInitial =
+      (chunk.input && typeof chunk.input === "object") ? chunk.input : {};
+    const blockId = newBlockId();
+    toolUses.set(callId, { blockId, started: true, argsJson: "", runId: toolRunId });
+    const startedBlock = {
+      id: blockId,
+      type: "tool_use",
+      tool_call_id: callId,
+      tool_name: toolName,
+      input: inputInitial,
+      input_complete: false,
+    };
+    const env = buildBlockStarted(toolRunId, startedBlock);
+    if (chunk.parent_tool_use_id) {
+      env.extensions = { parent_tool_use_id: chunk.parent_tool_use_id };
+    }
+    envelopes.push(env);
+  } else if (event === "response.function_call_arguments.delta") {
+    // picoclaw legacy event name → maps to tool_use.start + arguments.delta.
+    // chunk shape: { call_id, name, arguments } where arguments is a JSON
+    // fragment to append. We auto-start a tool_use block on first occurrence.
+    const callId = String(chunk.call_id || "");
+    const toolName = String(chunk.name || "unknown");
+    const argsFragment = String(chunk.arguments || "");
+    if (callId) {
+      let tu = toolUses.get(callId);
+      if (!tu) {
+        const blockId = newBlockId();
+        tu = { blockId, started: true, argsJson: "" };
+        toolUses.set(callId, tu);
+        envelopes.push(buildBlockStarted(runId, {
+          id: blockId, type: "tool_use",
+          tool_call_id: callId, tool_name: toolName,
+          input: {}, input_complete: false,
+        }));
+      }
+      if (argsFragment) {
+        tu.argsJson += argsFragment;
+        envelopes.push(buildBlockDelta(runId, tu.blockId, { input_json_delta: argsFragment }));
+      }
+    }
+  } else if (event === "response.tool_use.arguments.delta") {
+    const callId = String(chunk.call_id || chunk.tool_use_id || "");
+    const tu = toolUses.get(callId);
+    if (tu && tu.started) {
+      const fragment = String(chunk.delta ?? chunk.arguments ?? "");
+      tu.argsJson += fragment;
+      // Stream the arguments JSON fragment as block.delta with the
+      // standard input_json_delta key (matches Anthropic streaming convention).
+      // Delta MUST be on the same run scope as the tool_use.start envelope.
+      envelopes.push(
+        buildBlockDelta(tu.runId || runId, tu.blockId, { input_json_delta: fragment }),
+      );
+    }
+    // else: unknown call_id; drop silently
+  } else if (event === "response.tool_use.completed") {
+    const callId = String(chunk.call_id || chunk.tool_use_id || "");
+    const tu = toolUses.get(callId);
+    if (tu && tu.started) {
+      // Try to parse accumulated argsJson; if that fails, fall back to chunk.input.
+      let finalInput = {};
+      if (chunk.input && typeof chunk.input === "object") {
+        finalInput = chunk.input;
+      } else if (tu.argsJson) {
+        try { finalInput = JSON.parse(tu.argsJson); } catch { /* keep {} */ }
+      }
+      const completedBlock = {
+        id: tu.blockId,
+        type: "tool_use",
+        tool_call_id: callId,
+        tool_name: chunk.name || chunk.tool_name || "unknown",
+        input: finalInput,
+        input_complete: true,
+      };
+      // Same run scope as the matching .start envelope.
+      const env = buildBlockCompleted(tu.runId || runId, completedBlock);
+      if (chunk.parent_tool_use_id) {
+        env.extensions = { parent_tool_use_id: chunk.parent_tool_use_id };
+      }
+      envelopes.push(env);
+      toolUses.delete(callId);
+    }
+  } else if (event === "response.tool_result") {
+    // Tool result lives in a single block — emit started + completed together.
+    const callId = String(chunk.call_id || chunk.tool_use_id || "");
+    const blockId = newBlockId();
+    const rawOutput = Array.isArray(chunk.output) ? chunk.output : [];
+    // tool_result.output[*] 是嵌套 Block（block.schema.json 递归 $ref），
+    // 每项必须独立通过 block.schema 校验：id + type + status + 各子 schema 的
+    // required（text 块要 format/text）。runtime translator 大多只传
+    // {type, format, text}，server jsonschema oneOf 会拒（误导性日志报
+    // "missing properties: format, text"，其实是 id+status 缺失导致 text 分支
+    // 也跑挂）。在 builder 层集中补全。
+    const output = rawOutput.map(normalizeToolResultOutputItem);
+    const isError = !!chunk.is_error;
+    const summary = typeof chunk.summary === "string" ? chunk.summary : undefined;
+    const block = {
+      id: blockId, type: "tool_result", tool_call_id: callId,
+      output, is_error: isError, ...(summary !== undefined ? { summary } : {}),
+    };
+    // tool_result must land on the same run scope as the originating tool_use.
+    const started = buildBlockStarted(toolRunId, block);
+    const completed = buildBlockCompleted(toolRunId, block);
+    if (chunk.parent_tool_use_id) {
+      started.extensions = { parent_tool_use_id: chunk.parent_tool_use_id };
+      completed.extensions = { parent_tool_use_id: chunk.parent_tool_use_id };
+    }
+    envelopes.push(started, completed);
+  } else if (event === "response.output_text.done") {
+    // No incremental envelope needed — full text already accumulated via deltas.
+    // If runtime carries authoritative full text on .done (e.g. picoclaw), prefer it.
+    if (typeof chunk.text === "string" && chunk.text.length > 0) {
+      text.content = chunk.text;
+    }
+  } else if (
+    event === "response.completed" ||
+    event === "response.failed" ||
+    event === "end"
+  ) {
+    // Close any still-open tool_use blocks (defensive — runtimes SHOULD emit
+    // tool_use.completed for each, but if they crash mid-call, don't leak the block).
+    // Honor the per-tool runId so child-run tools close on their own run scope.
+    for (const [callId, tu] of toolUses) {
+      if (tu.started) {
+        envelopes.push(buildBlockCompleted(tu.runId || runId, {
+          id: tu.blockId, type: "tool_use",
+          tool_call_id: callId, tool_name: "unknown", input: {}, input_complete: false,
+        }));
+      }
+    }
+    toolUses.clear();
+    // Close thinking first, then text. Then run.completed/failed.
+    // Carry the accumulated full text on the completed envelope (protocol
+    // §5.3.5: completed payload is the terminal full state of the block).
+    if (thinking.started && thinking.blockId) {
+      envelopes.push(buildBlockCompleted(runId, {
+        id: thinking.blockId,
+        type: "thinking",
+        text: thinking.content || "",
+      }));
+    }
+    if (text.started && text.blockId) {
+      envelopes.push(buildBlockCompleted(runId, {
+        id: text.blockId,
+        type: "text",
+        text: text.content || "",
+      }));
+    }
+    if (event === "response.failed") {
+      // OpenClaw's gateway (OpenAI Responses format) nests the failure under
+      // `response.error`; older/other shapes use top-level `error`. Read the
+      // nested path first so the original message (e.g. authentication_error)
+      // reaches the App instead of the generic "runtime error" fallback.
+      const errMsg =
+        chunk.response?.error?.message ||
+        chunk.error?.message ||
+        chunk.message ||
+        chunk.text ||
+        "runtime error";
+      envelopes.push(buildRunFailed(runId, "runtime.error", errMsg));
+    } else {
+      envelopes.push(buildRunCompleted(runId, "end_turn"));
+    }
+    text = { blockId: null, started: false, content: "" };
+    thinking = { blockId: null, started: false, content: "" };
+  }
+  // Unknown events: return empty envelopes
+
+  return { envelopes, blockState: { text, thinking, toolUses } };
+}
+
+/**
+ * Convenience factory: produce an empty blockState with the shape expected by
+ * `translateOpenClawChunkToEnvelope`. Callers should use this instead of
+ * hand-rolling the shape so callsites stay correct across future shape changes.
+ */
+export function newBlockState() {
+  return {
+    text: { blockId: null, started: false, content: "" },
+    thinking: { blockId: null, started: false, content: "" },
+    toolUses: new Map(),
+  };
+}