@shardflux/sdk 0.6.2 → 0.8.0

package/CHANGELOG.md

@@ -3,7 +3,115 @@
 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.2 (not yet published; npm `latest` is 0.6.1)
+## 0.8.0 (2026-09-28)
+
+Types only; nothing changes at run time and the API is unchanged.
+
+### Provider tool exports type-check without casts
+
+- `toAnthropicTools(tools)` is assignable to `Anthropic.Tool[]` (`@anthropic-ai/sdk`) and `toOpenAITools(tools, { api:
+  'responses' })` to `OpenAI.Responses.FunctionTool[]` (`openai`) under TypeScript's `strict` checks, with no `as`
+  casts. `toOpenAITools(tools)` (and `{ api: 'chat' }`) is assignable to `OpenAI.Chat.ChatCompletionTool[]`.
+- `toOpenAITools` has one return type per format (overloads): an `api` known only at run time still returns either
+  array, as before.
+- `JsonSchema` is a type alias instead of an interface, so a schema is assignable to the providers' open schema types
+  (`{ [key: string]: unknown }`). An object literal typed as `JsonSchema` still rejects a misspelt keyword.
+- `executeToolCall(tools, call)` takes `input` as `unknown`, as the Anthropic SDK's `ToolUseBlock` types it, so a
+  `tool_use` block is passed as it is (no `block.input as Record<string, unknown>`); `execute` validates it as before.
+- New exported types for the three formats: `AnthropicToolDefinition`, `OpenAIChatToolDefinition`,
+  `OpenAIResponsesToolDefinition`.
+- Checked at compile time against `@anthropic-ai/sdk` 0.128.0 and `openai` 7.23.0 (devDependencies only; the SDK still
+  has no runtime dependencies).
+
+## 0.7.0 (2026-09-28)
+
+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
 

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.2. 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.8.0. Anything marked **(0.8.0+)** is not in 0.7.x, **(0.7.0+)** 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.
 
@@ -300,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
@@ -307,18 +383,135 @@ parameters and an `execute` function. Export them for your model provider and di
 calls:
 
 ```ts
+import Anthropic from '@anthropic-ai/sdk';
 import { executeToolCall, toAnthropicTools, toOpenAITools, workspaceTools } from '@shardflux/sdk';
 
 const tools = workspaceTools(workspace);
-const anthropicTools = toAnthropicTools(tools);   // or toOpenAITools(tools)
+const anthropicTools: Anthropic.Tool[] = toAnthropicTools(tools);
+const chatTools = toOpenAITools(tools);                               // OpenAI Chat Completions
+const responsesTools = toOpenAITools(tools, { api: 'responses' });    // OpenAI Responses API
 
-// For each tool call the model makes:
-const output = await executeToolCall(tools, { name: call.name, input: call.input });
+// For each tool call the model makes (an Anthropic tool_use block, or an OpenAI function_call item, as it is):
+const output = await executeToolCall(tools, block);
 ```
 
+**(0.8.0+)** The exports type-check as the provider SDKs' own types under `strict`, with no casts:
+`Anthropic.Tool[]`, `OpenAI.Chat.ChatCompletionTool[]` and, with `{ api: 'responses' }`,
+`OpenAI.Responses.FunctionTool[]`. `executeToolCall` takes a `tool_use` block's `unknown` input as it is and validates
+it.
+
 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
@@ -366,7 +559,7 @@ Treat unknown error codes and reasons as generic errors: show `message`, and use
 
 ## 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`,
@@ -376,7 +569,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.7 to 0.8).
 - `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;