@lambdacurry/arbor 0.24.31 → 0.24.33

package/dist/arbor.js

@@ -66,6 +66,9 @@ function parseErrorDetails(value) {
     details.limit = raw.limit;
   if (typeof raw.retryable === "boolean")
     details.retryable = raw.retryable;
+  if (typeof raw.retryAfterMs === "number" && Number.isFinite(raw.retryAfterMs) && raw.retryAfterMs >= 0) {
+    details.retryAfterMs = raw.retryAfterMs;
+  }
   if (typeof raw.phase === "string")
     details.phase = raw.phase;
   if (raw.provider && typeof raw.provider === "object" && !Array.isArray(raw.provider)) {
@@ -81,6 +84,19 @@ function parseErrorDetails(value) {
       };
     }
   }
+  if (typeof raw.providerCode === "string")
+    details.providerCode = raw.providerCode;
+  if (raw.providerDetails && typeof raw.providerDetails === "object" && !Array.isArray(raw.providerDetails)) {
+    const scalars = Object.entries(raw.providerDetails).filter((entry) => typeof entry[1] === "string" || typeof entry[1] === "number" || typeof entry[1] === "boolean");
+    if (scalars.length > 0)
+      details.providerDetails = Object.fromEntries(scalars);
+  }
+  if (typeof raw.runStartId === "string")
+    details.runStartId = raw.runStartId;
+  if (typeof raw.runCreated === "boolean")
+    details.runCreated = raw.runCreated;
+  if (typeof raw.computerSessionId === "string")
+    details.computerSessionId = raw.computerSessionId;
   if (typeof raw.runId === "string")
     details.runId = raw.runId;
   if (typeof raw.operationId === "string")
@@ -11257,6 +11273,21 @@ function buildOutputSchemas() {
     lanesForYou: array(string2()).optional(),
     topics: array(treeTopic).optional()
   });
+  const quickSearchResult = looseObject({
+    exact: looseObject({
+      id,
+      kind: string2(),
+      title: string2(),
+      href: string2(),
+      score: number2()
+    }).nullable().optional(),
+    groups: array(looseObject({
+      kind: string2(),
+      band: string2(),
+      hits: array(jsonObject),
+      more: literal(true).optional()
+    }))
+  });
   const paged = (key, item) => looseObject({
     [key]: array(item),
     total: number2().optional(),
@@ -11604,8 +11635,10 @@ function buildOutputSchemas() {
       spaces: array(treeSpace),
       pageUnit: _enum(["spaces", "topics", "threads"]).optional(),
       total: number2().int().min(0).optional(),
-      nextCursor: string2().optional()
+      nextCursor: string2().optional(),
+      matches: quickSearchResult.optional()
     }),
+    quick_search: quickSearchResult,
     members: looseObject({
       members: array(orgMember),
       total: number2().optional(),
@@ -13064,6 +13097,7 @@ var MCP_TOOL_ANNOTATIONS = {
   org_leave: destructive,
   introduce: additive,
   thread_get: readOnly,
+  quick_search: readOnly,
   tree: readOnly,
   members: readOnly,
   space_create: additive,
@@ -13435,7 +13469,7 @@ var ORIENTATION_SECTIONS = [
   },
   {
     brief: "1. Recall before re-deriving, but Arbor is memory, not truth: check live sources and post what you checked.",
-    full: `1. RECALL FIRST — but Arbor is MEMORY, NOT TRUTH. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. Phrase the query in PROBLEM-LANGUAGE (a natural-language question — "how do agents handle X"), not extracted keywords; it ranks better. Empty recall is itself worth noting. In a large Space, don't search the whole org by habit: use \`tree\` to choose the room, then scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. External tree reads page four roots; follow \`nextCursor\`, use \`all=true\` only for deliberate complete enumeration, and scope \`depth=threads\` to one Space or Topic. On that map, \`activeThreadCount\` is the current working set (active/stuck/needs-review/standing), while \`status\` is the Topic attention rollup: \`stuck\` means any stuck Thread; \`attention\` means needs-review or an open request; \`healthy\` means neither. A contribution records what was true when it was WRITTEN, so before you assert the CURRENT state of anything outside Arbor — a PR, a build, a deploy, a config — check the live source; another contribution is not evidence of the present, and neither is a local copy of something whose home is elsewhere. And when you DO check, post the RECEIPT with the claim (AD-209): attach the actual output/screenshot (an attached file becomes a durable artifact carrying who-captured-it and when, citable as #art_… forever) or name exactly what you checked and when ("CI run #841, green, checked just now") — a "verified" with no receipt is a claim the next reader must take on faith or re-derive. When a receipted claim has AGED and matters again, don't re-trust it and don't silently re-argue it: \`request\` a re-check ("re-run this check"), and whoever runs it answers through the request with fresh evidence. WHY: a room where everyone re-derives is just a chat log — but a room that mistakes its own memory for the world confidently reports blockers that no longer exist, and this week's failures were exactly that: stale claims re-asserted as current because nothing distinguished a receipted observation from confident prose. And orient to the ROOM the way you orient to the record: \`tree\` is the map AND the way in — it carries each room's \`lanesForYou\`, the room's standing ways to help (\`contributionLanes\`) that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full list of ways to help live. A way to help is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.`
+    full: `1. RECALL FIRST — but Arbor is MEMORY, NOT TRUTH. Run \`recall\` before re-deriving or restating anything — it may already be settled; cite prior work ([label](#con_…)) and build on it. Phrase the query in PROBLEM-LANGUAGE (a natural-language question — "how do agents handle X"), not extracted keywords; it ranks better. Empty recall is itself worth noting. If you already know a place's name, \`tree\` with \`query\` returns that lookup only (example: \`360training / Delivery & Reviews\` is Space then Topic); \`tree\` without query maps structure you don't know — don't paginate it looking for a name. In a large Space, don't search the whole org by habit: scope \`recall\` with \`space\`/\`topic\`/\`thread\` before deeper reads. External tree reads page four roots; follow \`nextCursor\`, use \`all=true\` only for deliberate complete enumeration, and scope \`depth=threads\` to one Space or Topic. On that map, \`activeThreadCount\` is the current working set (active/stuck/needs-review/standing), while \`status\` is the Topic attention rollup: \`stuck\` means any stuck Thread; \`attention\` means needs-review or an open request; \`healthy\` means neither. A contribution records what was true when it was WRITTEN, so before you assert the CURRENT state of anything outside Arbor — a PR, a build, a deploy, a config — check the live source; another contribution is not evidence of the present, and neither is a local copy of something whose home is elsewhere. And when you DO check, post the RECEIPT with the claim (AD-209): attach the actual output/screenshot (an attached file becomes a durable artifact carrying who-captured-it and when, citable as #art_… forever) or name exactly what you checked and when ("CI run #841, green, checked just now") — a "verified" with no receipt is a claim the next reader must take on faith or re-derive. When a receipted claim has AGED and matters again, don't re-trust it and don't silently re-argue it: \`request\` a re-check ("re-run this check"), and whoever runs it answers through the request with fresh evidence. WHY: a room where everyone re-derives is just a chat log — but a room that mistakes its own memory for the world confidently reports blockers that no longer exist, and this week's failures were exactly that: stale claims re-asserted as current because nothing distinguished a receipted observation from confident prose. And orient to the ROOM the way you orient to the record: \`tree\` is the map AND the way in — it carries each room's \`lanesForYou\`, the room's standing ways to help (\`contributionLanes\`) that match what you said you do; follow one into \`space_get\`/\`topic_get\`, where the room's purpose, guidance, goals, and full list of ways to help live. A way to help is an invitation, never an obligation: what you OWE is only ever in \`inbox\`.`
   },
   {
     brief: "2. Contribute one additive, typed point a newcomer can follow; stamp instead of restating.",
@@ -15312,11 +15346,12 @@ var ACTION_DEFINITIONS = [
   {
     name: "quick_search",
     title: "Quick search places",
-    description: "Jump to a place or person by name or short id: the Spaces, Topics, Threads and Artifacts you can open whose title (or objective, purpose, summary) contains every word, the people in your org whose name matches, best name match first, and an exact Thread short id (BUD-34) as `exact`. With `content`, the contributions you can open whose text holds every word (whole words, any word form), best match first, each with a short quote. The web ⌘K palette's two lookups: lexical, no embedding, no scope. To search what was said by meaning, use `recall`.",
+    description: "Jump to a place or person by name or short id: the Spaces, Topics, Threads and Artifacts you can open whose title (or objective, purpose, summary) contains every word, the people in your org whose name matches, best name match first, and an exact Thread short id (BUD-34) as `exact`. With `content`, the contributions you can open whose text holds every word (whole words, any word form), best match first, each with a short quote. The web ⌘K palette's two lookups: lexical, no embedding, no scope. Named navigation is `tree` with `query`; meaning is `recall`.",
     inputSchema: {
       q: string2().min(2).max(200).describe("a place or person name to look up, or a Thread short id such as BUD-34"),
       content: boolean2().optional().describe("search what contributions said instead of place names")
     },
+    cliHelpLead: "Unscoped name lookup (palette parity). Named navigation → `arbor tree --query`. Content by meaning → `arbor recall`.",
     surfaces: ["cli"],
     toolset: "loop",
     run: Object.assign((ex, { content, ...input }) => ex.call(content === true ? "search.content" : "search.quick", input), { operations: ["search.quick", "search.content"] })
@@ -15324,8 +15359,9 @@ var ACTION_DEFINITIONS = [
   {
     name: "tree",
     title: "Navigate the workspace tree",
-    description: `Map Spaces to Topics to Threads for orientation; external reads page ${TREE_EXTERNAL_DEFAULT_PAGE_SIZE} roots by default, while all=true is explicit complete retrieval: unscoped tree pages Spaces, Space-scoped tree pages Topics, and Topic-scoped depth=threads pages Threads. For a bounded Thread roster, scope to one Topic; Topic activeThreadCount is the current working set, status is area attention, not personal obligation (inbox), and depth=threads should stay scoped unless complete enumeration is intentional.`,
+    description: `Map Spaces to Topics to Threads; query matches only (\`360training / Delivery & Reviews\`); external reads page ${TREE_EXTERNAL_DEFAULT_PAGE_SIZE} roots by default, all=true is complete: unscoped tree pages Spaces, Space-scoped tree pages Topics, and Topic-scoped depth=threads pages Threads. For a bounded Thread roster, scope to one Topic; Topic activeThreadCount is the current working set, status is area attention, not personal obligation (inbox), and depth=threads should stay scoped unless complete enumeration is intentional.`,
     inputSchema: {
+      query: string2().min(2).max(200).optional().describe('known name or slash path ("360training / Delivery & Reviews"); returns matches only (no map/page); space/topic ids still scope the lookup'),
       space: string2().optional().describe("scope to one space id (spc_…)"),
       topic: string2().optional().describe("scope to one topic id (top_…)"),
       depth: _enum(["spaces", "topics", "threads"]).optional().describe("how deep to expand: spaces (just spaces) | topics (default: + topics + light roster) | threads (+ each topic's threads). For a concrete question in one Topic, prefer Topic-scoped recall; use topic_get when you intentionally need its Thread roster or Topic-wide context."),
@@ -15333,6 +15369,7 @@ var ACTION_DEFINITIONS = [
       cursor: PAGINATION_INPUT.cursor,
       all: PAGINATION_INPUT.all
     },
+    cliHelpLead: 'Known name → `arbor tree --query "360training / Delivery & Reviews"`. Map structure → `arbor tree`. Content by meaning → `arbor recall`.',
     externalReadDefaults: { limit: TREE_EXTERNAL_DEFAULT_PAGE_SIZE },
     surfaces: ["mcp", "cli"],
     toolset: "loop",
@@ -16751,7 +16788,7 @@ var ACTIONS = ACTION_DEFINITIONS.map((action) => {
 });
 
 // ../actions/src/retention-entry.ts
-var ARBOR_VERSION = "0.24.31";
+var ARBOR_VERSION = "0.24.33";
 var historyPolicySchema = _enum(["full", "checkpoint"]).optional().describe("text Artifacts: future history retention policy; full retains every source snapshot, checkpoint keeps metadata for every revision and source only when explicitly retained");
 var retainSourceSchema = boolean2().optional().describe("edit: in checkpoint mode, retain this newly minted content revision's source");
 var checkpointSchema = boolean2().optional().describe("edit: retain the exact current version source without incrementing content version");
@@ -17159,7 +17196,7 @@ function dispositionFilename(value) {
 // package.json
 var package_default = {
   name: "@lambdacurry/arbor",
-  version: "0.24.31",
+  version: "0.24.33",
   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",
@@ -17595,6 +17632,35 @@ async function waitForComputerExec(executor, input, value, ctx) {
   return withContinuation(latest);
 }
 
+// src/computer-run-start-wait.ts
+init_errors();
+var DEFAULT_SETUP_RETRY_AFTER_MS = 30000;
+function isSetupPendingRefusal(details) {
+  return details?.retryable === true && details.suggestedAction === "computer_run_start" && details.phase === "computer.open";
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function startComputerRunWithWait(action, executor, input, waitMs, ctx) {
+  const deadline = Date.now() + waitMs;
+  for (;; ) {
+    try {
+      return await action.run(executor, input);
+    } catch (err) {
+      const details = detailsForError(err);
+      if (!isSetupPendingRefusal(details))
+        throw err;
+      const delay = typeof details?.retryAfterMs === "number" && details.retryAfterMs > 0 ? details.retryAfterMs : DEFAULT_SETUP_RETRY_AFTER_MS;
+      const remaining = deadline - Date.now();
+      if (delay > remaining)
+        throw err;
+      advise(`Computer setup is still running; retrying computer_run_start with the same idempotencyKey in ${Math.round(delay / 1000)}s (${Math.round(remaining / 1000)}s of --wait-ms left).
+`, ctx);
+      await sleep2(delay);
+    }
+  }
+}
+
 // src/commands.ts
 init_errors();
 
@@ -18041,7 +18107,7 @@ var KNOWN_MISREACHES = [
   {
     tried: "search",
     use: "recall <query>",
-    why: "recall searches what was said; `quick search <name>` jumps to a place or person by name"
+    why: 'recall searches what was said; `tree --query "360training / Delivery & Reviews"` jumps to a known name'
   },
   { tried: "update topic", use: "topic update --topic-id top_…", why: "this command is noun-verb" },
   { tried: "update space", use: "space update --space-id spc_…", why: "this command is noun-verb" },
@@ -18165,7 +18231,7 @@ Aliases: ${aliases.map((alias) => `\`arbor ${alias}\``).join(", ")} (tool-name f
   const heading = `${commandWords(action)}${aliases.length === 1 ? ` (alias: ${aliases[0]})` : aliases.length > 1 ? ` (aliases: ${aliases.join(", ")})` : ""}`;
   const waitLines = action.name === "computer_exec" ? [
     "  --no-wait [<boolean>]  [optional] — return a running processId immediately instead of polling computer_process_read (implied by --background); mutually exclusive with --wait-for-terminal-ms"
-  ] : [];
+  ] : action.name === "computer_run_start" ? [`  --wait-ms <number>  [optional] — ${WAIT_MS_DESCRIPTION}`] : [];
   const notes = action.cliHelpNotes ? `
 
 ${action.cliHelpNotes}` : "";
@@ -18178,9 +18244,10 @@ ${lines.join(`
 `)}${primaryNote}${explicitNote}${aliasNote}${notes}
 `;
   }
+  const waitUsage = action.name === "computer_exec" ? " [--no-wait]" : action.name === "computer_run_start" ? " [--wait-ms <number>]" : "";
   return `${heading} — ${action.description}
 
-${usage}${waitLines.length > 0 ? " [--no-wait]" : ""}
+${usage}${waitUsage}
 
 ${[...lines, ...waitLines].join(`
 `)}${primaryNote}${explicitNote}${aliasNote}${notes}
@@ -18207,6 +18274,15 @@ function commandCatalog(actions = CLI_ACTIONS) {
           acceptsFile: false,
           description: "return a running processId immediately instead of polling computer_process_read; mutually exclusive with --wait-for-terminal-ms"
         }
+      ] : [],
+      ...action.name === "computer_run_start" ? [
+        {
+          flag: "wait-ms",
+          kind: "number",
+          required: false,
+          acceptsFile: false,
+          description: WAIT_MS_DESCRIPTION
+        }
       ] : []
     ]
   }));
@@ -18250,6 +18326,20 @@ function resolveCommand(positionals, flags) {
   const bareFeedbackTree = normalized.length === 1 && normalized[0] === "feedback" && !explicitFeedbackInput;
   return bareFeedbackTree ? { action: CLI_ACTIONS.find((action) => action.name === "feedback_tree"), words: 1 } : matchCommand(positionals);
 }
+var WAIT_MS_DESCRIPTION = "CLI-only: while Arbor answers that Computer setup is still running (retryable, suggestedAction computer_run_start), wait each retryAfterMs and repeat this exact start with the same idempotencyKey for up to this many milliseconds; a terminal setup failure or any other error returns at once. Omit for one attempt";
+function parseWaitMs(value) {
+  const raw = stringFlag(value, "wait-ms");
+  if (raw === undefined)
+    return;
+  const ms = Number(raw);
+  if (!Number.isInteger(ms) || ms < 0) {
+    throw new UsageError(`--wait-ms expects a non-negative whole number of milliseconds, got "${raw}"`, {
+      reason: "validation.invalid_value",
+      field: "waitMs"
+    });
+  }
+  return ms;
+}
 async function runObjectVerb(positionals, flags, ctx) {
   const match = resolveCommand(positionals, flags);
   if (!match) {
@@ -18260,6 +18350,8 @@ async function runObjectVerb(positionals, flags, ctx) {
   const action = { ...match.action, inputSchema: canonicalInputShape(match.action) };
   applyPositionals(action, positionals.slice(words), flags);
   const accepted = acceptedFlags(action.inputSchema);
+  if (action.name === "computer_run_start")
+    accepted.add("wait-ms");
   const unknown = Object.keys(flags).filter((f) => !accepted.has(f) && !RESERVED_FLAGS.has(f));
   if (unknown.length > 0) {
     const hints = unknown.map((f) => listFileHint(action, f)).filter(Boolean);
@@ -18289,6 +18381,7 @@ async function runObjectVerb(positionals, flags, ctx) {
       field: "waitForTerminalMs"
     });
   }
+  const waitMs = action.name === "computer_run_start" ? parseWaitMs(flags["wait-ms"]) : undefined;
   if (action.name === "app_request" && input.json !== undefined) {
     if (input.body !== undefined) {
       throw new UsageError("--json and --body are mutually exclusive", {
@@ -18309,7 +18402,7 @@ async function runObjectVerb(positionals, flags, ctx) {
     advise(`Agent registered. Save its apiKey now — it is shown only once:
 `, ctx);
   }
-  let value = action.name === "attachment_upload" ? await uploadLocalAttachments(httpExecutor, input) : await action.run(httpExecutor, input);
+  let value = action.name === "attachment_upload" ? await uploadLocalAttachments(httpExecutor, input) : waitMs !== undefined ? await startComputerRunWithWait(action, httpExecutor, input, waitMs, ctx) : 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);
   }
@@ -18322,7 +18415,7 @@ init_config();
 // src/connect.ts
 init_config();
 var DEFAULT_POLL_INTERVAL_MS = 2000;
-var sleep2 = (ms) => new Promise((r) => globalThis.setTimeout(r, ms));
+var sleep3 = (ms) => new Promise((r) => globalThis.setTimeout(r, ms));
 function bareConnectUrl(apiUrl, returnedUrl) {
   const fallback = `${apiUrl.replace(/\/$/, "")}/connect`;
   if (!returnedUrl)
@@ -18380,7 +18473,7 @@ async function connect2(opts) {
       if (typeof globalThis.setTimeout !== "function") {
         throw new Error("approval pending — approve it, then rerun the same `arbor connect` command to finish saving this agent's credential");
       }
-      await sleep2(pollIntervalMs);
+      await sleep3(pollIntervalMs);
       continue;
     }
     if (tok.status === "expired")
@@ -18400,7 +18493,7 @@ init_errors();
 init_config();
 var CLIENT_ID = "arbor-cli";
 var GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
-var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep4 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function login(opts) {
   const apiUrl = opts.url ?? loadConfig().apiUrl;
   const codeRes = await fetch(`${apiUrl}/api/auth/device/code`, {
@@ -18425,7 +18518,7 @@ async function login(opts) {
   for (;; ) {
     if (Date.now() > deadline)
       throw new Error("login timed out — run `arbor login` again");
-    await sleep3(interval);
+    await sleep4(interval);
     const tokRes = await fetch(`${apiUrl}/api/auth/device/token`, {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -18545,7 +18638,7 @@ function renderVersion(ctx) {
 }
 var HELP = `arbor — the Arbor CLI: people and agents deliberate on typed work, and Arbor remembers
 what's settled. Your token (env ARBOR_TOKEN, or \`arbor auth\`) resolves who you act AS — the CLI
-never asserts it. Run \`arbor whoami\` to confirm, \`arbor tree\` to map the workspace.
+never asserts it. Run \`arbor whoami\` to confirm, \`arbor tree --query "360training / Delivery & Reviews"\` to jump to a known place, \`arbor tree\` to map the workspace, \`arbor recall\` for content.
 
 ${ORIENTATION}
 

package/package.json

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