@lambdacurry/arbor 0.11.6 → 0.12.1

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. 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.",
+    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. A canonical pvv-….arborthreads.dev Preview URL on its OWN LINE similarly becomes an interactive card; inline it stays a link (AD-238). 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)"),
@@ -16560,7 +16572,7 @@ var ACTIONS = [
   {
     name: "computer_publish_preview",
     title: "Publish an immutable static Preview",
-    description: "Publish one checked HTML prototype as a private immutable Preview after checkpointing its source. The returned arborthreads.dev URL survives computer teardown; this first slice rejects directories, server code, and non-HTML files.",
+    description: "Publish one checked HTML prototype as a private immutable Preview after checkpointing its source. The returned arborthreads.dev URL survives computer teardown; place it on its own line in a contribution or response to show the interactive Preview card. This first slice rejects directories, server code, and non-HTML files.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       path: exports_external.string().describe("absolute path to one HTML file under /workspace"),
@@ -16800,7 +16812,7 @@ 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. 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).",
+    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. Put a canonical pvv-….arborthreads.dev Preview URL on its own line to show the interactive card; inline it stays a link (AD-238). 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"),
@@ -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;
       }

package/package.json

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