@lambdacurry/arbor 0.23.41 → 0.24.1

package/README.md

@@ -76,19 +76,37 @@ This prints a URL + short code to relay to the human, who approves it in their l
 ## Attach a local file
 
 ```bash
-arbor attachment upload --thread-id thr_… --file ./screenshot.png --description "Settings dialog after save"
-# Alias: arbor attachment_upload --thread-id thr_… --file ./screenshot.png
+arbor attachment upload ./screenshot.png --thread-id thr_… --description "Settings dialog after save"
+# Alias: arbor attachment_upload --file ./screenshot.png --thread-id thr_…
+arbor attachment get --attachment-id att_…
+arbor attachment list --thread-id thr_…
 ```
 
-No Arbor Computer Run is needed. Files are capped at **5 MiB**; supported extensions are
-PNG, JPG/JPEG, GIF, WebP, PDF, TXT, JSON, and CSV. MIME is inferred from the extension and
-validated against bytes on the server. Description defaults to the sanitized filename.
-
-The result contains `attachmentId`, `attachmentIds`, `downloadUrl`, uploader/time, and
-`attachments[].markdown`. Put that Markdown in `contribute` or `respond` body and pass
-`--attachment-ids att_…` to bind the file. Downloads require your own Arbor credential
-and current access to the destination Thread's Space. See the
-[attachment upload runbook](../../docs/runbooks/attachment-upload.md) for MCP and RPC input.
+Requires **Node**: js-exec coerces binary fetch bodies to strings, so upload fails early
+there with a Node requirement; metadata/get/list/upload-url/attach commands remain portable.
+The CLI computes SHA-256, requests a five-minute `upload_url`, and PUTs the file directly
+to R2 with the exact signed headers and no Arbor Authorization header, then calls `attach` with its token.
+Files must be non-empty and at most **100 MB (100,000,000 bytes)**; compress, split, or
+link larger files. PNG/JPEG/GIF/WebP/PDF/TXT/JSON/CSV are supported. There is no inline
+base64 upload. First attach is allowed until `attachExpiresAt` (one hour after PUT expiry);
+finalized receipts remain replayable after expiry. If a PUT or first attach expires, request
+a fresh upload URL and upload again. JSON syntax is checked only up to 10 MB (10,000,000 bytes);
+larger JSON receives UTF-8/control-byte checks only, so validate its syntax locally.
+
+The receipt contains uploader/time, SHA-256, `attachmentId`, `attachmentIds`, and
+`attachments[].markdown`. Bind the ids and place the Markdown in `contribute`/`respond`.
+`mediaUrl` and `downloadUrl` require an Arbor credential (401 otherwise); read URLs are
+private, never signed/public. `attachment get` (aliases `attachment_get`, `get_attachment`)
+and `attachment list` (`attachment_list`, `list_attachments`) recover receipts; the latter
+pages with `--cursor`. Finalized receipts replay with the same authentic token even after expiry.
+Duplicate SHA-256 warnings on the same Thread are best-effort; concurrent uploads may not warn.
+
+MCP exposes **one** tool, `attachment`, with `upload_url` / `attach` / `get` / `list` verbs.
+Refresh a stale client tool catalog if it still shows the retired individual tools, or use
+`arbor attachment upload`. `thread get --view full` retains body/Attachment read-back.
+Prefer `contribute --idempotency-key` for retries, then `mark_as_response` to bind an
+existing contribution as a response; direct `respond` has no idempotency-key input yet.
+See the [operator runbook](../../docs/runbooks/attachment-upload.md) for required configuration.
 
 ## Output contract (agent-friendly)
 

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.23.41",
+  version: "0.24.1",
   description: "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   keywords: [
     "agents",
@@ -5161,8 +5161,7 @@ var ARTIFACT_TYPES = [
   "external-reference"
 ];
 // ../core/src/blob/attachment-upload.ts
-var MAX_AGENT_ATTACHMENT_BYTES = 5 * 1024 * 1024;
-var MAX_AGENT_ATTACHMENT_BASE64 = 4 * Math.ceil(MAX_AGENT_ATTACHMENT_BYTES / 3);
+var MAX_ATTACHMENT_BYTES = 1e8;
 var AGENT_ATTACHMENT_MIME_TYPES = [
   "image/png",
   "image/jpeg",
@@ -8604,6 +8603,7 @@ var attachment2 = looseObject({
   size: number2(),
   sha256: string2(),
   downloadUrl: string2(),
+  mediaUrl: string2().optional(),
   markdown: string2()
 });
 var checkpoint = looseObject({
@@ -10277,13 +10277,58 @@ var MCP_OUTPUT_SCHEMAS = {
       sha256: string2()
     })
   }),
-  upload_attachment: looseObject({
+  get_attachment: looseObject({
+    ...attachment2.shape,
+    sha256: nullableString,
+    uploadedByProfileId: id,
+    createdAt: timestamp
+  }),
+  list_attachments: looseObject({
+    items: array(looseObject({
+      ...attachment2.shape,
+      sha256: nullableString,
+      uploadedByProfileId: id,
+      createdAt: timestamp
+    })),
+    nextCursor: nullableString,
+    total: number2()
+  }),
+  attachment: looseObject({
+    url: string2().optional(),
+    method: literal("PUT").optional(),
+    headers: record(string2(), string2()).optional(),
+    token: string2().optional(),
+    expiresAt: timestamp.optional(),
+    attachExpiresAt: timestamp.optional(),
+    maxBytes: number2().optional(),
+    curl: string2().optional(),
+    nextStep: string2().optional(),
+    attachmentId: id.optional(),
+    attachmentIds: array(id).optional(),
+    attachments: array(attachment2).optional(),
+    filename: string2().optional(),
+    mimeType: string2().optional(),
+    size: number2().optional(),
+    sha256: nullableString.optional(),
+    markdown: string2().optional(),
+    downloadUrl: string2().optional(),
+    mediaUrl: string2().optional(),
+    uploadedByProfileId: id.optional(),
+    createdAt: timestamp.optional(),
+    items: array(jsonObject).optional(),
+    nextCursor: nullableString.optional(),
+    total: number2().optional(),
+    warnings: array(string2()).optional(),
+    replayed: boolean2().optional()
+  }),
+  attachment_attach: looseObject({
     attachmentId: id,
     attachmentIds: array(id),
     downloadUrl: string2(),
     uploadedByProfileId: id,
     createdAt: timestamp,
-    attachments: array(attachment2)
+    attachments: array(attachment2),
+    warnings: array(string2()).optional()
   }),
   computer_export: looseObject({
     computerSessionId: id,
@@ -10377,7 +10422,7 @@ var MCP_OUTPUT_SCHEMAS = {
 };
 function outputSchemaFor(actionName) {
   if (actionName === "attachment_upload")
-    actionName = "upload_attachment";
+    actionName = "attachment_attach";
   return MCP_OUTPUT_SCHEMAS[actionName];
 }
 
@@ -10744,7 +10789,7 @@ var MCP_TOOL_ANNOTATIONS = {
   admin_feedback_edit: destructive,
   admin_feedback_curate: destructive,
   contribute: additive,
-  upload_attachment: additive,
+  attachment: additive,
   edit: additive,
   stamp: additive,
   react: idempotent,
@@ -11674,7 +11719,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "contribute",
     title: "Contribute to a thread",
-    description: "Add one point people and agents will read to understand a Thread and decide what's next — make it additive: stamp for one-line agreement or disagreement, respond or mark_as_response for requests. Prose refs stay citations; links create deliberate reply/contest edges.",
+    description: "Add one additive point to a Thread; use stamp for agreement, respond/mark_as_response for requests, and links for deliberate reply/contest edges. Pass idempotencyKey (CLI: --idempotency-key) for safe retries.",
     inputSchema: {
       threadId: string2().describe("the thread id, e.g. thr_…"),
       type: _enum(CONTRIBUTION_TYPES).describe("the contribution type (AD-066 taxonomy)"),
@@ -11683,7 +11728,7 @@ var ACTION_DEFINITIONS = [
       summary: string2().max(500).optional().describe(`optional gist: ${CONTRIBUTION_SUMMARY_GUIDANCE}. It is what newcomers read first (the Thread distillate and the recall snippet) and it sharpens recall for long bodies; write one when the body is long`),
       confidence: number2().int().min(0).max(100).optional().describe("optional 0–100 confidence"),
       computerSessionId: string2().optional().describe("the attached computer session that produced this result, cms_…"),
-      attachmentIds: array(string2()).max(10).optional().describe("Thread-scoped files to preserve with the contribution. To show Computer media inline, place the attachments[].markdown returned by computer_verify or computer_export or upload_attachment in the body; an attachment not placed in the body stays a compact download."),
+      attachmentIds: array(string2()).max(10).optional().describe("Thread-scoped files to preserve with the contribution. To show Computer media inline, place the attachments[].markdown returned by computer_verify, computer_export, or attachment attach in the body; an attachment not placed in the body stays a compact download."),
       mentions: array(object({
         kind: _enum(["person", "contribution", "artifact"]),
         id: string2(),
@@ -12267,32 +12312,85 @@ var ACTION_DEFINITIONS = [
     run: forward("computer_code.diagnostics")
   },
   {
-    name: "upload_attachment",
-    title: "Upload a local Thread file",
-    description: "Upload a local file to a Thread without a Computer Run (5 MiB maximum; PNG/JPEG/GIF/WebP/PDF/TXT/JSON/CSV). Bind returned attachmentIds in contribute/respond and place attachments[].markdown in the body; downloadUrl requires your Arbor credential.",
+    name: "attachment",
+    title: "Upload and read Thread Attachments",
+    description: "Upload a file (100 MB cap): upload_url → signed PUT (5 min) → attach (1 h after PUT expiry); receipts replay after expiry; JSON syntax checks stop at 10 MB, larger JSON gets UTF-8/control checks only, so validate locally. get/list recover receipts; mediaUrl/downloadUrl require an Arbor credential (401 otherwise), with no public read URLs.",
     inputSchema: {
-      threadId: string2().min(1).describe("destination Thread you can contribute to, thr_…"),
-      filename: string2().min(1).max(1000).describe("original filename; sanitized by the server"),
-      mimeType: _enum(AGENT_ATTACHMENT_MIME_TYPES).describe("declared MIME; must match the file signature or valid UTF-8 text"),
-      content: string2().min(1).max(MAX_AGENT_ATTACHMENT_BASE64).describe("canonical padded base64 file bytes, no data URL; decoded file must be at most 5 MiB"),
-      description: string2().min(1).max(500).optional().describe("what the file shows or contains; defaults to filename and becomes the Markdown label")
+      verb: _enum(["upload_url", "attach", "get", "list"]),
+      threadId: string2().optional().describe("upload_url/list: Thread id, thr_…"),
+      filename: string2().min(1).max(1000).optional().describe("upload_url: original filename"),
+      mimeType: _enum(AGENT_ATTACHMENT_MIME_TYPES).optional().describe("upload_url: supported MIME matching the bytes"),
+      size: number2().optional().describe("upload_url: exact file size, at most 100000000 bytes; compress, split, or link larger files"),
+      description: string2().min(1).max(500).optional(),
+      sha256: string2().regex(/^[a-f0-9]{64}$/).optional().describe("upload_url: optional SHA-256 hex; also signed into the PUT checksum header"),
+      token: string2().optional().describe("attach: token from upload_url; first attach before attachExpiresAt, replay finalized receipts even after expiry"),
+      attachmentId: string2().optional().describe("get: attachment id, att_…"),
+      ...PAGINATION_INPUT
     },
     surfaces: ["mcp"],
     toolset: "loop",
-    run: forward("attachment.upload")
+    run: dispatch({
+      upload_url: "attachment.upload_url",
+      attach: "attachment.attach",
+      get: "attachment.get",
+      list: "attachment.list"
+    })
+  },
+  {
+    name: "attachment_upload_url",
+    title: "Request an Attachment upload URL",
+    description: "Request a five-minute presigned PUT for a file up to 100 MB; upload with the exact returned headers, then attach before attachExpiresAt (one hour after PUT expiry). Compress, split, or link larger files; JSON syntax checks stop at 10 MB, larger JSON gets UTF-8/control checks only, so validate locally.",
+    inputSchema: {
+      threadId: string2().min(1),
+      filename: string2().min(1).max(1000),
+      mimeType: _enum(AGENT_ATTACHMENT_MIME_TYPES),
+      size: number2(),
+      description: string2().min(1).max(500).optional(),
+      sha256: string2().regex(/^[a-f0-9]{64}$/).optional()
+    },
+    surfaces: ["cli"],
+    toolset: "loop",
+    run: forward("attachment.upload_url")
+  },
+  {
+    name: "attachment_attach",
+    title: "Finalize an Attachment upload",
+    description: "Verify uploaded bytes before attachExpiresAt (one hour after PUT expiry); finalized receipts replay even after expiry; JSON syntax checks stop at 10 MB, larger JSON gets UTF-8/control checks only. Bind attachmentIds and place attachments[].markdown in contribute/respond; read URLs require an Arbor credential (401 otherwise).",
+    inputSchema: { token: string2().min(1) },
+    surfaces: ["cli"],
+    toolset: "loop",
+    run: forward("attachment.attach")
+  },
+  {
+    name: "get_attachment",
+    title: "Read an Attachment",
+    description: "Recover Attachment Markdown, authenticated URLs, SHA-256, uploader and time by id. mediaUrl/downloadUrl require an Arbor credential (401 otherwise); no signed/public read URLs.",
+    inputSchema: { attachmentId: string2().min(1) },
+    surfaces: ["cli"],
+    toolset: "loop",
+    run: forward("attachment.get")
+  },
+  {
+    name: "list_attachments",
+    title: "List Thread Attachments",
+    description: "List a Thread's Attachment receipts including unbound uploads; continue with nextCursor or all=true. mediaUrl/downloadUrl require an Arbor credential (401 otherwise); no signed/public read URLs.",
+    inputSchema: { threadId: string2().min(1), ...PAGINATION_INPUT },
+    surfaces: ["cli"],
+    toolset: "loop",
+    run: forward("attachment.list")
   },
   {
     name: "attachment_upload",
     title: "Upload a local Thread file",
-    description: "Upload --file from your local filesystem to a Thread without a Computer Run (5 MiB maximum; PNG/JPEG/GIF/WebP/PDF/TXT/JSON/CSV). Place returned attachments[].markdown in the contribution body and pass --attachment-ids to contribute or respond.",
+    description: "Upload with Node and SHA-256 via upload_url → presigned PUT → attach (100 MB cap); compress, split, or link larger files; JSON syntax checks stop at 10 MB, larger JSON gets UTF-8/control checks only. PUT expires in 5 min, first attach gets 1 h more, receipts replay after expiry; js-exec cannot upload; mediaUrl/downloadUrl require an Arbor credential (401 otherwise), no public read URLs; for a missing tool refresh the MCP tool catalog or use arbor attachment upload.",
     inputSchema: {
-      threadId: string2().min(1).describe("destination Thread, thr_…"),
-      file: string2().min(1).describe("local file path; MIME is inferred from the extension"),
-      description: string2().min(1).max(500).optional().describe("what the file shows or contains; defaults to filename")
+      threadId: string2().min(1),
+      file: string2().min(1).describe("local file path (or positional file); requires Node"),
+      description: string2().min(1).max(500).optional()
     },
     surfaces: ["cli"],
     toolset: "loop",
-    run: forward("attachment.upload")
+    run: forward("attachment.upload_url")
   },
   {
     name: "computer_export",
@@ -12653,7 +12751,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "respond",
     title: "Respond to a request",
-    description: "Fulfill a contribution request by posting its response so the request can complete; review requests are answered by stamp, and mark_as_response binds a response that was already posted. For file evidence, upload_attachment needs no Computer Run; pass attachmentIds and place returned attachments[].markdown in the body where media belongs, plus computerSessionId for Computer evidence.",
+    description: "Fulfill a contribution request with a response; use stamp for reviews, and pass attachmentIds plus returned Markdown for file evidence. For safe retries, contribute with idempotencyKey (--idempotency-key), then mark_as_response.",
     inputSchema: {
       requestId: string2().describe("the request id, req_…"),
       type: _enum(CONTRIBUTION_TYPES).describe("the contribution type"),
@@ -12781,7 +12879,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "thread_get",
     title: "Read a thread",
-    description: "Read one Thread as compact current context (distillate, requests, artifacts, recent tail, cursored unchanged checks) — not the durable transcript; pass view=full to page history (contribLimit default 50) or all=true for the complete transcript. Read it before contributing so you can answer open requests correctly.",
+    description: "Read one Thread as compact current context (distillate, requests, artifacts, recent tail, cursored unchanged checks) — not the durable transcript; pass view=full to read contribution bodies and attachments (including Markdown and authenticated URLs) and page history (contribLimit default 50) or all=true for the complete transcript. Read it before contributing so you can answer open requests correctly.",
     inputSchema: {
       threadId: string2().describe("the thread id, e.g. thr_…"),
       view: _enum(["full", "compact"]).optional().describe("MCP/CLI/API default compact = bounded decision-ready context; full = transcript page"),
@@ -14947,49 +15045,67 @@ import { basename } from "node:path";
 function checkFile(stat) {
   const isFile = typeof stat.isFile === "function" ? stat.isFile() : stat.isFile;
   if (!isFile)
-    throw new UsageError("--file must be a regular file");
-  if (stat.size > MAX_AGENT_ATTACHMENT_BYTES)
-    throw new UsageError("Attachment exceeds the 5 MiB limit");
+    throw new UsageError("Attachment must be a regular file");
+  if (stat.size > MAX_ATTACHMENT_BYTES)
+    throw new UsageError(`Attachment is ${stat.size} bytes; the limit is ${MAX_ATTACHMENT_BYTES} bytes (100 MB). Compress, split, or link the file.`);
+  if (!stat.size)
+    throw new UsageError("Attachment file is empty (0 bytes); choose a non-empty file");
 }
-async function localAttachmentInput(input) {
+async function uploadLocalAttachment(executor, input, fetcher = fetch) {
   const file = String(input.file);
   const filename = basename(file);
+  const fs = await import("node:fs");
+  const initialStat = fs.statSync(file);
+  checkFile(initialStat);
   const mimeType = localAttachmentMime(filename);
   if (!mimeType)
-    throw new UsageError("Unsupported file extension; use PNG/JPEG/GIF/WebP/PDF/TXT/JSON/CSV");
-  const fs = await import("node:fs");
-  checkFile(fs.statSync(file));
+    throw new UsageError(`Unsupported file extension for ${initialStat.size} bytes (limit ${MAX_ATTACHMENT_BYTES} bytes). Use PNG/JPEG/GIF/WebP/PDF/TXT/JSON/CSV, or link the file.`);
+  if (typeof fs.openSync !== "function")
+    throw new UsageError("Attachment upload requires Node: this js-exec runtime cannot PUT binary file bytes. Run `arbor attachment upload <file> --thread-id <thread>` with Node.");
+  const descriptor = fs.openSync(file, "r");
   let bytes;
-  if (typeof fs.openSync === "function") {
-    const descriptor = fs.openSync(file, "r");
-    try {
-      checkFile(fs.fstatSync(descriptor));
-      const buffer = Buffer.alloc(MAX_AGENT_ATTACHMENT_BYTES + 1);
-      let size = 0;
-      while (size < buffer.length) {
-        const count = fs.readSync(descriptor, buffer, size, buffer.length - size, null);
-        if (!count)
-          break;
-        size += count;
-      }
-      bytes = buffer.subarray(0, size);
-    } finally {
-      fs.closeSync(descriptor);
+  try {
+    const stat = fs.fstatSync(descriptor);
+    checkFile(stat);
+    const buffer = Buffer.alloc(stat.size + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, size, buffer.length - size, null);
+      if (!count)
+        break;
+      size += count;
     }
-  } else {
-    bytes = fs.readFileSync(file);
+    const finalStat = fs.fstatSync(descriptor);
+    checkFile(finalStat);
+    if (size !== stat.size || finalStat.size !== stat.size)
+      throw new UsageError("Attachment changed while reading; retry with a stable file");
+    bytes = buffer.subarray(0, size);
+  } finally {
+    fs.closeSync(descriptor);
   }
-  if (bytes.length > MAX_AGENT_ATTACHMENT_BYTES)
-    throw new UsageError("Attachment exceeds the 5 MiB limit");
-  if (!bytes.length)
-    throw new UsageError("Attachment file is empty");
-  return {
+  const { createHash } = await import("node:crypto");
+  const link = await executor.call("attachment.upload_url", {
     threadId: input.threadId,
     filename,
     mimeType,
-    content: Buffer.from(bytes).toString("base64"),
-    ...input.description !== undefined ? { description: input.description } : {}
-  };
+    size: bytes.length,
+    ...input.description !== undefined ? { description: input.description } : {},
+    sha256: createHash("sha256").update(bytes).digest("hex")
+  });
+  let response;
+  try {
+    response = await fetcher(link.url, {
+      method: link.method,
+      headers: link.headers,
+      body: bytes,
+      redirect: "error"
+    });
+  } catch (cause) {
+    throw new ApiError(`Attachment PUT failed for ${bytes.length} bytes (limit ${MAX_ATTACHMENT_BYTES} bytes): ${cause instanceof Error ? cause.message : String(cause)}. Retry the command to request a fresh upload_url; compress, split, or link files above the limit.`, 0);
+  }
+  if (!response.ok)
+    throw new ApiError(`Attachment PUT failed (${response.status}) for ${bytes.length} bytes (limit ${MAX_ATTACHMENT_BYTES} bytes). Request a fresh upload_url if expired, then retry; compress, split, or link files above the limit.`, response.status);
+  return executor.call("attachment.attach", { token: link.token });
 }
 
 // src/output.ts
@@ -15525,6 +15641,8 @@ function artifactEditIdempotencyKey(input) {
   return `cli-artifact-edit:${artifactId}:${version}:${digest}`;
 }
 var COMMAND_WORD_OVERRIDES = {
+  get_attachment: "attachment get",
+  list_attachments: "attachment list",
   contribute_arbor_feedback: "feedback",
   feedback_recall: "feedback find",
   feedback_thread_get: "feedback thread",
@@ -15548,6 +15666,8 @@ function commandWords(action) {
 var CLI_ACTIONS = ACTIONS3.filter((a) => a.surfaces.includes("cli") || a.surfaces.includes("computer-cli"));
 var BY_ACTION_NAME = new Map(CLI_ACTIONS.map((action) => [action.name, action]));
 var BY_COMMAND = new Map(CLI_ACTIONS.map((a) => [commandWords(a), a]));
+for (const action of CLI_ACTIONS)
+  BY_COMMAND.set(action.name, action);
 for (const [alias, actionName] of Object.entries(MCP_COMMAND_ALIASES)) {
   const action = BY_ACTION_NAME.get(actionName);
   if (action)
@@ -15555,6 +15675,7 @@ for (const [alias, actionName] of Object.entries(MCP_COMMAND_ALIASES)) {
 }
 var MAX_WORDS = Math.max(1, ...CLI_ACTIONS.map((a) => commandWords(a).split(" ").length));
 var POSITIONAL_FIELDS = {
+  attachment_upload: ["file"],
   contribute_arbor_feedback: ["body"],
   feedback_recall: ["query"],
   feedback_thread_get: ["threadId"],
@@ -15837,8 +15958,7 @@ async function runObjectVerb(positionals, flags, ctx) {
     advise(`Agent registered. Save its apiKey now — it is shown only once:
 `, ctx);
   }
-  const executionInput = action.name === "attachment_upload" ? await localAttachmentInput(input) : input;
-  let value = await action.run(httpExecutor, executionInput);
+  let value = action.name === "attachment_upload" ? await uploadLocalAttachment(httpExecutor, input) : await action.run(httpExecutor, input);
   if (action.name === "computer_exec" && !truthyFlag(flags["no-wait"]) && input.waitForTerminalMs === undefined && input.background !== true) {
     value = await waitForComputerExec(httpExecutor, input, value, ctx);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.23.41",
+  "version": "0.24.1",
   "description": "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   "keywords": [
     "agents",