@annals/agent-mesh 0.16.10 → 0.16.12

package/README.md

@@ -24,7 +24,7 @@ The ticket is one-time use and expires in 15 minutes.
 
 | Agent | Status | How it connects |
 |-------|--------|-----------------|
-| [OpenClaw](https://github.com/nicepkg/openclaw) | Available | WebSocket to local gateway (Protocol v3) |
+| [Claude Code](https://github.com/nicepkg/claude) | Available | WebSocket to local gateway (Protocol v3) |
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Available | stdio (stream-json format) |
 | Codex CLI | Planned | — |
 | Gemini CLI | Planned | — |
@@ -36,8 +36,8 @@ agent-mesh connect [type]              # Connect agent to platform
   --setup <url>                          #   One-click setup from ticket URL
   --agent-id <id>                        #   Agent UUID
   --project <path>                       #   Project path (Claude adapter)
-  --gateway-url <url>                    #   OpenClaw gateway URL
-  --gateway-token <token>                #   OpenClaw gateway token
+  --gateway-url <url>                    #   Claude Code gateway URL
+  --gateway-token <token>                #   Claude Code gateway token
   --sandbox                              #   Run inside sandbox (macOS, requires srt)
 
 agent-mesh login                       # Authenticate
@@ -49,7 +49,7 @@ agent-mesh status                      # Check connection
 ```
   Your machine                          Cloud                         Users
   ┌──────────────────┐    outbound     ┌─────────────────────┐     ┌──────────┐
-  │  OpenClaw         │   WebSocket    │                     │     │          │
+  │  Claude Code         │   WebSocket    │                     │     │          │
   │  Claude Code      ├──────────────► │  bridge.agents.hot  │ ◄── │ Platform │
   │  Codex (planned)  │   (no inbound  │  (Cloudflare Worker)│     │ IM bots  │
   │  Gemini (planned) │    ports)      │                     │     │ API      │
@@ -83,7 +83,7 @@ For Claude Code agents, any files the agent creates or modifies are automaticall
 
 ## 中文说明
 
-Agent Mesh CLI 把你本地的 AI Agent（OpenClaw、Claude Code 等）接入 [agents.hot](https://agents.hot) 平台。用户在网页聊天，你赚钱。Agent 始终运行在你自己的机器上，无需开放端口。
+Agent Mesh CLI 把你本地的 AI Agent（Claude Code、Claude Code 等）接入 [agents.hot](https://agents.hot) 平台。用户在网页聊天，你赚钱。Agent 始终运行在你自己的机器上，无需开放端口。
 
 每个用户自动获得独立的工作目录（workspace 隔离），Claude Code 的输出文件会自动上传回平台。
 

package/dist/{chunk-U32JDKSN.js → chunk-KEUGYA3L.js}

@@ -40,6 +40,16 @@ function updateConfig(partial) {
   const existing = loadConfig();
   saveConfig({ ...existing, ...partial });
 }
+function maybePrintDocsHint(docsUrl) {
+  const config = loadConfig();
+  if (config.docsHintShownAt) return;
+  process.stderr.write(`
+[agent-mesh] Docs: ${docsUrl}
+
+`);
+  config.docsHintShownAt = (/* @__PURE__ */ new Date()).toISOString();
+  saveConfig(config);
+}
 function parsePositiveInt(raw) {
   if (typeof raw !== "number" || !Number.isFinite(raw)) return void 0;
   const n = Math.floor(raw);
@@ -944,6 +954,7 @@ export {
   DEFAULT_RUNTIME_CONFIG,
   loadConfig,
   updateConfig,
+  maybePrintDocsHint,
   resolveRuntimeConfig,
   getRuntimeConfig,
   updateRuntimeConfig,

package/dist/index.js

@@ -16,6 +16,7 @@ import {
   isProcessAlive,
   listAgents,
   loadConfig,
+  maybePrintDocsHint,
   readPid,
   registerListCommand,
   removeAgent,
@@ -29,7 +30,7 @@ import {
   updateConfig,
   updateRuntimeConfig,
   writePid
-} from "./chunk-U32JDKSN.js";
+} from "./chunk-KEUGYA3L.js";
 
 // src/index.ts
 import { createRequire } from "module";
@@ -810,7 +811,7 @@ var BridgeManager = class {
   }
   async dispatchWithLocalQueue(opts) {
     const { msg, handle, requestKey } = opts;
-    const { session_id, request_id, content, attachments, upload_url, upload_token, client_id } = msg;
+    const { session_id, request_id, content, attachments, upload_url, upload_token, client_id, platform_task } = msg;
     const state = this.requestDispatches.get(requestKey);
     if (!state) return;
     try {
@@ -831,7 +832,7 @@ var BridgeManager = class {
       }
       const uploadCredentials = upload_url && upload_token ? { uploadUrl: upload_url, uploadToken: upload_token } : void 0;
       try {
-        handle.send(content, attachments, uploadCredentials, client_id);
+        handle.send(content, attachments, uploadCredentials, client_id, platform_task);
         this.sessionLastSeenAt.set(session_id, Date.now());
       } catch (err) {
         log.error(`Failed to send to adapter: ${err}`);
@@ -889,13 +890,16 @@ var BridgeManager = class {
       this.wsClient.send(chunk);
       this.sessionLastSeenAt.set(sessionId, Date.now());
     });
-    handle.onDone((attachments) => {
+    handle.onDone((payload) => {
       void this.releaseRequestLease(sessionId, requestRef.requestId, "done");
+      const attachments = payload?.attachments;
+      const fileManifest = payload?.fileManifest;
       const done = {
         type: "done",
         session_id: sessionId,
         request_id: requestRef.requestId,
         ...attachments && attachments.length > 0 && { attachments },
+        ...fileManifest && fileManifest.length > 0 && { file_manifest: fileManifest },
         ...fullResponseBuffer && { result: fullResponseBuffer }
       };
       this.trackRequest(sessionId, requestRef.requestId, "done");
@@ -1125,7 +1129,6 @@ var SENSITIVE_PATHS = [
   "~/.claude/ide",
   // IDE integration data
   // Other AI agent configs (contain API keys / tokens)
-  "~/.openclaw",
   // ~/.agent-mesh — fine-grained: block tokens/config, allow agent workspaces
   // NOT blocked: ~/.agent-mesh/agents/ (per-agent project workspaces used as cwd)
   "~/.agent-mesh/config.json",
@@ -1150,11 +1153,6 @@ var SANDBOX_PRESETS = {
     denyRead: [...SENSITIVE_PATHS],
     allowWrite: [".", "/tmp"],
     denyWrite: [".env", ".env.*"]
-  },
-  openclaw: {
-    denyRead: [...SENSITIVE_PATHS],
-    allowWrite: ["/tmp"],
-    denyWrite: [".env", ".env.*"]
   }
 };
 var sandboxManager = null;
@@ -1425,13 +1423,12 @@ function createClientWorkspace(projectPath, clientId) {
 }
 
 // src/adapters/claude.ts
-import { readFile as readFile2, writeFile, mkdir } from "fs/promises";
+import { readFile as readFile2, writeFile, mkdir, stat as stat2 } from "fs/promises";
 import { join as join5, relative as relative3, basename } from "path";
 
 // src/utils/auto-upload.ts
 import { readdir, readFile, stat } from "fs/promises";
 import { join as join4, relative as relative2 } from "path";
-var MAX_AUTO_UPLOAD_FILES = 50;
 var MAX_AUTO_UPLOAD_FILE_SIZE = 10 * 1024 * 1024;
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   ".git",
@@ -1485,76 +1482,152 @@ async function collectRealFiles(dir, maxFiles = Infinity) {
   await walk(dir);
   return files;
 }
-async function snapshotWorkspace(workspacePath) {
-  const snapshot = /* @__PURE__ */ new Map();
-  try {
-    const files = await collectRealFiles(workspacePath);
-    for (const filePath of files) {
-      try {
-        const s = await stat(filePath);
-        snapshot.set(filePath, { mtimeMs: s.mtimeMs, size: s.size });
-      } catch {
-      }
+
+// src/utils/zip.ts
+import { deflateRawSync, inflateRawSync } from "zlib";
+function dosTime(date) {
+  return {
+    time: date.getHours() << 11 | date.getMinutes() << 5 | date.getSeconds() >> 1,
+    date: date.getFullYear() - 1980 << 9 | date.getMonth() + 1 << 5 | date.getDate()
+  };
+}
+function crc32(buf) {
+  let crc = 4294967295;
+  for (let i = 0; i < buf.length; i++) {
+    crc ^= buf[i];
+    for (let j = 0; j < 8; j++) {
+      crc = crc >>> 1 ^ (crc & 1 ? 3988292384 : 0);
     }
-    log.debug(`Workspace snapshot: ${snapshot.size} files`);
-  } catch (err) {
-    log.debug(`Workspace snapshot failed: ${err}`);
   }
-  return snapshot;
+  return (crc ^ 4294967295) >>> 0;
 }
-async function diffAndUpload(params) {
-  const { workspace, snapshot, uploadUrl, uploadToken } = params;
-  const currentFiles = await collectRealFiles(workspace);
-  const newOrModified = [];
-  for (const filePath of currentFiles) {
-    try {
-      const s = await stat(filePath);
-      const prev = snapshot.get(filePath);
-      if (!prev || s.mtimeMs !== prev.mtimeMs || s.size !== prev.size) {
-        newOrModified.push(filePath);
-      }
-    } catch {
+function writeUint16LE(buf, val, offset) {
+  buf[offset] = val & 255;
+  buf[offset + 1] = val >>> 8 & 255;
+}
+function writeUint32LE(buf, val, offset) {
+  buf[offset] = val & 255;
+  buf[offset + 1] = val >>> 8 & 255;
+  buf[offset + 2] = val >>> 16 & 255;
+  buf[offset + 3] = val >>> 24 & 255;
+}
+function createZipBuffer(entries) {
+  const now = /* @__PURE__ */ new Date();
+  const { time, date } = dosTime(now);
+  const records = [];
+  const chunks = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const nameBytes = Buffer.from(entry.path, "utf-8");
+    const crc = crc32(entry.data);
+    const compressed = deflateRawSync(entry.data, { level: 6 });
+    const compressedSize = compressed.length;
+    const uncompressedSize = entry.data.length;
+    const header = Buffer.alloc(30 + nameBytes.length);
+    writeUint32LE(header, 67324752, 0);
+    writeUint16LE(header, 20, 4);
+    writeUint16LE(header, 0, 6);
+    writeUint16LE(header, 8, 8);
+    writeUint16LE(header, time, 10);
+    writeUint16LE(header, date, 12);
+    writeUint32LE(header, crc, 14);
+    writeUint32LE(header, compressedSize, 18);
+    writeUint32LE(header, uncompressedSize, 22);
+    writeUint16LE(header, nameBytes.length, 26);
+    writeUint16LE(header, 0, 28);
+    nameBytes.copy(header, 30);
+    records.push({ header, compressed, crc, compressedSize, uncompressedSize, offset });
+    chunks.push(header, compressed);
+    offset += header.length + compressed.length;
+  }
+  const centralDirStart = offset;
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const rec = records[i];
+    const nameBytes = Buffer.from(entry.path, "utf-8");
+    const cdh = Buffer.alloc(46 + nameBytes.length);
+    writeUint32LE(cdh, 33639248, 0);
+    writeUint16LE(cdh, 20, 4);
+    writeUint16LE(cdh, 20, 6);
+    writeUint16LE(cdh, 0, 8);
+    writeUint16LE(cdh, 8, 10);
+    writeUint16LE(cdh, time, 12);
+    writeUint16LE(cdh, date, 14);
+    writeUint32LE(cdh, rec.crc, 16);
+    writeUint32LE(cdh, rec.compressedSize, 20);
+    writeUint32LE(cdh, rec.uncompressedSize, 24);
+    writeUint16LE(cdh, nameBytes.length, 28);
+    writeUint16LE(cdh, 0, 30);
+    writeUint16LE(cdh, 0, 32);
+    writeUint16LE(cdh, 0, 34);
+    writeUint16LE(cdh, 0, 36);
+    writeUint32LE(cdh, 0, 38);
+    writeUint32LE(cdh, rec.offset, 42);
+    nameBytes.copy(cdh, 46);
+    chunks.push(cdh);
+    offset += cdh.length;
+  }
+  const centralDirSize = offset - centralDirStart;
+  const eocd = Buffer.alloc(22);
+  writeUint32LE(eocd, 101010256, 0);
+  writeUint16LE(eocd, 0, 4);
+  writeUint16LE(eocd, 0, 6);
+  writeUint16LE(eocd, entries.length, 8);
+  writeUint16LE(eocd, entries.length, 10);
+  writeUint32LE(eocd, centralDirSize, 12);
+  writeUint32LE(eocd, centralDirStart, 16);
+  writeUint16LE(eocd, 0, 20);
+  chunks.push(eocd);
+  return Buffer.concat(chunks);
+}
+function extractZipBuffer(buf) {
+  const entries = [];
+  let eocdOffset = -1;
+  for (let i = buf.length - 22; i >= 0; i--) {
+    if (buf.readUInt32LE(i) === 101010256) {
+      eocdOffset = i;
+      break;
     }
   }
-  if (newOrModified.length === 0) return [];
-  log.debug(`Workspace diff: ${newOrModified.length} new/modified file(s)`);
-  const attachments = [];
-  const filesToUpload = newOrModified.slice(0, MAX_AUTO_UPLOAD_FILES);
-  for (const absPath of filesToUpload) {
-    try {
-      const buffer = await readFile(absPath);
-      if (buffer.length === 0 || buffer.length > MAX_AUTO_UPLOAD_FILE_SIZE) continue;
-      const relPath = relative2(workspace, absPath).replace(/\\/g, "/");
-      const filename = relPath && !relPath.startsWith("..") ? relPath : absPath.split("/").pop() || "file";
-      const response = await fetch(uploadUrl, {
-        method: "POST",
-        headers: {
-          "X-Upload-Token": uploadToken,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          filename,
-          content: buffer.toString("base64")
-        })
-      });
-      if (!response.ok) {
-        log.warn(`Auto-upload failed (${response.status}) for ${filename}`);
-        continue;
+  if (eocdOffset === -1) {
+    throw new Error("Invalid ZIP: EOCD not found");
+  }
+  const entryCount = buf.readUInt16LE(eocdOffset + 10);
+  const centralDirOffset = buf.readUInt32LE(eocdOffset + 16);
+  let offset = centralDirOffset;
+  for (let i = 0; i < entryCount; i++) {
+    if (buf.readUInt32LE(offset) !== 33639248) {
+      throw new Error(`Invalid ZIP: bad central directory signature at ${offset}`);
+    }
+    const compressionMethod = buf.readUInt16LE(offset + 10);
+    const compressedSize = buf.readUInt32LE(offset + 20);
+    const uncompressedSize = buf.readUInt32LE(offset + 24);
+    const nameLen = buf.readUInt16LE(offset + 28);
+    const extraLen = buf.readUInt16LE(offset + 30);
+    const commentLen = buf.readUInt16LE(offset + 32);
+    const localHeaderOffset = buf.readUInt32LE(offset + 42);
+    const name = buf.subarray(offset + 46, offset + 46 + nameLen).toString("utf-8");
+    if (!name.endsWith("/")) {
+      const localNameLen = buf.readUInt16LE(localHeaderOffset + 26);
+      const localExtraLen = buf.readUInt16LE(localHeaderOffset + 28);
+      const dataOffset = localHeaderOffset + 30 + localNameLen + localExtraLen;
+      const compressedData = buf.subarray(dataOffset, dataOffset + compressedSize);
+      let data;
+      if (compressionMethod === 0) {
+        data = Buffer.from(compressedData);
+      } else if (compressionMethod === 8) {
+        data = inflateRawSync(compressedData);
+      } else {
+        throw new Error(`Unsupported compression method: ${compressionMethod}`);
       }
-      const payload = await response.json();
-      if (typeof payload.url === "string" && payload.url.length > 0) {
-        const ext = filename.split(".").pop()?.toLowerCase() || "";
-        attachments.push({
-          name: filename,
-          url: payload.url,
-          type: MIME_MAP[ext] || "application/octet-stream"
-        });
+      if (data.length !== uncompressedSize) {
+        throw new Error(`Size mismatch for ${name}: expected ${uncompressedSize}, got ${data.length}`);
       }
-    } catch (err) {
-      log.warn(`Auto-upload error for ${absPath}: ${err}`);
+      entries.push({ path: name, data });
     }
+    offset += 46 + nameLen + extraLen + commentLen;
   }
-  return attachments;
+  return entries;
 }
 
 // src/adapters/claude.ts
@@ -1568,9 +1641,9 @@ var CLAUDE_RUNTIME_ALLOW_WRITE_PATHS = [
   `${HOME_DIR}/.claude.json.tmp`,
   `${HOME_DIR}/.local/state/claude`
 ];
-var COLLECT_TASK_MARKER = "Collect files task (platform-issued):";
-var MAX_UPLOAD_FILE_SIZE = 20 * 1024 * 1024;
-var MAX_COLLECT_FILES = 1500;
+var MAX_UPLOAD_FILE_SIZE = 200 * 1024 * 1024;
+var MAX_COLLECT_FILES = 5e3;
+var DEFAULT_ZIP_MAX_BYTES = 200 * 1024 * 1024;
 function resolveIdleTimeoutMs() {
   const raw = process.env.AGENT_BRIDGE_CLAUDE_IDLE_TIMEOUT_MS;
   if (!raw) return DEFAULT_IDLE_TIMEOUT;
@@ -1606,9 +1679,7 @@ var ClaudeSession = class {
   uploadCredentials = null;
   /** Per-client workspace path (symlink-based), set on each send() */
   currentWorkspace;
-  /** Pre-message workspace file snapshot for diffing */
-  preMessageSnapshot = /* @__PURE__ */ new Map();
-  send(message, attachments, uploadCredentials, clientId) {
+  send(message, attachments, uploadCredentials, clientId, platformTask) {
     this.resetIdleTimer();
     this.doneFired = false;
     this.chunksEmitted = false;
@@ -1623,13 +1694,12 @@ var ClaudeSession = class {
     } else {
       this.currentWorkspace = void 0;
     }
-    const collectTask = this.parseCollectWorkspaceTask(message);
-    if (collectTask) {
-      void this.runCollectWorkspaceTask(collectTask);
+    if (platformTask) {
+      void this.runPlatformTask(platformTask);
       return;
     }
     const args = ["-p", message, "--continue", "--output-format", "stream-json", "--verbose", "--include-partial-messages", "--dangerously-skip-permissions"];
-    void this.downloadAttachments(attachments).then(() => this.takeSnapshot()).then(() => {
+    void this.downloadAttachments(attachments).then(() => {
       this.launchProcess(args);
     });
   }
@@ -1713,80 +1783,151 @@ var ClaudeSession = class {
       }
     });
   }
-  parseCollectWorkspaceTask(message) {
-    if (!message.includes("[PLATFORM TASK]") || !message.includes("[END PLATFORM TASK]")) {
-      return null;
-    }
-    if (!message.includes(COLLECT_TASK_MARKER)) {
-      return null;
-    }
-    const urlMatch = message.match(/UPLOAD_URL=(\S+)/);
-    const tokenMatch = message.match(/UPLOAD_TOKEN=(\S+)/);
-    if (!urlMatch || !tokenMatch) {
-      return null;
-    }
-    return {
-      uploadUrl: urlMatch[1].trim(),
-      uploadToken: tokenMatch[1].trim()
-    };
+  getWorkspaceRoot() {
+    return this.currentWorkspace || this.config.project || process.cwd();
+  }
+  normalizeRelativePath(inputPath) {
+    const normalized = inputPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!normalized || normalized.includes("\0")) return null;
+    if (normalized.split("/").some((seg) => seg === "..")) return null;
+    return normalized;
   }
-  async runCollectWorkspaceTask(task) {
-    const workspaceRoot = this.currentWorkspace || this.config.project || process.cwd();
+  async runPlatformTask(task) {
     try {
-      const files = await this.collectWorkspaceFiles(workspaceRoot);
-      if (files.length === 0) {
-        this.emitChunk("NO_FILES_FOUND");
-        this.doneFired = true;
-        for (const cb of this.doneCallbacks) cb();
-        return;
+      if (!this.uploadCredentials) {
+        throw new Error("Missing upload credentials for platform task");
       }
-      const uploadedUrls = [];
-      for (const absPath of files) {
-        this.resetIdleTimer();
-        try {
-          const buffer = await readFile2(absPath);
-          if (buffer.length === 0 || buffer.length > MAX_UPLOAD_FILE_SIZE) {
-            continue;
-          }
-          const relPath = relative3(workspaceRoot, absPath).replace(/\\/g, "/");
-          const filename = relPath && !relPath.startsWith("..") ? relPath : absPath.split("/").pop() || "file";
-          const response = await fetch(task.uploadUrl, {
-            method: "POST",
-            headers: {
-              "X-Upload-Token": task.uploadToken,
-              "Content-Type": "application/json"
-            },
-            body: JSON.stringify({
-              filename,
-              content: buffer.toString("base64")
-            })
-          });
-          if (!response.ok) {
-            log.warn(`collect-files upload failed (${response.status}) for ${filename}`);
-            continue;
-          }
-          const payload = await response.json();
-          if (typeof payload.url === "string" && payload.url.length > 0) {
-            uploadedUrls.push(payload.url);
-          }
-        } catch (error) {
-          log.warn(`collect-files upload error for ${absPath}: ${error}`);
-        }
-      }
-      if (uploadedUrls.length === 0) {
-        this.emitChunk("COLLECT_FILES_FAILED");
+      if (task.type === "upload_file") {
+        await this.runUploadFileTask(task.path);
+      } else if (task.type === "upload_all_zip") {
+        await this.runUploadAllZipTask(task.zip_name, task.max_bytes);
       } else {
-        this.emitChunk(uploadedUrls.join("\n"));
+        throw new Error(`Unsupported platform task: ${task.type || "unknown"}`);
       }
       this.doneFired = true;
-      for (const cb of this.doneCallbacks) cb();
     } catch (error) {
-      this.emitError(new Error(`Collect files task failed: ${error instanceof Error ? error.message : String(error)}`));
+      this.emitError(new Error(`Platform task failed: ${error instanceof Error ? error.message : String(error)}`));
+    }
+  }
+  async runUploadFileTask(path) {
+    const workspaceRoot = this.getWorkspaceRoot();
+    const relPath = this.normalizeRelativePath(path);
+    if (!relPath) {
+      throw new Error("Invalid file path");
+    }
+    const absPath = join5(workspaceRoot, relPath);
+    const info = await stat2(absPath);
+    if (!info.isFile()) {
+      throw new Error("Path is not a regular file");
+    }
+    const buffer = await readFile2(absPath);
+    if (buffer.length === 0 || buffer.length > MAX_UPLOAD_FILE_SIZE) {
+      throw new Error(`File size out of bounds: ${buffer.length}`);
+    }
+    const uploaded = await this.uploadBuffer(relPath, buffer);
+    for (const cb of this.doneCallbacks) cb({ attachments: [uploaded] });
+  }
+  async runUploadAllZipTask(zipName, maxBytes) {
+    const workspaceRoot = this.getWorkspaceRoot();
+    const files = await this.collectWorkspaceFiles(workspaceRoot);
+    if (files.length === 0) {
+      throw new Error("No files found");
     }
+    const maxZipBytes = typeof maxBytes === "number" && Number.isFinite(maxBytes) && maxBytes > 0 ? Math.floor(maxBytes) : DEFAULT_ZIP_MAX_BYTES;
+    const entries = [];
+    let totalBytes = 0;
+    for (const absPath of files) {
+      this.resetIdleTimer();
+      const relPath = relative3(workspaceRoot, absPath).replace(/\\/g, "/");
+      if (!relPath || relPath.startsWith("..")) continue;
+      const buffer = await readFile2(absPath);
+      if (buffer.length === 0) continue;
+      totalBytes += buffer.length;
+      if (totalBytes > maxZipBytes) {
+        throw new Error(`ZIP_TOO_LARGE:${totalBytes}`);
+      }
+      entries.push({ path: relPath, data: buffer });
+    }
+    const zipBuffer = createZipBuffer(entries);
+    if (zipBuffer.length > maxZipBytes) {
+      throw new Error(`ZIP_TOO_LARGE:${zipBuffer.length}`);
+    }
+    const safeZipName = this.normalizeRelativePath(zipName || "") || `workspace-${this.sessionId.slice(0, 8)}.zip`;
+    const uploaded = await this.uploadBuffer(safeZipName.endsWith(".zip") ? safeZipName : `${safeZipName}.zip`, zipBuffer);
+    for (const cb of this.doneCallbacks) cb({ attachments: [uploaded] });
+  }
+  async uploadBuffer(filename, buffer) {
+    const creds = this.uploadCredentials;
+    if (!creds) {
+      throw new Error("Upload credentials missing");
+    }
+    const response = await fetch(creds.uploadUrl, {
+      method: "POST",
+      headers: {
+        "X-Upload-Token": creds.uploadToken,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        filename,
+        content: buffer.toString("base64")
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Upload failed (${response.status}) for ${filename}`);
+    }
+    const payload = await response.json();
+    if (typeof payload.url !== "string" || payload.url.length === 0) {
+      throw new Error(`Upload response missing url for ${filename}`);
+    }
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    return {
+      name: filename,
+      url: payload.url,
+      type: MIME_MAP[ext] || "application/octet-stream"
+    };
   }
   async collectWorkspaceFiles(workspaceRoot) {
     return collectRealFiles(workspaceRoot, MAX_COLLECT_FILES);
   }
+  async collectWorkspaceManifest(workspaceRoot) {
+    const files = await this.collectWorkspaceFiles(workspaceRoot);
+    const manifest = [];
+    for (const absPath of files) {
+      const relPath = relative3(workspaceRoot, absPath).replace(/\\/g, "/");
+      if (!relPath || relPath.startsWith("..")) continue;
+      try {
+        const fileStat = await stat2(absPath);
+        if (!fileStat.isFile()) continue;
+        const ext = relPath.split(".").pop()?.toLowerCase() || "";
+        manifest.push({
+          path: relPath,
+          size: fileStat.size,
+          mtime_ms: Math.floor(fileStat.mtimeMs),
+          type: MIME_MAP[ext] || "application/octet-stream"
+        });
+      } catch {
+      }
+    }
+    manifest.sort((a, b) => a.path.localeCompare(b.path));
+    return manifest;
+  }
+  async finalizeDone(attachments) {
+    const workspaceRoot = this.getWorkspaceRoot();
+    let fileManifest;
+    try {
+      fileManifest = await this.collectWorkspaceManifest(workspaceRoot);
+    } catch (error) {
+      log.warn(`Manifest collection failed: ${error}`);
+    }
+    const payload = {};
+    if (attachments && attachments.length > 0) {
+      payload.attachments = attachments;
+    }
+    if (fileManifest) {
+      payload.fileManifest = fileManifest;
+    }
+    for (const cb of this.doneCallbacks) cb(payload);
+  }
   onChunk(cb) {
     this.chunkCallbacks.push(cb);
   }
@@ -1921,47 +2062,15 @@ var ClaudeSession = class {
         }
       }
       this.doneFired = true;
-      void this.autoUploadAndDone();
+      void this.finalizeDone();
       return;
     }
     if (event.type === "assistant" && event.subtype === "end") {
       this.doneFired = true;
-      for (const cb of this.doneCallbacks) cb();
+      void this.finalizeDone();
       return;
     }
   }
-  /**
-   * Auto-upload new/modified files from workspace, then fire done callbacks.
-   */
-  async autoUploadAndDone() {
-    let attachments;
-    const workspaceRoot = this.currentWorkspace || this.config.project;
-    if (this.uploadCredentials && workspaceRoot) {
-      try {
-        attachments = await diffAndUpload({
-          workspace: workspaceRoot,
-          snapshot: this.preMessageSnapshot,
-          uploadUrl: this.uploadCredentials.uploadUrl,
-          uploadToken: this.uploadCredentials.uploadToken
-        });
-        if (attachments && attachments.length > 0) {
-          log.info(`Auto-uploaded ${attachments.length} file(s) from workspace`);
-        }
-      } catch (err) {
-        log.warn(`Auto-upload failed: ${err}`);
-      }
-    }
-    for (const cb of this.doneCallbacks) cb(attachments);
-  }
-  /**
-   * Snapshot all files in the workspace before Claude starts processing.
-   */
-  async takeSnapshot() {
-    this.preMessageSnapshot.clear();
-    const workspaceRoot = this.currentWorkspace || this.config.project;
-    if (!workspaceRoot) return;
-    this.preMessageSnapshot = await snapshotWorkspace(workspaceRoot);
-  }
   emitChunk(text) {
     this.chunksEmitted = true;
     for (const cb of this.chunkCallbacks) cb(text);
@@ -2132,7 +2241,7 @@ function registerConnectCommand(program2) {
             log.error(`Failed to start. Check logs: ${getLogPath(slug)}`);
             process.exit(1);
           }
-          const { ListTUI } = await import("./list-KMJ463VL.js");
+          const { ListTUI } = await import("./list-ROLJARYB.js");
           const tui = new ListTUI();
           await tui.run();
           return;
@@ -3284,6 +3393,10 @@ async function asyncChat(opts) {
 `);
         }
       }
+      if (task.file_manifest) {
+        process.stdout.write(`${GRAY}[manifest: ${task.file_manifest.length} files]${RESET}
+`);
+      }
       return;
     }
     if (task.status === "failed") {
@@ -3490,7 +3603,7 @@ import { readFile as readFile4, writeFile as writeFile3, readdir as readdir2, mk
 import { join as join9, resolve, relative as relative4 } from "path";
 
 // src/utils/skill-parser.ts
-import { readFile as readFile3, writeFile as writeFile2, stat as stat2 } from "fs/promises";
+import { readFile as readFile3, writeFile as writeFile2, stat as stat3 } from "fs/promises";
 import { join as join8 } from "path";
 function parseSkillMd(raw) {
   const trimmed = raw.trimStart();
@@ -3601,7 +3714,7 @@ async function loadSkillManifest(dir) {
 }
 async function pathExists(p) {
   try {
-    await stat2(p);
+    await stat3(p);
     return true;
   } catch {
     return false;
@@ -3632,153 +3745,6 @@ ${updated}${after}`);
   }
 }
 
-// src/utils/zip.ts
-import { deflateRawSync, inflateRawSync } from "zlib";
-function dosTime(date) {
-  return {
-    time: date.getHours() << 11 | date.getMinutes() << 5 | date.getSeconds() >> 1,
-    date: date.getFullYear() - 1980 << 9 | date.getMonth() + 1 << 5 | date.getDate()
-  };
-}
-function crc32(buf) {
-  let crc = 4294967295;
-  for (let i = 0; i < buf.length; i++) {
-    crc ^= buf[i];
-    for (let j = 0; j < 8; j++) {
-      crc = crc >>> 1 ^ (crc & 1 ? 3988292384 : 0);
-    }
-  }
-  return (crc ^ 4294967295) >>> 0;
-}
-function writeUint16LE(buf, val, offset) {
-  buf[offset] = val & 255;
-  buf[offset + 1] = val >>> 8 & 255;
-}
-function writeUint32LE(buf, val, offset) {
-  buf[offset] = val & 255;
-  buf[offset + 1] = val >>> 8 & 255;
-  buf[offset + 2] = val >>> 16 & 255;
-  buf[offset + 3] = val >>> 24 & 255;
-}
-function createZipBuffer(entries) {
-  const now = /* @__PURE__ */ new Date();
-  const { time, date } = dosTime(now);
-  const records = [];
-  const chunks = [];
-  let offset = 0;
-  for (const entry of entries) {
-    const nameBytes = Buffer.from(entry.path, "utf-8");
-    const crc = crc32(entry.data);
-    const compressed = deflateRawSync(entry.data, { level: 6 });
-    const compressedSize = compressed.length;
-    const uncompressedSize = entry.data.length;
-    const header = Buffer.alloc(30 + nameBytes.length);
-    writeUint32LE(header, 67324752, 0);
-    writeUint16LE(header, 20, 4);
-    writeUint16LE(header, 0, 6);
-    writeUint16LE(header, 8, 8);
-    writeUint16LE(header, time, 10);
-    writeUint16LE(header, date, 12);
-    writeUint32LE(header, crc, 14);
-    writeUint32LE(header, compressedSize, 18);
-    writeUint32LE(header, uncompressedSize, 22);
-    writeUint16LE(header, nameBytes.length, 26);
-    writeUint16LE(header, 0, 28);
-    nameBytes.copy(header, 30);
-    records.push({ header, compressed, crc, compressedSize, uncompressedSize, offset });
-    chunks.push(header, compressed);
-    offset += header.length + compressed.length;
-  }
-  const centralDirStart = offset;
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i];
-    const rec = records[i];
-    const nameBytes = Buffer.from(entry.path, "utf-8");
-    const cdh = Buffer.alloc(46 + nameBytes.length);
-    writeUint32LE(cdh, 33639248, 0);
-    writeUint16LE(cdh, 20, 4);
-    writeUint16LE(cdh, 20, 6);
-    writeUint16LE(cdh, 0, 8);
-    writeUint16LE(cdh, 8, 10);
-    writeUint16LE(cdh, time, 12);
-    writeUint16LE(cdh, date, 14);
-    writeUint32LE(cdh, rec.crc, 16);
-    writeUint32LE(cdh, rec.compressedSize, 20);
-    writeUint32LE(cdh, rec.uncompressedSize, 24);
-    writeUint16LE(cdh, nameBytes.length, 28);
-    writeUint16LE(cdh, 0, 30);
-    writeUint16LE(cdh, 0, 32);
-    writeUint16LE(cdh, 0, 34);
-    writeUint16LE(cdh, 0, 36);
-    writeUint32LE(cdh, 0, 38);
-    writeUint32LE(cdh, rec.offset, 42);
-    nameBytes.copy(cdh, 46);
-    chunks.push(cdh);
-    offset += cdh.length;
-  }
-  const centralDirSize = offset - centralDirStart;
-  const eocd = Buffer.alloc(22);
-  writeUint32LE(eocd, 101010256, 0);
-  writeUint16LE(eocd, 0, 4);
-  writeUint16LE(eocd, 0, 6);
-  writeUint16LE(eocd, entries.length, 8);
-  writeUint16LE(eocd, entries.length, 10);
-  writeUint32LE(eocd, centralDirSize, 12);
-  writeUint32LE(eocd, centralDirStart, 16);
-  writeUint16LE(eocd, 0, 20);
-  chunks.push(eocd);
-  return Buffer.concat(chunks);
-}
-function extractZipBuffer(buf) {
-  const entries = [];
-  let eocdOffset = -1;
-  for (let i = buf.length - 22; i >= 0; i--) {
-    if (buf.readUInt32LE(i) === 101010256) {
-      eocdOffset = i;
-      break;
-    }
-  }
-  if (eocdOffset === -1) {
-    throw new Error("Invalid ZIP: EOCD not found");
-  }
-  const entryCount = buf.readUInt16LE(eocdOffset + 10);
-  const centralDirOffset = buf.readUInt32LE(eocdOffset + 16);
-  let offset = centralDirOffset;
-  for (let i = 0; i < entryCount; i++) {
-    if (buf.readUInt32LE(offset) !== 33639248) {
-      throw new Error(`Invalid ZIP: bad central directory signature at ${offset}`);
-    }
-    const compressionMethod = buf.readUInt16LE(offset + 10);
-    const compressedSize = buf.readUInt32LE(offset + 20);
-    const uncompressedSize = buf.readUInt32LE(offset + 24);
-    const nameLen = buf.readUInt16LE(offset + 28);
-    const extraLen = buf.readUInt16LE(offset + 30);
-    const commentLen = buf.readUInt16LE(offset + 32);
-    const localHeaderOffset = buf.readUInt32LE(offset + 42);
-    const name = buf.subarray(offset + 46, offset + 46 + nameLen).toString("utf-8");
-    if (!name.endsWith("/")) {
-      const localNameLen = buf.readUInt16LE(localHeaderOffset + 26);
-      const localExtraLen = buf.readUInt16LE(localHeaderOffset + 28);
-      const dataOffset = localHeaderOffset + 30 + localNameLen + localExtraLen;
-      const compressedData = buf.subarray(dataOffset, dataOffset + compressedSize);
-      let data;
-      if (compressionMethod === 0) {
-        data = Buffer.from(compressedData);
-      } else if (compressionMethod === 8) {
-        data = inflateRawSync(compressedData);
-      } else {
-        throw new Error(`Unsupported compression method: ${compressionMethod}`);
-      }
-      if (data.length !== uncompressedSize) {
-        throw new Error(`Size mismatch for ${name}: expected ${uncompressedSize}, got ${data.length}`);
-      }
-      entries.push({ path: name, data });
-    }
-    offset += 46 + nameLen + extraLen + commentLen;
-  }
-  return entries;
-}
-
 // src/commands/skills.ts
 var slog = {
   info: (msg) => {
@@ -4518,7 +4484,7 @@ async function asyncCall(opts) {
     }
     process.exit(1);
   }
-  const { request_id, call_id, status, error_message, error_code } = await res.json();
+  const { request_id, call_id, session_key, status, error_message, error_code } = await res.json();
   if (status === "failed") {
     log.error(`Call failed: ${error_message || error_code}`);
     process.exit(1);
@@ -4553,9 +4519,11 @@ async function asyncCall(opts) {
         console.log(JSON.stringify({
           call_id,
           request_id,
+          ...session_key ? { session_key } : {},
           status: "completed",
           result,
           ...task.attachments?.length ? { attachments: task.attachments } : {},
+          ...Array.isArray(task.file_manifest) ? { file_manifest: task.file_manifest } : {},
           rate_hint: `POST /api/agents/${opts.id}/rate  body: { call_id: "${call_id}", rating: 1-5 }`
         }));
       } else {
@@ -4565,6 +4533,13 @@ async function asyncCall(opts) {
             log.info(`  ${GRAY}File:${RESET} ${att.name}  ${GRAY}${att.url}${RESET}`);
           }
         }
+        const manifest = task.file_manifest;
+        if (Array.isArray(manifest)) {
+          log.info(`  ${GRAY}Manifest:${RESET} ${manifest.length} file(s)`);
+        }
+        if (session_key) {
+          log.info(`  ${GRAY}Session:${RESET} ${session_key}`);
+        }
       }
       if (opts.outputFile && result) {
         writeFileSync3(opts.outputFile, result);
@@ -4573,7 +4548,7 @@ async function asyncCall(opts) {
       if (!opts.json) {
         log.info(`${GRAY}Rate this call: agent-mesh rate ${call_id} <1-5> --agent ${opts.id}${RESET}`);
       }
-      return { callId: call_id };
+      return { callId: call_id, ...session_key ? { sessionKey: session_key } : {} };
     }
     if (task.status === "failed") {
       if (!opts.json) {
@@ -4637,7 +4612,7 @@ async function streamCall(opts) {
       console.log(`  ${GRAY}Created${RESET}    ${result.created_at}`);
       console.log("");
     }
-    return;
+    return { callId: result.call_id, ...result.session_key ? { sessionKey: result.session_key } : {} };
   }
   if (!res.body) {
     log.error("Empty response body");
@@ -4653,6 +4628,7 @@ async function streamCall(opts) {
   let outputBuffer = "";
   let inThinkingBlock = false;
   let callId = res.headers.get("X-Call-Id") || "";
+  let sessionKey = res.headers.get("X-Session-Key") || "";
   while (true) {
     const { done, value } = await reader.read();
     if (done) break;
@@ -4665,6 +4641,9 @@ async function streamCall(opts) {
         const event = JSON.parse(data);
         if (event.type === "start" && event.call_id) {
           callId = event.call_id;
+          if (event.session_key) {
+            sessionKey = event.session_key;
+          }
         }
         if (opts.json) {
           console.log(JSON.stringify(event));
@@ -4688,6 +4667,9 @@ async function streamCall(opts) {
             for (const att of event.attachments) {
               log.info(`  ${GRAY}File:${RESET} ${att.name}  ${GRAY}${att.url}${RESET}`);
             }
+            if (Array.isArray(event.file_manifest)) {
+              log.info(`  ${GRAY}Manifest:${RESET} ${event.file_manifest.length} file(s)`);
+            }
           } else if (event.type === "error") {
             process.stderr.write(`
 Error: ${event.message}
@@ -4726,11 +4708,14 @@ Error: ${event.message}
   if (!opts.json) {
     console.log("\n");
     log.success("Call completed");
+    if (sessionKey) {
+      log.info(`${GRAY}Session:${RESET} ${sessionKey}`);
+    }
     if (callId) {
       log.info(`${GRAY}Rate this call: agent-mesh rate ${callId} <1-5> --agent ${opts.id}${RESET}`);
     }
   }
-  return { callId };
+  return { callId, ...sessionKey ? { sessionKey } : {} };
 }
 function registerCallCommand(program2) {
   program2.command("call <agent>").description("Call an agent on the A2A network (default: async polling)").requiredOption("--task <description>", "Task description").option("--input-file <path>", "Read file and append to task description").option("--output-file <path>", "Save response text to file").option("--stream", "Use SSE streaming instead of async polling").option("--json", "Output JSONL events").option("--timeout <seconds>", "Timeout in seconds", "300").option("--rate <rating>", "Rate the agent after call (1-5)", parseInt).action(async (agentInput, opts) => {
@@ -5020,7 +5005,7 @@ function registerSubscribeCommand(program2) {
 
 // src/commands/register.ts
 var DEFAULT_BASE_URL5 = "https://agents.hot";
-var VALID_AGENT_TYPES = ["openclaw", "claude-code", "cursor", "windsurf", "custom"];
+var VALID_AGENT_TYPES = ["claude", "claude-code", "cursor", "windsurf", "custom"];
 function registerRegisterCommand(program2) {
   program2.command("register").description("Register a new agent on the platform and get an API key").requiredOption("--name <name>", "Agent name (alphanumeric + hyphens, 3-64 chars)").option("--type <type>", "Agent type", "claude-code").option("--description <text>", "Agent description").option("--capabilities <list>", "Comma-separated capabilities").option("--base-url <url>", "Platform base URL", DEFAULT_BASE_URL5).action(async (opts) => {
     if (!VALID_AGENT_TYPES.includes(opts.type)) {
@@ -5228,6 +5213,178 @@ function registerProfileCommand(program2) {
   });
 }
 
+// src/commands/files.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename2 } from "path";
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+function defaultOutputPath(filePath) {
+  const name = basename2(filePath || "") || "file";
+  return name;
+}
+function defaultZipOutputPath(sessionKey) {
+  const suffix = sessionKey.split(":").at(-1) || "session";
+  return `session-${suffix}.zip`;
+}
+function handleError7(err) {
+  if (err instanceof PlatformApiError) {
+    log.error(err.message);
+  } else {
+    log.error(err.message);
+  }
+  process.exit(1);
+}
+async function resolveTargetAgent(agentInput) {
+  const client = createClient();
+  return resolveAgentId(agentInput, client);
+}
+async function downloadToFile(url, outputPath) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Download failed: HTTP ${res.status}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  writeFileSync4(outputPath, buf);
+}
+function registerFilesCommand(program2) {
+  const files = program2.command("files").description("Session file manifest and on-demand upload/download commands");
+  files.command("list").requiredOption("--agent <agent>", "Target agent ID or name").requiredOption("--session <session_key>", "Session key").option("--json", "Output raw JSON").action(async (opts) => {
+    try {
+      const { id, name } = await resolveTargetAgent(opts.agent);
+      const client = createClient();
+      const data = await client.get(
+        `/api/agents/${id}/files?session_key=${encodeURIComponent(opts.session)}`
+      );
+      if (opts.json) {
+        console.log(JSON.stringify(data));
+        return;
+      }
+      log.banner(`Session Files \u2014 ${BOLD}${name}${RESET}`);
+      console.log(`  ${GRAY}Session${RESET}  ${data.session_key || opts.session}`);
+      console.log(`  ${GRAY}Count${RESET}    ${data.files.length}`);
+      if (data.updated_at) {
+        console.log(`  ${GRAY}Updated${RESET}  ${data.updated_at}`);
+      }
+      console.log("");
+      for (const f of data.files) {
+        console.log(`  ${f.path}  ${GRAY}${formatBytes(f.size)}${RESET}`);
+      }
+      console.log("");
+    } catch (err) {
+      handleError7(err);
+    }
+  });
+  files.command("upload").requiredOption("--agent <agent>", "Target agent ID or name").requiredOption("--session <session_key>", "Session key").requiredOption("--path <file_path>", "Relative file path in session workspace").option("--json", "Output raw JSON").action(async (opts) => {
+    try {
+      const { id } = await resolveTargetAgent(opts.agent);
+      const client = createClient();
+      const data = await client.post(`/api/agents/${id}/files/upload`, {
+        session_key: opts.session,
+        path: opts.path
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(data));
+        return;
+      }
+      if (!data.file?.url) {
+        throw new Error("No file URL returned");
+      }
+      log.success(`Uploaded ${opts.path}`);
+      console.log(`  ${GRAY}URL${RESET}  ${data.file.url}`);
+    } catch (err) {
+      handleError7(err);
+    }
+  });
+  files.command("upload-all").requiredOption("--agent <agent>", "Target agent ID or name").requiredOption("--session <session_key>", "Session key").option("--json", "Output raw JSON").action(async (opts) => {
+    try {
+      const { id } = await resolveTargetAgent(opts.agent);
+      const client = createClient();
+      const data = await client.post(`/api/agents/${id}/files/upload-all`, {
+        session_key: opts.session
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(data));
+        return;
+      }
+      if (!data.file?.url) {
+        throw new Error("No ZIP URL returned");
+      }
+      log.success("Uploaded session ZIP");
+      console.log(`  ${GRAY}URL${RESET}  ${data.file.url}`);
+    } catch (err) {
+      handleError7(err);
+    }
+  });
+  files.command("download").requiredOption("--agent <agent>", "Target agent ID or name").requiredOption("--session <session_key>", "Session key").requiredOption("--path <file_path>", "Relative file path in session workspace").option("--output <path>", "Local output path").option("--json", "Output raw JSON").action(async (opts) => {
+    try {
+      const { id } = await resolveTargetAgent(opts.agent);
+      const client = createClient();
+      const data = await client.post(`/api/agents/${id}/files/upload`, {
+        session_key: opts.session,
+        path: opts.path
+      });
+      const url = data.file?.url;
+      if (!url) throw new Error("No file URL returned");
+      const output = opts.output || defaultOutputPath(opts.path);
+      await downloadToFile(url, output);
+      if (opts.json) {
+        console.log(JSON.stringify({ success: true, output, url }));
+        return;
+      }
+      log.success(`Downloaded ${opts.path}`);
+      console.log(`  ${GRAY}Saved${RESET}  ${output}`);
+    } catch (err) {
+      handleError7(err);
+    }
+  });
+  files.command("download-all").requiredOption("--agent <agent>", "Target agent ID or name").requiredOption("--session <session_key>", "Session key").option("--output <path>", "Local output path").option("--json", "Output raw JSON").action(async (opts) => {
+    try {
+      const { id } = await resolveTargetAgent(opts.agent);
+      const client = createClient();
+      const data = await client.post(`/api/agents/${id}/files/upload-all`, {
+        session_key: opts.session
+      });
+      const url = data.file?.url;
+      if (!url) throw new Error("No ZIP URL returned");
+      const output = opts.output || defaultZipOutputPath(opts.session);
+      await downloadToFile(url, output);
+      if (opts.json) {
+        console.log(JSON.stringify({ success: true, output, url }));
+        return;
+      }
+      log.success("Downloaded session ZIP");
+      console.log(`  ${GRAY}Saved${RESET}  ${output}`);
+    } catch (err) {
+      handleError7(err);
+    }
+  });
+  files.command("help").description("Show machine-readable files command reference").option("--json", "Output JSON format").action((opts) => {
+    const reference = {
+      command: "agent-mesh files",
+      docs: "https://agents.hot/docs/cli/files",
+      commands: [
+        { name: "list", required: ["--agent", "--session"], optional: ["--json"] },
+        { name: "upload", required: ["--agent", "--session", "--path"], optional: ["--json"] },
+        { name: "upload-all", required: ["--agent", "--session"], optional: ["--json"] },
+        { name: "download", required: ["--agent", "--session", "--path"], optional: ["--output", "--json"] },
+        { name: "download-all", required: ["--agent", "--session"], optional: ["--output", "--json"] }
+      ]
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(reference));
+      return;
+    }
+    log.banner("Files Command Reference");
+    console.log(`  ${GRAY}Docs${RESET}  ${reference.docs}`);
+    for (const item of reference.commands) {
+      console.log(`  ${item.name}`);
+    }
+  });
+}
+
 // src/utils/auto-updater.ts
 import { spawnSync } from "child_process";
 var AUTO_UPGRADE_ENV = "AGENT_MESH_AUTO_UPGRADE";
@@ -5304,8 +5461,8 @@ function fetchLatestVersion(pkg) {
   if (result.error || result.status !== 0) return null;
   return parseLatestVersion(result.stdout ?? "");
 }
-function installLatest(pkg) {
-  const result = spawnSync("npm", ["install", "-g", `${pkg}@latest`], {
+function installResolvedVersion(pkg, version2) {
+  const result = spawnSync("npm", ["install", "-g", `${pkg}@${version2}`], {
     stdio: "inherit",
     timeout: INSTALL_TIMEOUT_MS
   });
@@ -5334,7 +5491,7 @@ function maybeAutoUpgradeOnStartup(opts) {
   if (!latest) return { relaunched: false };
   if (compareSemver(latest, current) <= 0) return { relaunched: false };
   log.info(`New ${packageName} version found: v${current} -> v${latest}. Upgrading...`);
-  if (!installLatest(packageName)) {
+  if (!installResolvedVersion(packageName, latest)) {
     log.warn("Auto-upgrade failed. Continuing with current version.");
     return { relaunched: false };
   }
@@ -5353,6 +5510,14 @@ program.name("agent-mesh").description("Connect local AI agents to the Agents.Ho
   console.log(version);
   process.exit(0);
 });
+program.configureOutput({
+  outputError: (str, write) => {
+    write(str);
+    if (str.trim().length > 0) {
+      write("\nDocs: https://agents.hot/docs/cli\n");
+    }
+  }
+});
 registerConnectCommand(program);
 registerLoginCommand(program);
 registerStatusCommand(program);
@@ -5377,4 +5542,21 @@ registerRegisterCommand(program);
 registerRateCommand(program);
 registerRuntimeCommand(program);
 registerProfileCommand(program);
+registerFilesCommand(program);
+program.command("help").description("Show CLI help").option("--json", "Output machine-readable command reference").action((opts) => {
+  if (opts.json) {
+    const commands = program.commands.map((cmd) => cmd.name()).filter((name) => name !== "help");
+    console.log(JSON.stringify({
+      name: "agent-mesh",
+      docs: "https://agents.hot/docs/cli",
+      commands
+    }));
+    return;
+  }
+  program.outputHelp();
+});
+var wantsJsonOutput = process.argv.includes("--json");
+if (!wantsJsonOutput && !process.argv.includes("--version") && !process.argv.includes("-v")) {
+  maybePrintDocsHint("https://agents.hot/docs/cli");
+}
 program.parse();

package/dist/{list-KMJ463VL.js → list-ROLJARYB.js}

@@ -2,7 +2,7 @@
 import {
   ListTUI,
   registerListCommand
-} from "./chunk-U32JDKSN.js";
+} from "./chunk-KEUGYA3L.js";
 export {
   ListTUI,
   registerListCommand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@annals/agent-mesh",
-  "version": "0.16.10",
+  "version": "0.16.12",
   "description": "CLI bridge connecting local AI agents to the Agents.Hot platform",
   "type": "module",
   "bin": {