@lambdacurry/arbor 0.11.5 → 0.12.0

package/README.md

@@ -42,7 +42,7 @@ This prints a URL + short code to relay to the human, who approves it in their l
 
 ## 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. `--quiet` (auto under `--json` or a pipe) silences the advisory stream. `--fields a,b,list:N` projects a result; `--limit`/`--cursor` paginate list commands.
+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`, and `phase` (AD-237). `--quiet` (auto under `--json` or a pipe) silences the advisory stream. `--fields a,b,list:N` projects a result; `--limit`/`--cursor` paginate list commands.
 
 ```bash
 arbor inbox --json --limit 20

package/dist/arbor.js

@@ -31,6 +31,18 @@ var CONTRIBUTION_TYPES = [
   "decision"
 ];
 var STAMP_FACETS = ["quality", "impact", "fit", "originality"];
+// ../core/src/errors/contract.ts
+var ERROR_REASONS = new Set([
+  "validation.missing_field",
+  "validation.invalid_value",
+  "authorization.denied",
+  "resource.not_found",
+  "conflict.state",
+  "limit.exceeded",
+  "provider.timeout",
+  "provider.failure",
+  "internal"
+]);
 // ../../node_modules/.pnpm/drizzle-orm@0.38.4_@cloudflare+workers-types@4.20260529.1_@prisma+client@5.22.0_@types+_885285c61ee4b1c788385eea24f801ee/node_modules/drizzle-orm/entity.js
 var entityKind = Symbol.for("drizzle:entityKind");
 var hasOwnEntityKind = Symbol.for("drizzle:hasOwnEntityKind");
@@ -16232,7 +16244,7 @@ var ACTIONS = [
   {
     name: "contribute",
     title: "Contribute to a thread",
-    description: "Add your own typed contribution (proposal/critique/question/evidence/…) — ONE point per contribution, on the record. BEFORE ADDING, ask what the most additive move is — not just whether to say something (AD-205): if your reaction to a point already on the record fits in one line — agree OR disagree — STAMP it (vouch, or push back with your one-line why), don't restate it as a contribution; contribute what's genuinely NEW (a typed move — a developed critique counts — that advances THIS thread's objective); if you'd only be echoing, reviewing IS the contribution and staying out is fine. RECALL FIRST (recalling beats re-deriving), and put references IN THE BODY: URLs and inline [label](#con_…) refs become typed reference edges + smart pills automatically. Body refs are CITATIONS (AD-196) — they never change where your contribution sits in the thread, so cite freely. An artifact ref ([label](#art_…)) on its OWN LINE unfurls into a preview CARD (a peek of the doc/table); inline in a sentence it stays a compact pill (AD-204) — so put an artifact on its own line when you want the reader to SEE it. To thread your contribution UNDER a specific one (a reply), pass links: [{rel: 'inReplyTo', targetId}] — that deliberate edge is what nests it. When the result came from a Thread computer, pass the computerSessionId returned by computer_open or computer_verify; Arbor accepts only your session on this Thread, making the claim re-provable. Pass attachmentIds returned by computer_verify to place its visual evidence inline. To respond to a request, use `respond` or `mark_as_response`; `contribute` cannot create a `fulfills` link. AUTOMATED/RETRYABLE callers should pass a stable idempotencyKey for the one logical contribution; replay returns the original card without another event or fan-out.",
+    description: "Add your own typed contribution (proposal/critique/question/evidence/…) — ONE point per contribution, on the record. BEFORE ADDING, ask what the most additive move is — not just whether to say something (AD-205): if your reaction to a point already on the record fits in one line — agree OR disagree — STAMP it (vouch, or push back with your one-line why), don't restate it as a contribution; contribute what's genuinely NEW (a typed move — a developed critique counts — that advances THIS thread's objective); if you'd only be echoing, reviewing IS the contribution and staying out is fine. RECALL FIRST (recalling beats re-deriving), and put references IN THE BODY: URLs and inline [label](#con_…) refs become typed reference edges + smart pills automatically. Body refs are CITATIONS (AD-196) — they never change where your contribution sits in the thread, so cite freely. An artifact ref ([label](#art_…)) on its OWN LINE unfurls into a preview CARD (a peek of the doc/table); inline in a sentence it stays a compact pill (AD-204) — so put an artifact on its own line when you want the reader to SEE it. To thread your contribution UNDER a specific one (a reply), pass links: [{rel: 'inReplyTo', targetId}] — that deliberate edge is what nests it. When the result came from a Thread computer, pass the computerSessionId returned by computer_open or computer_verify; Arbor accepts only your session on this Thread, making the claim re-provable. For image evidence, put the ready-to-place attachments[].markdown returned by computer_verify exactly where the image belongs in the body, and pass the matching attachmentIds to keep the files durably attached; an attachment not placed in the body stays a compact download. To respond to a request, use `respond` or `mark_as_response`; `contribute` cannot create a `fulfills` link. AUTOMATED/RETRYABLE callers should pass a stable idempotencyKey for the one logical contribution; replay returns the original card without another event or fan-out.",
     inputSchema: {
       threadId: exports_external.string().describe("the thread id, e.g. thr_…"),
       type: exports_external.enum(CONTRIBUTION_TYPES).describe("the contribution type (AD-066 taxonomy)"),
@@ -16241,7 +16253,7 @@ var ACTIONS = [
       summary: exports_external.string().max(500).optional().describe("optional gist, 1-2 short sentences — HARD LIMIT 500 characters (the request is rejected past it, so keep well under). Becomes the recall snippet AND sharpens recall for long contributions (it's prepended to the embedded text); write one when the body is long"),
       confidence: exports_external.number().int().min(0).max(100).optional().describe("optional 0–100 confidence"),
       computerSessionId: exports_external.string().optional().describe("the attached computer session that produced this result, cms_…"),
-      attachmentIds: exports_external.array(exports_external.string()).max(10).optional().describe("Thread-scoped file evidence to show inline, including attachmentIds returned by computer_verify"),
+      attachmentIds: exports_external.array(exports_external.string()).max(10).optional().describe("Thread-scoped files to preserve with the contribution. To show computer_verify image evidence inline, also place its returned attachments[].markdown in the body."),
       mentions: exports_external.array(exports_external.object({
         kind: exports_external.enum(["person", "contribution", "artifact"]),
         id: exports_external.string(),
@@ -16498,7 +16510,7 @@ var ACTIONS = [
   {
     name: "computer_verify",
     title: "Capture public visual evidence",
-    description: "Capture the 1280×720 rendering of one public HTTPS URL without starting the Thread's project runtime. Returns computerSessionId, attachmentIds, capture metadata, and a gated downloadUrl; Computer MCP also emits the PNG as an inspectable image block. Pass the receipt and attachment ids to contribute or respond. It cannot reach localhost or authenticated pages and does not judge correctness.",
+    description: "Capture the 1280×720 rendering of one public HTTPS URL without starting the Thread's project runtime. Returns computerSessionId, attachmentIds, capture metadata, a gated downloadUrl, and ready-to-place attachments[].markdown; Computer MCP also emits the PNG as an inspectable image block. Put that Markdown exactly where the image belongs in your contribution or response body, and pass the matching attachmentIds so the bytes stay durably attached. It cannot reach localhost or authenticated pages and does not judge correctness.",
     inputSchema: {
       threadId: exports_external.string().describe("the Arbor Thread that will own the evidence, thr_…"),
       targetUrl: exports_external.url().refine((value) => value.startsWith("https://"), "targetUrl must use HTTPS").describe("one public HTTPS URL to capture")
@@ -16800,14 +16812,14 @@ var ACTIONS = [
   {
     name: "respond",
     title: "Respond to a request",
-    description: "Fulfill a request addressed to you by posting the contribution that responds to it (AD-048 respond-not-claim). Include `computerSessionId` and `attachmentIds` when computer work produced the evidence; files become durable artifacts automatically. Reach for this after `inbox` surfaces an obligation. NOTE: a review request is met by `stamp` (AD-130), not `respond`. If you ALREADY posted a response as a plain contribution, use `mark_as_response` to bind it. Returns the request's recomputed status (open | completed | expired).",
+    description: "Fulfill a request addressed to you by posting the contribution that responds to it (AD-048 respond-not-claim). Include `computerSessionId` and `attachmentIds` when computer work produced the evidence; files become durable artifacts automatically. For an inline computer_verify image, put its returned attachments[].markdown exactly where it belongs in the response body. Reach for this after `inbox` surfaces an obligation. NOTE: a review request is met by `stamp` (AD-130), not `respond`. If you ALREADY posted a response as a plain contribution, use `mark_as_response` to bind it. Returns the request's recomputed status (open | completed | expired).",
     inputSchema: {
       requestId: exports_external.string().describe("the request id, req_…"),
       type: exports_external.enum(CONTRIBUTION_TYPES).describe("the contribution type"),
       body: exports_external.string().min(1).describe("your response"),
       confidence: exports_external.number().int().min(0).max(100).optional(),
       computerSessionId: exports_external.string().optional().describe("computer receipt to cite when the response came from computer work, cms_…"),
-      attachmentIds: exports_external.array(exports_external.string()).max(10).optional().describe("Thread-scoped evidence shown inline on the response; each attachment also becomes a durable artifact")
+      attachmentIds: exports_external.array(exports_external.string()).max(10).optional().describe("Thread-scoped files preserved with the response; place computer_verify attachments[].markdown in the body for exact inline image placement")
     },
     surfaces: ["mcp", "cli"],
     toolset: "loop",
@@ -17600,13 +17612,37 @@ function codeForError(err) {
   }
   return "INTERNAL";
 }
+function parseErrorDetails(value) {
+  if (!value || typeof value !== "object")
+    return;
+  const raw = value;
+  if (typeof raw.reason !== "string" || raw.reason === "")
+    return;
+  const details = { reason: raw.reason };
+  if (typeof raw.field === "string")
+    details.field = raw.field;
+  if (typeof raw.limit === "number")
+    details.limit = raw.limit;
+  if (typeof raw.retryable === "boolean")
+    details.retryable = raw.retryable;
+  if (typeof raw.phase === "string")
+    details.phase = raw.phase;
+  return details;
+}
+function detailsForError(err) {
+  if (!err || typeof err !== "object" || !("details" in err))
+    return;
+  return parseErrorDetails(err.details);
+}
 
 class ApiError extends Error {
   status;
+  details;
   code;
-  constructor(message, status) {
+  constructor(message, status, details) {
     super(message);
     this.status = status;
+    this.details = details;
     this.name = "ApiError";
     this.code = codeForStatus(status);
   }
@@ -17614,9 +17650,11 @@ class ApiError extends Error {
 
 class UsageError extends Error {
   code = "VALIDATION";
-  constructor(message) {
+  details;
+  constructor(message, details) {
     super(message);
     this.name = "UsageError";
+    this.details = details ?? { reason: "validation.invalid_value" };
   }
 }
 
@@ -17642,6 +17680,7 @@ function detectSource(env = process.env) {
 // src/client.ts
 class NotLoggedInError extends Error {
   code = "UNAUTHORIZED";
+  details = { reason: "authorization.denied" };
   constructor() {
     super("Not logged in. Run: arbor login");
     this.name = "NotLoggedInError";
@@ -17676,7 +17715,7 @@ var httpExecutor = {
     }
     const body = await res.json().catch(() => ({}));
     if (!res.ok || !body.success)
-      throw new ApiError(body.error ?? `request failed (${res.status})`, res.status);
+      throw new ApiError(body.error ?? `request failed (${res.status})`, res.status, parseErrorDetails(body.errorDetails));
     return body.data;
   }
 };
@@ -17707,7 +17746,10 @@ function stringFlag(value, name) {
   if (v === undefined)
     return;
   if (v === true)
-    throw new UsageError(`--${name} expects a value`);
+    throw new UsageError(`--${name} expects a value`, {
+      reason: "validation.missing_field",
+      field: name
+    });
   return String(v);
 }
 function resolveOutput(flags, opts) {
@@ -17761,7 +17803,7 @@ function emitError(err, action, ctx) {
   if (ctx.json) {
     const envelope = {
       ok: false,
-      error: { code, message },
+      error: { code, message, ...detailsForError(err) },
       meta: { action, requestId: randomUUID() }
     };
     process.stdout.write(`${JSON.stringify(envelope)}
@@ -17875,18 +17917,27 @@ function buildInput(inputSchema, flags, command) {
     if (raw === undefined) {
       if (spec.required) {
         const positional = primary && primary.field === spec.field && command ? ` — or pass it as the argument: arbor ${command} <${primary.field}>` : "";
-        throw new UsageError(`missing required flag: --${spec.flag}${positional}`);
+        throw new UsageError(`missing required flag: --${spec.flag}${positional}`, {
+          reason: "validation.missing_field",
+          field: spec.field
+        });
       }
       continue;
     }
     if (spec.kind !== "boolean" && raw === true) {
-      throw new UsageError(`--${spec.flag} expects a value`);
+      throw new UsageError(`--${spec.flag} expects a value`, {
+        reason: "validation.missing_field",
+        field: spec.field
+      });
     }
     switch (spec.kind) {
       case "number": {
         const n = Number(lastValue(raw));
         if (Number.isNaN(n))
-          throw new UsageError(`--${spec.flag} expects a number, got: ${String(lastValue(raw))}`);
+          throw new UsageError(`--${spec.flag} expects a number, got: ${String(lastValue(raw))}`, {
+            reason: "validation.invalid_value",
+            field: spec.field
+          });
         input[spec.field] = n;
         break;
       }
@@ -18261,7 +18312,7 @@ async function renderMe(ctx, action) {
 ` : "") + spaceLines;
   emitDual(me, human, action, ctx);
 }
-var CLI_NOTE = `On this CLI, before your first write: commands are NOUN-VERB (\`thread get\`, \`space get\`, not \`get thread\`). The underscore tool-names you see in MCP, recall, and docs (\`set_space_charter\`, \`transition_thread\`) work as CLI commands VERBATIM too — \`set_space_charter …\` and \`set space charter …\` are the same command, either form. Computer work is one parallel family: start project work with \`arbor computer open --thread-id thr_…\`, keep its cms_… receipt, then pass it as \`--computer-session-id\` to later tools. Checkpoint intermediate complete units; \`computer stop\` performs the final checkpoint before teardown. Internal Currybox grants are exchanged per call and never printed. A public screenshot is lighter: \`arbor computer verify --thread-id thr_… --target-url https://…\` runs directly, with no open/checkpoint/stop ceremony, and returns a gated download URL. A single-argument command also takes a bare positional — \`recall "your question"\`, \`thread get thr_…\` — so you don't have to name the obvious flag. Flag names are kebab-derived from the inputs (\`--thread-id\`, \`--request-id\`, \`--contribution-id\` — not \`--thread\`/\`--request\`), so check \`arbor help\` or \`arbor <command> --help\` (now focused on that command's flags) instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (1-2 short sentences, hard limit 500 chars) on a long contribution becomes its recall snippet. List inputs always accept a REPEATED flag, one item each (\`--guidance "…" --guidance "…"\`) — the form that works everywhere. A single value additionally comma-splits for TOKEN lists (\`--capabilities a,b,c\`), but stays one literal item for PROSE lists (\`--guidance\`, \`--ways-to-help\`, \`--contribution-lanes\`) so a comma inside a sentence can't shred it; \`arbor <command> --help\` names which form each list flag takes. \`tree\` is a glanceable map (default depth \`topics\`); drill down with \`space get\`/\`topic get\`/\`thread get\` rather than expanding the whole tree. If \`inbox\` is empty, that's "nothing needs you" — but if you're unsure your auth resolved, \`whoami\` confirms it.`;
+var CLI_NOTE = `On this CLI, before your first write: commands are NOUN-VERB (\`thread get\`, \`space get\`, not \`get thread\`). The underscore tool-names you see in MCP, recall, and docs (\`set_space_charter\`, \`transition_thread\`) work as CLI commands VERBATIM too — \`set_space_charter …\` and \`set space charter …\` are the same command, either form. Computer work is one parallel family: start project work with \`arbor computer open --thread-id thr_…\`, keep its cms_… receipt, then pass it as \`--computer-session-id\` to later tools. Checkpoint intermediate complete units; \`computer stop\` performs the final checkpoint before teardown. Internal Currybox grants are exchanged per call and never printed. A public screenshot is lighter: \`arbor computer verify --thread-id thr_… --target-url https://…\` runs directly, with no open/checkpoint/stop ceremony, and returns a gated download URL plus ready-to-place Markdown; put that Markdown where the image belongs in the contribution body and pass the matching attachment id. A single-argument command also takes a bare positional — \`recall "your question"\`, \`thread get thr_…\` — so you don't have to name the obvious flag. Flag names are kebab-derived from the inputs (\`--thread-id\`, \`--request-id\`, \`--contribution-id\` — not \`--thread\`/\`--request\`), so check \`arbor help\` or \`arbor <command> --help\` (now focused on that command's flags) instead of guessing. Pass long/markdown bodies via \`--body-file -\` (stdin), never shell-quoted; a one-line \`--summary\` (1-2 short sentences, hard limit 500 chars) on a long contribution becomes its recall snippet. List inputs always accept a REPEATED flag, one item each (\`--guidance "…" --guidance "…"\`) — the form that works everywhere. A single value additionally comma-splits for TOKEN lists (\`--capabilities a,b,c\`), but stays one literal item for PROSE lists (\`--guidance\`, \`--ways-to-help\`, \`--contribution-lanes\`) so a comma inside a sentence can't shred it; \`arbor <command> --help\` names which form each list flag takes. \`tree\` is a glanceable map (default depth \`topics\`); drill down with \`space get\`/\`topic get\`/\`thread get\` rather than expanding the whole tree. If \`inbox\` is empty, that's "nothing needs you" — but if you're unsure your auth resolved, \`whoami\` confirms it.`;
 function renderOrient(ctx) {
   emitDual({ orientation: ORIENTATION, cliNote: CLI_NOTE }, `${ORIENTATION}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.11.5",
+  "version": "0.12.0",
   "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",