baa-conductor

commit

26bd7b6

parent

d1f0624

author

im_wower

date

2026-03-28 01:24:48 +0800 CST

feat: switch browser delivery to text-only flow

 1@@ -6,8 +6,8 @@
 2 - 当前浏览器桥接主线已经完成到“Firefox 本地 WS bridge + Claude / ChatGPT 代发 + ChatGPT / Gemini 最终消息 raw relay + live instruction ingest + dedupe/journal 本地持久化 + artifact/upload/inject/send 主链 + 结构化 action_result + shell_runtime + 登录态持久化”的阶段。
 3 - 代码和自动化测试都表明：`/describe/business`、`/describe/control`、`GET /v1/browser`、`POST /v1/browser/actions`、`POST /v1/browser/request`、`POST /v1/browser/request/cancel` 已经形成正式主链路。
 4 - 目前不应再把系统描述成“只有 Claude / ChatGPT request relay”；当前更准确的表述是“通用 browser surface 已落地，正式 request relay 已覆盖 Claude 和 ChatGPT，ChatGPT / Gemini 的 `browser.final_message` raw relay 也已接通，但这层仍只是最终消息中继，不等于 Gemini 正式 request relay 已转正”。
 5-- 当前仍不能写成“全部收尾完成”。剩余未闭项主要是：真实 Firefox 手工 smoke 未完成、风控状态仍是进程内内存态、ChatGPT 仍依赖真实浏览器登录态 / header 且没有 Claude 风格 prompt shortcut、ChatGPT / Gemini 最终消息提取仍有平台特定边界，以及 BAA 仍只做到单节点本地持久化、有界 journal、单客户端单轮 delivery 首版和 Phase 1 exact target。
 6-- 此前拆出的后续任务卡里，`T-S027`、`T-S028`、`T-S029`、`T-S030`、`T-S031`、`T-S032`、`T-S033`、`T-S034` 已完成；当前主线剩余 `T-S026`，工程侧下一波任务是 `T-S035` 和 `T-S036`。
 7+- 当前仍不能写成“全部收尾完成”。剩余未闭项主要是：风控状态仍是进程内内存态、ChatGPT 仍依赖真实浏览器登录态 / header 且没有 Claude 风格 prompt shortcut、ChatGPT / Gemini 最终消息提取仍有平台特定边界，以及 BAA 仍只做到单节点本地持久化、有界 journal、单客户端单轮 delivery 首版和 Phase 1 exact target。
 8+- 此前拆出的后续任务卡里，`T-S026`、`T-S027`、`T-S028`、`T-S029`、`T-S030`、`T-S031`、`T-S032`、`T-S033`、`T-S034` 已完成；当前主线剩余任务是 `T-S035` 和 `T-S036`。
 9 
10 ## 本次核对依据
11 
12@@ -29,6 +29,8 @@
13   - 结果：`45/45` 通过
14 - `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
15   - 结果：`8/8` 通过
16+- 真实 Firefox 手工 smoke（`plugin_status`、`tab_open`、`tab_restore`、`ws_reconnect`、扩展重载自动恢复）
17+  - 结果：通过；`ws_reconnect` 额外完成 `disconnect_ms=3000`、`repeat_count=3`、`repeat_interval_ms=500` 的 3 轮稳定性验证
18 
19 ## 当前已完成功能
20 
21@@ -293,15 +295,15 @@
22 
23 ## 当前未完成 / 待复核
24 
25-### 1. 真实 Firefox 手工 smoke 仍未完成
26+### 1. 真实 Firefox 手工 smoke 已完成
27 
28-- 代码和任务文档里都没有新增“真实 Firefox.app 上手动关 tab -> tab_restore -> WS 重连 -> 状态恢复”的实测结论。
29-- 当前自动化 smoke 是 bridge / relay / persistence 层面的模拟 E2E，不等于真实 Firefox 桌面手工验收。
30+- `2026-03-27` 已在真实 `Firefox.app` 上完成“手动关 tab -> `tab_restore` -> WS 重连 -> 状态恢复”和“扩展重载后自动恢复”验收。
31+- `plugin_status`、`tab_open`、`tab_restore`、`ws_reconnect` 与扩展重载自动恢复都已通过；当前不再把“真机浏览器管理闭环未验证”列为残余风险。
32 
33-### 2. open bug backlog 当前已清空
34+### 2. open bug backlog 未清空
35 
36 - 当前不能把“已修复 bug”误写成“所有残余风险都已消失”。
37-- 当前没有 open bug 卡，但仍保留若干非 bug 型残余风险和后续增强项。
38+- open bug backlog 见 `../bugs/README.md`；截至本次核对仍保留 `BUG-018`、`BUG-019`、`BUG-020`。
39 
40 ### 3. Gemini 已接入最终消息 raw relay，但提取仍是启发式
41 
42@@ -326,11 +328,11 @@
43 - 这轮为避免误杀，默认只在 `5min` 无活跃更新后才回收 slot，并依赖 `lease.touch(...)` 标记关键活跃点。
44 - 如果未来出现“健康但长时间完全静默”的超长 buffered 请求，理论上仍存在被保守阈值误判的风险；当前文档里应把它写成残余边界，而不是“完全没有自愈”。
45 
46-### 7. `ws_reconnect` 的自动化验证还不是 Firefox 真实 reconnect 生命周期验收
47+### 7. `ws_reconnect` 自动化与真机验收都已覆盖，但完成判定仍依赖后续状态同步
48 
49-- 当前 smoke 覆盖的是 conductor 侧 `action_result` 语义透传。
50-- 真实 Firefox 扩展运行环境里的 reconnect 生命周期本身，仍依赖后续 `hello` / 状态同步来体现“真正重连完成”。
51-- 这一层现有设计未扩改，因此仍建议在真实 Firefox 环境里补手工 smoke。
52+- 当前 smoke 既覆盖 conductor 侧 `action_result` 语义透传，也已在真实 Firefox 扩展运行环境里完成手工 reconnect 验收。
53+- `ws_reconnect` 的设计仍是“HTTP 立即返回 `completed=false`，真正恢复靠后续 `hello` / 状态同步体现”；这属于当前合同语义，不再是未验收风险。
54+- 这轮额外补做了 `disconnect_ms=3000`、`repeat_count=3`、`repeat_interval_ms=500` 的 3 轮断开重连稳定性验证。
55 
56 ### 8. ChatGPT 已转正，但仍保留平台前提边界
57 
58@@ -354,13 +356,11 @@
59 
60 ## 已拆出的后续任务
61 
62-- `T-S026`：真实 Firefox 手工 smoke 与验收记录
63 - `T-S035`：加固插件侧 delivery adapter 与页面交付流程
64 - `T-S036`：补 artifact download 合同与 binary delivery 能力
65 
66 ## 下一波任务
67 
68-- `T-S026` 仍是主线第一优先级，因为这是当前唯一未完成的真实 Firefox 环境验收。
69 - `T-S035` 负责把 `Claude` / `ChatGPT` 的插件侧 `upload / inject / send` 从首版 DOM heuristic 收口成更稳定的 adapter 和 fail-closed 路径。
70 - `T-S036` 负责把当前本地 `download_url` + base64 JSON 的 artifact payload 合同升级到更适合 binary-safe delivery 的形式，同时保持现有 text/json 兼容。
71 
72@@ -381,4 +381,4 @@
73 
74 如果只写一段给外部协作者看，可以用下面这版：
75 
76-> 当前代码已经完成单节点 `mini` 主接口收口，以及 Firefox 本地 bridge 下的 Claude / ChatGPT request relay 主链路、ChatGPT / Gemini 最终消息 raw relay、conductor 侧 live instruction ingest、dedupe / execution journal 本地持久化，以及 artifact / upload / inject / send 主链。`GET /v1/browser`、`POST /v1/browser/actions`、`POST /v1/browser/request`、`POST /v1/browser/request/cancel`、正式 SSE、结构化 `action_result`、`shell_runtime`、登录态元数据持久化、`browser.final_message` 最近快照、`instruction_ingest` 最近摘要、upload receipt barrier，以及 `BUG-012` 的 stale `inFlight` 自愈清扫都已落地；`BUG-011`、`BUG-012`、`BUG-013`、`BUG-014`、`BUG-017` 也已在当前代码中修复，并已通过 `conductor-daemon build`、`index.test.js`（45/45）和 browser-control e2e smoke（8/8）。当前剩余缺口主要是：真实 Firefox 手工 smoke 未完成、ChatGPT / Gemini 最终消息提取仍有平台边界、插件侧 upload / inject / send 仍是首版 DOM heuristic、artifact payload 仍以本地 `download_url` 的 base64 JSON 形式提供且未覆盖大二进制 / download 闭环、BAA 仍只做单节点本地持久化、execution journal 只保留最近窗口，以及 live 执行路径仍只覆盖 Phase 1 exact target。
77+> 当前代码已经完成单节点 `mini` 主接口收口，以及 Firefox 本地 bridge 下的 Claude / ChatGPT request relay 主链路、ChatGPT / Gemini 最终消息 raw relay、conductor 侧 live instruction ingest、dedupe / execution journal 本地持久化，以及 artifact / upload / inject / send 主链。`GET /v1/browser`、`POST /v1/browser/actions`、`POST /v1/browser/request`、`POST /v1/browser/request/cancel`、正式 SSE、结构化 `action_result`、`shell_runtime`、登录态元数据持久化、`browser.final_message` 最近快照、`instruction_ingest` 最近摘要、upload receipt barrier，以及 `BUG-012` 的 stale `inFlight` 自愈清扫都已落地；`BUG-011`、`BUG-012`、`BUG-013`、`BUG-014`、`BUG-017` 也已在当前代码中修复，并已通过 `conductor-daemon build`、`index.test.js`（45/45）、browser-control e2e smoke（8/8）和 `2026-03-27` 的真实 Firefox 手工 smoke。当前剩余缺口主要是：ChatGPT / Gemini 最终消息提取仍有平台边界、插件侧 upload / inject / send 仍是首版 DOM heuristic、artifact payload 仍以本地 `download_url` 的 base64 JSON 形式提供且未覆盖大二进制 / download 闭环、BAA 仍只做单节点本地持久化、execution journal 只保留最近窗口，以及 live 执行路径仍只覆盖 Phase 1 exact target。

 1@@ -72,9 +72,13 @@ scripts/
 2   runtime/
 3 plans/
 4   STATUS_SUMMARY.md
 5+  archive/
 6 tasks/
 7   TASK_OVERVIEW.md
 8+  archive/
 9 bugs/
10+  README.md
11+  archive/
12 docs/
13   api/
14   auth/
15@@ -84,6 +88,8 @@ docs/
16   runtime/
17 ```
18 
19+已完成的任务卡、需求文档和缺陷文档现在统一放在各自目录下的 `archive/` 子目录。
20+
21 ## 当前约定
22 
23 - 所有新接口设计默认先落 `mini` 本地 `4317`

  1@@ -1,14 +1,9 @@
  2 import assert from "node:assert/strict";
  3-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
  4-import { tmpdir } from "node:os";
  5-import { join } from "node:path";
  6 import test from "node:test";
  7 
  8 import {
  9-  buildBaaArtifactManifest,
 10-  buildBaaDeliveryPlan,
 11-  materializeBaaExecutionArtifacts,
 12-  renderBaaArtifactIndexText
 13+  DEFAULT_BAA_DELIVERY_LINE_LIMIT,
 14+  renderBaaDeliveryMessageText
 15 } from "../dist/index.js";
 16 
 17 function createExecutionResult(overrides = {}) {
 18@@ -33,38 +28,34 @@ function createExecutionResult(overrides = {}) {
 19   };
 20 }
 21 
 22-test("artifact materializer turns exec output into artifact, manifest, and delivery plan uploads", async () => {
 23-  const outputDir = mkdtempSync(join(tmpdir(), "baa-conductor-artifacts-exec-"));
 24+function createProcessResult(executions, instructions = []) {
 25+  return {
 26+    blocks: [],
 27+    duplicates: [],
 28+    executions,
 29+    instructions,
 30+    status: executions.length === 0 ? "no_instructions" : "executed"
 31+  };
 32+}
 33 
 34-  try {
 35-    const materialization = await materializeBaaExecutionArtifacts(
 36-      [
 37-        {
 38-          blockIndex: 2,
 39-          execution: createExecutionResult({
 40+test("renderBaaDeliveryMessageText renders plain-text execution details", () => {
 41+  const rendered = renderBaaDeliveryMessageText(
 42+    {
 43+      assistantMessageId: "msg-render-plain",
 44+      conversationId: "conv-render-plain",
 45+      platform: "chatgpt",
 46+      processResult: createProcessResult(
 47+        [
 48+          createExecutionResult({
 49             data: {
 50-              ok: true,
 51-              operation: "exec",
 52-              input: {
 53-                command: "printf 'hello artifact'",
 54-                cwd: "/tmp",
 55-                maxBufferBytes: 1024,
 56-                timeoutMs: 2000
 57-              },
 58-              result: {
 59-                durationMs: 4,
 60-                exitCode: 0,
 61-                finishedAt: "2026-03-27T12:00:01.000Z",
 62-                signal: null,
 63-                startedAt: "2026-03-27T12:00:00.000Z",
 64-                stderr: "",
 65-                stdout: "hello artifact",
 66-                timedOut: false
 67-              }
 68+              b: 2,
 69+              a: 1
 70             },
 71-            dedupeKey: "dedupe-exec-1",
 72-            instructionId: "inst_exec_01",
 73-            requestId: "req-exec-1",
 74+            details: {
 75+              retryable: false
 76+            },
 77+            instructionId: "inst_render_01",
 78+            message: "command completed",
 79             route: {
 80               key: "local.exec",
 81               method: "POST",
 82@@ -72,256 +63,81 @@ test("artifact materializer turns exec output into artifact, manifest, and deliv
 83             },
 84             tool: "exec"
 85           })
 86-        }
 87-      ],
 88-      {
 89-        artifactOnlyTextBytes: 2000,
 90-        inlineTextBytes: 200,
 91-        outputDir,
 92-        roundId: "r03",
 93-        traceId: "trace_artifacts"
 94-      }
 95-    );
 96-
 97-    assert.equal(materialization.results[0].deliveryMode, "inline_and_artifact");
 98-    assert.equal(materialization.artifacts.length, 1);
 99-    assert.match(materialization.results[0].summary, /exec succeeded/);
100-    assert.equal(existsSync(materialization.artifacts[0].localPath), true);
101-    assert.match(readFileSync(materialization.artifacts[0].localPath, "utf8"), /\[stdout\]\nhello artifact/);
102-
103-    const manifestBundle = await buildBaaArtifactManifest(materialization);
104-    const indexText = renderBaaArtifactIndexText(materialization, manifestBundle);
105-    const plan = buildBaaDeliveryPlan({
106-      conversationId: "conv_exec",
107-      indexText,
108-      manifestBundle,
109-      materialization,
110-      target: "browser.claude"
111-    });
112-
113-    assert.equal(plan.uploads.length, 2);
114-    assert.deepEqual(plan.pendingBarriers, ["upload_receipt"]);
115-    assert.equal(plan.receiptBarrierImplemented, true);
116-    assert.match(indexText, /instruction_id: inst_exec_01/);
117-    assert.match(indexText, /baa-result_trace-artifacts_r03_b02_exec_conductor_ok\.log/);
118-    assert.match(indexText, /baa-manifest_trace-artifacts_r03\.json/);
119-  } finally {
120-    rmSync(outputDir, {
121-      force: true,
122-      recursive: true
123-    });
124-  }
125-});
126-
127-test("files/read small and large payloads do not collapse to the same delivery strategy", async () => {
128-  const outputDir = mkdtempSync(join(tmpdir(), "baa-conductor-artifacts-files-read-"));
129-  const largeContent = `HEADER\n${"0123456789".repeat(700)}\nTAIL_MARKER`;
130-
131-  try {
132-    const materialization = await materializeBaaExecutionArtifacts(
133-      [
134-        {
135-          blockIndex: 1,
136-          execution: createExecutionResult({
137-            data: {
138-              ok: true,
139-              operation: "files/read",
140-              input: {
141-                cwd: "/tmp",
142-                encoding: "utf8",
143-                path: "small.txt"
144-              },
145-              result: {
146-                absolutePath: "/tmp/small.txt",
147-                content: "small text\n",
148-                encoding: "utf8",
149-                modifiedAt: "2026-03-27T12:00:00.000Z",
150-                sizeBytes: 11
151-              }
152-            },
153-            dedupeKey: "dedupe-read-small",
154-            instructionId: "inst_read_small",
155-            route: {
156-              key: "local.files.read",
157-              method: "POST",
158-              path: "/v1/files/read"
159-            },
160-            tool: "files/read"
161-          })
162-        },
163-        {
164-          blockIndex: 2,
165-          execution: createExecutionResult({
166-            data: {
167-              ok: true,
168-              operation: "files/read",
169-              input: {
170-                cwd: "/tmp",
171-                encoding: "utf8",
172-                path: "large.txt"
173-              },
174-              result: {
175-                absolutePath: "/tmp/large.txt",
176-                content: largeContent,
177-                encoding: "utf8",
178-                modifiedAt: "2026-03-27T12:00:00.000Z",
179-                sizeBytes: largeContent.length
180-              }
181-            },
182-            dedupeKey: "dedupe-read-large",
183-            instructionId: "inst_read_large",
184-            route: {
185-              key: "local.files.read",
186-              method: "POST",
187-              path: "/v1/files/read"
188+        ],
189+        [
190+          {
191+            blockIndex: 3,
192+            dedupeBasis: {
193+              assistant_message_id: "msg-render-plain",
194+              block_index: 3,
195+              conversation_id: "conv-render-plain",
196+              params: null,
197+              platform: "chatgpt",
198+              target: "conductor",
199+              tool: "exec",
200+              version: "baa.v1"
201             },
202-            tool: "files/read"
203-          })
204-        }
205-      ],
206-      {
207-        artifactOnlyTextBytes: 1024,
208-        inlineTextBytes: 128,
209-        outputDir,
210-        roundId: "r05",
211-        traceId: "trace_files"
212-      }
213-    );
214-    const manifestBundle = await buildBaaArtifactManifest(materialization);
215-    const indexText = renderBaaArtifactIndexText(materialization, manifestBundle);
216-    const plan = buildBaaDeliveryPlan({
217-      indexText,
218-      manifestBundle,
219-      materialization,
220-      target: "browser.chatgpt"
221-    });
222+            dedupeKey: "dedupe-default",
223+            envelopeVersion: "baa.v1",
224+            instructionId: "inst_render_01",
225+            params: null,
226+            paramsKind: "none",
227+            platform: "chatgpt",
228+            rawBlock: "```baa```",
229+            rawInstruction: "@conductor::exec",
230+            target: "conductor",
231+            tool: "exec",
232+            assistantMessageId: "msg-render-plain",
233+            conversationId: "conv-render-plain"
234+          }
235+        ]
236+      )
237+    }
238+  );
239 
240-    assert.equal(materialization.results[0].deliveryMode, "inline");
241-    assert.equal(materialization.results[0].artifacts.length, 0);
242-    assert.equal(materialization.results[1].deliveryMode, "artifact_only");
243-    assert.equal(materialization.results[1].artifacts.length, 1);
244-    assert.match(indexText, /small text/);
245-    assert.match(indexText, /baa-result_trace-files_r05_b02_files-read_conductor_ok\.txt/);
246-    assert.doesNotMatch(indexText, /TAIL_MARKER/);
247-    assert.equal(plan.uploads.length, 2);
248-  } finally {
249-    rmSync(outputDir, {
250-      force: true,
251-      recursive: true
252-    });
253-  }
254+  assert.equal(rendered.executionCount, 1);
255+  assert.equal(rendered.messageTruncated, false);
256+  assert.match(rendered.messageText, /\[BAA 执行结果\]/u);
257+  assert.match(rendered.messageText, /assistant_message_id: msg-render-plain/u);
258+  assert.match(rendered.messageText, /block_index: 3/u);
259+  assert.match(rendered.messageText, /message:\ncommand completed/u);
260+  assert.match(rendered.messageText, /data:\n  a: 1\n  b: 2/u);
261+  assert.match(rendered.messageText, /details:\n  retryable: false/u);
262 });
263 
264-test("manifest order stays stable across multiple results and missing optional fields do not crash materialization", async () => {
265-  const outputDir = mkdtempSync(join(tmpdir(), "baa-conductor-artifacts-order-"));
266-
267-  try {
268-    const materialization = await materializeBaaExecutionArtifacts(
269-      [
270-        {
271-          blockIndex: 3,
272-          execution: createExecutionResult({
273-            data: {
274-              daemon: {
275-                leaseState: "leader"
276-              },
277-              runtime: {
278-                started: true
279-              }
280-            },
281-            dedupeKey: "dedupe-status",
282-            instructionId: "inst_status",
283-            message: null,
284-            requestId: null,
285-            route: {
286-              key: "local.status",
287-              method: "GET",
288-              path: "/v1/status"
289-            },
290-            tool: "status"
291-          })
292-        },
293-        {
294-          blockIndex: 1,
295-          execution: createExecutionResult({
296-            data: {
297-              endpoints: [
298-                {
299-                  method: "GET",
300-                  path: "/describe/control"
301-                }
302-              ],
303-              surface: "control"
304-            },
305-            dedupeKey: "dedupe-describe",
306-            instructionId: "inst_describe",
307-            route: {
308-              key: "local.describe.control",
309-              method: "GET",
310-              path: "/describe/control"
311-            },
312-            tool: "describe/control"
313-          })
314-        },
315-        {
316-          blockIndex: 2,
317-          execution: createExecutionResult({
318-            data: {
319-              ok: true,
320-              operation: "files/write",
321-              input: {
322-                content: "hello",
323-                createParents: false,
324-                cwd: "/tmp",
325-                encoding: "utf8",
326-                overwrite: true,
327-                path: "written.txt"
328-              },
329-              result: {
330-                absolutePath: "/tmp/written.txt",
331-                bytesWritten: 5,
332-                created: true,
333-                encoding: "utf8",
334-                modifiedAt: "2026-03-27T12:00:00.000Z"
335-              }
336-            },
337-            dedupeKey: "dedupe-write",
338-            details: null,
339-            instructionId: "inst_write",
340-            requestId: null,
341-            route: {
342-              key: "local.files.write",
343-              method: "POST",
344-              path: "/v1/files/write"
345-            },
346-            tool: "files/write"
347-          })
348-        }
349-      ],
350-      {
351-        artifactOnlyTextBytes: 512,
352-        inlineTextBytes: 32,
353-        outputDir,
354-        roundId: "r07",
355-        traceId: "trace_order"
356-      }
357-    );
358-    const manifestBundle = await buildBaaArtifactManifest(materialization);
359+test("renderBaaDeliveryMessageText truncates overlong output and appends marker", () => {
360+  const stdout = Array.from({
361+    length: DEFAULT_BAA_DELIVERY_LINE_LIMIT + 20
362+  }, (_, index) => `line-${index + 1}`).join("\n");
363+  const rendered = renderBaaDeliveryMessageText(
364+    {
365+      assistantMessageId: "msg-render-truncated",
366+      conversationId: "conv-render-truncated",
367+      platform: "claude",
368+      processResult: createProcessResult([
369+        createExecutionResult({
370+          data: {
371+            result: {
372+              stdout
373+            }
374+          },
375+          instructionId: "inst_render_truncated",
376+          route: {
377+            key: "local.exec",
378+            method: "POST",
379+            path: "/v1/exec"
380+          },
381+          tool: "exec"
382+        })
383+      ])
384+    }
385+  );
386 
387-    assert.deepEqual(
388-      materialization.results.map((entry) => entry.instructionId),
389-      ["inst_describe", "inst_write", "inst_status"]
390-    );
391-    assert.deepEqual(
392-      manifestBundle.manifest.results.map((entry) => entry.blockIndex),
393-      [1, 2, 3]
394-    );
395-    assert.equal(manifestBundle.manifest.resultCount, 3);
396-    assert.equal(manifestBundle.manifest.notes.length >= 2, true);
397-  } finally {
398-    rmSync(outputDir, {
399-      force: true,
400-      recursive: true
401-    });
402-  }
403+  assert.equal(rendered.messageLineLimit, DEFAULT_BAA_DELIVERY_LINE_LIMIT);
404+  assert.equal(rendered.messageTruncated, true);
405+  assert.equal(rendered.messageLineCount, DEFAULT_BAA_DELIVERY_LINE_LIMIT + 1);
406+  assert.ok(rendered.sourceLineCount > rendered.messageLineCount);
407+  assert.match(rendered.messageText, /line-1/u);
408+  assert.doesNotMatch(rendered.messageText, /line-220/u);
409+  assert.match(rendered.messageText, /超长截断$/u);
410 });

 1@@ -1,46 +0,0 @@
 2-import type {
 3-  BaaDeliveryPlan,
 4-  BaaDeliveryUploadItem,
 5-  BuildBaaDeliveryPlanInput
 6-} from "./types.js";
 7-
 8-function toUploadItem(artifact: {
 9-  artifactId: string;
10-  filename: string;
11-  localPath: string;
12-  mimeType: string;
13-  sha256: string;
14-  sizeBytes: number;
15-}): BaaDeliveryUploadItem {
16-  return {
17-    artifactId: artifact.artifactId,
18-    filename: artifact.filename,
19-    localPath: artifact.localPath,
20-    mimeType: artifact.mimeType,
21-    sha256: artifact.sha256,
22-    sizeBytes: artifact.sizeBytes
23-  };
24-}
25-
26-export function buildBaaDeliveryPlan(input: BuildBaaDeliveryPlanInput): BaaDeliveryPlan {
27-  const uploads = input.materialization.artifacts.map((artifact) => toUploadItem(artifact));
28-
29-  if (uploads.length > 0) {
30-    uploads.push(toUploadItem(input.manifestBundle.artifact));
31-  }
32-
33-  return {
34-    autoSend: input.autoSend ?? false,
35-    conversationId: input.conversationId ?? null,
36-    manifestId: input.manifestBundle.manifest.manifestId,
37-    messageText: input.indexText,
38-    pendingBarriers: uploads.length === 0 ? [] : ["upload_receipt"],
39-    planId: `plan_${input.materialization.traceId}_${input.materialization.roundId}`,
40-    receiptBarrierImplemented: true,
41-    roundId: input.materialization.roundId,
42-    target: input.target,
43-    traceId: input.materialization.traceId,
44-    uploads,
45-    version: "baa.delivery-plan.v1"
46-  };
47-}

1@@ -1,5 +1,2 @@
2 export * from "./types.js";
3-export * from "./materialize.js";
4-export * from "./manifest.js";
5-export * from "./delivery-plan.js";
6 export * from "./upload-session.js";

  1@@ -1,150 +0,0 @@
  2-import { createHash } from "node:crypto";
  3-import { writeFile } from "node:fs/promises";
  4-import { join } from "node:path";
  5-
  6-import type {
  7-  BaaArtifactManifest,
  8-  BaaArtifactManifestBundle,
  9-  BaaArtifactMaterialization,
 10-  BaaMaterializedArtifactRef
 11-} from "./types.js";
 12-
 13-function bytesOf(text: string): number {
 14-  return Buffer.byteLength(text, "utf8");
 15-}
 16-
 17-function sanitizeSegment(value: string): string {
 18-  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/gu, "-");
 19-  const collapsed = normalized.replace(/-+/gu, "-").replace(/^-|-$/gu, "");
 20-  return collapsed === "" ? "unknown" : collapsed;
 21-}
 22-
 23-function toManifestArtifactEntry(artifact: BaaMaterializedArtifactRef) {
 24-  return {
 25-    artifactId: artifact.artifactId,
 26-    blockIndex: artifact.blockIndex,
 27-    filename: artifact.filename,
 28-    instructionId: artifact.instructionId,
 29-    kind: artifact.kind,
 30-    localPath: artifact.localPath,
 31-    mimeType: artifact.mimeType,
 32-    sequence: artifact.sequence,
 33-    sha256: artifact.sha256,
 34-    sizeBytes: artifact.sizeBytes,
 35-    target: artifact.target,
 36-    tool: artifact.tool
 37-  };
 38-}
 39-
 40-function toManifestResultEntry(materialization: BaaArtifactMaterialization) {
 41-  return materialization.results.map((result) => ({
 42-    artifactIds: result.artifacts.map((artifact) => artifact.artifactId),
 43-    blockIndex: result.blockIndex,
 44-    dedupeKey: result.dedupeKey,
 45-    deliveryMode: result.deliveryMode,
 46-    errorCode: result.errorCode,
 47-    httpStatus: result.httpStatus,
 48-    instructionId: result.instructionId,
 49-    ok: result.ok,
 50-    requestId: result.requestId,
 51-    route: {
 52-      key: result.route.key,
 53-      method: result.route.method,
 54-      path: result.route.path
 55-    },
 56-    sequence: result.sequence,
 57-    summary: result.summary,
 58-    target: result.target,
 59-    tool: result.tool
 60-  }));
 61-}
 62-
 63-export async function buildBaaArtifactManifest(
 64-  materialization: BaaArtifactMaterialization
 65-): Promise<BaaArtifactManifestBundle> {
 66-  const manifest: BaaArtifactManifest = {
 67-    artifactCount: materialization.artifacts.length,
 68-    artifacts: materialization.artifacts.map((artifact) => toManifestArtifactEntry(artifact)),
 69-    createdAt: materialization.createdAt,
 70-    manifestId: `mf_${sanitizeSegment(materialization.traceId)}_${sanitizeSegment(materialization.roundId)}`,
 71-    notes: [
 72-      "Service-side artifact materialization, manifest generation, delivery-plan generation, and upload receipt barrier are implemented in conductor.",
 73-      "Firefox bridge delivery currently covers upload_artifacts, upload_receipt, inject_message, and send_message for the single-client live path."
 74-    ],
 75-    resultCount: materialization.results.length,
 76-    results: toManifestResultEntry(materialization),
 77-    roundId: materialization.roundId,
 78-    traceId: materialization.traceId,
 79-    version: "baa.manifest.v1"
 80-  };
 81-  const content = `${JSON.stringify(manifest, null, 2)}\n`;
 82-  const filename = `baa-manifest_${sanitizeSegment(materialization.traceId)}_${sanitizeSegment(materialization.roundId)}.json`;
 83-  const localPath = join(materialization.outputDir, filename);
 84-
 85-  await writeFile(localPath, content, "utf8");
 86-
 87-  return {
 88-    artifact: {
 89-      artifactId: manifest.manifestId,
 90-      blockIndex: null,
 91-      createdAt: materialization.createdAt,
 92-      filename,
 93-      instructionId: null,
 94-      kind: "manifest",
 95-      localPath,
 96-      mimeType: "application/json",
 97-      sequence: materialization.results.length,
 98-      sha256: createHash("sha256").update(content).digest("hex"),
 99-      sizeBytes: bytesOf(content),
100-      target: null,
101-      tool: null
102-    },
103-    manifest
104-  };
105-}
106-
107-export function renderBaaArtifactIndexText(
108-  materialization: BaaArtifactMaterialization,
109-  manifestBundle: BaaArtifactManifestBundle
110-): string {
111-  const lines = [
112-    "[BAA Result Index]",
113-    `- trace_id: ${materialization.traceId}`,
114-    `- round_id: ${materialization.roundId}`,
115-    `- manifest_id: ${manifestBundle.manifest.manifestId}`
116-  ];
117-
118-  for (const result of materialization.results) {
119-    lines.push("");
120-    lines.push(`- instruction_id: ${result.instructionId}`);
121-    lines.push(`- tool: ${result.target}::${result.tool}`);
122-    lines.push(`- status: ${result.ok ? "ok" : "failed"}`);
123-    lines.push(`- delivery_mode: ${result.deliveryMode}`);
124-    lines.push(`- summary: ${result.summary}`);
125-
126-    if (result.deliveryMode === "inline" && result.inlineText != null) {
127-      lines.push("- inline_text:");
128-      lines.push("```text");
129-      lines.push(result.inlineText.trimEnd());
130-      lines.push("```");
131-    } else if (result.deliveryMode === "inline_and_artifact") {
132-      const excerpt = result.previewText ?? result.inlineText;
133-
134-      if (excerpt != null && excerpt.trim() !== "") {
135-        lines.push("- excerpt:");
136-        lines.push("```text");
137-        lines.push(excerpt.trimEnd());
138-        lines.push("```");
139-      }
140-    }
141-
142-    if (result.artifacts.length > 0) {
143-      lines.push(`- artifacts: ${result.artifacts.map((artifact) => artifact.filename).join(", ")}`);
144-    }
145-  }
146-
147-  lines.push("");
148-  lines.push(`- manifest: ${manifestBundle.artifact.filename}`);
149-
150-  return `${lines.join("\n")}\n`;
151-}

  1@@ -1,712 +0,0 @@
  2-import { createHash } from "node:crypto";
  3-import { mkdir, writeFile } from "node:fs/promises";
  4-import { join } from "node:path";
  5-
  6-import {
  7-  sortBaaJsonValue,
  8-  type BaaInstructionExecutionResult,
  9-  type BaaJsonValue
 10-} from "../instructions/types.js";
 11-import type {
 12-  BaaArtifactContentKind,
 13-  BaaArtifactKind,
 14-  BaaArtifactMaterialization,
 15-  BaaArtifactMaterializeCandidate,
 16-  BaaArtifactMaterializeOptions,
 17-  BaaDeliveryMode,
 18-  BaaMaterializedArtifactRef,
 19-  BaaMaterializedResult
 20-} from "./types.js";
 21-
 22-export const DEFAULT_INLINE_TEXT_BYTES = 600;
 23-export const DEFAULT_ARTIFACT_ONLY_TEXT_BYTES = 4_096;
 24-export const DEFAULT_PREVIEW_CHARS = 240;
 25-
 26-interface JsonRecord {
 27-  [key: string]: BaaJsonValue;
 28-}
 29-
 30-interface Thresholds {
 31-  artifactOnlyTextBytes: number;
 32-  inlineTextBytes: number;
 33-  previewChars: number;
 34-}
 35-
 36-interface PreparedCandidate {
 37-  blockIndex: number | null;
 38-  execution: BaaInstructionExecutionResult;
 39-  sequence: number;
 40-}
 41-
 42-interface ArtifactSpec {
 43-  content: string;
 44-  extension: string;
 45-  kind: BaaArtifactKind;
 46-  mimeType: string;
 47-}
 48-
 49-interface MaterializedDraft {
 50-  artifactSpec: ArtifactSpec | null;
 51-  contentBytes: number;
 52-  contentKind: BaaArtifactContentKind;
 53-  deliveryMode: BaaDeliveryMode;
 54-  errorCode: string | null;
 55-  inlineText: string | null;
 56-  ok: boolean;
 57-  previewText: string | null;
 58-  summary: string;
 59-}
 60-
 61-interface TextDeliveryDecision {
 62-  deliveryMode: BaaDeliveryMode;
 63-  inlineText: string | null;
 64-  previewText: string | null;
 65-  shouldArtifact: boolean;
 66-}
 67-
 68-function asRecord(value: BaaJsonValue | null): JsonRecord | null {
 69-  if (value == null || typeof value !== "object" || Array.isArray(value)) {
 70-    return null;
 71-  }
 72-
 73-  return value as JsonRecord;
 74-}
 75-
 76-function readBooleanValue(record: JsonRecord | null, key: string): boolean | null {
 77-  const value = record?.[key];
 78-  return typeof value === "boolean" ? value : null;
 79-}
 80-
 81-function readNumberValue(record: JsonRecord | null, key: string): number | null {
 82-  const value = record?.[key];
 83-  return typeof value === "number" && Number.isFinite(value) ? value : null;
 84-}
 85-
 86-function readObjectValue(record: JsonRecord | null, key: string): JsonRecord | null {
 87-  return asRecord(record?.[key] ?? null);
 88-}
 89-
 90-function readStringValue(record: JsonRecord | null, key: string): string | null {
 91-  const value = record?.[key];
 92-  return typeof value === "string" ? value : null;
 93-}
 94-
 95-function bytesOf(text: string): number {
 96-  return Buffer.byteLength(text, "utf8");
 97-}
 98-
 99-function buildArtifactId(traceId: string, roundId: string, artifactSequence: number): string {
100-  return `art_${sanitizeSegment(traceId)}_${sanitizeSegment(roundId)}_${String(artifactSequence).padStart(3, "0")}`;
101-}
102-
103-function buildArtifactFilename(
104-  traceId: string,
105-  roundId: string,
106-  blockIndex: number | null,
107-  sequence: number,
108-  tool: string,
109-  target: string,
110-  ok: boolean,
111-  extension: string
112-): string {
113-  const blockLabel =
114-    blockIndex == null
115-      ? `s${String(sequence + 1).padStart(2, "0")}`
116-      : `b${String(blockIndex).padStart(2, "0")}`;
117-
118-  return [
119-    "baa-result",
120-    sanitizeSegment(traceId),
121-    sanitizeSegment(roundId),
122-    blockLabel,
123-    sanitizeSegment(tool),
124-    sanitizeSegment(target),
125-    ok ? "ok" : "fail"
126-  ].join("_") + `.${extension}`;
127-}
128-
129-function buildDefaultSummary(execution: BaaInstructionExecutionResult): string {
130-  const detail = truncateText(execution.message ?? execution.error ?? "completed", 96);
131-  return execution.ok ? `${execution.tool} completed: ${detail}` : `${execution.tool} failed: ${detail}`;
132-}
133-
134-function buildFailureText(execution: BaaInstructionExecutionResult): string {
135-  const sections: string[] = [];
136-
137-  if (execution.message) {
138-    sections.push(`message: ${execution.message}`);
139-  }
140-
141-  if (execution.error) {
142-    sections.push(`error: ${execution.error}`);
143-  }
144-
145-  if (execution.details != null) {
146-    sections.push(`[details]\n${stablePrettyJson(execution.details).trimEnd()}`);
147-  }
148-
149-  return sections.join("\n\n");
150-}
151-
152-function buildStructuredSummary(execution: BaaInstructionExecutionResult, data: BaaJsonValue | null): string {
153-  const root = asRecord(data);
154-
155-  if (execution.tool === "status") {
156-    const daemon = readObjectValue(root, "daemon");
157-    const runtime = readObjectValue(root, "runtime");
158-    const leaseState = readStringValue(daemon, "leaseState") ?? "unknown";
159-    const started = readBooleanValue(runtime, "started");
160-    return `status returned daemon=${leaseState}, runtime.started=${started == null ? "unknown" : String(started)}`;
161-  }
162-
163-  const surface = readStringValue(root, "surface");
164-  const endpoints = root?.endpoints;
165-  const endpointCount = Array.isArray(endpoints) ? endpoints.length : null;
166-  const baseSummary =
167-    surface == null
168-      ? `${execution.tool} returned structured JSON`
169-      : `${execution.tool} returned surface=${surface}`;
170-
171-  return endpointCount == null ? baseSummary : `${baseSummary} (${endpointCount} endpoints)`;
172-}
173-
174-function createTimestamp(input: string | undefined): string {
175-  if (typeof input === "string" && input.trim() !== "") {
176-    return input;
177-  }
178-
179-  return new Date().toISOString();
180-}
181-
182-function decideTextDelivery(
183-  text: string,
184-  thresholds: Thresholds,
185-  options: {
186-    alwaysArtifact?: boolean;
187-    binaryLike?: boolean;
188-  } = {}
189-): TextDeliveryDecision {
190-  const binaryLike = options.binaryLike ?? looksBinaryLike(text);
191-  const contentBytes = bytesOf(text);
192-
193-  if (contentBytes === 0) {
194-    return {
195-      deliveryMode: "inline",
196-      inlineText: null,
197-      previewText: null,
198-      shouldArtifact: options.alwaysArtifact === true
199-    };
200-  }
201-
202-  if (binaryLike) {
203-    return {
204-      deliveryMode: "artifact_only",
205-      inlineText: null,
206-      previewText: null,
207-      shouldArtifact: true
208-    };
209-  }
210-
211-  if (contentBytes <= thresholds.inlineTextBytes) {
212-    if (options.alwaysArtifact === true) {
213-      return {
214-        deliveryMode: "inline_and_artifact",
215-        inlineText: text,
216-        previewText: null,
217-        shouldArtifact: true
218-      };
219-    }
220-
221-    return {
222-      deliveryMode: "inline",
223-      inlineText: text,
224-      previewText: null,
225-      shouldArtifact: false
226-    };
227-  }
228-
229-  if (contentBytes <= thresholds.artifactOnlyTextBytes) {
230-    return {
231-      deliveryMode: "inline_and_artifact",
232-      inlineText: null,
233-      previewText: truncateText(text, thresholds.previewChars),
234-      shouldArtifact: true
235-    };
236-  }
237-
238-  return {
239-    deliveryMode: "artifact_only",
240-    inlineText: null,
241-    previewText: null,
242-    shouldArtifact: true
243-  };
244-}
245-
246-function extractErrorCode(
247-  execution: BaaInstructionExecutionResult,
248-  record: JsonRecord | null
249-): string | null {
250-  const errorRecord = readObjectValue(record, "error");
251-  return readStringValue(errorRecord, "code") ?? execution.error;
252-}
253-
254-async function createArtifact(
255-  prepared: PreparedCandidate,
256-  draft: MaterializedDraft,
257-  artifactSequence: number,
258-  options: BaaArtifactMaterializeOptions,
259-  createdAt: string
260-): Promise<BaaMaterializedArtifactRef | null> {
261-  const spec = draft.artifactSpec;
262-
263-  if (spec == null) {
264-    return null;
265-  }
266-
267-  const artifactId = buildArtifactId(options.traceId, options.roundId, artifactSequence);
268-  const filename = buildArtifactFilename(
269-    options.traceId,
270-    options.roundId,
271-    prepared.blockIndex,
272-    prepared.sequence,
273-    prepared.execution.tool,
274-    prepared.execution.target,
275-    draft.ok,
276-    spec.extension
277-  );
278-  const localPath = join(options.outputDir, filename);
279-
280-  await writeFile(localPath, spec.content, "utf8");
281-
282-  return {
283-    artifactId,
284-    blockIndex: prepared.blockIndex,
285-    createdAt,
286-    filename,
287-    instructionId: prepared.execution.instructionId,
288-    kind: spec.kind,
289-    localPath,
290-    mimeType: spec.mimeType,
291-    sequence: prepared.sequence,
292-    sha256: createHash("sha256").update(spec.content).digest("hex"),
293-    sizeBytes: bytesOf(spec.content),
294-    target: prepared.execution.target,
295-    tool: prepared.execution.tool
296-  };
297-}
298-
299-function isNonNegativeInteger(value: number | null | undefined): value is number {
300-  return typeof value === "number" && Number.isInteger(value) && value >= 0;
301-}
302-
303-function looksBinaryLike(text: string): boolean {
304-  if (text.includes("\0")) {
305-    return true;
306-  }
307-
308-  let controlCount = 0;
309-
310-  for (const char of text) {
311-    const codePoint = char.codePointAt(0);
312-
313-    if (codePoint == null) {
314-      continue;
315-    }
316-
317-    if ((codePoint >= 0 && codePoint < 32 && codePoint !== 9 && codePoint !== 10 && codePoint !== 13) || codePoint === 127) {
318-      controlCount += 1;
319-    }
320-  }
321-
322-  return controlCount >= 16 && controlCount / Math.max(text.length, 1) > 0.05;
323-}
324-
325-function normalizeThresholds(options: BaaArtifactMaterializeOptions): Thresholds {
326-  const inlineTextBytes =
327-    isNonNegativeInteger(options.inlineTextBytes) && options.inlineTextBytes > 0
328-      ? options.inlineTextBytes
329-      : DEFAULT_INLINE_TEXT_BYTES;
330-  const requestedArtifactOnlyBytes =
331-    isNonNegativeInteger(options.artifactOnlyTextBytes) && options.artifactOnlyTextBytes > 0
332-      ? options.artifactOnlyTextBytes
333-      : DEFAULT_ARTIFACT_ONLY_TEXT_BYTES;
334-
335-  return {
336-    artifactOnlyTextBytes: Math.max(requestedArtifactOnlyBytes, inlineTextBytes + 1),
337-    inlineTextBytes,
338-    previewChars:
339-      isNonNegativeInteger(options.previewChars) && options.previewChars > 3
340-        ? options.previewChars
341-        : DEFAULT_PREVIEW_CHARS
342-  };
343-}
344-
345-function prepareCandidates(
346-  inputs: readonly BaaArtifactMaterializeCandidate[]
347-): PreparedCandidate[] {
348-  return inputs
349-    .map((input, index) => ({
350-      blockIndex: isNonNegativeInteger(input.blockIndex) ? input.blockIndex : null,
351-      execution: input.execution,
352-      sequence: isNonNegativeInteger(input.sequence) ? input.sequence : index
353-    }))
354-    .sort((left, right) => {
355-      const leftBlock = left.blockIndex ?? Number.MAX_SAFE_INTEGER;
356-      const rightBlock = right.blockIndex ?? Number.MAX_SAFE_INTEGER;
357-
358-      if (leftBlock !== rightBlock) {
359-        return leftBlock - rightBlock;
360-      }
361-
362-      if (left.sequence !== right.sequence) {
363-        return left.sequence - right.sequence;
364-      }
365-
366-      const instructionOrder = left.execution.instructionId.localeCompare(right.execution.instructionId);
367-
368-      if (instructionOrder !== 0) {
369-        return instructionOrder;
370-      }
371-
372-      const toolOrder = left.execution.tool.localeCompare(right.execution.tool);
373-
374-      if (toolOrder !== 0) {
375-        return toolOrder;
376-      }
377-
378-      return left.execution.target.localeCompare(right.execution.target);
379-    });
380-}
381-
382-function sanitizeSegment(value: string): string {
383-  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/gu, "-");
384-  const collapsed = normalized.replace(/-+/gu, "-").replace(/^-|-$/gu, "");
385-  return collapsed === "" ? "unknown" : collapsed;
386-}
387-
388-function stablePrettyJson(value: BaaJsonValue): string {
389-  return `${JSON.stringify(sortBaaJsonValue(value), null, 2)}\n`;
390-}
391-
392-function truncateText(text: string, maxChars: number): string {
393-  if (text.length <= maxChars) {
394-    return text;
395-  }
396-
397-  return `${text.slice(0, Math.max(maxChars - 3, 1))}...`;
398-}
399-
400-function materializeDescribeLike(
401-  execution: BaaInstructionExecutionResult,
402-  thresholds: Thresholds
403-): MaterializedDraft {
404-  if (execution.data == null) {
405-    return materializeGeneric(execution, thresholds);
406-  }
407-
408-  const content = stablePrettyJson(execution.data);
409-  const decision = decideTextDelivery(content, thresholds);
410-
411-  return {
412-    artifactSpec: decision.shouldArtifact
413-      ? {
414-          content,
415-          extension: "json",
416-          kind: "payload",
417-          mimeType: "application/json"
418-        }
419-      : null,
420-    contentBytes: bytesOf(content),
421-    contentKind: "structured_json",
422-    deliveryMode: decision.deliveryMode,
423-    errorCode: execution.error,
424-    inlineText: decision.inlineText,
425-    ok: execution.ok,
426-    previewText: decision.previewText,
427-    summary: buildStructuredSummary(execution, execution.data)
428-  };
429-}
430-
431-function materializeExec(
432-  execution: BaaInstructionExecutionResult,
433-  thresholds: Thresholds
434-): MaterializedDraft {
435-  const record = asRecord(execution.data);
436-  const input = readObjectValue(record, "input");
437-  const result = readObjectValue(record, "result");
438-  const operationOk = readBooleanValue(record, "ok") ?? execution.ok;
439-  const command = readStringValue(input, "command") ?? "unknown command";
440-  const cwd = readStringValue(input, "cwd");
441-  const exitCode = readNumberValue(result, "exitCode");
442-  const stderr = readStringValue(result, "stderr") ?? "";
443-  const stdout = readStringValue(result, "stdout") ?? "";
444-  const timedOut = readBooleanValue(result, "timedOut") ?? false;
445-  const sections = [`$ ${command}`];
446-
447-  if (cwd != null) {
448-    sections.push(`cwd: ${cwd}`);
449-  }
450-
451-  if (stdout !== "") {
452-    sections.push(`[stdout]\n${stdout}`);
453-  }
454-
455-  if (stderr !== "") {
456-    sections.push(`[stderr]\n${stderr}`);
457-  }
458-
459-  if (stdout === "" && stderr === "") {
460-    sections.push("[output]\n(no stdout or stderr)");
461-  }
462-
463-  const content = `${sections.join("\n\n")}\n`;
464-  const decision = decideTextDelivery(content, thresholds, {
465-    alwaysArtifact: true,
466-    binaryLike: false
467-  });
468-  const statusDetail = timedOut
469-    ? "timeout"
470-    : exitCode == null
471-      ? extractErrorCode(execution, record) ?? "unknown"
472-      : `exitCode=${exitCode}`;
473-
474-  return {
475-    artifactSpec: {
476-      content,
477-      extension: "log",
478-      kind: "log",
479-      mimeType: "text/plain"
480-    },
481-    contentBytes: bytesOf(content),
482-    contentKind: "text",
483-    deliveryMode: decision.deliveryMode,
484-    errorCode: extractErrorCode(execution, record),
485-    inlineText: decision.inlineText,
486-    ok: operationOk,
487-    previewText: decision.previewText,
488-    summary: operationOk
489-      ? `exec succeeded (${statusDetail}): ${truncateText(command, 96)}`
490-      : `exec failed (${statusDetail}): ${truncateText(command, 96)}`
491-  };
492-}
493-
494-function materializeFileRead(
495-  execution: BaaInstructionExecutionResult,
496-  thresholds: Thresholds
497-): MaterializedDraft {
498-  const record = asRecord(execution.data);
499-  const input = readObjectValue(record, "input");
500-  const result = readObjectValue(record, "result");
501-  const operationOk = readBooleanValue(record, "ok") ?? execution.ok;
502-  const content = readStringValue(result, "content") ?? "";
503-  const absolutePath = readStringValue(result, "absolutePath") ?? readStringValue(input, "path") ?? "unknown";
504-  const reportedSizeBytes = readNumberValue(result, "sizeBytes");
505-  const contentBytes = content === "" ? 0 : bytesOf(content);
506-  const binaryLike = looksBinaryLike(content);
507-  const errorCode = extractErrorCode(execution, record);
508-
509-  if (!operationOk || content === "") {
510-    return {
511-      artifactSpec: null,
512-      contentBytes: 0,
513-      contentKind: "none",
514-      deliveryMode: "inline",
515-      errorCode,
516-      inlineText: null,
517-      ok: operationOk,
518-      previewText: null,
519-      summary: operationOk
520-        ? `files/read completed with no content: ${absolutePath}`
521-        : `files/read failed${errorCode == null ? "" : ` (${errorCode})`}: ${absolutePath}`
522-    };
523-  }
524-
525-  const decision = decideTextDelivery(content, thresholds, {
526-    binaryLike
527-  });
528-
529-  return {
530-    artifactSpec: decision.shouldArtifact
531-      ? {
532-          content,
533-          extension: binaryLike ? "bin" : "txt",
534-          kind: "payload",
535-          mimeType: binaryLike ? "application/octet-stream" : "text/plain"
536-        }
537-      : null,
538-    contentBytes,
539-    contentKind: binaryLike ? "binary_like_text" : "text",
540-    deliveryMode: decision.deliveryMode,
541-    errorCode,
542-    inlineText: decision.inlineText,
543-    ok: operationOk,
544-    previewText: decision.previewText,
545-    summary: binaryLike
546-      ? `files/read returned binary-like text: ${absolutePath} (${reportedSizeBytes ?? contentBytes} B)`
547-      : `files/read succeeded: ${absolutePath} (${reportedSizeBytes ?? contentBytes} B)`
548-  };
549-}
550-
551-function materializeFileWrite(
552-  execution: BaaInstructionExecutionResult
553-): MaterializedDraft {
554-  const record = asRecord(execution.data);
555-  const input = readObjectValue(record, "input");
556-  const result = readObjectValue(record, "result");
557-  const operationOk = readBooleanValue(record, "ok") ?? execution.ok;
558-  const absolutePath = readStringValue(result, "absolutePath") ?? readStringValue(input, "path") ?? "unknown";
559-  const bytesWritten = readNumberValue(result, "bytesWritten");
560-  const created = readBooleanValue(result, "created");
561-  const errorCode = extractErrorCode(execution, record);
562-
563-  return {
564-    artifactSpec: null,
565-    contentBytes: 0,
566-    contentKind: "none",
567-    deliveryMode: "inline",
568-    errorCode,
569-    inlineText: null,
570-    ok: operationOk,
571-    previewText: null,
572-    summary: operationOk
573-      ? `files/write succeeded: ${absolutePath} (${bytesWritten ?? 0} B, ${created === true ? "created" : "updated"})`
574-      : `files/write failed${errorCode == null ? "" : ` (${errorCode})`}: ${absolutePath}`
575-  };
576-}
577-
578-function materializeGeneric(
579-  execution: BaaInstructionExecutionResult,
580-  thresholds: Thresholds
581-): MaterializedDraft {
582-  if (execution.data != null) {
583-    return materializeDescribeLike(execution, thresholds);
584-  }
585-
586-  const failureText = buildFailureText(execution);
587-
588-  if (failureText !== "") {
589-    const decision = decideTextDelivery(failureText, thresholds);
590-
591-    return {
592-      artifactSpec: decision.shouldArtifact
593-        ? {
594-            content: `${failureText}\n`,
595-            extension: "txt",
596-            kind: "summary",
597-            mimeType: "text/plain"
598-          }
599-        : null,
600-      contentBytes: bytesOf(failureText),
601-      contentKind: "text",
602-      deliveryMode: decision.deliveryMode,
603-      errorCode: execution.error,
604-      inlineText: decision.inlineText,
605-      ok: execution.ok,
606-      previewText: decision.previewText,
607-      summary: buildDefaultSummary(execution)
608-    };
609-  }
610-
611-  return {
612-    artifactSpec: null,
613-    contentBytes: 0,
614-    contentKind: "none",
615-    deliveryMode: "inline",
616-    errorCode: execution.error,
617-    inlineText: null,
618-    ok: execution.ok,
619-    previewText: null,
620-    summary: buildDefaultSummary(execution)
621-  };
622-}
623-
624-function materializePreparedCandidate(
625-  prepared: PreparedCandidate,
626-  thresholds: Thresholds
627-): MaterializedDraft {
628-  switch (prepared.execution.tool) {
629-    case "exec":
630-      return materializeExec(prepared.execution, thresholds);
631-    case "files/read":
632-      return materializeFileRead(prepared.execution, thresholds);
633-    case "files/write":
634-      return materializeFileWrite(prepared.execution);
635-    case "describe":
636-    case "status":
637-      return materializeDescribeLike(prepared.execution, thresholds);
638-    default:
639-      return prepared.execution.tool.startsWith("describe/")
640-        ? materializeDescribeLike(prepared.execution, thresholds)
641-        : materializeGeneric(prepared.execution, thresholds);
642-  }
643-}
644-
645-export async function materializeBaaExecutionArtifacts(
646-  inputs: readonly BaaArtifactMaterializeCandidate[],
647-  options: BaaArtifactMaterializeOptions
648-): Promise<BaaArtifactMaterialization> {
649-  const createdAt = createTimestamp(options.createdAt);
650-  const thresholds = normalizeThresholds(options);
651-  const preparedCandidates = prepareCandidates(inputs);
652-  const artifacts: BaaMaterializedArtifactRef[] = [];
653-  const results: BaaMaterializedResult[] = [];
654-  let artifactSequence = 0;
655-
656-  await mkdir(options.outputDir, {
657-    recursive: true
658-  });
659-
660-  for (const prepared of preparedCandidates) {
661-    const draft = materializePreparedCandidate(prepared, thresholds);
662-    const artifact =
663-      draft.artifactSpec == null
664-        ? null
665-        : await createArtifact(prepared, draft, ++artifactSequence, options, createdAt);
666-    const resultArtifacts = artifact == null ? [] : [artifact];
667-
668-    if (artifact != null) {
669-      artifacts.push(artifact);
670-    }
671-
672-    results.push({
673-      artifacts: resultArtifacts,
674-      audit: {
675-        contentBytes: draft.contentBytes,
676-        contentKind: draft.contentKind,
677-        hasArtifact: artifact != null,
678-        localApiOk: prepared.execution.ok,
679-        operationOk: draft.ok
680-      },
681-      blockIndex: prepared.blockIndex,
682-      dedupeKey: prepared.execution.dedupeKey,
683-      deliveryMode: draft.deliveryMode,
684-      errorCode: draft.errorCode,
685-      httpStatus: prepared.execution.httpStatus,
686-      inlineText: draft.inlineText,
687-      instructionId: prepared.execution.instructionId,
688-      ok: draft.ok,
689-      previewText: draft.previewText,
690-      requestId: prepared.execution.requestId,
691-      route: {
692-        key: prepared.execution.route.key,
693-        method: prepared.execution.route.method,
694-        path: prepared.execution.route.path
695-      },
696-      sequence: prepared.sequence,
697-      summary: draft.summary,
698-      target: prepared.execution.target,
699-      tool: prepared.execution.tool
700-    });
701-  }
702-
703-  return {
704-    artifactCount: artifacts.length,
705-    artifacts,
706-    createdAt,
707-    outputDir: options.outputDir,
708-    results,
709-    roundId: options.roundId,
710-    traceId: options.traceId,
711-    version: "baa.artifacts.v1"
712-  };
713-}