@lambdacurry/arbor 0.23.39 → 0.23.41

package/README.md

@@ -73,6 +73,23 @@ 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 --thread-id thr_… --file ./screenshot.png --description "Settings dialog after save"
+# Alias: arbor attachment_upload --thread-id thr_… --file ./screenshot.png
+```
+
+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.
+
 ## 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.39",
+  version: "0.23.41",
   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,34 @@ var ARTIFACT_TYPES = [
   "eval-rubric",
   "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 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",
@@ -10249,6 +10277,14 @@ var MCP_OUTPUT_SCHEMAS = {
       sha256: string2()
     })
   }),
+  upload_attachment: looseObject({
+    attachmentId: id,
+    attachmentIds: array(id),
+    downloadUrl: string2(),
+    uploadedByProfileId: id,
+    createdAt: timestamp,
+    attachments: array(attachment2)
+  }),
   computer_export: looseObject({
     computerSessionId: id,
     replayed: boolean2(),
@@ -10340,6 +10376,8 @@ var MCP_OUTPUT_SCHEMAS = {
   })
 };
 function outputSchemaFor(actionName) {
+  if (actionName === "attachment_upload")
+    actionName = "upload_attachment";
   return MCP_OUTPUT_SCHEMAS[actionName];
 }
 
@@ -10706,6 +10744,7 @@ var MCP_TOOL_ANNOTATIONS = {
   admin_feedback_edit: destructive,
   admin_feedback_curate: destructive,
   contribute: additive,
+  upload_attachment: additive,
   edit: additive,
   stamp: additive,
   react: idempotent,
@@ -11644,7 +11683,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 or computer_export or upload_attachment 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 +12266,34 @@ var ACTION_DEFINITIONS = [
     toolset: "loop",
     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.",
+    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")
+    },
+    surfaces: ["mcp"],
+    toolset: "loop",
+    run: forward("attachment.upload")
+  },
+  {
+    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.",
+    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")
+    },
+    surfaces: ["cli"],
+    toolset: "loop",
+    run: forward("attachment.upload")
+  },
   {
     name: "computer_export",
     title: "Export a Thread file",
@@ -12586,7 +12653,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 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.",
     inputSchema: {
       requestId: string2().describe("the request id, req_…"),
       type: _enum(CONTRIBUTION_TYPES).describe("the contribution type"),
@@ -13427,7 +13494,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "artifact",
     title: "Create or edit an Artifact",
-    description: "Create/edit an Artifact, bind a Thread Live Preview, set a Computer snapshot, or promote a Thread attachment to a file Artifact. Git writes: stable key; same-key retry only after unknown outcome. To reference an exported report within an existing baseline Artifact, use the Attachment's durable downloadUrl instead of promoting it into that artifactId. For a computer:// .tldr snapshot mint: computer_export the exact locator path and same-Thread PNG, then use set_snapshot. Board save and TLP do not mint snapshots. set_snapshot does not wake Computer or change the locator; read artifact_get before changing it, while lifecycle/removal stay in artifact_transition and artifact_delete.",
+    description: "Create/edit an Artifact, bind a Live Preview, set a Computer snapshot, or promote a Thread attachment. Git edits derive retry keys (omitted edits derive one); keyless creates mint per-invocation keys; stable idempotencyKey supports caller retries. Retry only after unknown outcomes; never blindly repeat ambiguous creates. Exported reports use the Attachment downloadUrl; tldraw snapshot and lifecycle actions use their dedicated operations.",
     inputSchema: {
       verb: _enum(["create", "edit", "set_live_preview", "set_snapshot", "promote_attachment"]).describe("which artifact move"),
       title: string2().optional().describe("create: the artifact's title"),
@@ -13445,7 +13512,7 @@ var ACTION_DEFINITIONS = [
       baseVersion: number2().optional().describe("edit: the version you READ (from get/create) — stale base is rejected with the current source"),
       patches: array(object({ old: string2(), new: string2() })).optional().describe("edit: exact-match hunks applied in order, atomically; each old must match exactly once"),
       note: string2().optional().describe("edit: one-line summary of what changed"),
-      idempotencyKey: string2().min(1).max(200).optional().describe("create/edit for Git-backed text: stable key for one logical write; reuse unchanged only to recover an unknown outcome, never to start a new write"),
+      idempotencyKey: string2().min(1).max(200).optional().describe("create: optional caller-stable key; omitted creates mint one per invocation; edit: optional stable key (omitted edits derive one from actor/artifact/base/payload); reuse unchanged only to recover an unknown outcome, never to start a new write"),
       sourceAttachmentId: string2().optional().describe("set_snapshot: computer_export of the exact computer:// locator path; MIME application/vnd.tldraw+json, computerPath stamped and matching defaultCwd + locator"),
       previewAttachmentId: string2().optional().describe("set_snapshot: same-Thread computer_export image/png Attachment, used as the asleep face preview"),
       attachmentId: string2().optional().describe("promote_attachment: the upload, att_…"),
@@ -14211,7 +14278,7 @@ function retentionAction(action) {
   if (action.name === "artifact") {
     return {
       ...action,
-      description: "Create/edit a durable Artifact with full|checkpoint retention or manage Live Preview/snapshot/attachments. Git text writes require a stable idempotencyKey; retry the same key only after an unknown outcome; promote_attachment creates a separate file Artifact from a source Contribution; exported reports use the Attachment's durable downloadUrl; content edits return artifactVersionId; identical edits reuse the current version; policy/checkpoint changes do not mint content versions.",
+      description: "Create/edit a durable Artifact with full|checkpoint retention or manage Live Preview, snapshots, and attachments. Git edits derive retry keys (omitted edits derive one); keyless creates mint per-invocation keys; stable idempotencyKey supports caller retries; never blindly repeat ambiguous creates. promote_attachment creates a file Artifact from a Contribution; exported reports use the Attachment downloadUrl; policy changes do not mint content versions.",
       inputSchema: {
         ...action.inputSchema,
         historyPolicy: historyPolicySchema,
@@ -14875,6 +14942,56 @@ 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("--file must be a regular file");
+  if (stat.size > MAX_AGENT_ATTACHMENT_BYTES)
+    throw new UsageError("Attachment exceeds the 5 MiB limit");
+}
+async function localAttachmentInput(input) {
+  const file = String(input.file);
+  const filename = basename(file);
+  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));
+  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);
+    }
+  } else {
+    bytes = fs.readFileSync(file);
+  }
+  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 {
+    threadId: input.threadId,
+    filename,
+    mimeType,
+    content: Buffer.from(bytes).toString("base64"),
+    ...input.description !== undefined ? { description: input.description } : {}
+  };
+}
+
 // src/output.ts
 function writeOutput(value, stream, fallback) {
   if (stream && typeof stream.write === "function") {
@@ -15720,7 +15837,8 @@ 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);
+  const executionInput = action.name === "attachment_upload" ? await localAttachmentInput(input) : input;
+  let value = await action.run(httpExecutor, executionInput);
   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.39",
+  "version": "0.23.41",
   "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",