@lambdacurry/arbor 0.23.40 → 0.24.1

package/README.md

@@ -73,6 +73,41 @@ npx @lambdacurry/arbor connect <pairing-key>
 
 This prints a URL + short code to relay to the human, who approves it in their logged-in session. On approval the agent receives its own key (saved to `~/.arbor/config.json`) and acts as a managed, collaborate-only member of the org thereafter.
 
+## Attach a local file
+
+```bash
+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_…
+```
+
+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)
 
 Every command takes `--json` to emit a stable `{ ok, data | error, meta }` envelope on stdout (with structured error codes and agent-mode exit codes); advisory/human text goes to stderr. A failure envelope adds the server's granular `reason` — `validation.missing_field`, `limit.exceeded`, `conflict.state`, … — beside the coarse `code`, optionally with `field`, `limit`, `retryable`, `phase`, and bounded sanitized `provider` lifecycle diagnostics (AD-237/261). `--quiet` (auto under `--json` or a pipe) silences the advisory stream. `--fields a,b,list:N` projects a result; `--limit`/`--cursor` paginate list commands.

package/dist/arbor.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.23.40",
+  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",
@@ -5160,6 +5160,33 @@ var ARTIFACT_TYPES = [
   "eval-rubric",
   "external-reference"
 ];
+// ../core/src/blob/attachment-upload.ts
+var MAX_ATTACHMENT_BYTES = 1e8;
+var AGENT_ATTACHMENT_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+  "text/plain",
+  "application/json",
+  "text/csv"
+];
+function localAttachmentMime(filename) {
+  const extension = filename.toLowerCase().split(".").at(-1) ?? "";
+  const types = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    pdf: "application/pdf",
+    txt: "text/plain",
+    json: "application/json",
+    csv: "text/csv"
+  };
+  return types[extension];
+}
 // ../core/src/feedback/constants.ts
 var ARBOR_FEEDBACK_TYPES = [
   "comment",
@@ -8576,6 +8603,7 @@ var attachment2 = looseObject({
   size: number2(),
   sha256: string2(),
   downloadUrl: string2(),
+  mediaUrl: string2().optional(),
   markdown: string2()
 });
 var checkpoint = looseObject({
@@ -10249,6 +10277,59 @@ var MCP_OUTPUT_SCHEMAS = {
       sha256: string2()
     })
   }),
+  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),
+    warnings: array(string2()).optional()
+  }),
   computer_export: looseObject({
     computerSessionId: id,
     replayed: boolean2(),
@@ -10340,6 +10421,8 @@ var MCP_OUTPUT_SCHEMAS = {
   })
 };
 function outputSchemaFor(actionName) {
+  if (actionName === "attachment_upload")
+    actionName = "attachment_attach";
   return MCP_OUTPUT_SCHEMAS[actionName];
 }
 
@@ -10706,6 +10789,7 @@ var MCP_TOOL_ANNOTATIONS = {
   admin_feedback_edit: destructive,
   admin_feedback_curate: destructive,
   contribute: additive,
+  attachment: additive,
   edit: additive,
   stamp: additive,
   react: idempotent,
@@ -11635,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)"),
@@ -11644,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 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(),
@@ -12227,6 +12311,87 @@ var ACTION_DEFINITIONS = [
     toolset: "loop",
     run: forward("computer_code.diagnostics")
   },
+  {
+    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: {
+      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: 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 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),
+      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_url")
+  },
   {
     name: "computer_export",
     title: "Export a Thread file",
@@ -12586,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 Computer evidence, pass computerSessionId/attachmentIds and place returned attachments[].markdown in the body where media belongs.",
+    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"),
@@ -12714,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"),
@@ -14875,6 +15040,74 @@ var httpExecutor = {
   }
 };
 
+// src/attachment-upload.ts
+import { basename } from "node:path";
+function checkFile(stat) {
+  const isFile = typeof stat.isFile === "function" ? stat.isFile() : stat.isFile;
+  if (!isFile)
+    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 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 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;
+  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;
+    }
+    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);
+  }
+  const { createHash } = await import("node:crypto");
+  const link = await executor.call("attachment.upload_url", {
+    threadId: input.threadId,
+    filename,
+    mimeType,
+    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
 function writeOutput(value, stream, fallback) {
   if (stream && typeof stream.write === "function") {
@@ -15408,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",
@@ -15431,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)
@@ -15438,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"],
@@ -15720,7 +15958,7 @@ async function runObjectVerb(positionals, flags, ctx) {
     advise(`Agent registered. Save its apiKey now — it is shown only once:
 `, ctx);
   }
-  let value = await action.run(httpExecutor, input);
+  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.40",
+  "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",