@shardflux/sdk 0.7.0 → 0.9.0

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.9.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -8,6 +8,8 @@ export interface RequestOptions {
     accept?: string;
     headers?: Record<string, string>;
     idempotencyKey?: string;
+    /** The request has no effect a retry could duplicate (a read-only POST such as files/search): retried like a GET. */
+    idempotent?: boolean;
     signal?: AbortSignal;
     /** Override the client's default request timeout (ms); 0 disables it (streams). */
     timeoutMs?: number;
@@ -22,6 +24,8 @@ export interface HttpOptions {
     maxRetries: number;
     source: 'api' | 'cell';
     sleep?: (ms: number) => Promise<void>;
+    /** Called after each 2xx response (never throws into the request; the version check starts from it). */
+    onSuccess?: (() => void) | undefined;
 }
 export declare const defaultSleep: (ms: number) => Promise<void>;
 /**
@@ -35,6 +39,8 @@ export declare const defaultSleep: (ms: number) => Promise<void>;
  */
 export declare function defaultFetch(env?: Record<string, string | undefined> | undefined, undiciVersion?: string | undefined): typeof fetch;
 export declare function buildUrl(base: string, path: string, query?: RequestOptions['query']): string;
+/** `X-Tree-Revision` (file-first workspaces, contracts §29.8): a non-negative integer, else null. */
+export declare function treeRevisionOf(headers: Headers): number | null;
 /** Turns a non-2xx response into a ShardfluxApiError (or a protocol error for undocumented bodies). */
 export declare function errorFrom(res: Response, source: 'api' | 'cell'): Promise<Error>;
 export declare class HttpClient {

package/dist/http.js

@@ -1,12 +1,14 @@
 /**
  * Minimal HTTP layer shared by the application API client and the cell
  * client: JSON in/out, structured errors, per-request timeout, and bounded
- * retries only where a retry cannot duplicate an effect (safe methods, or
- * requests carrying an Idempotency-Key).
+ * retries only where a retry cannot duplicate an effect (safe methods,
+ * requests carrying an Idempotency-Key, and read-only POSTs marked
+ * `idempotent`). A retryable 429/502/503/504 (e.g. 503 `host_capacity`, 503
+ * `wake_failed`) waits `Retry-After` (at most 5 s) before the retry.
  */
-import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
+import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.7.0';
+export const SDK_VERSION = '0.9.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends
@@ -43,6 +45,14 @@ function retryAfterSeconds(res) {
     const n = Number(v);
     return Number.isFinite(n) && n >= 0 ? n : undefined;
 }
+/** `X-Tree-Revision` (file-first workspaces, contracts §29.8): a non-negative integer, else null. */
+export function treeRevisionOf(headers) {
+    const v = headers.get('x-tree-revision');
+    if (v === null || !/^\d{1,19}$/.test(v))
+        return null;
+    const n = Number(v);
+    return Number.isSafeInteger(n) ? n : null;
+}
 /** Turns a non-2xx response into a ShardfluxApiError (or a protocol error for undocumented bodies). */
 export async function errorFrom(res, source) {
     const text = await res.text();
@@ -54,7 +64,7 @@ export async function errorFrom(res, source) {
         parsed = null;
     }
     if (isErrorBody(parsed))
-        return new ShardfluxApiError(res.status, parsed, source, retryAfterSeconds(res));
+        return apiError(res.status, parsed, source, retryAfterSeconds(res), treeRevisionOf(res.headers) ?? undefined);
     return new ShardfluxProtocolError(`HTTP ${res.status} from ${source === 'api' ? 'the Shardflux API' : 'the cell gateway'} without an error body`, res.status);
 }
 export class HttpClient {
@@ -66,7 +76,7 @@ export class HttpClient {
     async raw(method, path, init = {}, authorization) {
         const url = buildUrl(this.opts.baseUrl, path, init.query);
         const safe = method === 'GET' || method === 'HEAD';
-        const retriable = safe || init.idempotencyKey !== undefined;
+        const retriable = safe || init.idempotencyKey !== undefined || init.idempotent === true;
         const sleep = this.opts.sleep ?? defaultSleep;
         for (let attempt = 0;; attempt += 1) {
             const headers = {
@@ -102,8 +112,17 @@ export class HttpClient {
                 await sleep(delayMs);
                 continue;
             }
-            if (res.ok)
+            if (res.ok) {
+                if (this.opts.onSuccess) {
+                    try {
+                        this.opts.onSuccess();
+                    }
+                    catch {
+                        // A hook never fails the request.
+                    }
+                }
                 return res;
+            }
             const error = await errorFrom(res, this.opts.source);
             const retryableStatus = res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504;
             const retryableError = error instanceof ShardfluxApiError ? error.retryable && retryableStatus : retryableStatus;

package/dist/index.d.ts

@@ -6,16 +6,21 @@
  *   const workspace = await cloud.workspaces.open({ key: `${customerId}/${projectId}`, template: 'python-node-browser' });
  *   await agent.run({ input: userMessage, tools: workspaceTools(workspace) });
  *
+ * File-first workspaces (`mode: 'file_first'`, contracts §29) keep a versioned file tree and run each command as an
+ * execution: `await workspace.executions.run(['bash', '-lc', 'pytest -q'])`.
+ *
  * Types come from the committed OpenAPI documents: application API
  * and cell gateway.
  */
 export type { components, operations, paths } from './generated/app-api.js';
 export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from './client.js';
-export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
-export type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
+export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { FinishedOperation, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
 export { formatTiming } from './progress.js';
 export type { LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
+export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from './feedback.js';
+export type { AccountFeedbackParams, FeedbackCategory, FeedbackContext, FeedbackReceipt, SendFeedbackParams } from './feedback.js';
 export { UsageApi } from './usage.js';
 export type { Grants, Spend, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
 export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from './templates.js';
@@ -33,16 +38,22 @@ export type { AttachVolumeParams, AttachmentResult, CreateVolumeParams, DeleteVo
 export { AuditApi, auditQuery, parseAuditNdjson } from './audit.js';
 export type { AuditActorType, AuditEvent, AuditFilters, AuditListParams, AuditOutcome, AuditSource } from './audit.js';
 export { Workspace } from './workspace.js';
-export type { WakeOptions } from './workspace.js';
+export type { HintOptions, HintResult, WakeOptions } from './workspace.js';
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from './cell.js';
-export type { BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileInfo, FileList, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, RunOptions, RunResult, Signal, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
+export { EXECUTION_ID, ExecutionResult, newExecutionId } from './executions.js';
+export type { ExecutionChange, ExecutionError, ExecutionGetOptions, ExecutionResultBody, ExecutionRunOptions, ExecutionState } from './executions.js';
+export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
 export { ToolTokenManager } from './tokens.js';
 export type { ToolName, ToolToken, ToolTokenOptions } from './tokens.js';
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from './tools.js';
-export type { JsonSchema, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, OpenAIResponsesToolDefinition, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
 export { CaptureError, ToolCallCapture, captureTool } from './capture.js';
 export type { CallLike, CallRef, CaptureCall, CaptureErrorKind, CaptureEvent, CaptureFlushResult, CapturePart, CaptureSelector, CaptureSource, CaptureStats, CaptureStatus, DropReason, ToolCallCaptureOptions, WrapOptions, } from './capture.js';
 export type { AiSdkAdapter, AiSdkToolEndEvent, AnthropicAdapter, ClaudeAdapter, ClaudeCaptureHooks, ClaudeHookCallback, ClaudeHookMatcher, LangChainAdapter, LangChainToolHandler, MastraAdapter, MastraAfterToolCallContext, McpAdapter, OpenAIAgentsAdapter, } from './capture-adapters.js';
-export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from './errors.js';
-export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason } from './errors.js';
+export { NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
+export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason, WorkspaceMode } from './errors.js';
 export { SDK_VERSION } from './http.js';
+export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from './account.js';
+export type { AccountClientOptions, AccountDeletion, AccountDeletionCanceled, AccountDeletionScheduled, ApiKey, ApiKeyPage, ApiKeyToolPermission, AuditExportParams, AuthSessionInfo, AuthSessionPage, AuthSessionState, AuthUser, BillingInvoicePage, BillingPortalSession, CheckoutStatus, CreateApiKeyParams, CreatedApiKey, DataExport, EmailChangeConfirmResult, EmailChangeResult, Invitation, InvitationPage, LoginResult, Member, MemberPage, MemberRole, MfaChallengeResult, Organization, OrganizationDeletion, OrganizationDeletionResult, OrganizationPage, OrganizationRole, OrganizationWorkspacePage, OrganizationWorkspacesParams, PageParams, PasswordChangeResult, PasswordResetConfirmResult, PasswordResetRequestResult, Project, ProjectPage, RecoveryCodes, RegisterResult, ResendVerificationResult, SessionTokenUpdate, ShardfluxAccountOptions, StepUpResult, TotpConfirmResult, TotpDisableResult, TotpEnrollment, VerifyEmailResult, WaitForCheckoutOptions, } from './account.js';
+export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from './version-check.js';
+export type { CheckClientVersionOptions, ClientEcosystem, ClientVersionEntry, ClientVersionStatus, ClientVersionStatusKind, ClientVersions, VersionCheckIdentity, VersionCheckOption, } from './version-check.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
 export { formatTiming } from "./progress.js";
+export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from "./feedback.js";
 export { UsageApi } from "./usage.js";
 export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from "./templates.js";
 export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from "./template-file.js";
@@ -10,8 +11,11 @@ export { VolumesApi } from "./volumes.js";
 export { AuditApi, auditQuery, parseAuditNdjson } from "./audit.js";
 export { Workspace } from "./workspace.js";
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from "./cell.js";
+export { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
 export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
-export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+export { NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
 export { SDK_VERSION } from "./http.js";
+export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from "./account.js";
+export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from "./version-check.js";

package/dist/lifecycle.d.ts

@@ -6,10 +6,11 @@
  * and resolves when the change has FINISHED, returning the succeeded operation (typed FinishedOperation) and, on a
  * workspace handle, the refreshed view. Both paths are traced (see progress.ts).
  */
-import type { ClientContext, Operation, WaitOptions } from './client.js';
+import type { ClientContext, Operation, WaitOptions, WorkspaceView } from './client.js';
 import type { RequestOptions } from './http.js';
 import { Trace } from './progress.js';
 import type { LifecycleAction, ProgressListener } from './progress.js';
+import type { ToolName, ToolToken } from './tokens.js';
 /** An operation that has finished successfully: what a lifecycle call with `wait` resolves to. */
 export type FinishedOperation = Operation & {
     state: 'succeeded';
@@ -31,15 +32,39 @@ export interface LifecycleOptions {
 export type WaitedLifecycleOptions = LifecycleOptions & {
     wait: true | WaitOptions;
 };
+/**
+ * `resume()` options (0.9.0). With `wait`, the server holds the resume until the workspace runs and returns a tool token
+ * with it (contracts §22.6): `agentLabel` and `tools` choose that token (defaults: a workspace handle's own, those given
+ * to open(); `workspaces.resume(id)` otherwise the key's tools and label `default`). A handle keeps it for its `cell()`
+ * clients of the same label and tools; `workspaces.resume(id)` only attributes it.
+ */
+export interface ResumeOptions extends LifecycleOptions {
+    agentLabel?: string;
+    tools?: ToolName[];
+}
+export type WaitedResumeOptions = ResumeOptions & {
+    wait: true | WaitOptions;
+};
 /** Internal: the trace a wait continues instead of starting its own (open(), wake() and waited lifecycle calls). */
 export declare const TRACE: unique symbol;
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
 export declare const AFTER_WAIT: unique symbol;
+/**
+ * Internal: a workspace handle's part in a held resume (contracts §22.6): the tool token to ask for, and how it takes the
+ * running workspace and that token from a 200 (instead of reading the view and fetching a token afterwards).
+ */
+export declare const HELD_RESUME: unique symbol;
+export interface HeldResumeTarget {
+    agentLabel: string | undefined;
+    tools: readonly ToolName[] | undefined;
+    adopt(view: WorkspaceView, token: ToolToken | null): void;
+}
 export type InternalWaitOptions = WaitOptions & {
     [TRACE]?: Trace;
 };
-export type InternalLifecycleOptions = LifecycleOptions & {
+export type InternalLifecycleOptions = ResumeOptions & {
     [AFTER_WAIT]?: (trace: Trace, operation: Operation) => Promise<void>;
+    [HELD_RESUME]?: HeldResumeTarget;
 };
 export declare function waitOptionsOf(opts: LifecycleOptions): WaitOptions | null;
 /**

package/dist/lifecycle.js

@@ -4,6 +4,11 @@ import { Trace, combineListeners, traced } from "./progress.js";
 export const TRACE = Symbol('shardflux.trace');
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
 export const AFTER_WAIT = Symbol('shardflux.afterWait');
+/**
+ * Internal: a workspace handle's part in a held resume (contracts §22.6): the tool token to ask for, and how it takes the
+ * running workspace and that token from a 200 (instead of reading the view and fetching a token afterwards).
+ */
+export const HELD_RESUME = Symbol('shardflux.heldResume');
 export function waitOptionsOf(opts) {
     if (opts.wait === undefined || opts.wait === false)
         return null;

package/dist/progress.js

@@ -81,8 +81,10 @@ export function describeFailure(err, timeoutMs) {
         if (err.name === 'TimeoutError')
             return timeoutMs !== undefined ? `timeout after ${timeoutMs} ms` : 'timeout';
         const e = err;
-        if (e.name === 'ShardfluxApiError' || e.name === 'ShardfluxProtocolError')
-            return `HTTP ${e.status}${e.code ? ` ${e.code}` : ''}`;
+        // ShardfluxApiError and its subclasses (typed by reason) carry requestId; a protocol error only a status.
+        if (e.name === 'ShardfluxProtocolError' || (typeof e.status === 'number' && typeof e.requestId === 'string')) {
+            return `HTTP ${e.status}${e.code ? ` ${e.code}` : ''}${typeof e.reason === 'string' ? ` ${e.reason}` : ''}`;
+        }
         return `network: ${e.cause?.code ?? e.cause?.message ?? e.message}`;
     }
     return 'network error';

package/dist/templates.js

@@ -241,7 +241,7 @@ export class TemplateBuildsApi {
      * Throws TemplateBuildTimeoutError at the deadline (default 30 min); the build continues.
      */
     async waitForBuild(organizationId, buildId, opts = {}) {
-        const { sleep, http, authorization } = this.#ctx();
+        const { sleep, http } = this.#ctx();
         const timeoutMs = opts.timeoutMs ?? 1_800_000;
         const maxInterval = opts.maxPollIntervalMs ?? 10_000;
         let interval = opts.pollIntervalMs ?? 1_000;
@@ -252,7 +252,7 @@ export class TemplateBuildsApi {
                 throw opts.signal.reason instanceof Error ? opts.signal.reason : new Error('aborted');
             const waitS = opts.serverWait === false ? 0 : (timeoutMs - (Date.now() - started)) / 1000;
             const t0 = Date.now();
-            const { body: build, applied } = await pollWithWait(http, `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}`, authorization, waitS, opts.signal);
+            const { body: build, applied } = await pollWithWait(http, `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}`, this.#ctx().authorization, waitS, opts.signal);
             const key = `${build.state}/${build.registration.state}`;
             const changed = key !== lastKey;
             lastKey = key;

package/dist/tools.d.ts

@@ -1,7 +1,13 @@
 import type { CellClientOptions } from './cell.js';
+import type { WorkspaceMode } from './errors.js';
 import type { ToolName } from './tokens.js';
 import type { Workspace } from './workspace.js';
-export interface JsonSchema {
+/**
+ * The JSON Schema subset of the tool definitions. A type alias rather than an interface (0.8.0+), so a schema is
+ * assignable to the providers' open schema types (`{ [key: string]: unknown }`) without a cast, and an object literal
+ * typed as JsonSchema still rejects a misspelt keyword.
+ */
+export type JsonSchema = {
     type?: 'object' | 'string' | 'integer' | 'number' | 'boolean' | 'array';
     description?: string;
     properties?: Record<string, JsonSchema>;
@@ -13,10 +19,12 @@ export interface JsonSchema {
     maximum?: number;
     minLength?: number;
     maxLength?: number;
+    /** ECMAScript regular expression a string must match (0.7.0+). */
+    pattern?: string;
     minItems?: number;
     maxItems?: number;
     default?: unknown;
-}
+};
 export interface WorkspaceTool<A extends Record<string, unknown> = Record<string, unknown>, R = unknown> {
     name: string;
     description: string;
@@ -39,7 +47,12 @@ export declare class ToolArgumentError extends Error {
 /** Validates the JSON-Schema subset used by the tool definitions. Returns problems (empty = valid). */
 export declare function validateArgs(schema: JsonSchema, value: unknown, path?: string): string[];
 export interface WorkspaceToolsOptions {
-    /** Tool permissions to expose (default: the tools of the workspace's last token, else all). */
+    /**
+     * Tool permissions to expose (default: the tools of the workspace's last token, else all). A file-first workspace
+     * (`workspace.mode`, contracts §29) gets only the `exec` and `files` tools: `exec` runs each command as an execution
+     * (a fresh VM on the workspace's files; the result adds `execution_id`, `state`, `changed` and `tree_revision`), and
+     * the process, terminal, git and browser tools are not offered because nothing runs between executions.
+     */
     tools?: ToolName[];
     /** Attribution label for the tokens these tools use (one agent session per label). */
     agentLabel?: string;
@@ -53,47 +66,84 @@ export interface WorkspaceToolsOptions {
     wake?: CellClientOptions['wake'];
     /** Bound on lifecycle waits (busy waits plus wakes) per tool call (CellClientOptions.transitionTimeoutMs). */
     transitionTimeoutMs?: number;
+    /**
+     * Send `workspace.hint()` when a tool call starts, without waiting for it (default true; 0.9.0+), so a parked
+     * workspace is being restored while the call is prepared. Pass false when you call `workspace.hint()` yourself
+     * earlier (e.g. when the model starts streaming a tool call). `read_file`, `list_files` and `search_files` never send
+     * it: a sleeping workspace serves them from its disk without waking (contracts §26.4), and the hint would wake a
+     * suspended workspace (or restore a hibernated one) that the read does not need.
+     */
+    hint?: boolean;
+    /**
+     * The mode to build the tools for (0.9.0+; default `workspace.mode`). Given, the workspace is not touched until a tool
+     * runs, so definitions can be built without one (e.g. to publish them before any workspace exists).
+     */
+    mode?: WorkspaceMode;
+    /**
+     * File-first workspaces: called with the execution id before the `exec` tool sends its execution (0.9.0+). An
+     * execution cannot be canceled, so a caller that stops waiting (an aborted signal) can still fetch its result later
+     * with `workspace.executions.get(id)`.
+     */
+    onExecution?: (executionId: string) => void;
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export declare function workspaceTools(workspace: Workspace, opts?: WorkspaceToolsOptions): WorkspaceTool[];
-/** OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`) or Responses API. */
-export declare function toOpenAITools(tools: readonly WorkspaceTool[], opts?: {
-    api?: 'chat' | 'responses';
-}): {
-    type: "function";
+/** Anthropic Messages API tool definition; assignable to `Anthropic.Tool` (0.8.0+). */
+export type AnthropicToolDefinition = {
     name: string;
     description: string;
-    parameters: JsonSchema & {
-        type: "object";
+    input_schema: JsonSchema & {
+        type: 'object';
     };
-    strict: boolean;
-}[] | {
-    type: "function";
+};
+/** OpenAI Chat Completions tool definition; assignable to `OpenAI.Chat.ChatCompletionFunctionTool` (0.8.0+). */
+export type OpenAIChatToolDefinition = {
+    type: 'function';
     function: {
         name: string;
         description: string;
         parameters: JsonSchema & {
-            type: "object";
+            type: 'object';
         };
     };
-}[];
-/** Anthropic Messages API tool definitions (`{ name, description, input_schema }`). */
-export declare function toAnthropicTools(tools: readonly WorkspaceTool[]): {
+};
+/** OpenAI Responses API tool definition; assignable to `OpenAI.Responses.FunctionTool` (0.8.0+). */
+export type OpenAIResponsesToolDefinition = {
+    type: 'function';
     name: string;
     description: string;
-    input_schema: JsonSchema & {
-        type: "object";
+    parameters: JsonSchema & {
+        type: 'object';
     };
-}[];
+    strict: boolean;
+};
+/**
+ * OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`, the default) or, with
+ * `{ api: 'responses' }`, the Responses API. The return type follows `api` (0.8.0+); an `api` known only at run time
+ * gives either array.
+ */
+export declare function toOpenAITools(tools: readonly WorkspaceTool[], opts: {
+    api: 'responses';
+}): OpenAIResponsesToolDefinition[];
+export declare function toOpenAITools(tools: readonly WorkspaceTool[], opts?: {
+    api?: 'chat';
+}): OpenAIChatToolDefinition[];
+export declare function toOpenAITools(tools: readonly WorkspaceTool[], opts?: {
+    api?: 'chat' | 'responses';
+}): OpenAIChatToolDefinition[] | OpenAIResponsesToolDefinition[];
+/** Anthropic Messages API tool definitions (`{ name, description, input_schema }`). */
+export declare function toAnthropicTools(tools: readonly WorkspaceTool[]): AnthropicToolDefinition[];
 /**
  * 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). The call's `id` / `call_id` is passed
- * to `execute` as `toolCallId` (0.7.0+), so `executeToolCall(capture.tools(tools), call)` records it.
+ * 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 declare function executeToolCall(tools: readonly WorkspaceTool[], call: {
     name: string;
     arguments?: string | Record<string, unknown>;
-    input?: Record<string, unknown>;
+    input?: unknown;
     id?: string;
     call_id?: string;
 }, options?: {