@shardflux/sdk 0.6.2 → 0.7.0

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.7.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,35 @@
   "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",
     "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",