autowonder 0.2.150 → 0.2.152

package/README.md

@@ -6,23 +6,19 @@ AutoWonder 本地 agent runtime。安装后启动 daemon，持续轮询本地 as
 
 ```bash
 # Qoder CLI（模型使用 provider model ID；Context Window 使用固定档位）
-npx -y autowonder@0.2.150 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qoder --model qmodel_latest --reasoning-effort medium --context-window 260000
+npx -y autowonder@0.2.152 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qoder --model qmodel_latest --reasoning-effort medium --context-window 260000
 
 # Qoder CLI CN
-npx -y autowonder@0.2.150 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
-
-# Claude Code
-npx -y autowonder@0.2.150 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider claude
-
-# Codex CLI
-npx -y autowonder@0.2.150 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider codex --model gpt-5.5 --reasoning-effort medium
+npx -y autowonder@0.2.152 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
 ```
 
-`connect` 会安装当前 npm 包内置的 daemon，并使用页面生成的 WebSocket endpoint、Token 和执行器 ID 建立连接。选择 Qoder 时需要 Node.js 20+；runtime 会在缺少 `qodercli` 时自动通过 npm 安装，并在尚未登录时打开 Qoder 浏览器登录。Claude Code 和 Codex CLI 仍需提前安装并登录。runtime 会继承当前用户的 HOME、环境变量和 CLI 登录状态。
+`connect` 会安装当前 npm 包内置的 daemon，并使用页面生成的 WebSocket endpoint、Token 和执行器 ID 建立连接。客户端只支持通过 Qoder 系列 CLI 启动（`qoder` 对应 `qodercli`，`qodercn` 对应 `qodercn`），其他 `--provider` 取值会在启动 daemon 前直接报错拦截并提示 `Unsupported provider`。选择 Qoder 时需要 Node.js 20+；runtime 会在缺少 `qodercli` 时自动通过 npm 安装，并在尚未登录时打开 Qoder 浏览器登录。runtime 会继承当前用户的 HOME、环境变量和 CLI 登录状态。
 
 `qodercn` 是国内版 Qoder CLI。runtime 会在缺少 `qodercn` 时自动把 `@qodercn-ai/qoderclicn` 安装到 `~/.autowonder/qoder-cn-cli`，并在尚未登录时打开浏览器登录。它使用自己的配置根（`QODERCN_CONFIG_DIR`，默认 `~/.qoder-cn`），与国际版 `qoder` 不共享可执行文件、凭证和会话。可用 `AUTOWONDER_QODERCN_CLI` 指定自定义可执行文件路径。
 
-Qoder 的 Context Window 只能使用 `1000000`、`400000` 或 `260000`，Reasoning Effort 只能使用 `none`、`low`、`medium`、`high`、`xhigh` 或 `max`。建议直接复制 AutoWonder 执行器页面生成的命令，避免把模型展示名称误当成 provider model ID。
+Qoder 的 Context Window 只能使用 `1000000`、`400000` 或 `260000`，Reasoning Effort 只能使用 `none`、`low`、`medium`、`high`、`xhigh` 或 `max`。`--model` 不再校验固定白名单：取值经 `AUTOWONDER_MODEL` 原样透传给 Qoder CLI，因此服务端上线新模型无需升级本客户端。建议直接复制 AutoWonder 执行器页面生成的命令，避免把模型展示名称误当成 provider model ID。
+
+daemon 会响应服务端的 `QODER_MODEL_CATALOG_REQUEST` 帧，用当前 provider 对应的本机 Qoder CLI 发现可用模型目录，只回传 `{id, name}`，让执行器页面展示这台机器真实可选的模型。该请求仅在 `executorId` 与 `provider` 都与本机一致时处理，发现超时 20 秒，并发请求合并为一次发现，`qoder` 与 `qodercn` 的发现互相隔离、不共享配置根。
 
 给 `connect` 追加 `--token-aware-enable` 可开启 qoder / qodercn 的 token 用量采集：CLI 会以 sidecar 方式启动本地 HTTPS 转发代理（`bin/token-proxy.js`），从 Qoder API 的 SSE 响应流中提取 usage 数据并按 dispatch ID 归属上报。该功能旁路设计、不阻塞任务执行，代理启动失败时仅告警并继续。代理端口可用 `TOKEN_PROXY_PORT` 环境变量调整（默认 19876）；CA 证书位于 `~/.autowonder/token-tap/ca-cert.pem`。daemon 退出时 sidecar 一并停止。
 
@@ -66,7 +62,7 @@ mv "$queue/.assignment.tmp" "$queue/assignment.json"
 也可以直接提交到本地 API：
 
 ```bash
-npx -y autowonder@0.2.150 dispatch ./assignment.json
+npx -y autowonder@0.2.152 dispatch ./assignment.json
 ```
 
 ## 上传工单附件
@@ -74,17 +70,27 @@ npx -y autowonder@0.2.150 dispatch ./assignment.json
 把本地需求/设计文档直接上传到工单，避免在会话里传递大文件：
 
 ```bash
-npx -y autowonder@0.2.150 workitem upload --server-url <autowonder-server-url> --workitem-id <id> --file <filepath-1> --file <filepath-2> --json
+npx -y autowonder@0.2.152 workitem upload --server-url <autowonder-server-url> --workitem-id <id> --file <filepath-1> --file <filepath-2> --json
 ```
 
 上传令牌通过 MCP 工具 `autowonder.workitem_cli_upload_token` 签发，经 `--token` 或 `AUTOWONDER_UPLOAD_TOKEN` 环境变量传入。`--file` 可重复指定多个文件；`--json` 输出机器可读结果。失败时按错误类型返回不同退出码（401→3、403→4、404→5、409→6、413→7、其他 4xx→8、网络/重定向→9）。
 
+## 下载工单附件
+
+把工单上已有的需求/设计文档下载到本地目录，再用本地文件工具阅读，避免把大文件或二进制附件搬进会话上下文：
+
+```bash
+npx -y autowonder@0.2.152 workitem download --server-url <autowonder-server-url> --workitem-id <id> --file <name-or-id> --output-dir <dir> --json
+```
+
+下载令牌通过 MCP 工具 `autowonder.workitem_cli_download_token` 签发（与上传令牌相互独立），经 `--token` 或 `AUTOWONDER_DOWNLOAD_TOKEN` 环境变量传入。`--file` 可重复指定文档名或 artifact id，省略则下载该工单的全部附件；`--output-dir` 默认为当前目录；`--json` 输出机器可读结果，含每个文件的 `id`、`name`、`path`、`size`。退出码约定与 `workitem upload` 相同（401→3、403→4、404→5、409→6、413→7、其他 4xx→8、网络/重定向→9）。
+
 ## 上传定时任务附件
 
 把需求/设计文档上传到 7x24 定时任务，用法与工单附件一致（同一套上传令牌与预检规则）：
 
 ```bash
-npx -y autowonder@0.2.150 scheduled-task upload --server-url <autowonder-server-url> --scheduled-task-id <id> --file <filepath-1> --file <filepath-2> --json
+npx -y autowonder@0.2.152 scheduled-task upload --server-url <autowonder-server-url> --scheduled-task-id <id> --file <filepath-1> --file <filepath-2> --json
 ```
 
 上传令牌同样通过 `autowonder.workitem_cli_upload_token` 签发（令牌为用户级，对当前可修改的任意定时任务生效），经 `--token` 或 `AUTOWONDER_UPLOAD_TOKEN` 传入；退出码约定与 `workitem upload` 相同。
@@ -92,8 +98,8 @@ npx -y autowonder@0.2.150 scheduled-task upload --server-url <autowonder-server-
 ## 管理 daemon
 
 ```bash
-npx -y autowonder@0.2.150 status
-npx -y autowonder@0.2.150 stop
+npx -y autowonder@0.2.152 status
+npx -y autowonder@0.2.152 stop
 ```
 
 默认 API 是 `http://127.0.0.1:34989`，日志位于 `~/.autowonder/daemon.log`。npm 包不包含任何 agent、MCP 或服务端凭证。
@@ -101,7 +107,7 @@ npx -y autowonder@0.2.150 stop
 ## 调试
 
 ```bash
-npx -y autowonder@0.2.150 connect ... --debug
+npx -y autowonder@0.2.152 connect ... --debug
 ```
 
 `--debug` 会让 CLI 以 `AUTOWONDER_DEBUG=1` 启动 daemon，把完整的 daemon 与 agent 活动（runtime 事件流、provider 事件解码、重试退避与会话门等待、空闲时的阻塞点）同时输出到控制台和会话调试日志。调试日志不做脱敏，仅用于本机排障；不传 `--debug` 时该环境变量不会注入。

package/bin/cli.js

@@ -9,7 +9,7 @@ const os = require("os");
 const https = require("https");
 const http = require("http");
 
-const { ensureDir, error, findOnPath, log, resolveUserPath } = require("./shared");
+const { ensureDir, error, log, resolveUserPath } = require("./shared");
 const {
   ensureQoderReady,
   findQoderExecutable,
@@ -46,26 +46,23 @@ function safeChmod(filePath, mode) {
 
 function detectProvider() {
   const providers = [];
-  if (findOnPath("claude")) providers.push("claude");
-  if (findOnPath("codex")) providers.push("codex");
   if (findQoderExecutable("qoder")) providers.push("qoder");
   return providers;
 }
 
-const QODER_MODELS = new Set([
-  "auto", "ultimate", "performance", "efficient", "lite",
-  "qmodel_38max", "qfmodel", "qmodel_latest", "qmodel",
-  "kmodel_latest", "kmodel", "gmodel", "gfmodel",
-  "dmodel", "dfmodel", "mmodel",
-]);
+// The client only launches the Qoder-family CLIs, so every other provider is
+// rejected here before any unsupported command can be spawned.
+function assertSupportedProvider(provider) {
+  if (isQoderFamilyProvider(provider)) return provider;
+  const shown = provider ? `: ${provider}` : "";
+  error(`Unsupported provider${shown}. The AutoWonder client only launches the Qoder CLI (qodercli) or Qoder CLI CN (qodercn) command; use --provider qoder or --provider qodercn`);
+  process.exit(1);
+}
+
 const QODER_CONTEXT_WINDOWS = new Set(["1000000", "400000", "260000"]);
 const QODER_REASONING_EFFORTS = new Set(["none", "low", "medium", "high", "xhigh", "max"]);
 
 function validateQoderOptions(flags) {
-  if (flags.model && !QODER_MODELS.has(flags.model)) {
-    error(`Unsupported Qoder model ID: ${flags.model}. Use a provider model ID shown in the executor form.`);
-    return false;
-  }
   if (flags["reasoning-effort"] && !QODER_REASONING_EFFORTS.has(flags["reasoning-effort"])) {
     error("--reasoning-effort must be one of: none, low, medium, high, xhigh, max");
     return false;
@@ -340,14 +337,16 @@ async function cmdConnect(args) {
   }
 
   const requestedProvider = flags.provider;
+  if (requestedProvider) assertSupportedProvider(requestedProvider);
   if (isQoderFamilyProvider(requestedProvider) && !validateQoderOptions(flags)) process.exit(1);
 
   const providers = detectProvider();
   const provider = requestedProvider || providers[0];
   if (!provider) {
-    error(`No agent CLI detected. Install one of: claude, codex, qodercli`);
+    error(`No agent CLI detected. Install one of: qodercli, qodercn`);
     process.exit(1);
   }
+  assertSupportedProvider(provider);
   if (isQoderFamilyProvider(provider) && !(await ensureQoderReady(provider, { debug: Boolean(flags.debug) }))) process.exit(1);
 
   // A version-pinned npx command must always run the binary bundled with that package.
@@ -495,17 +494,24 @@ async function cmdConnect(args) {
 
 async function cmdStart(args) {
   const flags = parseFlags(args, ["provider", "max-tasks", "addr"]);
+  if (flags.provider) assertSupportedProvider(flags.provider);
 
   if (daemonRunning()) {
     log("Daemon is already running.");
     return true;
   }
 
+  const providers = detectProvider();
+  const provider = flags.provider || providers[0];
+  if (!provider) {
+    error(`No agent CLI detected. Install one of: qodercli, qodercn`);
+    process.exit(1);
+  }
+  assertSupportedProvider(provider);
+
   const installed = await installBinary();
   if (!installed) process.exit(1);
 
-  const providers = detectProvider();
-  const provider = flags.provider || providers[0] || "claude";
   const addr = flags.addr || DEFAULT_API_ADDR;
   const maxTasks = flags["max-tasks"] || "10";
 
@@ -673,6 +679,9 @@ async function cmdWorkitem(args) {
   if (sub === "upload") {
     return cmdWorkitemUpload(args.slice(1));
   }
+  if (sub === "download") {
+    return cmdWorkitemDownload(args.slice(1));
+  }
   error(`Unknown workitem command: ${sub || "(none)"}`);
   cmdHelp();
   process.exit(1);
@@ -756,6 +765,53 @@ async function cmdWorkitemUpload(args) {
   }
 }
 
+async function cmdWorkitemDownload(args) {
+  const download = require("../lib/workitem-download");
+  const json = args.includes("--json");
+  try {
+    const parsed = download.parseDownloadFlags(args);
+    const serverUrl = download.validateServerUrl(parsed.serverUrl);
+    const workitemId = download.validateWorkitemId(parsed.workitemId);
+    const token = parsed.token || process.env.AUTOWONDER_DOWNLOAD_TOKEN;
+    if (!token) {
+      throw new download.DownloadError(
+        "no download token provided. Invoke the MCP tool autowonder.workitem_cli_download_token to mint one, " +
+        "then pass it via --token or the AUTOWONDER_DOWNLOAD_TOKEN environment variable.",
+        { kind: "token" },
+      );
+    }
+    const outputDir = parsed.outputDir || ".";
+    ensureDir(outputDir);
+
+    const index = await download.fetchDocumentIndex({ serverUrl, workitemId, token });
+    const selected = download.selectDocuments(index, parsed.files);
+
+    const downloaded = [];
+    for (const entry of selected) {
+      const res = await download.downloadDocument({
+        serverUrl, workitemId, artifactId: entry.id, token,
+      });
+      const filename = download.documentFilename(entry);
+      const target = download.writeDocument({ outputDir, filename, body: res.body });
+      downloaded.push({ id: entry.id, name: filename, path: target, size: res.body.length });
+    }
+
+    if (parsed.json) {
+      console.log(JSON.stringify({
+        success: true,
+        workitemId: Number(workitemId),
+        outputDir: path.resolve(outputDir),
+        downloaded,
+      }));
+    } else {
+      log(`Downloaded ${downloaded.length} file(s) from workitem ${workitemId} to ${path.resolve(outputDir)}: ${downloaded.map((d) => d.name).join(", ")}`);
+    }
+  } catch (err) {
+    reportUploadFailure(err, json);
+    process.exit(uploadExitCode(err));
+  }
+}
+
 async function cmdScheduledTask(args) {
   const sub = args[0];
   if (sub === "upload") {
@@ -818,6 +874,7 @@ async function cmdScheduledTaskUpload(args) {
 
 async function cmdInstall(args) {
   const flags = parseFlags(args, ["force", "provider", "max-tasks", "addr"]);
+  if (flags.provider) assertSupportedProvider(flags.provider);
   const force = flags.force === "true" || args.includes("--force");
   if (force && daemonRunning() && !await cmdStop({ quiet: true })) {
     process.exit(1);
@@ -833,18 +890,20 @@ function cmdHelp() {
 
   Usage:
     autowonder connect --ws-url <url> --token <token> --executor-id <id>  Connect to server and run
-    autowonder start [--provider claude]                     Start daemon in background
+    autowonder start [--provider qoder|qodercn]              Start daemon in background
     autowonder stop                                          Stop background daemon
     autowonder status                                        Show daemon status
     autowonder dispatch <assignment.json>                    Submit a dispatch
     autowonder install [--force]                             Install/update and start daemon
     autowonder workitem upload --server-url <url> --workitem-id <id> --file <path> [--file <path>...]
                                                              Upload local requirement/design files to a workitem
+    autowonder workitem download --server-url <url> --workitem-id <id> [--file <name-or-id>...] --output-dir <dir>
+                                                             Download workitem requirement/design files (no --file = all)
     autowonder scheduled-task upload --server-url <url> --scheduled-task-id <id> --file <path> [--file <path>...]
                                                              Upload local requirement/design files to a scheduled task
 
   Options:
-    --provider <name>     Agent provider: claude, codex, qoder, qodercn (default: auto-detect; qodercn must be explicit)
+    --provider <name>     Agent provider: qoder, qodercn only; other providers are rejected (default: auto-detect; qodercn must be explicit)
     --max-tasks <n>       Max concurrent dispatches (default: 10)
     --addr <host:port>    Local API address (default: 127.0.0.1:34989)
     --ws-url <url>        Executor WebSocket endpoint
@@ -861,11 +920,13 @@ function cmdHelp() {
                           also settable via AUTOWONDER_WORKSPACE_ROOT. On Windows use a
                           non-C drive path here when the default location is not writable)
     --debug               Stream full daemon and agent activity to console + log file
-    --server-url <url>    AutoWonder server base URL (workitem/scheduled-task upload)
-    --workitem-id <id>    Target workitem ID (workitem upload)
+    --server-url <url>    AutoWonder server base URL (workitem/scheduled-task upload, workitem download)
+    --workitem-id <id>    Target workitem ID (workitem upload/download)
     --scheduled-task-id <id>  Target scheduled task ID (scheduled-task upload)
-    --file <path>         Local file to upload, repeatable (workitem/scheduled-task upload)
-    --json                Machine-readable output (workitem/scheduled-task upload)
+    --file <path>         Local file to upload, repeatable (workitem/scheduled-task upload);
+                          on download, a document name or artifact id to fetch, repeatable (omit for all)
+    --output-dir <dir>    Directory to save downloaded files into (workitem download; default: .)
+    --json                Machine-readable output (workitem/scheduled-task upload, workitem download)
     -h, --help            Show this help
 
   Examples:
@@ -882,6 +943,9 @@ function cmdHelp() {
     # Upload requirement/design documents from local files
     npx -y autowonder@0.2.130 workitem upload --server-url https://private-autowonder.example.com --workitem-id 50063 --file <filepath-1> --file <filepath-2> --file <images-1> --json
 
+    # Download workitem requirement/design documents to a local directory (omit --file for all)
+    npx -y autowonder@0.2.130 workitem download --server-url https://private-autowonder.example.com --workitem-id 50063 --file <name-or-id> --output-dir <dir> --json
+
     # Upload requirement/design documents to a 7x24 scheduled task
     npx -y autowonder scheduled-task upload --server-url https://auto-wonder.example.com --scheduled-task-id 123 --file <filepath-1> --file <filepath-2> --json
 

package/lib/workitem-download.js

@@ -0,0 +1,239 @@
+"use strict";
+
+// Workitem requirement/design document download: streaming GET over Node >= 16
+// built-ins only. Bodies are collected as Buffers (never strings) so binary
+// attachments survive intact; the server is authoritative for authorization and
+// validation. Mirrors lib/workitem-upload.js.
+
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const path = require("node:path");
+
+const DOCUMENT_PREFIX = "requirements/";
+const INDEX_PATH_PREFIX = "/api/cli/workitems/";
+const INDEX_PATH_SUFFIX = "/requirement-documents/index";
+
+class DownloadError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "DownloadError";
+    Object.assign(this, details);
+  }
+}
+
+function parseDownloadFlags(args) {
+  const FLAG_KEYS = {
+    "server-url": "serverUrl",
+    "workitem-id": "workitemId",
+    token: "token",
+    file: "file",
+    "output-dir": "outputDir",
+  };
+  const options = { files: [], json: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      throw new DownloadError(`unexpected argument: ${arg}`, { kind: "usage" });
+    }
+    const key = arg.slice(2);
+    if (!FLAG_KEYS[key]) {
+      throw new DownloadError(`unknown option: ${arg}`, { kind: "usage" });
+    }
+    if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+      throw new DownloadError(`--${key} requires a value`, { kind: "usage" });
+    }
+    const value = args[++i];
+    if (key === "file") {
+      options.files.push(value);
+      continue;
+    }
+    const optionKey = FLAG_KEYS[key];
+    if (options[optionKey] !== undefined) {
+      throw new DownloadError(`--${key} may only be specified once`, { kind: "usage" });
+    }
+    options[optionKey] = value;
+  }
+  return options;
+}
+
+function validateServerUrl(value) {
+  if (!value) {
+    throw new DownloadError("--server-url is required", { kind: "usage" });
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new DownloadError(`--server-url must be an absolute http(s) URL: ${value}`, { kind: "usage" });
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new DownloadError(`--server-url must use http or https: ${value}`, { kind: "usage" });
+  }
+  if (url.username || url.password) {
+    throw new DownloadError("--server-url must not embed credentials", { kind: "usage" });
+  }
+  if (url.search) {
+    throw new DownloadError("--server-url must not contain a query string", { kind: "usage" });
+  }
+  if (url.hash) {
+    throw new DownloadError("--server-url must not contain a fragment", { kind: "usage" });
+  }
+  return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`;
+}
+
+function validateWorkitemId(value) {
+  if (value === undefined || value === null || !/^[1-9][0-9]*$/.test(String(value))) {
+    throw new DownloadError(`--workitem-id must be a positive integer: ${value}`, { kind: "usage" });
+  }
+  return String(value);
+}
+
+function parseJson(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+    // non-JSON bodies are kept as-is by callers
+  }
+  return null;
+}
+
+// Original on-disk filename for an index entry: the stored name carries the
+// "requirements/" prefix, so reduce it to a safe basename.
+function documentFilename(entry) {
+  const raw = entry && typeof entry.name === "string" ? entry.name : "";
+  const base = raw.startsWith(DOCUMENT_PREFIX) ? raw.slice(DOCUMENT_PREFIX.length) : path.posix.basename(raw);
+  const filename = path.basename(base);
+  if (!filename || filename === "." || filename === "..") {
+    throw new DownloadError(`document has an unusable filename: ${raw || "(empty)"}`, { kind: "http" });
+  }
+  return filename;
+}
+
+// Resolve --file selectors (artifact id or filename, repeatable) against the
+// index. An empty selector list means "every document". Results are deduped by
+// id and preserve index order.
+function selectDocuments(index, selectors) {
+  const entries = Array.isArray(index) ? index : [];
+  if (!selectors || selectors.length === 0) {
+    return entries.slice();
+  }
+  const chosen = new Map();
+  for (const selector of selectors) {
+    const match = entries.find((entry) => {
+      if (/^[1-9][0-9]*$/.test(String(selector))) {
+        return String(entry.id) === String(selector);
+      }
+      const filename = documentFilename(entry);
+      return entry.name === selector || filename === selector || filename === path.basename(selector);
+    });
+    if (!match) {
+      throw new DownloadError(`no requirement document matches: ${selector}`, { kind: "usage" });
+    }
+    chosen.set(String(match.id), match);
+  }
+  return entries.filter((entry) => chosen.has(String(entry.id)));
+}
+
+function httpGet({ serverUrl, path: requestPath, token }) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(`${serverUrl}${requestPath}`);
+    const client = url.protocol === "https:" ? https : http;
+    let settled = false;
+    const fail = (err) => { if (!settled) { settled = true; reject(err); } };
+    const finish = (value) => { if (!settled) { settled = true; resolve(value); } };
+
+    const request = client.request(
+      url,
+      { method: "GET", headers: { Authorization: `Bearer ${token}` } },
+      (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400) {
+          request.destroy();
+          fail(new DownloadError(
+            `server responded with a redirect (HTTP ${response.statusCode}); refusing to follow redirects`,
+            { kind: "redirect", statusCode: response.statusCode },
+          ));
+          return;
+        }
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => finish({
+          statusCode: response.statusCode,
+          headers: response.headers,
+          body: Buffer.concat(chunks),
+        }));
+        response.on("error", (err) => fail(
+          new DownloadError(`response error: ${err.message}`, { kind: "network" }),
+        ));
+      },
+    );
+
+    request.on("error", (err) => fail(
+      new DownloadError(`connection failed: ${err.message}`, { kind: "network" }),
+    ));
+    request.end();
+  });
+}
+
+async function fetchDocumentIndex({ serverUrl, workitemId, token }) {
+  const res = await httpGet({
+    serverUrl,
+    path: `${INDEX_PATH_PREFIX}${workitemId}${INDEX_PATH_SUFFIX}`,
+    token,
+  });
+  const text = res.body.toString("utf8");
+  if (res.statusCode !== 200) {
+    throw new DownloadError(
+      `server rejected the document list (HTTP ${res.statusCode})`,
+      { kind: "http", statusCode: res.statusCode, serverError: parseJson(text) },
+    );
+  }
+  const parsed = parseJson(text);
+  if (!parsed || parsed.success !== true || !Array.isArray(parsed.data)) {
+    throw new DownloadError("unexpected document list response", { kind: "http", statusCode: res.statusCode });
+  }
+  return parsed.data;
+}
+
+async function downloadDocument({ serverUrl, workitemId, artifactId, token }) {
+  const res = await httpGet({
+    serverUrl,
+    path: `${INDEX_PATH_PREFIX}${workitemId}/requirement-documents/${artifactId}/content`,
+    token,
+  });
+  if (res.statusCode !== 200) {
+    throw new DownloadError(
+      `server rejected the download (HTTP ${res.statusCode})`,
+      { kind: "http", statusCode: res.statusCode, serverError: parseJson(res.body.toString("utf8")) },
+    );
+  }
+  return res;
+}
+
+function writeDocument({ outputDir, filename, body }) {
+  if (path.basename(filename) !== filename) {
+    throw new DownloadError(`refusing to write outside the output directory: ${filename}`, { kind: "read" });
+  }
+  const target = path.join(outputDir, filename);
+  fs.writeFileSync(target, body);
+  return target;
+}
+
+module.exports = {
+  DOCUMENT_PREFIX,
+  DownloadError,
+  parseDownloadFlags,
+  validateServerUrl,
+  validateWorkitemId,
+  parseJson,
+  documentFilename,
+  selectDocuments,
+  fetchDocumentIndex,
+  downloadDocument,
+  writeDocument,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autowonder",
-  "version": "0.2.150",
+  "version": "0.2.152",
   "description": "AutoWonder local runtime — execute AI agent dispatch packages on your machine",
   "bin": {
     "autowonder": "bin/cli.js"