toc-ocra 0.2.7 → 0.2.9

package/README.md

@@ -73,6 +73,14 @@ node dist/src/index.js run
 - **服务端对账兜底**：心跳会上报本机正在运行的任务，服务端据此释放本机已经不存在的运行；Agent 崩溃重启时，会清理上次遗留的 CLI 进程。
 - **加一个 CLI**：在 `src/providers/cli/` 新增一个文件，实现 `HeadlessProvider`（启动参数 + 解析每一行输出），再在 `src/providers/registry.ts` 加一行。
 
+### 看板附件
+
+任务链附件在 CLI 启动前由本机代理下载到本次实际工作目录的 `.echo/attachments/message-{message_id}/`，完成大小与 SHA-256 校验后，提示词中的附件引用会替换为本机绝对路径。下载目录必须属于已允许的 CLI 工作目录，不能通过符号链接跳出；未配置设备默认目录或工位工作目录时会拒绝附件任务。每条消息最多 16 个附件，准备过程可取消、可复用已校验文件，最长等待 15 分钟。
+
+窗口工位使用同机代理的 `run.files.prepare` 先下载文件，然后由服务端转发路径；同机设备代理必须在线。更新后的代理通过心跳声明 `task_attachments.version=1`，服务端会拒绝把附件任务发给不支持此协议的旧代理。请更新并重启设备代理与对应后端后使用。
+
+下载文件暂时保留，可手工清理；`.echo` 不进入设备目录扫描，并带有仅作用于该内部目录的 Git 忽略规则。视频也可下载为文件，实际解析取决于 CLI 的能力。
+
 详见 [docs/architecture.md](docs/architecture.md)。
 
 ## 开发

package/dist/service/agent.mjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 
 // src/plugin-service.ts
 import { existsSync as existsSync6 } from "node:fs";
-import { delimiter as delimiter5, join as join9 } from "node:path";
+import { delimiter as delimiter5, join as join10 } from "node:path";
 
 // src/config.ts
 import { randomUUID } from "node:crypto";
@@ -15731,8 +15731,8 @@ var CliDetectionService = class {
 var cliDetection = new CliDetectionService();
 
 // src/runtime/agent-runtime.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
-import { join as join8 } from "node:path";
+import { randomUUID as randomUUID3 } from "node:crypto";
+import { join as join9 } from "node:path";
 
 // src/exec/script-runner.ts
 import { spawn as spawn3 } from "node:child_process";
@@ -16717,8 +16717,8 @@ function commandOf(pid) {
 
 // src/runs/run-supervisor.ts
 import { spawn as spawn7 } from "node:child_process";
-import { mkdir as mkdir4, realpath, stat as stat2, writeFile as writeFile4 } from "node:fs/promises";
-import { basename as basename2, isAbsolute as isAbsolute2, join as join6, relative, resolve as resolve3 } from "node:path";
+import { mkdir as mkdir5, realpath as realpath2, stat as stat2, writeFile as writeFile5 } from "node:fs/promises";
+import { basename as basename3, isAbsolute as isAbsolute3, join as join7, relative as relative2, resolve as resolve3 } from "node:path";
 import { createInterface as createInterface2 } from "node:readline";
 
 // src/session/terminal-line-sanitizer.ts
@@ -16837,6 +16837,88 @@ function clipToCharacterBudget(rows, budget) {
   return { lines: rows, limited: false };
 }
 
+// src/runs/task-attachments.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
+import { constants as constants2 } from "node:fs";
+import { lstat, mkdir as mkdir4, open, realpath, rename as rename4, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { basename as basename2, isAbsolute as isAbsolute2, join as join6, relative } from "node:path";
+function within(root, path) {
+  const segment = relative(root, path);
+  return segment === "" || !segment.startsWith("..") && !isAbsolute2(segment);
+}
+async function attachmentDirectory(workdir, messageId) {
+  let directory = workdir;
+  for (const segment of [".echo", "attachments", `message-${encodeURIComponent(messageId).slice(0, 180)}`]) {
+    directory = join6(directory, segment);
+    await mkdir4(directory, { mode: 448 }).catch((error51) => {
+      if (error51.code !== "EEXIST") throw error51;
+    });
+    const metadata = await lstat(directory);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory() || !within(workdir, await realpath(directory))) {
+      throw new Error("\u9644\u4EF6\u76EE\u5F55\u5FC5\u987B\u4F4D\u4E8E CLI \u5DE5\u4F5C\u76EE\u5F55\u5185\uFF0C\u4E14\u4E0D\u80FD\u662F\u7B26\u53F7\u94FE\u63A5");
+    }
+    if (segment === ".echo") await writeFile4(join6(directory, ".gitignore"), "*\n", { flag: "wx", mode: 384 }).catch((error51) => {
+      if (error51.code !== "EEXIST") throw error51;
+    });
+  }
+  return directory;
+}
+async function matches(path, size, sha256, signal2) {
+  const metadata = await lstat(path).catch(() => void 0);
+  if (!metadata?.isFile() || metadata.isSymbolicLink() || metadata.size !== size) return false;
+  const file2 = await open(path, constants2.O_RDONLY | (constants2.O_NOFOLLOW ?? 0));
+  try {
+    const hash2 = createHash2("sha256");
+    let read = 0;
+    for await (const chunk of file2.createReadStream({ autoClose: false })) {
+      signal2.throwIfAborted();
+      read += chunk.length;
+      if (read > size) return false;
+      hash2.update(chunk);
+    }
+    return hash2.digest("hex") === sha256;
+  } finally {
+    await file2.close();
+  }
+}
+async function prepareTaskAttachments(payload, workdir, download, signal2) {
+  const files = payload.task_attachments ?? [];
+  if (!files.length) return payload.prompt;
+  const directory = await attachmentDirectory(workdir, payload.message_id || payload.run_id);
+  let prompt = payload.prompt;
+  const paths = [];
+  for (const file2 of files) {
+    signal2.throwIfAborted();
+    const token = `{{echo-file:${file2.file_id}}}`;
+    if (file2.prompt_token !== token) throw new Error("\u9644\u4EF6\u8DEF\u5F84\u5360\u4F4D\u7B26\u65E0\u6548\uFF0C\u8BF7\u66F4\u65B0\u670D\u52A1\u5668");
+    const characters = Array.from(basename2(file2.name.replace(/\\/g, "/")).replace(/[^\p{L}\p{N}._-]/gu, "_").replace(/\.+$/u, ""));
+    while (Buffer.byteLength(characters.join("")) > 160) characters.shift();
+    const name = characters.join("") || "attachment";
+    const path = join6(directory, `${file2.file_id}-${name}`);
+    if (!await matches(path, file2.size, file2.sha256, signal2)) {
+      const temporary = join6(directory, `.download-${file2.file_id}-${randomUUID2()}.part`);
+      try {
+        await download(payload.run_id, file2.file_id, temporary, file2.size, file2.sha256, signal2);
+        signal2.throwIfAborted();
+        if (!within(workdir, await realpath(directory))) throw new Error("\u9644\u4EF6\u76EE\u5F55\u5DF2\u6539\u53D8\uFF0C\u8BF7\u91CD\u8BD5");
+        await rename4(temporary, path);
+      } finally {
+        await rm2(temporary, { force: true });
+      }
+    }
+    if (!within(workdir, await realpath(path))) throw new Error("\u9644\u4EF6\u8DEF\u5F84\u4E0D\u5728 CLI \u5DE5\u4F5C\u76EE\u5F55\u5185");
+    prompt = prompt.split(token).join(path);
+    paths.push(`- ${JSON.stringify(path)}\uFF08${file2.mime}\uFF0C${file2.size} \u5B57\u8282\uFF09`);
+  }
+  if (prompt.includes("{{echo-file:")) throw new Error("\u9644\u4EF6\u8DEF\u5F84\u672A\u5B8C\u6574\u89E3\u6790");
+  prompt += `
+
+\u9644\u4EF6\u5DF2\u7531\u8BBE\u5907\u4EE3\u7406\u4E0B\u8F7D\u5230\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\u3002\u8BF7\u76F4\u63A5\u8BFB\u53D6\u4EE5\u4E0B\u672C\u673A\u6587\u4EF6\uFF0C\u65E0\u9700\u4E0B\u8F7D\uFF1A
+${paths.join("\n")}`;
+  if (Buffer.byteLength(prompt) > 512 * 1024) throw new Error("\u5305\u542B\u9644\u4EF6\u8DEF\u5F84\u7684\u6D88\u606F\u8FC7\u957F");
+  return prompt;
+}
+
 // src/runs/run-supervisor.ts
 var COMPLETION_EXIT_GRACE_MS = 15e3;
 var RECENT_RUN_TTL_MS = 10 * 6e4;
@@ -16858,12 +16940,13 @@ var RunSupervisor = class {
   /** Run ids whose finish report has not been acknowledged yet. */
   unreported = /* @__PURE__ */ new Set();
   chatRunIds = /* @__PURE__ */ new Set();
+  preparing = /* @__PURE__ */ new Map();
   get activeCount() {
-    return this.active.size;
+    return this.active.size + this.preparing.size;
   }
   /** Runs to list in the heartbeat: still running, or finished but not yet reported. */
   activeRunIds() {
-    return [.../* @__PURE__ */ new Set([...this.active.keys(), ...this.unreported])];
+    return [.../* @__PURE__ */ new Set([...this.active.keys(), ...this.preparing.keys(), ...this.unreported])];
   }
   activeChatRunIds() {
     return this.activeRunIds().filter((id) => this.chatRunIds.has(id));
@@ -16885,6 +16968,16 @@ var RunSupervisor = class {
    * directory, unknown CLI) are reported as a failed run, never thrown.
    */
   async start(payload) {
+    if (this.preparing.has(payload.run_id)) return;
+    const controller = new AbortController();
+    this.preparing.set(payload.run_id, { workstationId: payload.workstation_id, controller });
+    try {
+      await this.startPrepared(payload, controller.signal);
+    } finally {
+      this.preparing.delete(payload.run_id);
+    }
+  }
+  async startPrepared(payload, signal2) {
     if (this.active.has(payload.run_id) || this.recent.has(payload.run_id)) {
       this.logger.info("run-duplicate-ignored", { runId: payload.run_id });
       return;
@@ -16895,20 +16988,32 @@ var RunSupervisor = class {
       this.remember({ runId: payload.run_id, workstationId: payload.workstation_id, tail: new TerminalTailBuffer(), finishedAt: Date.now(), status: "failed", chat: !!payload.chat_session_id });
       await this.report(payload.run_id, { status: "failed", error: error51, duration_ms: 0 });
     };
-    if ([...this.active.values()].some((run2) => run2.workstationId === payload.workstation_id)) {
+    if ([...this.active.values()].some((run2) => run2.workstationId === payload.workstation_id) || [...this.preparing].some(([id, run2]) => id !== payload.run_id && run2.workstationId === payload.workstation_id)) {
       return refuse("\u672C\u673A\u8BE5\u5DE5\u4F4D\u5DF2\u6709\u4EFB\u52A1\u5728\u8FD0\u884C");
     }
-    if (this.active.size >= this.config.maxConcurrentRuns) {
+    if (this.active.size + this.preparing.size > this.config.maxConcurrentRuns) {
       return refuse(`\u672C\u673A\u540C\u65F6\u8FD0\u884C\u7684\u4EFB\u52A1\u5DF2\u8FBE\u4E0A\u9650\uFF08${this.config.maxConcurrentRuns}\uFF09`);
     }
     let provider;
     let workdir;
     try {
       provider = resolveHeadlessProvider(payload.agent_type);
+      if (payload.task_attachments?.length && !payload.workdir) throw new Error("\u9644\u4EF6\u9700\u8981\u914D\u7F6E\u8BBE\u5907\u9ED8\u8BA4\u76EE\u5F55\u6216\u5DE5\u4F4D\u5DE5\u4F5C\u76EE\u5F55");
       workdir = payload.chat_session_id && !payload.workdir ? await this.defaultChatWorkdir() : await this.validateWorkdir(payload.workdir || this.config.allowedRoots[0]);
     } catch (error51) {
       return refuse(errorMessage(error51));
     }
+    try {
+      if (payload.task_attachments?.length) payload = { ...payload, prompt: await this.prepareTaskFiles(payload, signal2, workdir) };
+      signal2.throwIfAborted();
+    } catch (error51) {
+      if (signal2.aborted) {
+        this.remember({ runId: payload.run_id, workstationId: payload.workstation_id, tail: new TerminalTailBuffer(), finishedAt: Date.now(), status: "cancelled", chat: !!payload.chat_session_id });
+        await this.report(payload.run_id, { status: "cancelled", error: "\u9644\u4EF6\u51C6\u5907\u5DF2\u53D6\u6D88", duration_ms: 0 });
+        return;
+      }
+      return refuse(`\u9644\u4EF6\u4E0B\u8F7D\u5931\u8D25\uFF1A${errorMessage(error51)}`);
+    }
     const request = {
       prompt: payload.prompt,
       sessionId: payload.session_id,
@@ -16927,7 +17032,7 @@ var RunSupervisor = class {
     }
     if (!payload.prompt && !payload.attachments?.length) return refuse("\u6D88\u606F\u5185\u5BB9\u4E3A\u7A7A");
     if ([...this.active.values()].some((run2) => run2.workstationId === payload.workstation_id)) return refuse("\u672C\u673A\u8BE5\u5DE5\u4F4D\u5DF2\u6709\u4EFB\u52A1\u5728\u8FD0\u884C");
-    if (this.active.size >= this.config.maxConcurrentRuns) return refuse("\u672C\u673A\u540C\u65F6\u8FD0\u884C\u7684\u4EFB\u52A1\u5DF2\u8FBE\u4E0A\u9650");
+    if (this.active.size + this.preparing.size > this.config.maxConcurrentRuns) return refuse("\u672C\u673A\u540C\u65F6\u8FD0\u884C\u7684\u4EFB\u52A1\u5DF2\u8FBE\u4E0A\u9650");
     const launch = provider.buildLaunch({
       prompt: payload.prompt,
       sessionId: payload.session_id,
@@ -16976,6 +17081,7 @@ var RunSupervisor = class {
       timers: []
     };
     this.active.set(run.runId, run);
+    this.preparing.delete(run.runId);
     this.unreported.add(run.runId);
     if (run.pid > 1) this.orphans?.add({ runId: run.runId, pid: run.pid, executable: launch.executable, startedAt: run.startedAt });
     run.tail.append(`\u25CF ${provider.id} \u542F\u52A8\u4E8E ${workdir}${payload.session_id ? `\uFF08\u7EE7\u7EED\u4F1A\u8BDD ${payload.session_id}\uFF09` : ""}
@@ -16995,7 +17101,7 @@ var RunSupervisor = class {
       run.tail.append(`${clean}
 `);
     });
-    child.once("close", (code, signal2) => void this.onExit(run, code, signal2, spawnError));
+    child.once("close", (code, signal3) => void this.onExit(run, code, signal3, spawnError));
     if (provider.startInput) {
       child.once("spawn", () => {
         try {
@@ -17026,16 +17132,15 @@ var RunSupervisor = class {
     });
   }
   onStdout(run, rawLine) {
-    const line = sanitizeTerminalLine(rawLine);
-    const parsed = run.provider.parseLine(line);
+    const parsed = run.provider.parseLine(rawLine);
     if (run.chat && !run.forwardingFailed) {
-      for (const event of parsed.chatEvents ?? []) this.queueChatEvent(run, event);
+      for (const event of parsed.chatEvents ?? []) this.queueChatEvent(run, sanitizeChatEvent(event));
       if (parsed.sessionId) run.chatReady = true;
     }
-    for (const row of parsed.display) run.tail.append(`${row}
+    for (const row of parsed.display) run.tail.append(`${sanitizeTerminalLine(row)}
 `);
-    if (parsed.message !== void 0) run.finalMessage = parsed.message;
-    if (parsed.turnError) run.turnError = parsed.turnError;
+    if (parsed.message !== void 0) run.finalMessage = sanitizeTerminalLine(parsed.message);
+    if (parsed.turnError) run.turnError = sanitizeTerminalLine(parsed.turnError);
     if (parsed.sessionId && parsed.sessionId !== run.sessionId) {
       run.sessionId = parsed.sessionId;
       void this.reporter.started(run.runId, { session_id: parsed.sessionId }).catch(() => void 0);
@@ -17131,16 +17236,16 @@ var RunSupervisor = class {
   async prepareChatAttachments(payload) {
     if (!payload.attachments?.length) return [];
     if (!this.reporter.chatMedia) throw new Error("\u9644\u4EF6\u8F6C\u53D1\u672A\u914D\u7F6E");
-    const directory = join6(this.config.dataDir, "chat-media", encodeURIComponent(payload.chat_session_id ?? payload.run_id));
-    await mkdir4(directory, { recursive: true, mode: 448 });
+    const directory = join7(this.config.dataDir, "chat-media", encodeURIComponent(payload.chat_session_id ?? payload.run_id));
+    await mkdir5(directory, { recursive: true, mode: 448 });
     const files = [];
     for (const attachment of payload.attachments) {
-      const name = basename2(attachment.name).replace(/[^\p{L}\p{N}._-]/gu, "_").slice(-120) || "attachment";
-      const path = join6(directory, `${encodeURIComponent(attachment.media_id)}-${name}`);
+      const name = basename3(attachment.name).replace(/[^\p{L}\p{N}._-]/gu, "_").slice(-120) || "attachment";
+      const path = join7(directory, `${encodeURIComponent(attachment.media_id)}-${name}`);
       const existing = await stat2(path).catch(() => void 0);
       if (!existing?.isFile()) {
         const data = await this.reporter.chatMedia(payload.run_id, attachment.media_id);
-        await writeFile4(path, data, { mode: 384 });
+        await writeFile5(path, data, { mode: 384 });
       }
       files.push({ path, name: attachment.name, kind: attachment.kind });
     }
@@ -17153,7 +17258,14 @@ var RunSupervisor = class {
   /** Stops a run: the whole process tree, then a `cancelled` report. */
   async cancel(runId) {
     const run = this.active.get(runId);
-    if (!run) return false;
+    if (!run) {
+      const preparing = this.preparing.get(runId);
+      if (preparing) {
+        preparing.controller.abort();
+        return true;
+      }
+      return false;
+    }
     run.cancelRequested = true;
     run.tail.append("\u25CF \u6536\u5230\u505C\u6B62\u6307\u4EE4\uFF0C\u6B63\u5728\u7ED3\u675F\u8FDB\u7A0B\u6811\n");
     this.logger.info("run-cancel", { runId, pid: run.pid });
@@ -17176,6 +17288,7 @@ var RunSupervisor = class {
     return { ...read, status: this.active.has(target.runId) ? "running" : "finished", run_id: target.runId };
   }
   async disposeAll() {
+    for (const entry of this.preparing.values()) entry.controller.abort();
     await Promise.all([...this.active.values()].map((run) => {
       run.cancelRequested = true;
       return killProcessTree(run.pid, 1e3);
@@ -17201,23 +17314,47 @@ var RunSupervisor = class {
     if (!input) throw new Error("\u6CA1\u6709\u914D\u7F6E\u5141\u8BB8\u7684\u5DE5\u4F5C\u76EE\u5F55");
     let candidate;
     try {
-      candidate = await realpath(isAbsolute2(input) ? input : resolve3(input));
+      candidate = await realpath2(isAbsolute3(input) ? input : resolve3(input));
     } catch {
       throw new Error(`\u5DE5\u4F5C\u76EE\u5F55\u4E0D\u5B58\u5728\uFF1A${input}`);
     }
     for (const root of this.config.allowedRoots) {
-      const allowed = await realpath(root).catch(() => resolve3(root));
-      const segment = relative(allowed, candidate);
-      if (segment === "" || !segment.startsWith("..") && !isAbsolute2(segment)) return candidate;
+      const allowed = await realpath2(root).catch(() => resolve3(root));
+      const segment = relative2(allowed, candidate);
+      if (segment === "" || !segment.startsWith("..") && !isAbsolute3(segment)) return candidate;
     }
     throw new Error(`\u5DE5\u4F5C\u76EE\u5F55\u4E0D\u5728\u5141\u8BB8\u8303\u56F4\u5185\uFF1A${input}`);
   }
+  async prepareTaskFiles(payload, signal2 = AbortSignal.timeout(15 * 6e4), workdir) {
+    if (!payload.workdir) throw new Error("\u8BF7\u5148\u914D\u7F6E\u8BBE\u5907\u9ED8\u8BA4\u76EE\u5F55\u6216\u5DE5\u4F4D\u5DE5\u4F5C\u76EE\u5F55");
+    if (!this.reporter.taskFile) throw new Error("\u4EFB\u52A1\u9644\u4EF6\u4E0B\u8F7D\u672A\u914D\u7F6E");
+    return prepareTaskAttachments(payload, workdir ?? await this.validateWorkdir(payload.workdir), this.reporter.taskFile, AbortSignal.any([signal2, AbortSignal.timeout(15 * 6e4)]));
+  }
 };
 function errorMessage(error51) {
   return error51 instanceof Error ? error51.message : String(error51);
 }
+function sanitizeChatEvent(event) {
+  const sanitize = (value) => {
+    if (typeof value === "string") return sanitizeTerminalLine(value);
+    if (Array.isArray(value)) return value.map(sanitize);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitize(item)]));
+    }
+    return value;
+  };
+  return {
+    ...event,
+    ...event.text !== void 0 ? { text: sanitizeTerminalLine(event.text) } : {},
+    ...event.item ? { item: sanitize(event.item) } : {}
+  };
+}
 
 // src/transport/gateway-client.ts
+import { createHash as createHash3 } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 var GatewayError = class extends Error {
   constructor(message, status) {
     super(message);
@@ -17299,19 +17436,46 @@ var GatewayClient = class {
   runStarted(runId, body) {
     return this.request("POST", `/runs/${encodeURIComponent(runId)}/started`, body, 15e3);
   }
+  async taskFile(runId, fileId, destination, size, sha256, signal2) {
+    const response = await fetch(`${this.config.serverUrl}/api/agent/runs/${encodeURIComponent(runId)}/files/${encodeURIComponent(fileId)}`, {
+      headers: { authorization: `Bearer ${this.config.token}` },
+      redirect: "error",
+      signal: AbortSignal.any([signal2, AbortSignal.timeout(15 * 6e4)])
+    });
+    if (!response.ok || !response.body) throw new GatewayError("\u65E0\u6CD5\u8BFB\u53D6\u4EFB\u52A1\u9644\u4EF6\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u662F\u5426\u5DF2\u5220\u9664\u53CA\u8BBE\u5907\u51ED\u636E", response.status);
+    const declared = response.headers.get("content-length");
+    if (declared !== null && Number(declared) !== size) {
+      await response.body.cancel();
+      throw new Error("\u9644\u4EF6\u5927\u5C0F\u4E0E\u4FDD\u5B58\u7684\u8BB0\u5F55\u4E0D\u4E00\u81F4");
+    }
+    const hash2 = createHash3("sha256");
+    let received = 0;
+    const verifier = new Transform({ transform(chunk, _encoding, callback) {
+      received += chunk.length;
+      if (received > size) {
+        callback(new Error("\u9644\u4EF6\u4E0B\u8F7D\u8D85\u51FA\u8BB0\u5F55\u5927\u5C0F"));
+        return;
+      }
+      hash2.update(chunk);
+      callback(null, chunk);
+    } });
+    const target = createWriteStream(destination, { flags: "wx", mode: 384 });
+    await pipeline(Readable.fromWeb(response.body), verifier, target, { signal: signal2 });
+    if (received !== size || hash2.digest("hex") !== sha256) throw new Error("\u9644\u4EF6\u4E0B\u8F7D\u4E0D\u5B8C\u6574\u6216\u6821\u9A8C\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5");
+  }
   runFinished(runId, body) {
     return this.request("POST", `/runs/${encodeURIComponent(runId)}/finished`, body, 15e3);
   }
 };
 
 // src/workspace/directory-browser.ts
-import { readdir, realpath as realpath2, stat as stat3 } from "node:fs/promises";
+import { readdir, realpath as realpath3, stat as stat3 } from "node:fs/promises";
 import { homedir as homedir5 } from "node:os";
 import { dirname as dirname6, parse as parse3, resolve as resolve4 } from "node:path";
 var MAX_ENTRIES = 1e3;
 async function listDirectory(requested, allowedRoots) {
   const raw = requested.trim().replace(/^~(?=$|[\\/])/, homedir5()) || homedir5();
-  const directory = await realpath2(resolve4(raw)).catch(() => {
+  const directory = await realpath3(resolve4(raw)).catch(() => {
     throw new Error(`\u76EE\u5F55\u4E0D\u5B58\u5728\uFF1A${requested}`);
   });
   if (!(await stat3(directory)).isDirectory()) throw new Error("\u8FD9\u4E0D\u662F\u4E00\u4E2A\u76EE\u5F55");
@@ -17343,12 +17507,13 @@ async function listDirectory(requested, allowedRoots) {
 
 // src/workspace/workspace-manager.ts
 import { spawn as spawn8 } from "node:child_process";
-import { chmod as chmod3, mkdir as mkdir5, mkdtemp, opendir, realpath as realpath3, rm as rm2, stat as stat4, writeFile as writeFile5 } from "node:fs/promises";
+import { chmod as chmod3, mkdir as mkdir6, mkdtemp, opendir, realpath as realpath4, rm as rm3, stat as stat4, writeFile as writeFile6 } from "node:fs/promises";
 import { homedir as homedir6, tmpdir } from "node:os";
-import { isAbsolute as isAbsolute3, join as join7, relative as relative2, resolve as resolve5 } from "node:path";
+import { isAbsolute as isAbsolute4, join as join8, relative as relative3, resolve as resolve5 } from "node:path";
 var MAX_NODES = 2e3;
 var MAX_DIRECTORY_ENTRIES = 12e3;
 var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+  ".echo",
   ".git",
   "node_modules",
   ".next",
@@ -17394,12 +17559,12 @@ var WorkspaceManager = class {
   validateRootPath(value) {
     const raw = value.trim().replace(/^~(?=$|[\\/])/, homedir6());
     const root = resolve5(raw);
-    if (!isAbsolute3(raw)) throw new Error("\u6839\u76EE\u5F55\u5FC5\u987B\u662F\u7EDD\u5BF9\u8DEF\u5F84");
-    if (relative2(root, resolve5(root, "..")) === "") throw new Error("\u4E0D\u80FD\u628A\u6587\u4EF6\u7CFB\u7EDF\u6839\u76EE\u5F55\u4F5C\u4E3A\u76EE\u5F55\u6839");
+    if (!isAbsolute4(raw)) throw new Error("\u6839\u76EE\u5F55\u5FC5\u987B\u662F\u7EDD\u5BF9\u8DEF\u5F84");
+    if (relative3(root, resolve5(root, "..")) === "") throw new Error("\u4E0D\u80FD\u628A\u6587\u4EF6\u7CFB\u7EDF\u6839\u76EE\u5F55\u4F5C\u4E3A\u76EE\u5F55\u6839");
     return root;
   }
   async syncTree(rootPath, request) {
-    await mkdir5(rootPath, { recursive: true });
+    await mkdir6(rootPath, { recursive: true });
     await addAllowedRoot(this.config, rootPath);
     const results = [];
     const requestedPaths = /* @__PURE__ */ new Set();
@@ -17423,7 +17588,7 @@ var WorkspaceManager = class {
           });
           continue;
         }
-        await mkdir5(target, { recursive: true });
+        await mkdir6(target, { recursive: true });
         results.push({
           relative_path: relativePath,
           status: "created",
@@ -17472,7 +17637,7 @@ var WorkspaceManager = class {
     }
     if (!metadata) {
       if (!gitUrl) throw new Error("A missing repository needs a Git remote URL");
-      await mkdir5(resolve5(target, ".."), { recursive: true });
+      await mkdir6(resolve5(target, ".."), { recursive: true });
       const cloneArgs = branch ? ["clone", "--branch", branch, "--single-branch", gitUrl, target] : ["clone", gitUrl, target];
       await this.runGit(cloneArgs, rootPath, timeoutSeconds, false, gitEnvironment);
       created = true;
@@ -17566,13 +17731,13 @@ var WorkspaceManager = class {
     };
   }
   async scanTree(rootPath, maxDepth, scanRoots) {
-    const resolvedRoot = await realpath3(rootPath);
+    const resolvedRoot = await realpath4(rootPath);
     const rootMetadata = await stat4(resolvedRoot);
     if (!rootMetadata.isDirectory()) throw new Error("The workspace root is not a directory");
     const nodes = [];
     let entriesRead = 0;
     const appendNode = async (target) => {
-      const relativePath = relative2(resolvedRoot, target).replaceAll("\\", "/");
+      const relativePath = relative3(resolvedRoot, target).replaceAll("\\", "/");
       if (!relativePath || !this.isSafeRelativePath(relativePath)) return void 0;
       const git = await this.readGitMetadata(target);
       if (git) {
@@ -17656,8 +17821,8 @@ var WorkspaceManager = class {
     if (result.exitCode !== 0 || !topLevel) return false;
     try {
       const [resolvedDirectory, resolvedTopLevel] = await Promise.all([
-        realpath3(directory),
-        realpath3(topLevel)
+        realpath4(directory),
+        realpath4(topLevel)
       ]);
       return resolvedDirectory === resolvedTopLevel;
     } catch {
@@ -17677,8 +17842,8 @@ var WorkspaceManager = class {
   }
   resolveWithinRoot(rootPath, relativePath) {
     const target = resolve5(rootPath, relativePath);
-    const relativeToRoot = relative2(rootPath, target);
-    if (relativeToRoot.startsWith("..") || isAbsolute3(relativeToRoot)) {
+    const relativeToRoot = relative3(rootPath, target);
+    if (relativeToRoot.startsWith("..") || isAbsolute4(relativeToRoot)) {
       throw new Error("A workspace path must remain under the configured workspace root");
     }
     return target;
@@ -17719,13 +17884,13 @@ var WorkspaceManager = class {
   }
   async createGitAuthEnvironment(auth) {
     if (!auth) return void 0;
-    const directory = await mkdtemp(join7(tmpdir(), "toc-ocra-git-auth-"));
+    const directory = await mkdtemp(join8(tmpdir(), "toc-ocra-git-auth-"));
     const isWindows = process.platform === "win32";
-    const scriptPath = join7(directory, isWindows ? "askpass.cmd" : "askpass.sh");
+    const scriptPath = join8(directory, isWindows ? "askpass.cmd" : "askpass.sh");
     let script;
     if (isWindows) {
-      const helperPath = join7(directory, "askpass.cjs");
-      await writeFile5(
+      const helperPath = join8(directory, "askpass.cjs");
+      await writeFile6(
         helperPath,
         'const prompt = process.argv.slice(2).join(" ");\nprocess.stdout.write(/username/i.test(prompt) ? process.env.ECHO_GIT_USERNAME ?? "" : process.env.ECHO_GIT_PASSWORD ?? "");\n',
         { mode: 448 }
@@ -17734,7 +17899,7 @@ var WorkspaceManager = class {
     } else {
       script = '#!/bin/sh\ncase "$1" in *Username*|*username*) printf "%s\\n" "$ECHO_GIT_USERNAME" ;; *) printf "%s\\n" "$ECHO_GIT_PASSWORD" ;; esac\n';
     }
-    await writeFile5(scriptPath, script, { mode: 448 });
+    await writeFile6(scriptPath, script, { mode: 448 });
     if (!isWindows) await chmod3(scriptPath, 448);
     return {
       env: {
@@ -17745,7 +17910,7 @@ var WorkspaceManager = class {
         ECHO_GIT_USERNAME: auth.username,
         ECHO_GIT_PASSWORD: auth.password
       },
-      cleanup: () => rm2(directory, { recursive: true, force: true })
+      cleanup: () => rm3(directory, { recursive: true, force: true })
     };
   }
   message(error51) {
@@ -17770,6 +17935,7 @@ var RunStartPayloadSchema = external_exports.object({
   prompt: external_exports.string().max(512 * 1024),
   chat_session_id: external_exports.string().max(64).optional(),
   attachments: external_exports.array(external_exports.object({ media_id: external_exports.string().min(1).max(64), name: external_exports.string().max(200), kind: external_exports.enum(["image", "file"]) })).max(16).optional(),
+  task_attachments: external_exports.array(external_exports.object({ file_id: external_exports.uuid(), name: external_exports.string().min(1).max(255), mime: external_exports.string().max(255), size: external_exports.number().int().positive(), sha256: external_exports.string().regex(/^[a-f0-9]{64}$/), prompt_token: external_exports.string().max(100) })).max(16).nullish(),
   session_id: external_exports.string().max(200).optional().default(""),
   model: external_exports.string().max(100).optional().default(""),
   reasoning_effort: external_exports.string().max(40).optional().default(""),
@@ -17840,13 +18006,14 @@ var AgentRuntime = class {
         await this.retry(() => this.client.chatEvents(runId, events), 5);
       },
       chatMedia: (runId, mediaId) => this.client.chatMedia(runId, mediaId),
+      taskFile: (runId, fileId, destination, size, sha256, signal2) => this.client.taskFile(runId, fileId, destination, size, sha256, signal2),
       finished: async (runId, report) => {
         this.pendingReports.set(runId, report);
         await this.flushReport(runId);
       }
     };
     this.workspaces = new WorkspaceManager(config2, this.logger);
-    this.orphans = new OrphanRegistry(join8(config2.dataDir, chatOnly ? "chat-active-runs.json" : "active-runs.json"));
+    this.orphans = new OrphanRegistry(join9(config2.dataDir, chatOnly ? "chat-active-runs.json" : "active-runs.json"));
     this.runs = new RunSupervisor(config2, this.logger, reporter, this.orphans);
   }
   config;
@@ -17859,7 +18026,7 @@ var AgentRuntime = class {
   workspaces;
   stopController = new AbortController();
   startedAt = (/* @__PURE__ */ new Date()).toISOString();
-  chatRunnerId = randomUUID2();
+  chatRunnerId = randomUUID3();
   chatReady = false;
   chatLeaseInitialized = false;
   chatError;
@@ -18000,6 +18167,7 @@ var AgentRuntime = class {
     return {
       providers: snapshot.providers.map((p) => ({ id: p.id, installed: p.installed, runnable: p.available, version: p.version ?? "", path: p.resolvedPath ?? "" })),
       cli_chat: { version: 1, providers: CHAT_PROVIDERS.filter((id) => snapshot.detectedIds.includes(id)) },
+      task_attachments: { version: 1 },
       detected_ids: snapshot.detectedIds,
       refreshed_at: snapshot.refreshedAt
     };
@@ -18053,6 +18221,11 @@ var AgentRuntime = class {
   }
   async execute(command) {
     switch (command.type) {
+      case "run.files.prepare": {
+        const payload = RunStartPayloadSchema.parse(command.payload);
+        const prompt = await this.runs.prepareTaskFiles(payload);
+        return { success: true, result: { prompt } };
+      }
       case "chat.run.start":
       case "run.start": {
         const payload = RunStartPayloadSchema.parse(command.payload);
@@ -18387,7 +18560,7 @@ function preferSystemNode() {
   const names = process.platform === "win32" ? ["node.exe"] : ["node"];
   for (const directory of (process.env.PATH ?? "").split(delimiter5)) {
     for (const name of names) {
-      const candidate = directory && join9(directory, name);
+      const candidate = directory && join10(directory, name);
       if (candidate && existsSync6(candidate)) {
         process.env.TOC_OCRA_NODE_PATH = candidate;
         return;

package/dist/src/runs/run-supervisor.d.ts

@@ -4,6 +4,7 @@ import type { ChatContentEvent } from '../providers/provider.js';
 import { type TerminalTailRead } from '../session/terminal-tail-buffer.js';
 import type { RunFinishedReport, RunStartPayload, RunStartedReport } from '../types/protocol.js';
 import { OrphanRegistry } from './orphan-registry.js';
+import { type TaskFileDownload } from './task-attachments.js';
 /**
  * Supervises headless CLI turns. One process per turn:
  *
@@ -17,6 +18,7 @@ import { OrphanRegistry } from './orphan-registry.js';
  */
 export declare const COMPLETION_EXIT_GRACE_MS = 15000;
 export type RunReporter = {
+    taskFile?: TaskFileDownload;
     chatEvents?(runId: string, events: Array<ChatContentEvent & {
         sequence: number;
     }>): Promise<void>;
@@ -38,6 +40,7 @@ export declare class RunSupervisor {
     /** Run ids whose finish report has not been acknowledged yet. */
     private readonly unreported;
     private readonly chatRunIds;
+    private readonly preparing;
     constructor(config: AgentConfig, logger: DiagnosticLogger, reporter: RunReporter, orphans?: OrphanRegistry | undefined);
     get activeCount(): number;
     /** Runs to list in the heartbeat: still running, or finished but not yet reported. */
@@ -56,6 +59,7 @@ export declare class RunSupervisor {
      * directory, unknown CLI) are reported as a failed run, never thrown.
      */
     start(payload: RunStartPayload): Promise<void>;
+    private startPrepared;
     private onStdout;
     private onExit;
     private queueChatEvent;
@@ -72,4 +76,5 @@ export declare class RunSupervisor {
     private remember;
     private defaultChatWorkdir;
     validateWorkdir(input: string | undefined): Promise<string>;
+    prepareTaskFiles(payload: RunStartPayload, signal?: AbortSignal, workdir?: string): Promise<string>;
 }