@shardflux/sdk 0.6.2 → 0.8.0

package/dist/tools.js

@@ -1,3 +1,16 @@
+/**
+ * Framework-neutral agent tools for a workspace (TEMPLATES.md):
+ *
+ *   await agent.run({ input, tools: workspaceTools(workspace) });
+ *
+ * Each tool is { name, description, parameters (JSON Schema 2020-12), execute }.
+ * `execute` validates its arguments against `parameters` (the same schema the
+ * model saw), then calls the cell gateway through the workspace's managed tool
+ * token. The customer's model and agent loop stay in the customer's
+ * application; toOpenAITools/toAnthropicTools export the definitions in those
+ * providers' formats and executeToolCall dispatches a model's tool call.
+ */
+import { CAPTURE_BARRIER } from "./cell.js";
 export class ToolArgumentError extends Error {
     tool;
     issues;
@@ -283,11 +296,15 @@ export function workspaceTools(workspace, opts = {}) {
             const issues = validateArgs(d.parameters, args);
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
-            return d.run(args, options);
+            // Read-your-writes: tool calls captured before this one are in the workspace before it runs (bounded).
+            const barrier = workspace[CAPTURE_BARRIER];
+            const pending = typeof barrier === 'function' ? barrier.call(workspace) : undefined;
+            if (pending)
+                await pending;
+            return d.run(args, options.signal ? { signal: options.signal } : {});
         },
     }));
 }
-/** OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`) or Responses API. */
 export function toOpenAITools(tools, opts = {}) {
     return opts.api === 'responses'
         ? tools.map((t) => ({ type: 'function', name: t.name, description: t.description, parameters: t.parameters, strict: false }))
@@ -299,7 +316,10 @@ export function toAnthropicTools(tools) {
 }
 /**
  * Runs a model's tool call: `arguments` may be the JSON string (OpenAI) or an object (Anthropic
- * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError).
+ * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError). The call's `id` / `call_id` is passed
+ * to `execute` as `toolCallId` (0.7.0+), so `executeToolCall(capture.tools(tools), call)` records it. `input` is
+ * `unknown` (0.8.0+), as in the Anthropic SDK's `ToolUseBlock`, so a tool_use block is passed as it is; `execute`
+ * validates it.
  */
 export async function executeToolCall(tools, call, options = {}) {
     const tool = tools.find((t) => t.name === call.name);
@@ -313,5 +333,6 @@ export async function executeToolCall(tools, call, options = {}) {
     catch {
         throw new ToolArgumentError(call.name, ['arguments are not valid JSON']);
     }
-    return tool.execute(args, options);
+    const toolCallId = call.call_id ?? call.id;
+    return tool.execute(args, toolCallId === undefined ? options : { ...options, toolCallId });
 }

package/dist/workspace.d.ts

@@ -3,13 +3,15 @@
  * tool tokens and cell clients (one per agent label / tool set).
  */
 import type { ClientContext, DiskLayout, ForkTarget, Operation, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
-import { CellClient } from './cell.js';
+import { CAPTURE_BARRIER, CellClient } from './cell.js';
+import { ToolCallCapture } from './capture.js';
+import type { ToolCallCaptureOptions } from './capture.js';
 import type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
 import { WorkspaceSecrets } from './secrets.js';
 import type { CellClientOptions, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
-import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
+import type { SaveAsTemplateParams, SaveAsTemplateResponse, WorkspaceStartup } from './templates.js';
 import { ToolTokenManager } from './tokens.js';
 import type { ToolName, ToolToken } from './tokens.js';
 export interface WakeOptions {
@@ -59,10 +61,18 @@ export declare class Workspace {
     get origin(): WorkspaceOrigin | null;
     /** How a session ended (closed, idle_timeout, draft_discarded); null while live or for a plain delete. */
     get endedReason(): WorkspaceView['ended_reason'];
+    /**
+     * Start commands and services of the workspace's template version (0.7.0; contracts §24.4): `state` pending, running,
+     * ready or failed (the failed step, its exit code, reason and output tail). Null when the version has neither, or on
+     * an older API. A failed startup leaves the workspace running for inspection; the next open runs the failed step again.
+     */
+    get startup(): WorkspaceStartup | null;
     /** The raw view (GET /v1/workspaces/{id}). */
     get data(): WorkspaceView;
     /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
     get secrets(): WorkspaceSecrets;
+    /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
+    inputs(): Promise<Record<string, string>>;
     refresh(): Promise<this>;
     /** Waits for the active operation (if any) and refreshes. */
     waitUntilReady(opts?: WaitOptions): Promise<this>;
@@ -123,6 +133,19 @@ export declare class Workspace {
      */
     reset(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     reset(opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Captures the tool calls of your agent harness into this workspace (docs/decisions/0006-tool-call-capture.md): each
+     * call's input and full output become files under `dir` (default `/home/user/tool-calls/<run>/`), so the agent can
+     * work on them with code, and they are in snapshots and forks. Wrapped tools return exactly what they returned before;
+     * capture never throws into the harness. Shardflux calls through this client (exec, files, workspaceTools, snapshot,
+     * fork, suspend, close, saveAsTemplate) first wait for writes recorded before them; delete and reset drop them.
+     *
+     *   const capture = workspace.captureToolCalls();
+     *   const out = await capture.run(block, () => myTools[block.name](block.input));
+     */
+    captureToolCalls(opts?: ToolCallCaptureOptions): ToolCallCapture;
+    /** Internal: waits for tool-call capture writes recorded so far (workspaceTools calls it before each tool). */
+    [CAPTURE_BARRIER](): Promise<void> | undefined;
     /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
     saveAsTemplate(params: SaveAsTemplateParams): Promise<SaveAsTemplateResponse>;
     /**

package/dist/workspace.js

@@ -1,6 +1,7 @@
-import { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS } from "./cell.js";
+import { CAPTURE_BARRIER, CellClient, DEFAULT_TRANSITION_TIMEOUT_MS } from "./cell.js";
+import { ToolCallCapture } from "./capture.js";
 import { OperationFailedError, ShardfluxApiError } from "./errors.js";
-import { randomId } from "./http.js";
+import { defaultSleep, randomId } from "./http.js";
 import { AFTER_WAIT, TRACE } from "./lifecycle.js";
 import { Trace, combineListeners, traced } from "./progress.js";
 import { WorkspaceSecrets } from "./secrets.js";
@@ -107,6 +108,14 @@ export class Workspace {
     get endedReason() {
         return this.#view.ended_reason ?? null;
     }
+    /**
+     * Start commands and services of the workspace's template version (0.7.0; contracts §24.4): `state` pending, running,
+     * ready or failed (the failed step, its exit code, reason and output tail). Null when the version has neither, or on
+     * an older API. A failed startup leaves the workspace running for inspection; the next open runs the failed step again.
+     */
+    get startup() {
+        return this.#view.startup ?? null;
+    }
     /** The raw view (GET /v1/workspaces/{id}). */
     get data() {
         return this.#view;
@@ -115,6 +124,10 @@ export class Workspace {
     get secrets() {
         return new WorkspaceSecrets(this.#ctx, this.id);
     }
+    /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
+    inputs() {
+        return this.#ctx.workspaces.inputs(this.id);
+    }
     async refresh() {
         this.#view = await this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.id)}`, {}, this.#ctx.authorization);
         return this;
@@ -142,6 +155,8 @@ export class Workspace {
         return this.#ctx.workspaces.fork(this.id, target, this.#tracked(opts));
     }
     async close(opts = {}) {
+        // Closing aborts in-flight cell requests: tool-call capture writes recorded before it are flushed first (bounded).
+        await this.#ctx.captures.settle(this.id);
         for (const c of this.#cells.values())
             c.close();
         this.#cells.clear();
@@ -159,6 +174,37 @@ export class Workspace {
             m.invalidate();
         return op;
     }
+    /**
+     * Captures the tool calls of your agent harness into this workspace (docs/decisions/0006-tool-call-capture.md): each
+     * call's input and full output become files under `dir` (default `/home/user/tool-calls/<run>/`), so the agent can
+     * work on them with code, and they are in snapshots and forks. Wrapped tools return exactly what they returned before;
+     * capture never throws into the harness. Shardflux calls through this client (exec, files, workspaceTools, snapshot,
+     * fork, suspend, close, saveAsTemplate) first wait for writes recorded before them; delete and reset drop them.
+     *
+     *   const capture = workspace.captureToolCalls();
+     *   const out = await capture.run(block, () => myTools[block.name](block.input));
+     */
+    captureToolCalls(opts = {}) {
+        const defaults = this.#defaults.tools;
+        const tools = defaults && !defaults.includes('files') ? [...defaults, 'files'] : defaults;
+        const agentLabel = opts.agentLabel ?? this.#defaults.agentLabel;
+        const manager = this.tokens({ ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) });
+        // The capture's own client: not in #cells (close() flushes it before aborting those) and without the barrier.
+        const cell = new CellClient(this.id, manager, {
+            fetch: this.#ctx.fetch,
+            userAgent: this.#ctx.userAgent,
+            sleep: this.#ctx.sleep,
+            maxRetries: 0,
+            ...(opts.transitionTimeoutMs !== undefined ? { transitionTimeoutMs: opts.transitionTimeoutMs } : {}),
+            ...(this.#ctx.onProgress ? { onProgress: this.#ctx.onProgress } : {}),
+            wake: opts.wake === undefined ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}) }) : opts.wake,
+        });
+        return new ToolCallCapture({ workspaceId: this.id, cell, registry: this.#ctx.captures, ...(this.#ctx.sleep !== defaultSleep ? { sleep: this.#ctx.sleep } : {}) }, opts);
+    }
+    /** Internal: waits for tool-call capture writes recorded so far (workspaceTools calls it before each tool). */
+    [CAPTURE_BARRIER]() {
+        return this.#ctx.captures.settle(this.id);
+    }
     /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
     saveAsTemplate(params) {
         return this.#ctx.workspaces.saveAsTemplate(this.id, params);
@@ -205,6 +251,7 @@ export class Workspace {
                 ...cellOpts,
                 ...(listener ? { onProgress: listener } : {}),
                 wake: wake === undefined ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}), ...(onProgress ? { onProgress } : {}) }) : wake,
+                [CAPTURE_BARRIER]: () => this.#ctx.captures.settle(this.id),
             });
             this.#cells.set(k, c);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",
@@ -36,13 +36,36 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "yaml": "^2.4.0"
+  },
+  "peerDependenciesMeta": {
+    "yaml": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@ai-sdk/provider": "4.0.18",
+    "@anthropic-ai/claude-agent-sdk": "0.3.283",
+    "@anthropic-ai/sdk": "0.128.0",
     "@eslint/js": "10.0.1",
+    "@langchain/core": "1.2.13",
+    "@langchain/langgraph": "1.4.18",
+    "@mastra/core": "1.71.0",
+    "@modelcontextprotocol/client": "2.1.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@openai/agents-core": "0.18.0",
     "@types/node": "24.13.6",
+    "ai": "7.0.118",
+    "ajv": "8.20.0",
     "eslint": "10.11.0",
+    "langchain": "1.5.14",
+    "openai": "7.23.0",
     "openapi-typescript": "7.13.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.70.1"
+    "typescript-eslint": "8.70.1",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "scripts": {
     "build": "node scripts/build.mjs",