autowonder 0.2.130 → 0.2.132

package/README.md

@@ -6,17 +6,22 @@ AutoWonder 本地 agent runtime。安装后启动 daemon，持续轮询本地 as
 
 ```bash
 # Qoder CLI（模型使用 provider model ID；Context Window 使用固定档位）
-npx -y autowonder@0.2.130 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.132 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.132 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider qodercn
 
 # Claude Code
-npx -y autowonder@0.2.130 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider claude
+npx -y autowonder@0.2.132 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider claude
 
 # Codex CLI
-npx -y autowonder@0.2.130 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.132 connect --ws-url <wss-endpoint> --token <executor-token> --executor-id <executor-id> --provider codex --model gpt-5.5 --reasoning-effort medium
 ```
 
 `connect` 会安装当前 npm 包内置的 daemon，并使用页面生成的 WebSocket endpoint、Token 和执行器 ID 建立连接。选择 Qoder 时需要 Node.js 20+；runtime 会在缺少 `qodercli` 时自动通过 npm 安装，并在尚未登录时打开 Qoder 浏览器登录。Claude Code 和 Codex CLI 仍需提前安装并登录。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。
 
 ## 自动更新
@@ -57,14 +62,32 @@ mv "$queue/.assignment.tmp" "$queue/assignment.json"
 也可以直接提交到本地 API：
 
 ```bash
-npx -y autowonder@0.2.130 dispatch ./assignment.json
+npx -y autowonder@0.2.132 dispatch ./assignment.json
+```
+
+## 上传工单附件
+
+把本地需求/设计文档直接上传到工单，避免在会话里传递大文件：
+
+```bash
+npx -y autowonder@0.2.132 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）。
+
 ## 管理 daemon
 
 ```bash
-npx -y autowonder@0.2.130 status
-npx -y autowonder@0.2.130 stop
+npx -y autowonder@0.2.132 status
+npx -y autowonder@0.2.132 stop
 ```
 
 默认 API 是 `http://127.0.0.1:34989`，日志位于 `~/.autowonder/daemon.log`。npm 包不包含任何 agent、MCP 或服务端凭证。
+
+## 调试
+
+```bash
+npx -y autowonder@0.2.132 connect ... --debug
+```
+
+`--debug` 会让 CLI 以 `AUTOWONDER_DEBUG=1` 启动 daemon，把完整的 daemon 与 agent 活动（runtime 事件流、provider 事件解码、重试退避与会话门等待、空闲时的阻塞点）同时输出到控制台和会话调试日志。调试日志不做脱敏，仅用于本机排障；不传 `--debug` 时该环境变量不会注入。

package/bin/cli.js

@@ -24,6 +24,46 @@ const PID_PATH = path.join(AUTOWONDER_HOME, "daemon.pid");
 const STATE_PATH = path.join(AUTOWONDER_HOME, "daemon-state.json");
 const LOG_PATH = path.join(AUTOWONDER_HOME, "daemon.log");
 const MANAGED_QODER_DIR = path.join(AUTOWONDER_HOME, "qoder-cli");
+const MANAGED_QODERCN_DIR = path.join(AUTOWONDER_HOME, "qoder-cn-cli");
+
+// qoder and qodercn are two distinct provider identities that share the same
+// bootstrap flow. Each identity keeps its own executable, npm package, managed
+// install dir and env override so the two CLIs never shadow each other.
+const QODER_FAMILY_PROFILES = {
+  qoder: {
+    displayName: "Qoder CLI",
+    executable: "qodercli",
+    envVar: "AUTOWONDER_QODER_CLI",
+    npmPackage: "@qoder-ai/qodercli@latest",
+    managedDir: MANAGED_QODER_DIR,
+    managedBinName: "qodercli",
+    windowsShimName: "qodercli.cmd",
+    unixCandidates: [
+      path.join(os.homedir(), ".local", "bin", "qodercli"),
+      path.join(os.homedir(), ".qoder", "bin", "qodercli", "qodercli"),
+    ],
+  },
+  qodercn: {
+    displayName: "Qoder CLI CN",
+    executable: "qodercn",
+    envVar: "AUTOWONDER_QODERCN_CLI",
+    npmPackage: "@qodercn-ai/qoderclicn@latest",
+    managedDir: MANAGED_QODERCN_DIR,
+    managedBinName: "qodercn",
+    windowsShimName: "qodercn.cmd",
+    unixCandidates: [
+      path.join(os.homedir(), ".local", "bin", "qodercn"),
+    ],
+  },
+};
+
+function profileForExecutable(name) {
+  return Object.values(QODER_FAMILY_PROFILES).find((profile) => profile.executable === name) || null;
+}
+
+function isQoderFamilyProvider(provider) {
+  return provider === "qoder" || provider === "qodercn";
+}
 
 const BINARY_BASE_URL = process.env.AUTOWONDER_BINARY_URL || "";
 const SOURCE_REPO = process.env.AUTOWONDER_SOURCE_REPO || "";
@@ -59,8 +99,9 @@ function detectProvider() {
 }
 
 function findExecutable(name) {
-  if (name === "qodercli" && process.env.AUTOWONDER_QODER_CLI) {
-    const configured = resolveUserPath(process.env.AUTOWONDER_QODER_CLI);
+  const profile = profileForExecutable(name);
+  if (profile && process.env[profile.envVar]) {
+    const configured = resolveUserPath(process.env[profile.envVar]);
     try { fs.accessSync(configured, fs.constants.X_OK); return configured; } catch {}
   }
   const finder = process.platform === "win32" ? "where" : "which";
@@ -69,17 +110,17 @@ function findExecutable(name) {
     const first = (found.stdout || "").split(/\r?\n/).map((value) => value.trim()).find(Boolean);
     if (first) return first;
   }
-  if (name === "qodercli" && process.platform !== "win32") {
-    for (const candidate of [
-      path.join(MANAGED_QODER_DIR, "node_modules", ".bin", "qodercli"),
-      path.join(os.homedir(), ".local", "bin", "qodercli"),
-      path.join(os.homedir(), ".qoder", "bin", "qodercli", "qodercli"),
-    ]) {
+  if (profile && process.platform !== "win32") {
+    const candidates = [
+      path.join(profile.managedDir, "node_modules", ".bin", profile.managedBinName),
+      ...profile.unixCandidates,
+    ];
+    for (const candidate of candidates) {
       try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch {}
     }
   }
-  if (name === "qodercli" && process.platform === "win32") {
-    const candidate = path.join(MANAGED_QODER_DIR, "node_modules", ".bin", "qodercli.cmd");
+  if (profile && process.platform === "win32") {
+    const candidate = path.join(profile.managedDir, "node_modules", ".bin", profile.windowsShimName);
     try { fs.accessSync(candidate, fs.constants.F_OK); return candidate; } catch {}
   }
   return "";
@@ -100,10 +141,11 @@ function qoderAuthenticated(executable) {
   return result.status === 0 && Boolean((result.stdout || "").trim());
 }
 
-function installQoderCLI() {
-  log("Qoder CLI is not installed. Installing @qoder-ai/qodercli...");
+function installQoderCLI(provider) {
+  const profile = QODER_FAMILY_PROFILES[provider];
+  log(`${profile.displayName} is not installed. Installing ${profile.npmPackage}...`);
   const args = [
-    "install", "--prefix", MANAGED_QODER_DIR, "@qoder-ai/qodercli@latest", "--no-audit", "--no-fund",
+    "install", "--prefix", profile.managedDir, profile.npmPackage, "--no-audit", "--no-fund",
   ];
   // npm is a .cmd shim on Windows. When launched by npx, npm_execpath points
   // at npm-cli.js, which Node can execute directly without cmd.exe quoting.
@@ -112,16 +154,16 @@ function installQoderCLI() {
     : spawnSync("npm", npmArgs, { stdio: "inherit" });
   let result = runNpm(args);
   if (result.status !== 0 && IS_WIN32) {
-    log("Default npm registry failed; retrying Qoder CLI installation with npmmirror...");
+    log(`Default npm registry failed; retrying ${profile.displayName} installation with npmmirror...`);
     result = runNpm([...args, "--registry", "https://registry.npmmirror.com"]);
   }
   if (result.status !== 0) {
     const detail = result.error?.message || (result.signal ? `signal ${result.signal}` : `exit status ${result.status}`);
-    error(`Failed to install Qoder CLI into ${MANAGED_QODER_DIR}: ${detail}`);
+    error(`Failed to install ${profile.displayName} into ${profile.managedDir}: ${detail}`);
     return "";
   }
-  const executable = findExecutable("qodercli");
-  if (!executable) error("Qoder CLI was installed but qodercli is not available on PATH.");
+  const executable = findExecutable(profile.executable);
+  if (!executable) error(`${profile.displayName} was installed but ${profile.executable} is not available on PATH.`);
   return executable;
 }
 
@@ -166,19 +208,20 @@ function qoderLoginCommand(executable) {
   return IS_WIN32 ? `& ${quoted} login` : `${quoted} login`;
 }
 
-async function ensureQoderReady() {
+async function ensureQoderReady(provider) {
   if (process.env.AUTOWONDER_SKIP_QODER_BOOTSTRAP === "1") return true;
+  const profile = QODER_FAMILY_PROFILES[provider];
   const nodeVersion = qoderNodeVersion();
   const nodeMajor = Number.parseInt(nodeVersion.split(".")[0], 10);
   if (!Number.isInteger(nodeMajor) || nodeMajor < 20) {
-    error(`Qoder CLI requires Node.js 20 or newer; current version is ${nodeVersion}. Upgrade Node.js and retry.`);
+    error(`${profile.displayName} requires Node.js 20 or newer; current version is ${nodeVersion}. Upgrade Node.js and retry.`);
     return false;
   }
-  let executable = findExecutable("qodercli");
-  if (!executable) executable = installQoderCLI();
+  let executable = findExecutable(profile.executable);
+  if (!executable) executable = installQoderCLI(provider);
   if (!executable) return false;
   if (!qoderAuthenticated(executable)) {
-    log("Qoder login is required. Opening browser login...");
+    log(`${profile.displayName} login is required. Opening browser login...`);
     const login = spawnQoderSync(executable, ["login"], { stdio: "inherit" });
     if (login.status !== 0) {
       const detail = login.error?.message || `exit status ${login.status}`;
@@ -191,13 +234,13 @@ async function ensureQoderReady() {
       return false;
     }
   }
-  process.env.AUTOWONDER_QODER_CLI = executable;
+  process.env[profile.envVar] = executable;
   const executableDir = path.dirname(executable);
   const pathEntries = (process.env.PATH || "").split(path.delimiter);
   if (!pathEntries.includes(executableDir)) {
     process.env.PATH = `${executableDir}${path.delimiter}${process.env.PATH || ""}`;
   }
-  log("Qoder CLI is installed and authenticated.");
+  log(`${profile.displayName} is installed and authenticated.`);
   return true;
 }
 
@@ -483,12 +526,12 @@ async function cmdConnect(args) {
   const flags = parseFlags(args, ["ws-url", "token", "executor-id", "provider", "name", "max-tasks", "model", "reasoning-effort", "context-window", "memory-mode", "settings"]);
 
   if (!flags["ws-url"] || !flags.token || !flags["executor-id"]) {
-    error("Usage: autowonder connect --ws-url <url> --token <token> --executor-id <id> [--provider qoder]");
+    error("Usage: autowonder connect --ws-url <url> --token <token> --executor-id <id> [--provider qoder|qodercn]");
     process.exit(1);
   }
 
   const requestedProvider = flags.provider;
-  if (requestedProvider === "qoder" && !validateQoderOptions(flags)) process.exit(1);
+  if (isQoderFamilyProvider(requestedProvider) && !validateQoderOptions(flags)) process.exit(1);
 
   const providers = detectProvider();
   const provider = requestedProvider || providers[0];
@@ -496,7 +539,7 @@ async function cmdConnect(args) {
     error(`No agent CLI detected. Install one of: claude, codex, qodercli`);
     process.exit(1);
   }
-  if (provider === "qoder" && !(await ensureQoderReady())) process.exit(1);
+  if (isQoderFamilyProvider(provider) && !(await ensureQoderReady(provider))) process.exit(1);
 
   // A version-pinned npx command must always run the binary bundled with that package.
   // Windows locks a running .exe. Its versioned path is immutable, so another
@@ -505,15 +548,15 @@ async function cmdConnect(args) {
   if (!installed) process.exit(1);
 
   const hasProviderSettings = Boolean(flags.model || flags["reasoning-effort"]);
-  if (hasProviderSettings && provider !== "codex" && provider !== "qoder") {
-    error("--model and --reasoning-effort are supported only for codex and qoder");
+  if (hasProviderSettings && provider !== "codex" && !isQoderFamilyProvider(provider)) {
+    error("--model and --reasoning-effort are supported only for codex, qoder and qodercn");
     process.exit(1);
   }
-  if (flags["context-window"] && provider !== "qoder") {
-    error("--context-window is supported only for qoder");
+  if (flags["context-window"] && !isQoderFamilyProvider(provider)) {
+    error("--context-window is supported only for qoder and qodercn");
     process.exit(1);
   }
-  if (provider === "qoder" && !validateQoderOptions(flags)) process.exit(1);
+  if (isQoderFamilyProvider(provider) && !validateQoderOptions(flags)) process.exit(1);
   let claudeSettingsPath = "";
   if (flags.settings) {
     if (provider !== "claude") {
@@ -574,6 +617,7 @@ async function cmdConnect(args) {
   if (flags["reasoning-effort"]) env.AUTOWONDER_REASONING_EFFORT = flags["reasoning-effort"];
   if (flags["context-window"]) env.AUTOWONDER_CONTEXT_WINDOW = flags["context-window"];
   if (config.claudeSettingsPath) env.AUTOWONDER_CLAUDE_SETTINGS = config.claudeSettingsPath;
+  if (flags.debug) env.AUTOWONDER_DEBUG = "1";
 
   const child = spawn(DAEMON_BIN, [], { env, stdio: "inherit" });
   child.on("exit", (code) => process.exit(code || 0));
@@ -764,6 +808,94 @@ async function cmdDispatch(args) {
   }
 }
 
+async function cmdWorkitem(args) {
+  const sub = args[0];
+  if (sub === "upload") {
+    return cmdWorkitemUpload(args.slice(1));
+  }
+  error(`Unknown workitem command: ${sub || "(none)"}`);
+  cmdHelp();
+  process.exit(1);
+}
+
+function uploadExitCode(err) {
+  if (err && err.statusCode) {
+    switch (err.statusCode) {
+      case 401: return 3;
+      case 403: return 4;
+      case 404: return 5;
+      case 409: return 6;
+      case 413: return 7;
+    }
+    if (err.statusCode >= 400) return 8;
+    return 9;
+  }
+  if (err && (err.kind === "network" || err.kind === "redirect")) return 9;
+  return 2;
+}
+
+function reportUploadFailure(err, json) {
+  if (json) {
+    const payload = { success: false, error: err.message };
+    if (err.statusCode) payload.status = err.statusCode;
+    if (err.kind) payload.kind = err.kind;
+    if (err.serverError) payload.server = err.serverError;
+    console.log(JSON.stringify(payload));
+  } else {
+    error(err.message);
+    if (err.serverError && (err.serverError.message || err.serverError.code)) {
+      error(`server: ${err.serverError.message || "rejected"} (code ${err.serverError.code})`);
+    }
+  }
+}
+
+async function cmdWorkitemUpload(args) {
+  const upload = require("../lib/workitem-upload");
+  const json = args.includes("--json");
+  try {
+    const parsed = upload.parseUploadFlags(args);
+    const serverUrl = upload.validateServerUrl(parsed.serverUrl);
+    const workitemId = upload.validateWorkitemId(parsed.workitemId);
+    const token = parsed.token || process.env.AUTOWONDER_UPLOAD_TOKEN;
+    if (!token) {
+      throw new upload.UploadError(
+        "no upload token provided. Invoke the MCP tool autowonder.workitem_cli_upload_token to mint one, " +
+        "then pass it via --token or the AUTOWONDER_UPLOAD_TOKEN environment variable.",
+        { kind: "token" },
+      );
+    }
+    const files = upload.preflightFiles(parsed.files);
+
+    const { statusCode, body } = await upload.uploadWorkitemDocuments({
+      serverUrl, workitemId, files, token,
+    });
+
+    if (statusCode === 200) {
+      let parsedBody = null;
+      try { parsedBody = JSON.parse(body); } catch { /* non-JSON success bodies are ignored */ }
+      if (parsed.json) {
+        console.log(JSON.stringify({
+          success: true,
+          workitemId: Number(workitemId),
+          uploaded: files.map((f) => f.filename),
+          response: parsedBody,
+        }));
+      } else {
+        log(`Uploaded ${files.length} file(s) to workitem ${workitemId}: ${files.map((f) => f.filename).join(", ")}`);
+      }
+      return;
+    }
+
+    throw new upload.UploadError(
+      `server rejected the upload (HTTP ${statusCode})`,
+      { kind: "http", statusCode, serverError: upload.parseServerError(body) },
+    );
+  } catch (err) {
+    reportUploadFailure(err, json);
+    process.exit(uploadExitCode(err));
+  }
+}
+
 async function cmdInstall(args) {
   const flags = parseFlags(args, ["force", "provider", "max-tasks", "addr"]);
   const force = flags.force === "true" || args.includes("--force");
@@ -786,9 +918,11 @@ function cmdHelp() {
     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
 
   Options:
-    --provider <name>     Agent provider: claude, codex, qoder (default: auto-detect)
+    --provider <name>     Agent provider: claude, codex, qoder, qodercn (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
@@ -800,6 +934,11 @@ function cmdHelp() {
     --settings <file>     Claude settings JSON file
     --memory-mode <mode>  Memory: platform, provider-local, or none (default: platform)
     --name <name>         Runtime name (default: provider + executor ID)
+    --debug               Stream full daemon and agent activity to console + log file
+    --server-url <url>    AutoWonder server base URL (workitem upload)
+    --workitem-id <id>    Target workitem ID (workitem upload)
+    --file <path>         Local file to upload, repeatable (workitem upload)
+    --json                Machine-readable output (workitem upload)
     -h, --help            Show this help
 
   Examples:
@@ -810,6 +949,9 @@ function cmdHelp() {
     npx -y autowonder start
     npx -y autowonder dispatch ./assignment.json
 
+    # 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
+
     # Check what's happening
     npx -y autowonder status
   `);
@@ -847,6 +989,7 @@ async function main() {
     case "status":   return cmdStatus();
     case "dispatch": return cmdDispatch(commandArgs);
     case "install":  return cmdInstall(commandArgs);
+    case "workitem": return cmdWorkitem(commandArgs);
     case "help":
     case "--help":
     case "-h":       return cmdHelp();

package/lib/workitem-upload.js

@@ -0,0 +1,285 @@
+"use strict";
+
+// Workitem requirement/design document upload: streaming multipart over
+// Node >= 16 built-ins only. Never Base64 encodes and never buffers whole
+// file bodies; the server is authoritative for validation.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const path = require("node:path");
+
+const ALLOWED_EXTENSIONS = [".md", ".markdown", ".png", ".jpg", ".jpeg", ".webp"];
+const MAX_FILES = 10;
+const MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024;
+const MAX_TOTAL_SIZE_BYTES = 20 * 1024 * 1024;
+const UPLOAD_PATH_PREFIX = "/api/cli/workitems/";
+const UPLOAD_PATH_SUFFIX = "/requirement-documents";
+
+const CONTENT_TYPES = {
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+};
+
+class UploadError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "UploadError";
+    Object.assign(this, details);
+  }
+}
+
+function parseUploadFlags(args) {
+  const FLAG_KEYS = {
+    "server-url": "serverUrl",
+    "workitem-id": "workitemId",
+    token: "token",
+    file: "file",
+  };
+  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 UploadError(`unexpected argument: ${arg}`, { kind: "usage" });
+    }
+    const key = arg.slice(2);
+    if (!FLAG_KEYS[key]) {
+      throw new UploadError(`unknown option: ${arg}`, { kind: "usage" });
+    }
+    if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+      throw new UploadError(`--${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 UploadError(`--${key} may only be specified once`, { kind: "usage" });
+    }
+    options[optionKey] = value;
+  }
+  return options;
+}
+
+function validateServerUrl(value) {
+  if (!value) {
+    throw new UploadError("--server-url is required", { kind: "usage" });
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new UploadError(`--server-url must be an absolute http(s) URL: ${value}`, { kind: "usage" });
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new UploadError(`--server-url must use http or https: ${value}`, { kind: "usage" });
+  }
+  if (url.username || url.password) {
+    throw new UploadError("--server-url must not embed credentials", { kind: "usage" });
+  }
+  if (url.search) {
+    throw new UploadError("--server-url must not contain a query string", { kind: "usage" });
+  }
+  if (url.hash) {
+    throw new UploadError("--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 UploadError(`--workitem-id must be a positive integer: ${value}`, { kind: "usage" });
+  }
+  return String(value);
+}
+
+function preflightFiles(filePaths) {
+  if (!filePaths.length) {
+    throw new UploadError("at least one --file is required", { kind: "usage" });
+  }
+  if (filePaths.length > MAX_FILES) {
+    throw new UploadError(`too many files: at most ${MAX_FILES} per upload`, { kind: "usage" });
+  }
+  let total = 0;
+  const prepared = [];
+  for (const filePath of filePaths) {
+    let stat;
+    try {
+      fs.accessSync(filePath, fs.constants.R_OK);
+      stat = fs.statSync(filePath);
+    } catch {
+      throw new UploadError(`file not found or not readable: ${filePath}`, { kind: "usage" });
+    }
+    if (!stat.isFile()) {
+      throw new UploadError(`not a regular file: ${filePath}`, { kind: "usage" });
+    }
+    const extension = path.extname(filePath).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.includes(extension)) {
+      throw new UploadError(
+        `unsupported file type: ${filePath} (allowed: ${ALLOWED_EXTENSIONS.join(", ")})`,
+        { kind: "usage" },
+      );
+    }
+    if (stat.size > MAX_FILE_SIZE_BYTES) {
+      throw new UploadError(
+        `file too large: ${filePath} (${stat.size} bytes; limit is ${MAX_FILE_SIZE_BYTES})`,
+        { kind: "usage" },
+      );
+    }
+    total += stat.size;
+    prepared.push({ filePath, filename: path.basename(filePath), size: stat.size });
+  }
+  if (total > MAX_TOTAL_SIZE_BYTES) {
+    throw new UploadError(
+      `total upload size too large: ${total} bytes (limit is ${MAX_TOTAL_SIZE_BYTES})`,
+      { kind: "usage" },
+    );
+  }
+  return prepared;
+}
+
+function writeChunk(request, chunk) {
+  return new Promise((resolve) => {
+    if (request.write(chunk)) {
+      resolve();
+    } else {
+      request.once("drain", resolve);
+    }
+  });
+}
+
+async function writePart(request, boundary, file) {
+  const safeName = file.filename.replace(/["\r\n]/g, "_");
+  const contentType = CONTENT_TYPES[path.extname(file.filename).toLowerCase()] || "application/octet-stream";
+  await writeChunk(
+    request,
+    `--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="files"; filename="${safeName}"\r\n` +
+      `Content-Type: ${contentType}\r\n\r\n`,
+  );
+  await new Promise((resolve, reject) => {
+    const stream = fs.createReadStream(file.filePath);
+    stream.on("error", (err) => {
+      err.filePath = file.filePath;
+      reject(err);
+    });
+    stream.on("data", (chunk) => {
+      if (!request.write(chunk)) {
+        stream.pause();
+      }
+    });
+    request.on("drain", () => stream.resume());
+    stream.on("end", resolve);
+  });
+  await writeChunk(request, "\r\n");
+}
+
+function parseServerError(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;
+}
+
+function uploadWorkitemDocuments({ serverUrl, workitemId, files, token }) {
+  return new Promise((resolve, reject) => {
+    const boundary = `----autowonder${crypto.randomBytes(16).toString("hex")}`;
+    const url = new URL(`${serverUrl}${UPLOAD_PATH_PREFIX}${workitemId}${UPLOAD_PATH_SUFFIX}`);
+    const client = url.protocol === "https:" ? https : http;
+    let settled = false;
+    let sentAny = 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: "POST",
+        headers: {
+          "Content-Type": `multipart/form-data; boundary=${boundary}`,
+          Authorization: `Bearer ${token}`,
+        },
+      },
+      (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400) {
+          request.destroy();
+          fail(new UploadError(
+            `server responded with a redirect (HTTP ${response.statusCode}); refusing to follow redirects`,
+            { kind: "redirect", statusCode: response.statusCode },
+          ));
+          return;
+        }
+        let body = "";
+        response.on("data", (chunk) => { body += chunk; });
+        response.on("end", () => finish({ statusCode: response.statusCode, body }));
+        response.on("error", (err) => fail(new UploadError(`response error: ${err.message}`, { kind: "network" })));
+      },
+    );
+
+    request.on("error", (err) => {
+      fail(new UploadError(
+        sentAny
+          ? "connection lost after part of the upload was sent; the outcome is ambiguous. " +
+            "List the workitem's documents to see what arrived before retrying."
+          : `connection failed: ${err.message}`,
+        { kind: "network" },
+      ));
+    });
+
+    (async () => {
+      try {
+        for (const file of files) {
+          await writePart(request, boundary, file);
+          sentAny = true;
+        }
+        await writeChunk(request, `--${boundary}--\r\n`);
+        request.end();
+      } catch (err) {
+        request.destroy();
+        fail(new UploadError(
+          `failed reading ${err.filePath || "file"}: ${err.message}`,
+          { kind: "read" },
+        ));
+      }
+    })();
+  });
+}
+
+module.exports = {
+  ALLOWED_EXTENSIONS,
+  MAX_FILES,
+  MAX_FILE_SIZE_BYTES,
+  MAX_TOTAL_SIZE_BYTES,
+  UploadError,
+  parseUploadFlags,
+  validateServerUrl,
+  validateWorkitemId,
+  preflightFiles,
+  parseServerError,
+  uploadWorkitemDocuments,
+};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "autowonder",
-  "version": "0.2.130",
+  "version": "0.2.132",
   "description": "AutoWonder local runtime — execute AI agent dispatch packages on your machine",
   "bin": {
     "autowonder": "bin/cli.js"
   },
   "files": [
     "bin/",
+    "lib/",
     "scripts/",
     "vendor/"
   ],