@shardflux/sdk 0.8.0 → 0.10.0

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.8.0";
+export declare const SDK_VERSION = "0.10.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.8.0';
+export const SDK_VERSION = '0.10.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,18 +6,23 @@
  *   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, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, 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 type { Grants, Spend, SpendCap, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } 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';
 export type { PackedFile, YamlParser } from './template-file.js';
@@ -33,9 +38,11 @@ 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';
@@ -43,6 +50,10 @@ export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, Ope
 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 { ExecStartError, 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, SpendPolicyUpdate, 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 { ExecStartError, 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,4 +1,5 @@
 import type { CellClientOptions } from './cell.js';
+import type { WorkspaceMode } from './errors.js';
 import type { ToolName } from './tokens.js';
 import type { Workspace } from './workspace.js';
 /**
@@ -18,6 +19,8 @@ export type 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;
@@ -44,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;
@@ -58,6 +66,25 @@ 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[];

package/dist/tools.js

@@ -11,6 +11,8 @@
  * providers' formats and executeToolCall dispatches a model's tool call.
  */
 import { CAPTURE_BARRIER } from "./cell.js";
+import { ExecStartError } from "./errors.js";
+import { newExecutionId } from "./executions.js";
 export class ToolArgumentError extends Error {
     tool;
     issues;
@@ -51,6 +53,8 @@ export function validateArgs(schema, value, path = '$') {
             issues.push(`${path} is too short`);
         if (schema.maxLength !== undefined && value.length > schema.maxLength)
             issues.push(`${path} is too long`);
+        if (schema.pattern !== undefined && !new RegExp(schema.pattern, 'u').test(value))
+            issues.push(`${path} must match ${schema.pattern}`);
     }
     else if (t === 'integer' || t === 'number') {
         if (typeof value !== 'number' || !Number.isFinite(value) || (t === 'integer' && !Number.isInteger(value)))
@@ -79,6 +83,12 @@ export function validateArgs(schema, value, path = '$') {
     return issues;
 }
 const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
+/** The tool permissions whose tools work on a file-first workspace (contracts §29.8): files and executions. */
+const FILE_FIRST_TOOLS = ['exec', 'files'];
+/** Changed paths returned to the model per execution (the rest is flagged `changed_truncated`). */
+const MAX_CHANGED_LISTED = 200;
+/** Tools served from a sleeping workspace's disk without waking it (contracts §26.4): the runner sends no hint. */
+const DISK_READS = new Set(['read_file', 'list_files', 'search_files']);
 const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
 const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
 const signal = { type: 'string', description: 'Signal name such as SIGTERM, SIGINT or SIGKILL.', minLength: 2, maxLength: 12 };
@@ -97,29 +107,88 @@ export function workspaceTools(workspace, opts = {}) {
     });
     const max = opts.maxOutputBytes ?? 65_536;
     const prefix = opts.prefix ?? '';
-    const allowed = new Set(opts.tools ?? workspace.grantedTools ?? ALL);
+    // A file-first workspace (contracts §29) has files and executions only: no processes, terminals, version control or
+    // browser between calls, so those tools are not offered, and exec runs each command as an execution.
+    const fileFirst = (opts.mode ?? workspace.mode) === 'file_first';
+    const allowed = new Set((opts.tools ?? workspace.grantedTools ?? ALL).filter((t) => !fileFirst || FILE_FIRST_TOOLS.includes(t)));
+    const execParameters = obj({
+        command: { type: 'string', minLength: 1, maxLength: 100_000, description: 'Shell command line, e.g. "pip install -r requirements.txt && pytest -q".' },
+        cwd: { type: 'string', maxLength: 4096, description: 'Working directory (absolute).' },
+        timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
+        stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
+    }, ['command']);
     const defs = [
-        {
-            name: 'exec',
-            permission: 'exec',
-            description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
-            parameters: obj({
-                command: { type: 'string', minLength: 1, maxLength: 100_000, description: 'Shell command line, e.g. "pip install -r requirements.txt && pytest -q".' },
-                cwd: { type: 'string', maxLength: 4096, description: 'Working directory (absolute).' },
-                timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
-                stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
-            }, ['command']),
-            run: async (a, o) => {
-                const r = await cell().exec.run(['bash', '-lc', String(a.command)], {
-                    ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
-                    timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
-                    ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
-                    maxOutputBytes: max,
-                    ...(o.signal ? { signal: o.signal } : {}),
-                });
-                return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+        fileFirst
+            ? {
+                name: 'exec',
+                permission: 'exec',
+                description: 'Run a shell command (Linux; bash -lc) in a fresh VM on the workspace’s files and return its exit code, stdout, stderr, the files it changed and the new tree revision. Only files under /home/user persist between calls: processes, background jobs and changes elsewhere (e.g. system packages) do not, so install dependencies into /home/user (e.g. a virtualenv) and start servers within the same command.',
+                parameters: execParameters,
+                run: async (a, o) => {
+                    const executionId = newExecutionId();
+                    opts.onExecution?.(executionId);
+                    const r = await cell().executions.run(['bash', '-lc', String(a.command)], {
+                        executionId,
+                        ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                        timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
+                        ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                        // The cell captures what the model can be given, and flags the rest as truncated.
+                        outputLimitBytes: Math.max(1, Math.min(16_777_216, max)),
+                        ...(o.signal ? { signal: o.signal } : {}),
+                    });
+                    const out = clip(r.stdoutText, max);
+                    const err = clip(r.stderrText, max);
+                    const changed = r.changed.slice(0, MAX_CHANGED_LISTED).map((c) => ({ path: c.path, change: c.change, type: c.type }));
+                    return {
+                        exit_code: r.exitCode,
+                        term_signal: r.termSignal,
+                        timed_out: r.timedOut,
+                        stdout: out.text,
+                        stderr: err.text,
+                        truncated: r.stdoutTruncated || r.stderrTruncated || out.truncated || err.truncated,
+                        execution_id: r.executionId,
+                        state: r.state,
+                        tree_revision: r.treeRevision,
+                        changed,
+                        changed_truncated: r.changedTruncated || r.changed.length > changed.length,
+                        ...(r.error ? { error: { code: r.error.code, message: r.error.message, reason: r.errorReason } } : {}),
+                    };
+                },
+            }
+            : {
+                name: 'exec',
+                permission: 'exec',
+                description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
+                parameters: execParameters,
+                run: async (a, o) => {
+                    let r;
+                    try {
+                        r = await cell().exec.run(['bash', '-lc', String(a.command)], {
+                            ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                            timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
+                            ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                            maxOutputBytes: max,
+                            ...(o.signal ? { signal: o.signal } : {}),
+                        });
+                    }
+                    catch (e) {
+                        // Nothing ran (e.g. a cwd that is not a directory): the model gets the reason, as for an execution.
+                        if (!(e instanceof ExecStartError))
+                            throw e;
+                        return {
+                            exit_code: null,
+                            term_signal: null,
+                            timed_out: false,
+                            stdout: '',
+                            stderr: '',
+                            truncated: false,
+                            session_id: e.sessionId,
+                            error: { code: e.code, message: e.message, reason: e.reason },
+                        };
+                    }
+                    return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+                },
             },
-        },
         {
             name: 'read_file',
             permission: 'files',
@@ -159,6 +228,77 @@ export function workspaceTools(workspace, opts = {}) {
                 return { entries: r.entries.map((e) => ({ name: e.name, path: e.path, type: e.type, size: e.size, modified_at: e.modified_at })), truncated: r.truncated };
             },
         },
+        {
+            name: 'search_files',
+            permission: 'files',
+            description: 'Search file contents under a directory (or in one file) in the workspace (like grep -rn) and return the matching lines with path, line and column. The pattern is literal text unless regex is true (RE2 syntax). Binary files, symbolic links and .git/node_modules directories are skipped.',
+            parameters: obj({
+                path: path('Directory (or one file) to search, absolute, e.g. /home/user/project.'),
+                pattern: { type: 'string', minLength: 1, maxLength: 1000, description: 'Text to find, or an RE2 regular expression when regex is true.' },
+                regex: { type: 'boolean', description: 'Treat pattern as an RE2 regular expression.' },
+                case_insensitive: { type: 'boolean', description: 'Ignore case.' },
+                include: { type: 'array', maxItems: 32, items: { type: 'string', minLength: 1, maxLength: 256 }, description: 'Only files matching one of these gitignore-style globs: "*.py" matches the name at any depth, "src/**/*.ts" the path relative to path.' },
+                exclude: { type: 'array', maxItems: 32, items: { type: 'string', minLength: 1, maxLength: 256 }, description: 'Skip files and directories matching these globs, e.g. "build/" (default .git and node_modules; [] searches everything).' },
+                max_matches: { type: 'integer', minimum: 1, maximum: 5000, description: 'Stop after this many matches (default 200).' },
+                context_lines: { type: 'integer', minimum: 0, maximum: 5, description: 'Lines of context to return before and after each match.' },
+            }, ['path', 'pattern']),
+            run: async (a, o) => {
+                const r = await cell().files.search(String(a.path), String(a.pattern), {
+                    ...(typeof a.regex === 'boolean' ? { regex: a.regex } : {}),
+                    ...(typeof a.case_insensitive === 'boolean' ? { caseInsensitive: a.case_insensitive } : {}),
+                    ...(Array.isArray(a.include) ? { include: a.include } : {}),
+                    ...(Array.isArray(a.exclude) ? { exclude: a.exclude } : {}),
+                    ...(typeof a.max_matches === 'number' ? { maxMatches: a.max_matches } : {}),
+                    ...(typeof a.context_lines === 'number' ? { contextLines: a.context_lines } : {}),
+                    ...(o.signal ? { signal: o.signal } : {}),
+                });
+                // Whole matches only, up to the output budget; the rest is counted.
+                const matches = [];
+                let used = 0;
+                for (const m of r.matches) {
+                    used += Buffer.byteLength(JSON.stringify(m), 'utf8');
+                    if (used > max)
+                        break;
+                    matches.push(m);
+                }
+                const omitted = r.matches.length - matches.length;
+                return { matches, truncated: r.truncated || omitted > 0, stop_reason: r.stop_reason ?? null, omitted_matches: omitted, files_scanned: r.files_scanned };
+            },
+        },
+        {
+            name: 'edit_file',
+            permission: 'files',
+            description: 'Edit a text file in the workspace by replacing exact text. Each old_text must occur exactly once in the file (include enough surrounding lines to make it unique) unless replace_all is true. The edits apply in order and atomically: all of them or none. Fails without changing anything if the file changed since expected_revision; read it again then.',
+            parameters: obj({
+                path: path(),
+                edits: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 100,
+                    description: 'Edits applied in order.',
+                    items: obj({
+                        old_text: { type: 'string', minLength: 1, maxLength: 1_048_576, description: 'Exact text to replace, including whitespace and indentation.' },
+                        new_text: { type: 'string', maxLength: 1_048_576, description: 'Replacement text (empty to delete).' },
+                        replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring exactly one.' },
+                    }, ['old_text', 'new_text']),
+                },
+                expected_revision: {
+                    type: 'string',
+                    pattern: '^[0-9a-f]{64}$',
+                    description: 'The revision your edits are based on (the revision returned by the previous edit_file of this file). Default: the file’s revision read just before editing.',
+                },
+            }, ['path', 'edits']),
+            run: async (a, o) => {
+                const c = cell();
+                const file = String(a.path);
+                // Without a revision from the model, pin the edit to the content current now, so a concurrent change between
+                // this read and the patch is refused (revision_mismatch) instead of edited blindly.
+                const expected = typeof a.expected_revision === 'string' ? a.expected_revision : (await c.files.stat(file, { revision: true })).revision;
+                const edits = a.edits.map((e) => ({ oldText: e.old_text, newText: e.new_text, ...(e.replace_all !== undefined ? { replaceAll: e.replace_all } : {}) }));
+                const r = await c.files.patch({ path: file, edits, ...(expected !== undefined ? { expectedRevision: expected } : {}) }, o.signal ? { signal: o.signal } : {});
+                return { path: r.path, revision: r.revision, previous_revision: r.previous_revision, replacements: r.replacements ?? null, bytes_written: r.bytes_written };
+            },
+        },
         {
             name: 'list_processes',
             permission: 'process',
@@ -296,6 +436,17 @@ export function workspaceTools(workspace, opts = {}) {
             const issues = validateArgs(d.parameters, args);
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
+            // Fire and forget: a parked workspace starts restoring while this call is prepared (contracts §26.6). Not for
+            // the reads a sleeping workspace serves from its disk (§26.4): the hint would wake it for nothing.
+            if (opts.hint !== false && !DISK_READS.has(d.name)) {
+                workspace
+                    .hint({
+                    ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}),
+                    ...(opts.wake !== undefined ? { wake: opts.wake } : {}),
+                    ...(opts.transitionTimeoutMs !== undefined ? { wakeTimeoutMs: opts.transitionTimeoutMs } : {}),
+                })
+                    .catch(() => undefined);
+            }
             // 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;