@shardflux/sdk 0.14.0 → 0.15.0

package/dist/generated/cell-api.d.ts

@@ -731,6 +731,87 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/computer": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * The workspace desktop's state (does not start it)
+         * @description Contracts §45.4. Tool `computer` (the token carries it only while the
+         *     workspace's computer use is on, §45.1).
+         */
+        get: operations["computerStatus"];
+        put?: never;
+        /**
+         * Start the workspace desktop (no-op while it runs)
+         * @description The size applies when this call starts the desktop; a running desktop
+         *     keeps its size (stop it first to change it). `409 conflict`
+         *     `details.reason computer_use_unavailable` when the workspace's template
+         *     cannot run a desktop.
+         */
+        post: operations["computerStart"];
+        /** Stop the workspace desktop (its windows close) */
+        delete: operations["computerStop"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/computer/actions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run a batch of computer actions, optionally ending with a screenshot
+         * @description Contracts §45.3. Starts the desktop when it does not run. The actions
+         *     run in order; the first failure stops the batch and the rest are
+         *     reported `skipped`. An invalid batch runs nothing: `422
+         *     validation_failed` with `details.index` (-1 for the batch itself).
+         */
+        post: operations["computerActions"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/computer/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Start the desktop viewer on its guest port
+         * @description Contracts §45.5. Expose the returned port with the ports API and open a
+         *     signed link whose `path` is the returned path. Port 61002 is view
+         *     only (the guest drops input); 61003 lets the viewer use the desktop.
+         */
+        post: operations["computerStreamStart"];
+        /** End every view of the desktop */
+        delete: operations["computerStreamStop"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_id}/wake-hint": {
         parameters: {
             query?: never;
@@ -1490,6 +1571,111 @@ export interface components {
             }[];
             stderr?: string;
         };
+        ComputerStartRequest: {
+            /** @default 1280 */
+            width?: number;
+            /** @default 800 */
+            height?: number;
+        };
+        ComputerStatus: {
+            running: boolean;
+            /** @example :1 */
+            display?: string;
+            width?: number;
+            height?: number;
+            /** Format: date-time */
+            started_at?: string;
+            /** @description The session command (window manager and panel). */
+            session?: string;
+            streams: {
+                view: boolean;
+                interactive: boolean;
+            };
+        };
+        /**
+         * @description One of Claude's computer toolset members with its parameters
+         *     (contracts §45.3). A parameter the action does not take is refused.
+         */
+        ComputerAction: {
+            /** @enum {string} */
+            action: "screenshot" | "zoom" | "left_click" | "right_click" | "middle_click" | "double_click" | "triple_click" | "left_click_drag" | "mouse_move" | "left_mouse_down" | "left_mouse_up" | "cursor_position" | "scroll" | "type" | "key" | "hold_key" | "wait";
+            /** @description [x, y] screen pixels. */
+            coordinate?: number[];
+            start_coordinate?: number[];
+            /** @description zoom: [x0, y0, x1, y1]. */
+            region?: number[];
+            /** @description type: the text; key/hold_key: key combinations; clicks, drag, scroll: modifiers held. */
+            text?: string;
+            /** @enum {string} */
+            scroll_direction?: "up" | "down" | "left" | "right";
+            scroll_amount?: number;
+            /** @description Seconds (wait */
+            duration?: number;
+            repeat?: number;
+        };
+        ComputerActionsRequest: {
+            actions: components["schemas"]["ComputerAction"][];
+            /**
+             * @description Append a screenshot after the last action that ran.
+             * @default false
+             */
+            screenshot?: boolean;
+            /** @default 250 */
+            settle_ms?: number;
+            /**
+             * @default png
+             * @enum {string}
+             */
+            format?: "png" | "jpeg";
+            /**
+             * @description jpeg only.
+             * @default 80
+             */
+            quality?: number;
+        };
+        ComputerImage: {
+            /** @enum {string} */
+            format: "png" | "jpeg";
+            width: number;
+            height: number;
+            data: string;
+        };
+        ComputerActionResult: {
+            action: string;
+            ok: boolean;
+            /** @description cursor_position: X=…, Y=… */
+            output?: string;
+            image?: components["schemas"]["ComputerImage"];
+            error?: {
+                /** @enum {string} */
+                code: "action_failed";
+                message: string;
+            };
+            /** @description An earlier action of the batch failed; this one did not run. */
+            skipped?: boolean;
+            /** Format: int64 */
+            took_ms: number;
+        };
+        ComputerActionsResult: {
+            results: components["schemas"]["ComputerActionResult"][];
+            screenshot?: components["schemas"]["ComputerImage"];
+            cursor: number[];
+            display: {
+                width: number;
+                height: number;
+            };
+        };
+        ComputerStreamRequest: {
+            /** @default false */
+            interactive?: boolean;
+        };
+        ComputerStream: {
+            /** @enum {integer} */
+            port: 61002 | 61003;
+            interactive: boolean;
+            /** @description The viewer page */
+            path: string;
+        };
         BrowserScreenshotRequest: {
             url: string;
             /** @default 1280 */
@@ -2582,6 +2768,152 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
+    computerStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Desktop state. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerStatus"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStart: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ComputerStartRequest"];
+            };
+        };
+        responses: {
+            /** @description Desktop state. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerStatus"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStop: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Stopped */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerActions: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ComputerActionsRequest"];
+            };
+        };
+        responses: {
+            /** @description Per-action results. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerActionsResult"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStreamStart: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ComputerStreamRequest"];
+            };
+        };
+        responses: {
+            /** @description Viewer started. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerStream"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStreamStop: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Viewers stopped. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["Error"];
+        };
+    };
     workspaceWakeHint: {
         parameters: {
             query?: never;

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.14.0";
+export declare const SDK_VERSION = "0.15.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

package/dist/http.js

@@ -11,7 +11,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody, isWorkingQuotaRefusal } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.14.0';
+export const SDK_VERSION = '0.15.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * How long an idle pooled connection stays reusable (ms): 5 minutes, instead of undici's 4 s default, so the request

package/dist/index.d.ts

@@ -14,8 +14,10 @@
  */
 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, AllocationMode, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResizeAppliesAt, ResizeCpu, ResizeDeferReason, ResizeDisk, ResizeLimitReason, ResizeMemory, ResizeParams, ResizeResult, ResizeResponse, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } from './client.js';
+export { WorkspaceRef } from './workspace-ref.js';
+export type { WorkspaceRefFiles, WorkspaceRefParams } from './workspace-ref.js';
+export type { AgentSession, AllocationMode, ComputerUse, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResizeAppliesAt, ResizeCpu, ResizeDeferReason, ResizeDisk, ResizeLimitReason, ResizeMemory, ResizeParams, ResizeResult, ResizeResponse, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
 export type { FinishedOperation, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 export { COLD_BOOT_REASONS, durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from './progress.js';
 export type { ColdBootReason, Durability, HostLost, LostSuspend, LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
@@ -30,6 +32,8 @@ export { tarEnd, tarHeader, tarPadding } from './tar.js';
 export type { TarEntry, TarEntryType } from './tar.js';
 export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionImmutable, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
 export { WorkspacePorts } from './ports.js';
+export { COMPUTER_TOOLSET, WorkspaceComputer, computerToolset, decodeComputerImage } from './computer.js';
+export type { ComputerActOptions, ComputerScreenshot, ComputerStream, ComputerStreamOptions, ComputerToolResult, ComputerToolsetOptions, ToolUseBlockLike } from './computer.js';
 export type { ExposePortResult, ExposedPort, PortCallbackResponse, PortCallbackUrl, PortLink, PortLinkOptions, PortLinkResponse, PortToken, PortTokenOptions, PortTokenResponse, PortView } from './ports.js';
 export { SecretsApi, WorkspaceSecrets } from './secrets.js';
 export type { BoundSecretStatus, CreateOrganizationSecretParams, CreateSecretParams, Secret, SecretAccessEvent, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams, WorkspaceSecretBindings, } from './secrets.js';
@@ -44,11 +48,11 @@ export type { HintOptions, HintResult, WakeOptions } from './workspace.js';
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } 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, MemoryGrow, BurstSummary, BurstError, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, ResourceHint, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
+export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ComputerAction, ComputerActionName, ComputerActionResult, ComputerActionsRequest, ComputerActionsResult, ComputerImage, ComputerStartRequest, ComputerStatus, ComputerStreamInfo, ExecSession, ExecStartRequest, MemoryGrow, BurstSummary, BurstError, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, ResourceHint, 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 { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, OpenAIResponsesToolDefinition, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, OpenAIResponsesToolDefinition, ToolTarget, 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';

package/dist/index.js

@@ -1,4 +1,5 @@
-export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } from "./client.js";
+export { WorkspaceRef } from "./workspace-ref.js";
 export { COLD_BOOT_REASONS, durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from "./progress.js";
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from "./feedback.js";
 export { UsageApi } from "./usage.js";
@@ -6,6 +7,8 @@ export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, Templat
 export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from "./template-file.js";
 export { tarEnd, tarHeader, tarPadding } from "./tar.js";
 export { WorkspacePorts } from "./ports.js";
+// Computer use (0.15.0+, contracts §45).
+export { COMPUTER_TOOLSET, WorkspaceComputer, computerToolset, decodeComputerImage } from "./computer.js";
 export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";

package/dist/templates.d.ts

@@ -215,6 +215,8 @@ export interface TemplateSummary {
         memory_mib: number | null;
         idle_policy: string | null;
     };
+    /** Computer use (0.15.0+, contracts §45.1): the template's switch for its workspaces (a workspace may override it). */
+    computer_use: boolean;
     open_version: TemplateVersion | null;
     /** The live draft (organization templates in dev mode), or null. */
     draft: TemplateDraftSummary | null;
@@ -900,6 +902,16 @@ export declare class TemplatesApi {
         includeArchived?: boolean;
         owner?: TemplateOwner;
     }): Promise<TemplateDetail>;
+    /**
+     * Computer use (0.15.0+, contracts §45.1): switches it on or off for every workspace of one of your organization's
+     * templates (a workspace may override it with setComputerUse). 403 for platform templates (switch a workspace on
+     * instead). Owners and admins (sessions) or API keys of the organization with a tool permission.
+     */
+    setComputerUse(slug: string, enabled: boolean, params?: {
+        organizationId?: string;
+    }): Promise<{
+        enabled: boolean;
+    }>;
     /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
     find(slug: string, params?: {
         organizationId?: string;

package/dist/templates.js

@@ -693,6 +693,15 @@ export class TemplatesApi {
         const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}`;
         return this.#ctx().http.json('GET', path, { query: { include_archived: params.includeArchived, owner: params.owner } }, this.#ctx().authorization);
     }
+    /**
+     * Computer use (0.15.0+, contracts §45.1): switches it on or off for every workspace of one of your organization's
+     * templates (a workspace may override it with setComputerUse). 403 for platform templates (switch a workspace on
+     * instead). Owners and admins (sessions) or API keys of the organization with a tool permission.
+     */
+    async setComputerUse(slug, enabled, params = {}) {
+        const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}/computer-use` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}/computer-use`;
+        return this.#ctx().http.json('PUT', path, { json: { enabled } }, this.#ctx().authorization);
+    }
     /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
     async find(slug, params = {}) {
         try {

package/dist/tools.d.ts

@@ -1,7 +1,7 @@
-import type { CellClientOptions } from './cell.js';
+import type { CellClient, CellClientOptions } from './cell.js';
 import type { WorkspaceMode } from './errors.js';
 import type { ToolName } from './tokens.js';
-import type { Workspace } from './workspace.js';
+import type { HintOptions, HintResult } from './workspace.js';
 /**
  * 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
@@ -48,6 +48,19 @@ 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[];
+/**
+ * What workspace tools act on: an opened `Workspace`, or a `WorkspaceRef` (0.15.0+) whose first tool call opens the key.
+ * `cell()` may return a promise (a ref opens first); `mode` and `grantedTools` are read when the tools are built.
+ */
+export interface ToolTarget {
+    readonly mode: WorkspaceMode;
+    readonly grantedTools: ToolName[] | null;
+    cell(opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    } & CellClientOptions): CellClient | Promise<CellClient>;
+    hint(opts?: HintOptions): Promise<HintResult>;
+}
 export interface WorkspaceToolsOptions {
     /**
      * Tool permissions to expose (default: the tools of the workspace's last token, else all). A file-first workspace
@@ -102,7 +115,7 @@ export interface WorkspaceToolsOptions {
     burst?: boolean;
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
-export declare function workspaceTools(workspace: Workspace, opts?: WorkspaceToolsOptions): WorkspaceTool[];
+export declare function workspaceTools(workspace: ToolTarget, opts?: WorkspaceToolsOptions): WorkspaceTool[];
 /** Anthropic Messages API tool definition; assignable to `Anthropic.Tool` (0.8.0+). */
 export type AnthropicToolDefinition = {
     name: string;