@shardflux/sdk 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -3,7 +3,111 @@
 Every API the README shows is available from the version named here. Below 1.0, a minor release may break
 compatibility; breaking changes are marked **Breaking**.
 
-## 0.6.1 (not yet published; npm `latest` is 0.6.0)
+## 0.7.0 (not yet published; npm `latest` is 0.6.2)
+
+Needs an API with the template editor (contracts §24); every new field is additive and older fields are unchanged.
+
+### Template editor: build a template from template.yaml
+
+- `templates.buildFromFile(path, { templateSlug, autoPublish?, description?, displayName?, acknowledgedScanFindings?,
+  organizationId?, wait?, onProgress?, root?, parseYaml? })` (Node only): reads template.yaml (or a `.json` file with
+  the same document), uploads each local `from` path of `build.files` (folders packed as a reproducible tar, files as
+  they are; each distinct path once; bytes the organization already has are not sent), creates the recipe v2 build and
+  with `wait` follows it. Returns `{ build, recipe, uploads }`. Progress events: `pack`, `upload`, `build`.
+  `templates.buildFromRecipe(doc, { baseDir, ... })` does the same for a document in memory.
+- YAML is read with the optional peer dependency `yaml` (`npm install yaml`) or `parseYaml`; JSON needs nothing. The
+  SDK keeps no runtime dependencies, and the Node-only code is loaded with dynamic imports, so browser bundles are
+  unaffected.
+- The folder tar is byte-identical to the Python SDK's (`shardflux` 0.3.0) for the same folder: members sorted by UTF-8
+  path, mtime 0, uid/gid 0 without names, permission bits kept, symlinks as symlinks, pax records for long or
+  non-ASCII names. Absolute or escaping symlinks, devices, FIFOs and sockets are refused before any request, as the
+  build host would.
+- `TemplateFileError` (a file that cannot be read, parsed or packed; nothing was sent) and `TemplateUploadError` (the
+  storage refused a PUT: `status`, `code` such as `BadDigest`; never the presigned URL). Exported: `packDirectory`,
+  `readTemplateFile`, `parseTemplateText`, the tar writer (`tarHeader`, `tarPadding`, `tarEnd`).
+
+### Template editor: the API surface (contracts §24.6)
+
+- `templates.uploads.request({ sha256, size, kind })`, `templates.uploads.put(bytes | Blob | stream, { kind, sha256?,
+  size? })` (PUT with exactly the presigned headers, skipped when the organization has the bytes, confirmed after) and
+  `templates.uploads.putPath(path)` (Node).
+- `templates.builds.create()` takes recipe v2 (`TemplateRecipeV2`), `description` and `acknowledgedScanFindings`.
+  `TemplateBuild.denied_hosts`. **Breaking (types only):** `TemplateBuild.recipe` is `{dockerfile}` or the stored
+  recipe v2 (`TemplateBuildRecipeV2`); narrow with `'dockerfile' in build.recipe` before reading `dockerfile`.
+  `waitForBuild()` takes `onChange`.
+- `templates.versions.recipe(slug, version)`: the recipe and settings a version was built from, ready to build again.
+- `templates.versionTestInstances.create(slug, version, { inputs?, key?, caps?, ... })`: a session workspace on a
+  registered version, published or not.
+- `templates.languages(base)`: the languages and versions a base offers `build.languages` (`included` when the base
+  already has one).
+- `templates.packages.search(ecosystem, query, { base?, limit? })` and `templates.packages.get(ecosystem, name)`.
+- `workspaces.open({ inputs })`, `workspace.inputs()` / `workspaces.inputs(id)`, `workspace.startup` (start commands
+  and services: pending, running, ready or failed with the step, exit code and output tail).
+- Drafts: `create({ displayName, inputs })`, `openTestInstance({ inputs })`, `publish({ settings })`;
+  `saveAsTemplate({ settings })`.
+- Views: `TemplateVersion.settings`, `TemplateSummary.category` / `TemplateDetail.category`,
+  `WorkspaceEgressPolicy.template_egress` and `effective_policy`. Types: `TemplateSettings`, `TemplateSettingsInput`,
+  `TemplateInput`, `TemplateStartCommand`, `TemplateService`, `TemplateEgressDefault`, `TemplateUpload*`,
+  `TemplateVersionRecipe`, `TemplateLanguages`, `TemplatePackage*`, `WorkspaceStartup`, `WorkspaceInputs`.
+- Error reasons: `invalid_recipe`, `base_not_layered`, `language_unavailable`, `language_conflict`, `upload_required`,
+  `upload_missing`, `upload_digest_mismatch`, `upload_too_large`, `invalid_settings`, `services_unsupported`,
+  `input_required`, `input_unknown`, `input_invalid`, `egress_widening`, `package_index_unavailable` and the operation
+  error `startup_failed` (`KnownErrorReason`).
+
+### Tool-call capture
+
+`workspace.captureToolCalls(options)` saves the tool calls of your own agent harness (web search, SQL, HTTP APIs, MCP
+servers) into the workspace: each call's input and full output become files under `/home/user/tool-calls/<run>/`
+with a JSON-lines index, so the agent can compute on them with code and snapshots and forks keep them. The format is
+docs/decisions/0006-tool-call-capture.md (shared with the Python SDK 0.3.0).
+
+- Invisible: a wrapped tool returns the same value, the same promise object and the same thrown error; a synchronous
+  tool stays synchronous; capture never throws into the harness (failures go to `onError` and `capture.stats`).
+  Serialization runs in `setImmediate`, writes in the background (4 in parallel, index lines batched every 50 ms).
+- Explicit capture: `capture.record(call)`, `capture.run(toolCall, fn)` (Anthropic `tool_use`, Responses
+  `function_call`, Chat `tool_calls`, `{ name, input }`), `capture.wrap(name, fn)` (async generators pass through and
+  are stored as `.jsonl`), `capture.tools(toolsObjOrArray)`, and `captureTool(name, fn)` with `capture.activate(fn)`
+  for tools defined at import time.
+- Adapters (structural types, no dependency): `capture.aiSdk.tools()` / `.callbacks()` (Vercel AI SDK 7, streaming
+  tools included), `capture.mastra.hooks()` / `.tools()`, `capture.anthropic.tools()` (tool runner),
+  `capture.openaiAgents.tools()` / `.execute()` / `.attach(runner | agent)`, `capture.claude.hooks()` (Claude Agent
+  SDK, with a PreToolUse barrier for `mcp__shardflux__` tools), `capture.langchain.handler()`, `capture.mcp.instrument()`.
+- Selection: explicit capture always records; hook-level adapters apply `include` / `exclude`. Call ids are
+  deduplicated (last 10 000), so a wrapper and a hook can be combined.
+- Output encoding: JSON, text, HTML, bytes by magic number (PNG, JPEG, GIF, WebP, PDF, ZIP, gzip, Parquet), MCP results
+  and content blocks as a directory of parts; limits `maxOutputBytes` (32 MiB, text cut as `.part`),
+  `maxInlineInputBytes` (64 KiB), `maxPendingBytes` (128 MiB of files, index lines and inline inputs, then
+  `dropped: "queue_full"` with a small line), `maxPendingCalls` (10 000; past it a call is not recorded and `onError`
+  says so); `transform` for redaction (fails closed); streams are never read; out-of-range timestamps are recorded as
+  `started_at: null`. A wrapped async tool's promise is marked handled (no `unhandledRejection` if nobody awaits it).
+- Read-your-writes: calls through the same client (exec and files through `workspace.cell()`, `workspaceTools`,
+  snapshot, fork, suspend, saveAsTemplate, close; also `cloud.workspaces.*(id)`) wait for capture writes recorded
+  before them, bounded by `settleTimeoutMs` (30 s). Lifecycle timing shows the wait as a new `capture_flush` phase.
+  `delete` and `reset` drop pending writes. Writes wake a suspended workspace (`wake: null` opts out).
+- `capture.flush()` / `capture.close()` never reject (`{ complete, written, failed, dropped }`); `capture.promptHint()`
+  returns a paragraph for your system prompt.
+- `executeToolCall()` passes the call's `id` / `call_id` to `execute` as `toolCallId`, and `WorkspaceTool.execute`'s
+  options accept it.
+- **Breaking (types only):** `LifecyclePhase` gains `capture_flush`; an exhaustive `switch` over phases without a
+  `default` case needs the new member.
+
+## 0.6.2 (2026-09-28)
+
+### Starts that wait for capacity end
+
+The API no longer lets a start (open, resume, restore, fork) wait in `capacity_pending` forever. One that no host
+could admit 15 minutes after it was created fails with `capacity_unavailable` and `retryable: true`: nothing was
+started, the concurrency slot is released, and a suspended workspace stays suspended with its state. Before, a VM could
+boot (and bill) long after every wait had given up.
+
+- `OperationFailedError.retryable`: the operation error's `retryable` flag (`false` when absent). `true` for
+  `capacity_unavailable` (retry later), `false` for a definitive failure. The SDK does not retry it itself.
+- `OperationTimeoutError.deadlineAt`: when a wait gives up while the start is still `capacity_pending`, the time it
+  stops waiting for a host (`error.details.deadline_at`); the message says so. Null in other states.
+- `onProgress`: a `capacity_pending` `phase` event carries `deadlineAt` when the API reports it.
+- Docs: waits no longer say a pending start continues indefinitely.
+
+## 0.6.1 (2026-09-28)
 
 - `formatTiming()` joined two phases that followed each other with `∥` (ran together) when their 0.1 ms times summed
   with a floating-point error (1000.2 + 300.1 > 1300.3); it now prints `→`.

package/README.md

@@ -4,16 +4,18 @@ TypeScript SDK for [Shardflux](https://shardflux.dev): cloud computers for AI ag
 
 Open a persistent workspace by key, run commands and move files in it, suspend it when idle, resume
 it later with its disk and memory intact, and fork it. Hand your agent framework-neutral workspace
-tools (exec, files, processes, PTY, git, browser) that plug into any model provider.
+tools (exec, files, processes, PTY, git, browser) that plug into any model provider, and save your harness's own
+tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 
 > **Early access.** Shardflux is in early access. The API is versioned (`/v1`), but this SDK is
 > below 1.0: a minor release may contain breaking changes (see [Compatibility](#compatibility)).
 
-> **Versions.** This README describes 0.6.1. Anything marked **(0.6.0+)** is not in 0.5.0;
-> [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
+> **Versions.** This README describes 0.7.0. Anything marked **(0.7.0+)** is not in 0.6.x and **(0.6.0+)** not in
+> 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
-- ESM only, no runtime dependencies, Node.js 24 or later.
+- ESM only, no runtime dependencies, Node.js 24 or later. Reading a YAML template file uses the optional peer
+  dependency `yaml` (`npm install yaml`); JSON template files need nothing.
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
 
@@ -127,6 +129,23 @@ means depends on `wait`:
 wait again with `cloud.workspaces.waitForOperation(err.operationId)`. Without `wait`, the returned operation is the
 handle for the work in progress: pass its `id` to `waitForOperation()` when you need it finished.
 
+**A start waits for capacity for at most 15 minutes.** An open, resume, restore or fork that no host can admit yet
+waits in `capacity_pending`. Its `error.details.deadline_at` says when it gives up; the `phase` progress event carries
+it as `deadlineAt` **(0.6.2+)**, and so does `OperationTimeoutError` when your wait ends first. A start still pending
+at the deadline fails with `capacity_unavailable`: nothing was started, the concurrency slot is released, and a
+suspended workspace stays suspended with its state. `OperationFailedError.retryable` **(0.6.2+)** is `true` for it,
+so you can tell "retry later" from a definitive failure. The SDK does not retry it for you.
+
+```ts
+try {
+  await workspace.resume({ wait: true });
+} catch (err) {
+  if (err instanceof OperationFailedError && err.retryable) {
+    // err.errorCode === 'capacity_unavailable': no host had room; nothing changed. Try again later.
+  } else throw err;
+}
+```
+
 **Suspended workspaces wake on use.** A tool call on a suspended workspace resumes it (or joins the resume or open
 already running), then runs. A call made during a suspend or resume waits for the transition to finish. The call
 never runs twice: the cell executes nothing it refused.
@@ -148,9 +167,9 @@ await cell.exec.run(['make', 'test']);                         // resumes the wo
 the response until the operation changes (`Prefer: wait`, at most 20 s per request), so completion arrives within
 one round trip of the commit. Against an API without bounded waits (or with `serverWait: false`) it polls with
 backoff (250 ms doubling to 5 s, ±20 % jitter). If the timeout passes, it throws `OperationTimeoutError` and the
-operation keeps running server side; wait for it again with the same call. `templates.builds.waitForBuild()` waits
-the same way. A waited `open()` issues the first tool token together with the final workspace read, so the first
-tool call starts at once.
+operation keeps running server side (a start waiting for capacity until its `deadlineAt`); wait for it again with the
+same call. `templates.builds.waitForBuild()` waits the same way. A waited `open()` issues the first tool token
+together with the final workspace read, so the first tool call starts at once.
 
 On Node 26 the default fetch sends `Connection: close`: its bundled undici 8 can stall a request on a reused
 keep-alive connection for tens of seconds. Pass your own `fetch`, or set `SHARDFLUX_HTTP_KEEPALIVE=1`, to change that.
@@ -283,6 +302,80 @@ await draft.discard();                               // deletes the draft and en
 `states()`, `statesAll()` and `testInstances({ includeEnded })` list the draft's states and test instances. Only
 owners, admins and API keys with a tool permission may change drafts; others get 403 `template_dev_mode_role`.
 
+## Build a template from template.yaml (0.7.0+)
+
+A template is a recipe v2: a base, what the build adds (languages, apt/pip/npm packages, files, named build steps) and
+the settings a workspace gets when it opens (environment, open-time inputs, start commands, services, defaults).
+`template.yaml` is that document in YAML. A file entry may name a local `from` path (relative to the file): a folder is
+copied as a tar, a file as it is.
+
+```yaml
+# acme/template.yaml
+base: ubuntu-24.04@1
+build:
+  languages: [{ id: python }, { id: node, version: "22" }]
+  packages:
+    apt: [jq]
+    pip: { packages: [pandas==2.3.2], requirements: [/home/user/app/requirements.txt] }
+  files:
+    - { from: ./app, to: /home/user/app, owner: user }                 # a folder: uploaded as a tar
+    - { from: ./config/settings.toml, to: /home/user/.config/acme/settings.toml, owner: user, mode: "0600" }
+  steps:
+    - { name: install, run: npm ci, user: user, cwd: /home/user/app }
+settings:
+  env: { APP_ENV: development }
+  inputs:
+    PROJECT_NAME: { kind: text, required: true }
+    OPENAI_API_KEY: { kind: secret }                                  # a stored secret of that name, bound at open
+  start: [{ name: seed, when: create, run: python seed.py, user: user, cwd: /home/user/app }]
+  services:
+    web: { run: npm start, user: user, cwd: /home/user/app, ready: { port: 3000 } }
+```
+
+```ts
+const { build, uploads } = await cloud.templates.buildFromFile('acme/template.yaml', {
+  templateSlug: 'acme-dev',
+  autoPublish: false,            // register it unpublished, test it, publish it later
+  wait: true,                    // until registered (or failed); default: return the queued build
+  onProgress: (e) => console.log(e.type, e.type === 'build' ? e.build.state : e.from),
+});
+console.log(build.state, build.template_version, build.provenance.recipe_sha256, uploads);
+```
+
+`buildFromFile` is Node only (it reads the disk; browsers never load that code). Folders are packed as a
+reproducible tar (sorted, mtime 0, no owner names; symlinks must stay inside the folder), the same bytes as the Python
+SDK packs, so the same inputs give the same `recipe_sha256`. Uploads the organization already has are not sent
+again. It throws `TemplateFileError` before any request for a file it cannot read or pack, and `TemplateUploadError`
+when the storage refuses the bytes. A recipe already in memory: `templates.buildFromRecipe(doc, { templateSlug,
+baseDir })`. Pass `root` to refuse local paths outside a directory, and `parseYaml` to use another YAML parser.
+
+The pieces on their own:
+
+```ts
+const up = await cloud.templates.uploads.put(bytes, { kind: 'file' });          // Uint8Array, Blob or a stream
+const dir = await cloud.templates.uploads.putPath('./app');                      // Node: a folder as the tar
+await cloud.templates.builds.create(orgId, { templateSlug: 'acme-dev', recipe: { schema: 'shardflux.template-recipe.v2',
+  base: 'ubuntu-24.04@1', build: { files: [{ upload: up.ref, kind: 'file', to: '/etc/acme.conf' }] }, settings: {} } });
+const exported = await cloud.templates.versions.recipe('acme-dev', 3);          // the recipe to build again, and settings
+const langs = await cloud.templates.languages('ubuntu-24.04@1');                // what build.languages offers on a base
+const pkgs = await cloud.templates.packages.search('apt', 'ffmpeg', { base: 'ubuntu-24.04@1' });
+```
+
+Test a version before publishing it, with its inputs, then open workspaces with inputs:
+
+```ts
+const test = await cloud.templates.versionTestInstances.create('acme-dev', 4, { inputs: { PROJECT_NAME: 'demo' } });
+console.log(test.startup);                     // start commands and services: pending | running | ready | failed
+await test.close();
+const ws = await cloud.workspaces.open({ key: 'customer-42/main', template: 'acme-dev', inputs: { PROJECT_NAME: 'acme' } });
+console.log(await ws.inputs(), ws.startup);
+```
+
+A failed start command or service fails the open (`OperationFailedError`, code `startup_failed`, retryable); the
+workspace keeps running so you can inspect it, and `workspace.startup` names the step, its exit code and output tail.
+The next open runs the failed step again. Versions report their `settings`, platform templates their `category`
+(`os` or `stack`), builds the `denied_hosts` their build network refused (add them to `build.network.extra_hosts`).
+
 ## Agent tools
 
 `workspaceTools(workspace)` returns tools with a name, a description, a JSON Schema for the
@@ -302,6 +395,115 @@ const output = await executeToolCall(tools, { name: call.name, input: call.input
 Your agent loop and model calls stay in your application; the workspace is the computer the tools
 act on.
 
+## Tool-call capture (0.7.0+)
+
+Your harness's tools (web search, SQL, HTTP APIs, MCP servers) run in your application, so their results reach the
+model but not the workspace. `workspace.captureToolCalls()` saves every call's input and full output as files in the
+workspace, where the agent can process them with `jq` or Python, and where snapshots and forks keep them.
+
+```ts
+const capture = workspace.captureToolCalls();
+
+// A hand-rolled loop (Anthropic tool_use, Responses function_call, Chat tool_calls item, or { name, input }):
+for (const block of message.content) {
+  if (block.type !== 'tool_use') continue;
+  const output = await capture.run(block, () => myTools[block.name](block.input));
+  results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(output) });
+}
+```
+
+Capture is invisible to the harness. A wrapped tool returns the same value, the same promise object and the same
+thrown error; a synchronous tool stays synchronous. Nothing capture does throws into your code: write failures,
+drops and a throwing `transform` go to `onError` and `capture.stats`. Serialization runs after the call returns and
+the writes run in the background.
+
+One line per framework:
+
+| Harness | Integration |
+|---|---|
+| Hand-rolled loop | `capture.run(call, () => ...)`, `capture.wrap('name', fn)`, or `capture.record({ tool, input, output, callId })` |
+| Shardflux tools | `executeToolCall(capture.tools(workspaceTools(workspace)), call)` (the call's `id` is recorded) |
+| Vercel AI SDK 7 | `generateText({ tools: capture.aiSdk.tools(tools) })`, or `...capture.aiSdk.callbacks()` (`onToolExecutionEnd`; `{ legacy: true }` for `experimental_onToolCallFinish`) |
+| Mastra | `new Agent({ tools: capture.mastra.tools({ weather }), hooks: capture.mastra.hooks() })` |
+| Anthropic tool runner | `client.beta.messages.toolRunner({ tools: capture.anthropic.tools([weatherTool]) })` |
+| OpenAI Agents JS | `const detach = capture.openaiAgents.attach(runner)`, or `tools: capture.openaiAgents.tools([...])` |
+| Claude Agent SDK | `query({ prompt, options: { hooks: capture.claude.hooks(myHooks) } })` |
+| LangChain.js / LangGraph.js | `agent.invoke(input, { callbacks: [capture.langchain.handler()] })` |
+| MCP client | `const release = capture.mcp.instrument(client, { server: 'github' })` |
+
+```ts
+// Vercel AI SDK: the wrapper keeps toolCallId, abortSignal and every other tool property. A streaming tool
+// (async generator execute) passes through unchanged; its final value is recorded.
+const result = await generateText({ model, tools: capture.aiSdk.tools({ weather, search }), prompt });
+
+// Claude Agent SDK: your own hooks are kept. PostToolUse / PostToolUseFailure record every tool, and a
+// PreToolUse hook matching ^mcp__shardflux__ waits for pending writes, so the Shardflux MCP server sees them.
+for await (const m of query({ prompt, options: { hooks: capture.claude.hooks(), mcpServers } })) handle(m);
+
+// OpenAI Agents JS: agent_tool_end reports a tool's error as the string the model got (status ok). For the exact
+// error, wrap execute: tool({ name: 'get_weather', parameters, execute: capture.openaiAgents.execute('get_weather', fn) }).
+const detach = capture.openaiAgents.attach(runner);
+
+// Tools defined at import time in a multi-tenant server: late-bound to the capture active for the request.
+export const lookup = captureTool('lookup', async (id: string) => db.find(id));
+await capture.activate(() => handleRequest(req));   // lookup() records into this capture; elsewhere it passes through
+```
+
+**Selection.** Explicit capture (`record`, `run`, `wrap`, `tools`, `captureTool`) always records. Hook-level
+adapters (`callbacks()`, `hooks()`, `attach()`, `handler()`, `instrument()`) see every tool, Shardflux's own
+included, filtered by `include` / `exclude` (names, a RegExp, or `(tool, source) => boolean`). A capture remembers the
+last 10 000 call ids and records each once, so a wrapper and a hook can be combined.
+
+**In the workspace** (`dir` defaults to `/home/user/tool-calls`; point it at a subdirectory, e.g.
+`/home/user/tool-calls/conv-123`, to group runs):
+
+```
+<dir>/README.md                     layout and jq recipes, for the agent
+<dir>/<run>/index.jsonl             one JSON line per call: seq, call_id, tool, status, input, output_path, ...
+<dir>/<run>/000007-web_search.json  the output (.json, .txt, .html, .png, .pdf, ... from its content)
+<dir>/<run>/000010-github.search/   an MCP result or content blocks: part-1.txt, part-2.png, result.json
+<dir>/<run>/000011-sql.input.json   an input over 64 KiB
+```
+
+`<run>` is `capture.runId` (start time plus a random suffix; `capture.runDir` is the full path). Read the index with
+`jq -cR 'fromjson? // empty' <dir>/*/index.jsonl`, which skips a line torn by a failed append. `capture.promptHint()`
+returns a paragraph that tells the agent where its tool calls are; add it to your system prompt if you want (it is
+never injected).
+
+**Read-your-writes.** Calls through the same client first wait for capture writes recorded before them (bounded by
+`settleTimeoutMs`, 30 s; they never fail because of capture): `exec` and files calls through `workspace.cell()`,
+`workspaceTools`, `snapshot`, `fork`, `suspend`, `saveAsTemplate` and `close` (on the workspace handle and on
+`cloud.workspaces.*(id)`). A lifecycle call's timing shows the wait as a `capture_flush` phase. `delete` and `reset`
+drop pending writes. A write to a suspended workspace wakes it (`wake: null` opts out).
+
+**Serverless.** Writes finish in the background, so let them finish before the function is frozen:
+`waitUntil(capture.flush())` on Vercel (or Next.js `after(() => capture.flush())`), `await capture.flush()` before
+returning on AWS Lambda. `flush()` and `close()` never reject; they return `{ complete, written, failed, dropped }`.
+
+**Redaction.** Nothing is redacted by default (the input came from the model). `transform(event)` gets a copy of each
+call and returns it (changed or not) or `null` to drop it; if it throws, the call is dropped, never written unredacted.
+
+```ts
+const capture = workspace.captureToolCalls({
+  exclude: ['exec'],
+  transform: (e) => (e.tool === 'crm_lookup' ? { ...e, output: redact(e.output) } : e),
+  onError: (err) => log.warn(err.kind, err.message),
+});
+```
+
+**Limits.** An output over `maxOutputBytes` (32 MiB) is cut when it is text or JSON (`.part`, `truncated: true`) and
+not stored when it is binary (`dropped: "too_large"`). What pending calls hold in memory (files, index lines, inline
+inputs) is bounded by `maxPendingBytes` (128 MiB): over it the output and a large input are dropped and the call keeps
+a small index line with `dropped: "queue_full"`; the call never waits. At most `maxPendingCalls` (10 000) calls are
+pending: past that, while the workspace takes no writes, a call is not recorded at all (`record()` returns null,
+`onError` gets `queue_full`). A write is retried for `retryWindowMs` (120 s) and then dropped (`write_failed`).
+Observing an async tool marks its promise handled: if your code never awaits a wrapped tool's promise and it rejects,
+Node reports no `unhandledRejection` for it (the error is still in the index; Node has no way to observe a rejection
+without handling it). About one write per call: more than roughly 100 calls per second per
+workspace reaches the pending limit. `Response`, `ReadableStream`, Node streams and `Blob` results are never read
+(`meta.note: "stream_not_captured"`). On template v1 the files API writes as root, so the agent can read the captured
+files but not change them. The format is specified in `docs/decisions/0006-tool-call-capture.md`.
+
 ## Secrets
 
 Store credentials once and give them to a workspace's processes as environment variables. Values
@@ -338,15 +540,18 @@ await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPEN
   `message`, `requestId`, `retryable`, `details`, `operationId`, `retryAfterSeconds`, and `reason`
   (`details.reason`, e.g. `not_session`, `draft_not_found`, `legacy_disk_layout`; see `KnownErrorReason`).
 - `OperationFailedError`: an awaited operation ended `failed` or `canceled` (`errorCode`,
-  `operation`, `timing`).
-- `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `timing`).
+  `retryable` **(0.6.2+)**, `operation`, `timing`). `retryable` is the operation error's own flag: `true` for
+  `capacity_unavailable` (no host could admit the start before its deadline; retry later), `false` for a definitive
+  failure.
+- `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `lastState`, `lastReason`,
+  `deadlineAt` **(0.6.2+)** while it waits for capacity, `timing`).
 - `ShardfluxProtocolError`: a response was not the documented shape.
 
 Treat unknown error codes and reasons as generic errors: show `message`, and use `retryable`.
 
 ## More of the API
 
-The `Shardflux` object also has `templates` (including custom template builds), `volumes`
+The `Shardflux` object also has `templates` (including custom template builds and the template editor), `volumes`
 (shared persistent storage attached to workspaces), `secrets` (see above), `egress` (outbound allowlists),
 `usage`, `billing`, `me()`, `entitlements(orgId)` and `request(method, path)` for any `/v1`
 route. The package exports the OpenAPI-generated types as well (`paths`, `components`,
@@ -356,7 +561,7 @@ route. The package exports the OpenAPI-generated types as well (`paths`, `compon
 
 - The SDK follows the API's `/v1` contract. New fields, enum values and error codes can appear in
   any release; ignore unknown fields.
-- While below 1.0, a breaking change bumps the minor version (0.5 to 0.6).
+- While below 1.0, a breaking change bumps the minor version (0.6 to 0.7).
 - `SDK_VERSION` is exported; requests send `User-Agent: shardflux-sdk-ts/<version>`.
 - Examples in this README, in `examples/` and on shardflux.dev name the version they need. The examples on the
   website and in the console are checked against the version published on npm before they ship.

package/dist/capture-adapters.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Framework adapters for tool-call capture. Structural types only: no framework is a dependency of the SDK, and each
+ * adapter's output is checked against the real framework types in test/capture-types.ts.
+ *
+ * Explicit wrappers (`tools()` of each framework, `capture.tools()`) always record. Hook-level adapters (AI SDK
+ * callbacks, Mastra hooks, OpenAI Agents `attach`, Claude Agent SDK hooks, LangChain callbacks, MCP instrumentation)
+ * see every tool and apply `include` / `exclude`. A capture remembers the last 10 000 call ids, so a wrapper and a hook
+ * on the same call record it once.
+ */
+import type { CallRef, CaptureCall, CaptureFlushResult, CaptureSource, CaptureStatus } from './capture.js';
+/** How the capture observes one call (internal). */
+export interface ObserveSpec {
+    tool: string;
+    source: CaptureSource;
+    input: unknown;
+    callId: string | null;
+    meta?: Record<string, unknown>;
+    /** An async iterable result: record its last item (AI SDK streaming tools) instead of every item. */
+    final?: boolean;
+    /** Filtered by include/exclude (hook-level adapters). */
+    hookLevel?: boolean;
+    /** Maps a successful result to what is recorded (LangChain ToolMessage, MCP isError, Mastra ValidationError). */
+    post?: (output: unknown) => {
+        output: unknown;
+        error?: unknown;
+        status?: CaptureStatus;
+    };
+}
+/** What the adapters need from a capture (internal). */
+export interface CaptureCore {
+    observe<T>(spec: ObserveSpec, fn: (...args: never[]) => T, thisArg: unknown, args: unknown[]): T;
+    hook(call: CaptureCall): CallRef | null;
+    settle(): Promise<unknown> | undefined;
+    flush(timeoutMs?: number): Promise<CaptureFlushResult>;
+    accepts(tool: string, source: CaptureSource): boolean;
+}
+/** A copy of `target` with its prototype and own properties, and `key` replaced by `value` (the original is untouched). */
+export declare function copyWith<T extends object>(target: T, key: string, value: unknown): T;
+/** A LangChain ToolMessage: recorded as its content (plus artifact), status error when the message says so. */
+export declare function isToolMessage(v: unknown): v is {
+    content: unknown;
+    artifact?: unknown;
+    status?: string;
+    tool_call_id: string;
+    name?: string;
+};
+/** The part of an AI SDK 7 `onToolExecutionEnd` event capture reads (also the v6 `experimental_onToolCallFinish` shape). */
+export interface AiSdkToolEndEvent {
+    toolCall?: {
+        toolCallId?: string;
+        toolName?: string;
+        input?: unknown;
+    } | undefined;
+    toolExecutionMs?: number | undefined;
+    toolOutput?: {
+        type?: string;
+        output?: unknown;
+        error?: unknown;
+    } | undefined;
+    success?: boolean | undefined;
+    output?: unknown;
+    error?: unknown;
+    durationMs?: number | undefined;
+}
+export interface AiSdkAdapter {
+    /** `generateText({ tools: capture.aiSdk.tools(tools) })`: wraps each `execute` (keeps toolCallId, abortSignal and every other property). */
+    tools<T>(tools: T): T;
+    /** `generateText({ ...capture.aiSdk.callbacks() })`: `onToolExecutionEnd` (hook-level). */
+    callbacks(opts?: {
+        legacy?: false;
+    }): {
+        onToolExecutionEnd: (event: AiSdkToolEndEvent) => void;
+    };
+    /** `{ legacy: true }`: the deprecated alias `experimental_onToolCallFinish`. */
+    callbacks(opts: {
+        legacy: true;
+    }): {
+        experimental_onToolCallFinish: (event: AiSdkToolEndEvent) => void;
+    };
+}
+/** Mastra `afterToolCall` context (ToolAfterHookContext). */
+export interface MastraAfterToolCallContext {
+    toolName?: string;
+    input?: unknown;
+    context?: unknown;
+    metadata?: unknown;
+    output?: unknown;
+    error?: unknown;
+}
+export interface MastraHooksLike {
+    beforeToolCall?: (...args: any[]) => any;
+    afterToolCall?: (ctx: any) => void | Promise<void>;
+}
+export interface MastraAdapter {
+    /** `new Agent({ hooks: capture.mastra.hooks(myHooks) })`: records in `afterToolCall`, then calls yours. */
+    hooks<H extends MastraHooksLike = Record<never, never>>(existing?: H): H & {
+        afterToolCall: (ctx: MastraAfterToolCallContext) => Promise<void>;
+    };
+    /** `new Agent({ tools: capture.mastra.tools({ weather }) })`: wraps each `execute(inputData, context)`. */
+    tools<T>(tools: T): T;
+}
+export interface AnthropicAdapter {
+    /** `client.beta.messages.toolRunner({ tools: capture.anthropic.tools([...]) })`: wraps `run(input, context)`. */
+    tools<T>(tools: T): T;
+}
+export interface OpenAIAgentsAdapter {
+    /** `new Agent({ tools: capture.openaiAgents.tools([...]) })`: wraps each FunctionTool's `invoke`. */
+    tools<T>(tools: T): T;
+    /**
+     * `tool({ execute: capture.openaiAgents.execute('name', fn) })`: records around your execute, with the exact error
+     * (a FunctionTool's own error function turns a thrown error into a string result before `invoke` returns).
+     */
+    execute<F extends (...args: any[]) => any>(name: string, fn: F): F;
+    /** Subscribes `agent_tool_end` on a Runner or an Agent (hook-level); returns the function that unsubscribes. */
+    attach(target: {
+        on(event: 'agent_tool_end', listener: (...args: any[]) => void): unknown;
+        off(event: 'agent_tool_end', listener: (...args: any[]) => void): unknown;
+    }): () => void;
+}
+export type ClaudeHookCallback = (input: any, toolUseID: string | undefined, options: {
+    signal: AbortSignal;
+}) => Promise<{
+    continue?: boolean;
+}>;
+export interface ClaudeHookMatcher {
+    matcher?: string;
+    hooks: ClaudeHookCallback[];
+    timeout?: number;
+}
+export interface ClaudeHookMatcherLike {
+    matcher?: string;
+    hooks: Array<(input: any, toolUseID: string | undefined, options: {
+        signal: AbortSignal;
+    }) => Promise<unknown>>;
+    timeout?: number;
+}
+export type ClaudeHooksLike = Partial<Record<string, ClaudeHookMatcherLike[]>>;
+export type ClaudeCaptureHooks = {
+    PreToolUse: ClaudeHookMatcher[];
+    PostToolUse: ClaudeHookMatcher[];
+    PostToolUseFailure: ClaudeHookMatcher[];
+};
+export interface ClaudeAdapter {
+    /**
+     * `query({ prompt, options: { hooks: capture.claude.hooks(myHooks) } })`: PostToolUse and PostToolUseFailure record
+     * (hook-level); a PreToolUse hook matching `^mcp__shardflux__` waits for pending writes (bounded) so the Shardflux MCP
+     * server sees them. Your hooks are kept and run as before.
+     */
+    hooks<H extends ClaudeHooksLike = Record<never, never>>(existing?: H): Omit<H, keyof ClaudeCaptureHooks> & ClaudeCaptureHooks;
+}
+export interface LangChainToolHandler {
+    handleToolStart(tool: unknown, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): void;
+    handleToolEnd(output: unknown, runId: string, parentRunId?: string, tags?: string[]): void;
+    handleToolError(err: unknown, runId: string, parentRunId?: string, tags?: string[]): void;
+}
+export interface LangChainAdapter {
+    /** `{ callbacks: [capture.langchain.handler()] }` (a plain methods object: LangChain wraps it with fromMethods). */
+    handler(): LangChainToolHandler;
+}
+export interface McpAdapter {
+    /** Patches this client instance's `callTool` (hook-level). Returns the function that restores it. */
+    instrument(client: {
+        callTool: (...args: any[]) => any;
+    }, opts?: {
+        server?: string;
+    }): () => void;
+}
+export interface CaptureAdapters {
+    wrapAny<T>(tools: T): T;
+    aiSdk: AiSdkAdapter;
+    mastra: MastraAdapter;
+    anthropic: AnthropicAdapter;
+    openaiAgents: OpenAIAgentsAdapter;
+    claude: ClaudeAdapter;
+    langchain: LangChainAdapter;
+    mcp: McpAdapter;
+}
+export declare function createAdapters(core: CaptureCore): CaptureAdapters;