@lambdacurry/arbor 0.20.14 → 0.20.15

package/dist/arbor.js

@@ -18424,7 +18424,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_open",
     title: "Open a Thread computer",
-    description: "Open or resume this Thread's project environment for filesystem or command work. A safe living-profile revision drift is reconciled automatically by replacing the generation, restoring supported state, and returning reconciliation metadata; structural recipe changes still fail explicitly with computer_reprovision as the suggested action. Every configured repository is re-authorized through its explicit GitHub connection; a fresh reusable base clones it with a request-scoped contents:read credential before strict setup runs, while a restore receives no credential. Returns computerSessionId — pass it unchanged to later Computer tools and cited work — plus a compact Agent Brief with Thread objective, scoped Space/Topic guidance and provenance, durable parent snapshot, repositories, explicit unchecked remote-freshness guidance, and active Runs; the selected profile contract; a resolved capabilities card; workspaceRoot; each materialized repositories[].path; and defaultCwd. Omitted computer_exec.cwd uses defaultCwd: the single checkout when exactly one repository is configured, workspaceRoot otherwise.",
+    description: "Open or resume a Thread's project environment when you need filesystem, command, Run, checkpoint, Preview, or publication work. Returns the session handle, workspace/repositories/default cwd, Agent Brief, profile/capabilities, active Runs, and any reconciliation notice.",
     inputSchema: {
       threadId: exports_external.string().describe("the Arbor Thread whose stable computer to open, thr_…"),
       vcpus: exports_external.number().int().min(1).max(4).optional().describe("optional container vCPU request"),
@@ -18437,7 +18437,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_reprovision",
     title: "Replace a Thread computer",
-    description: "DESTRUCTIVE RECOVERY: explicitly replace an incompatible active Computer generation from the Thread's effective recipe. This one recovery action is also available on the normal Arbor MCP so a structurally stale Computer can be replaced before Computer MCP attachment is possible. The old generation remains authoritative unless the successor restores supported state and passes health. Same-provider worker-shell→container migration is supported; container→worker-shell and cross-provider migration fail explicitly. Reuse one idempotencyKey only for the same replacement request.",
+    description: "DESTRUCTIVE RECOVERY: Replace an incompatible active Computer generation from the Thread's effective recipe when Arbor reports structural recipe incompatibility. Preserves the old generation unless the successor restores supported state and passes health.",
     inputSchema: {
       threadId: exports_external.string().describe("the Thread whose active Computer generation is replaced, thr_…"),
       idempotencyKey: exports_external.string().min(1).max(200).describe("stable key for this ONE replacement request; reuse it unchanged for retries"),
@@ -18450,7 +18450,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_start",
     title: "Start a run",
-    description: "Start one unit of work inside an opened Thread computer. Write Runs default to isolated execution restored from the Computer's current base snapshot, so independent work does not collide. For intentional live collaboration, pass execution='shared' and the Run works directly in the Thread Computer alongside other shared Runs. Read Runs always share. All placements present the same /workspace layout; pass runId to Run-aware Computer operations and Arbor routes them correctly. An isolated WRITE Run does not mutate the parent Computer, its provider environment is disposable, and finish destroys that environment. The start result states those durability facts and returns the inherited scoped guidance; follow any durability-first project guidance before broad validation. Git publication remains unknown until Arbor can prove a clean changed HEAD exists on the configured remote; a local commit, isolated filesystem, or Preview is not that proof. This creates no second Thread or durable Computer.",
+    description: "Start one bounded unit of work inside an opened Thread Computer when you need a read or write Run. Returns runId plus placement, base Git/snapshot state, durability facts, and inherited guidance; write Runs default to isolated unless execution='shared' is chosen.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       mode: exports_external.enum(["read", "write"]).describe("write for mutable work; read for shared inspection"),
@@ -18464,7 +18464,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_repo_work_status",
     title: "Inspect repository finish state",
-    description: "READ ONLY: resolve repository-finish state for an active isolated WRITE Run from authoritative Git remote proof plus GitHub PR, CI, and review reads; the bounded inspection uses three batched provider exec phases and at most four GitHub REST calls per eligible repository. It reports durable state, explicit push/PR retrySafety, known PR-head mismatches versus unavailable GitHub proof, the next action, and Run finishability; it never commits, pushes, creates a PR, merges, or deploys.",
+    description: "READ ONLY: Inspect an active isolated WRITE Run before a push/PR retry or finish when Git publication, PR, CI, or review state matters. Returns authoritative durability/finishability, retry safety, mismatches, and the next repository action without mutating GitHub.",
     inputSchema: {
       runId: exports_external.string().describe("the active isolated WRITE Run to inspect, run_…")
     },
@@ -18475,7 +18475,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_finish",
     title: "Finish a run",
-    description: "Close a Run with its terminal outcome and the one line that explains it. Before destroying an isolated WRITE environment, Arbor inspects bounded Git state: newly dirty work or a live remote check proving the new HEAD is absent blocks ordinary finish. Publication uncertainty remains explicitly unknown. Pass discard=true only when intentionally destroying work Arbor proved non-durable. Repeating the same outcome is a safe no-op, and the terminal receipt preserves the durability assessment.",
+    description: "Finish a Run with an explicit terminal outcome after its work is complete or intentionally abandoned. Ordinary finish succeeds unless Arbor proves isolated WRITE work non-durable; use discard=true only to intentionally destroy that proven non-durable work; publication can remain unknown, repeating the same outcome is a safe no-op, and the receipt preserves the durability assessment.",
     inputSchema: {
       runId: exports_external.string().describe("the runId returned by computer_run_start, run_…"),
       outcome: exports_external.enum(["finished", "failed", "cancelled"]).optional().describe("terminal outcome; defaults to finished"),
@@ -18489,7 +18489,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_run_receipt",
     title: "Read a run receipt",
-    description: "READ ONLY: read one run's compact receipt — its purpose, actor, computer session, base snapshot and starting Git projection, explicit isolation/durability contract, pre-teardown durability assessment when available (including publication that remains unknown unless proven), durable operation receipts with stable state/reason/retry-safety, meaningful activity, and terminal outcome. Foreground and background work may appear as distilled process identities/labels/outcomes, but Arbor keeps no raw command transcript or process output. The receipt stays readable after the Run is terminal.",
+    description: "READ ONLY: Inspect one Run's durable receipt during or after execution when you need purpose, placement, durability, recoverable operation state, activity, or terminal outcome. Returns compact Run history and assessments, including durable operation receipts, not raw command transcripts or process output.",
     inputSchema: {
       runId: exports_external.string().describe("the run to read, run_… (from computer_run_start or computer_runs)")
     },
@@ -18500,7 +18500,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_runs",
     title: "List runs",
-    description: "READ ONLY: list the active and recent runs of this Thread computer with each run's mode, execution placement, and workspace identity. Use it to see what other work is in flight on the same computer before starting or finishing your own.",
+    description: "READ ONLY: List active or recent Runs for this Thread Computer when deciding whether to resume existing work or start another unit. Returns each Run's mode, execution placement, workspace identity, and lifecycle status.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       status: exports_external.enum(["active", "finished", "failed", "cancelled"]).optional().describe("filter to one lifecycle status"),
@@ -18513,12 +18513,12 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_exec",
     title: "Run a command",
-    description: "Run one bounded logical operation in an opened Thread computer. Omitting cwd uses the environment's defaultCwd; pass cwd explicitly to override it. Pass runId to route the command according to that Run's execution placement; without runId the command executes in the parent Computer. Strict Bash semantics are ON by default. For explicit asynchronous work, background=true returns a processId immediately. On an isolated container Run, foreground exec also establishes a durable operation/process identity before Arbor waits; a missed foreground response can be recovered from computer_run_receipt.operations and computer_process_read without repeating the mutation. For a labeled run-scoped verification check, pass activityKind=verification so the terminal exit becomes a distilled verification outcome. For a connected human, Arbor supplies ambient GitHub authorization and Git identity ephemerally without writing credentials into the workspace. Provider-owned processes stay in the environment where they were started.",
+    description: "Run one bounded shell operation in the parent Computer or a Run; connected humans receive ambient GitHub authorization and Git identity without workspace credentials. Background work returns a processId, and a missed isolated-Run foreground response can be recovered from computer_run_receipt.operations with computer_process_read instead of repeating the mutation.",
     inputSchema: {
       computerSessionId: exports_external.string().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
       command: exports_external.string().min(1).describe("the shell command to run"),
       runId: exports_external.string().optional().describe("route this command according to this Run execution placement, run_… (from computer_run_start)"),
-      cwd: exports_external.string().optional().describe("working directory under /workspace, or under the run"),
+      cwd: exports_external.string().optional().describe("working directory under /workspace, or under the run; omit to use defaultCwd"),
       timeout: exports_external.number().int().min(1000).max(1800000).optional().describe("timeout in milliseconds, from 1,000 through 1,800,000"),
       background: exports_external.boolean().optional().describe("start a container process and return its pid"),
       activityLabel: exports_external.string().min(1).max(COMPUTER_RUN_ACTIVITY_LABEL_MAX).optional().describe("short human-readable label for run-scoped background work; Arbor records this label instead of the raw command or output"),
@@ -18532,7 +18532,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_process_read",
     title: "Read a background process",
-    description: "READ ONLY: Read one provider-owned process from computer_exec, including a recoverable foreground operation discovered through computer_run_receipt.operations. With no cursor, returns only the latest small output window; pass nextCursor on the next read to receive only newer output. Defaults to 4 KB total and allows an explicit larger read up to 64 KB. Returns the existing compact activity receipt that distinguishes fresh output, active CPU work, quiet running, terminal state, and unavailable telemetry without exposing raw process tables. For a known foreground recovery handle whose provider state cannot be observed, returns structured recovery state/reason/retry-safety instead of guessing. Once terminal, also returns the final exit result.",
+    description: "READ ONLY: Read a provider-owned process from computer_exec, including a foreground operation recovered from a Run receipt, and use nextCursor for incremental output. Returns compact activity or recovery state plus the final exit result when observable.",
     inputSchema: {
       computerSessionId: exports_external.string().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
       runId: exports_external.string().optional().describe("the Run that owns this process, if it was started inside a Run"),
@@ -18547,7 +18547,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_process_terminate",
     title: "Terminate a background process",
-    description: "Terminate one process returned by computer_exec(background=true), including its provider-owned process tree. Returns the observed terminal state so ChatGPT can stop long verification explicitly without shell PIDs or ps/kill workarounds.",
+    description: "Terminate a background process started by computer_exec when it should no longer run. Stops the provider-owned process tree and returns the observed terminal state without requiring shell PIDs or ps/kill.",
     inputSchema: {
       computerSessionId: exports_external.string().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
       runId: exports_external.string().optional().describe("the Run that owns this process, if it was started inside a Run"),
@@ -18560,7 +18560,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_status",
     title: "Inspect a computer",
-    description: "READ ONLY: Read what this computer can do right now — the same resolved capabilities card computer_open returns, each entry ready or available — plus live Currybox process/runtime status and the declared container profile contract. Reach for it when you are unsure whether a capability — background processes, semantic code intelligence, Preview publication — is usable on this session. This cannot modify files, processes, checkpoints, or Thread state; use get_computer on the Arbor surface for durable config and snapshot lineage.",
+    description: "READ ONLY: Inspect live Computer capabilities, runtime/process state, and the declared profile when computer_open did not answer a current operational question. Use get_computer instead for durable recipe, generation, and snapshot lineage.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…")
     },
@@ -18571,7 +18571,7 @@ var ACTION_DEFINITIONS = [
   {
     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, 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.",
+    description: "Capture a 1280×720 screenshot of one public HTTPS URL as Thread evidence without opening the project runtime. Returns capture metadata plus ready-to-place attachments[].markdown; put that Markdown exactly where the image belongs and bind the matching attachmentIds, while localhost and authenticated pages remain unavailable and the capture 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")
@@ -18583,7 +18583,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "code_symbols",
     title: "Outline a file's symbols",
-    description: "Outline the symbols a file or directory defines, resolved by the project's language server. Reach for this before reading a large unfamiliar file — unlike a grep through `computer_exec`, it returns the real declarations with their kinds rather than every textual match. Needs the semantic-code capability shown on the computer_status card.",
+    description: "READ ONLY: Outline real declarations in a file or directory when you need structure without reading or searching the whole source. Uses the language server to return symbols and kinds, distinguishing declarations from textual matches.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       runId: exports_external.string().optional().describe("route this semantic read according to this Run execution placement, run_…"),
@@ -18596,7 +18596,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "code_find_symbol",
     title: "Find a symbol by name path",
-    description: "Locate a declaration by its name path (`ClassName/methodName`) and optionally return its body. Use it instead of a `computer_exec` grep when you want THE definition rather than every line mentioning the name; the language server distinguishes the declaration from its call sites and its string occurrences. Needs the semantic-code capability shown on the computer_status card.",
+    description: "READ ONLY: Locate a declaration by name path when you need the definition rather than text matches. Uses the language server and can include the symbol body and bounded child depth.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       runId: exports_external.string().optional().describe("route this semantic read according to this Run execution placement, run_…"),
@@ -18612,7 +18612,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "code_references",
     title: "Find what references a symbol",
-    description: 'List the places that actually reference a symbol, each with a short snippet. This is the operation `computer_exec` cannot do: a text search finds the same identifier in comments, unrelated modules, and shadowed scopes, while the language server resolves real references — so it answers "is this safe to change". Needs the semantic-code capability shown on the computer_status card.',
+    description: "READ ONLY: Find semantic references to a declaration when you need to know what actually depends on it before a change. Uses the language server to return resolved references with snippets, excluding unrelated textual matches.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       runId: exports_external.string().optional().describe("route this semantic read according to this Run execution placement, run_…"),
@@ -18626,7 +18626,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "code_implementations",
     title: "Find implementations of a symbol",
-    description: "List the concrete implementations or subtypes of an interface, abstract type, or method. A `computer_exec` search cannot follow a type relationship — only the language server knows which declarations satisfy this one. Needs the semantic-code capability shown on the computer_status card.",
+    description: "READ ONLY: Find concrete implementations or subtypes of an interface, abstract type, or method. Uses the language server to resolve type relationships that text search cannot follow.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       runId: exports_external.string().optional().describe("route this semantic read according to this Run execution placement, run_…"),
@@ -18640,7 +18640,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "code_diagnostics",
     title: "Read language-server diagnostics for a file",
-    description: "Return the language server's live errors and warnings for one file, mapped to symbols. Reach for it on a file you just edited: it answers in seconds without the whole-project build a `computer_exec` typecheck runs, though a green result here is not a substitute for that build. Needs the semantic-code capability shown on the computer_status card.",
+    description: "READ ONLY: Check live language-server errors and warnings for one file, especially after an edit. Returns diagnostics mapped to symbols for fast local feedback; it does not replace a whole-project build or typecheck.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       runId: exports_external.string().optional().describe("route this semantic read according to this Run execution placement, run_…"),
@@ -18653,7 +18653,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_export",
     title: "Export a Thread file",
-    description: "Move one bounded image, MP4/WebM video, or supported file from an opened Computer or Run into a durable Thread Attachment. Pass runId to export the exact files visible to that Run execution placement. Describe what it shows so the returned attachments[].markdown has meaningful image alt text or a video/file label; put that Markdown where the media belongs and bind those ids when contributing or responding. Supply one stable idempotencyKey per logical export: safe retries return the original Attachment, while reusing the key for another path or description conflicts.",
+    description: "Export one bounded file from the parent Computer or a Run into a durable Thread Attachment when the file itself is evidence. Returns attachment ids and ready-to-place attachments[].markdown; put that Markdown exactly where the media belongs and bind the matching ids, while idempotencyKey controls safe retry identity.",
     inputSchema: {
       computerSessionId: exports_external.string().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
       runId: exports_external.string().optional().describe("route this export according to this Run execution placement, run_…"),
@@ -18668,7 +18668,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_write",
     title: "Write a project file",
-    description: "Write one file under /workspace. Content is UTF-8 by default; pass encoding=base64 only for binary bytes. Pass runId to route the write according to that Run: isolated Runs target their Sandbox, shared Runs target the live parent Computer. Without runId the write targets the parent Computer. Prefer normal editing tools for code changes; reach for this when the MCP/CLI computer surface is the only filesystem path.",
+    description: "Write or replace one file in the parent Computer or a Run when the Computer surface is your filesystem editing path. Routes by runId when supplied and supports UTF-8 or explicit base64 bytes.",
     inputSchema: {
       computerSessionId: exports_external.string().optional().describe("the computerSessionId returned by computer_open, cms_…; required unless runId is supplied"),
       path: exports_external.string().describe("absolute path under /workspace, or a path inside the run"),
@@ -18683,7 +18683,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_checkpoint",
     title: "Checkpoint completed work",
-    description: "Save the live parent Thread Computer into durable Thread lineage. This is intentionally not Run-scoped: isolated Run publication/integration is a separate contract. If your work is in an isolated Run, do not call this expecting it to save that fork; publish the work through its repository workflow first. A running background process may still be writing the workspace, so checkpointing refuses until it is finished or explicitly terminated; use computer_status to inspect active processes. For the final unit, call computer_stop instead; it performs the final checkpoint before teardown. No checkpoint is needed for computer_verify alone because remote visual capture starts no project runtime.",
+    description: "Checkpoint a completed unit from the live parent Thread Computer into durable Thread lineage when more parent work will follow. It is not Run-scoped; isolated Run work must be made durable through its repository workflow, and running background processes can block the checkpoint.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…")
     },
@@ -18694,7 +18694,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_publish_preview",
     title: "Publish an immutable static Preview",
-    description: "Publish one checked HTML file or bounded static build directory as a private immutable Preview. Parent publication uses computerSessionId, checkpoints the source into Thread lineage, then publishes it. Isolated Run publication uses runId, freezes that Run's exact static bytes without checkpointing, adopting the Run, or advancing parent lineage, and remains durable after the Run is destroyed. The returned arborthreads.dev URL survives teardown; put it on its own line to show the interactive Preview card. A directory must contain index.html, use relative local asset URLs, and cannot include dotfiles, source maps, secrets, symlinks, or server code. Supply one stable idempotencyKey per logical publication: safe retries return the original immutable URL, while reusing the key for another path/title or Run fork conflicts.",
+    description: "Publish one checked HTML file or bounded static directory as a private immutable Preview for review. Parent publication checkpoints first; isolated Run publication freezes that Run's bytes without adopting it, and the returned arborthreads.dev URL survives teardown.",
     inputSchema: {
       computerSessionId: exports_external.string().optional().describe("the computerSessionId returned by computer_open, cms_…; required for parent publication, optional when runId is supplied"),
       runId: exports_external.string().optional().describe("active isolated write Run whose static workspace bytes should be published as review output"),
@@ -18709,7 +18709,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_publish_app_bundle",
     title: "Publish an immutable AppBundle",
-    description: "From the live parent Thread Computer, after a Bun container build is green, verify that entryPath bytes exactly match the referenced ArtifactVersion, then capture source hashes plus Git/workspace provenance, then freeze the Worker module and optional static assets into a content-addressed AppBundle. A mismatch is rejected; dirty or untracked source is allowed but returned as an explicit warning. Use the returned bundleId with app_deploy; retries require the same idempotencyKey. AppBundle publication remains intentionally parent-only; an isolated Run Preview is review output and does not adopt the Run.",
+    description: "Publish a content-addressed AppBundle from the live parent Computer after a green build when an ArtifactVersion is ready for app deployment. Verifies entry bytes against the ArtifactVersion, captures source/Git provenance and static assets, and returns bundleId; isolated Runs are not accepted.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…"),
       artifactVersionId: exports_external.string().describe("the source ArtifactVersion, artv_…"),
@@ -18731,7 +18731,7 @@ var ACTION_DEFINITIONS = [
   {
     name: "computer_stop",
     title: "Checkpoint and stop",
-    description: "Finish an opened computer after a unit of work. Currybox checkpoints and Arbor publishes before teardown; any durability failure refuses the stop instead of silently discarding state. A running background process also refuses the checkpoint; use computer_status to inspect it and computer_process_terminate when it should be stopped.",
+    description: "Checkpoint and stop an opened parent Computer after the final unit of work. Teardown is refused if checkpoint durability fails or a background process is still running, so state is not silently discarded.",
     inputSchema: {
       computerSessionId: exports_external.string().describe("the computerSessionId returned by computer_open, cms_…")
     },

package/package.json

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