@shardflux/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -3,7 +3,27 @@
 Every API the README shows is available from the version named here. Below 1.0, a minor release may break
 compatibility; breaking changes are marked **Breaking**.
 
-## 0.7.0 (not yet published; npm `latest` is 0.6.2)
+## 0.8.0 (2026-09-28)
+
+Types only; nothing changes at run time and the API is unchanged.
+
+### Provider tool exports type-check without casts
+
+- `toAnthropicTools(tools)` is assignable to `Anthropic.Tool[]` (`@anthropic-ai/sdk`) and `toOpenAITools(tools, { api:
+  'responses' })` to `OpenAI.Responses.FunctionTool[]` (`openai`) under TypeScript's `strict` checks, with no `as`
+  casts. `toOpenAITools(tools)` (and `{ api: 'chat' }`) is assignable to `OpenAI.Chat.ChatCompletionTool[]`.
+- `toOpenAITools` has one return type per format (overloads): an `api` known only at run time still returns either
+  array, as before.
+- `JsonSchema` is a type alias instead of an interface, so a schema is assignable to the providers' open schema types
+  (`{ [key: string]: unknown }`). An object literal typed as `JsonSchema` still rejects a misspelt keyword.
+- `executeToolCall(tools, call)` takes `input` as `unknown`, as the Anthropic SDK's `ToolUseBlock` types it, so a
+  `tool_use` block is passed as it is (no `block.input as Record<string, unknown>`); `execute` validates it as before.
+- New exported types for the three formats: `AnthropicToolDefinition`, `OpenAIChatToolDefinition`,
+  `OpenAIResponsesToolDefinition`.
+- Checked at compile time against `@anthropic-ai/sdk` 0.128.0 and `openai` 7.23.0 (devDependencies only; the SDK still
+  has no runtime dependencies).
+
+## 0.7.0 (2026-09-28)
 
 Needs an API with the template editor (contracts §24); every new field is additive and older fields are unchanged.
 

package/README.md

@@ -10,8 +10,8 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **Early access.** Shardflux is in early access. The API is versioned (`/v1`), but this SDK is
 > below 1.0: a minor release may contain breaking changes (see [Compatibility](#compatibility)).
 
-> **Versions.** This README describes 0.7.0. Anything marked **(0.7.0+)** is not in 0.6.x and **(0.6.0+)** not in
-> 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
+> **Versions.** This README describes 0.8.0. Anything marked **(0.8.0+)** is not in 0.7.x, **(0.7.0+)** not in 0.6.x
+> and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
 - ESM only, no runtime dependencies, Node.js 24 or later. Reading a YAML template file uses the optional peer
@@ -383,15 +383,23 @@ parameters and an `execute` function. Export them for your model provider and di
 calls:
 
 ```ts
+import Anthropic from '@anthropic-ai/sdk';
 import { executeToolCall, toAnthropicTools, toOpenAITools, workspaceTools } from '@shardflux/sdk';
 
 const tools = workspaceTools(workspace);
-const anthropicTools = toAnthropicTools(tools);   // or toOpenAITools(tools)
+const anthropicTools: Anthropic.Tool[] = toAnthropicTools(tools);
+const chatTools = toOpenAITools(tools);                               // OpenAI Chat Completions
+const responsesTools = toOpenAITools(tools, { api: 'responses' });    // OpenAI Responses API
 
-// For each tool call the model makes:
-const output = await executeToolCall(tools, { name: call.name, input: call.input });
+// For each tool call the model makes (an Anthropic tool_use block, or an OpenAI function_call item, as it is):
+const output = await executeToolCall(tools, block);
 ```
 
+**(0.8.0+)** The exports type-check as the provider SDKs' own types under `strict`, with no casts:
+`Anthropic.Tool[]`, `OpenAI.Chat.ChatCompletionTool[]` and, with `{ api: 'responses' }`,
+`OpenAI.Responses.FunctionTool[]`. `executeToolCall` takes a `tool_use` block's `unknown` input as it is and validates
+it.
+
 Your agent loop and model calls stay in your application; the workspace is the computer the tools
 act on.
 
@@ -561,7 +569,7 @@ route. The package exports the OpenAPI-generated types as well (`paths`, `compon
 
 - The SDK follows the API's `/v1` contract. New fields, enum values and error codes can appear in
   any release; ignore unknown fields.
-- While below 1.0, a breaking change bumps the minor version (0.6 to 0.7).
+- While below 1.0, a breaking change bumps the minor version (0.7 to 0.8).
 - `SDK_VERSION` is exported; requests send `User-Agent: shardflux-sdk-ts/<version>`.
 - Examples in this README, in `examples/` and on shardflux.dev name the version they need. The examples on the
   website and in the console are checked against the version published on npm before they ship.

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.8.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

package/dist/http.js

@@ -6,7 +6,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.7.0';
+export const SDK_VERSION = '0.8.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

package/dist/index.d.ts

@@ -39,7 +39,7 @@ export type { BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, C
 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';

package/dist/tools.d.ts

@@ -1,7 +1,12 @@
 import type { CellClientOptions } from './cell.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>;
@@ -16,7 +21,7 @@ export interface JsonSchema {
     minItems?: number;
     maxItems?: number;
     default?: unknown;
-}
+};
 export interface WorkspaceTool<A extends Record<string, unknown> = Record<string, unknown>, R = unknown> {
     name: string;
     description: string;
@@ -56,44 +61,62 @@ export interface WorkspaceToolsOptions {
 }
 /** 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?: {

package/dist/tools.js

@@ -305,7 +305,6 @@ export function workspaceTools(workspace, opts = {}) {
         },
     }));
 }
-/** OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`) or Responses API. */
 export function toOpenAITools(tools, opts = {}) {
     return opts.api === 'responses'
         ? tools.map((t) => ({ type: 'function', name: t.name, description: t.description, parameters: t.parameters, strict: false }))
@@ -318,7 +317,9 @@ export function toAnthropicTools(tools) {
 /**
  * Runs a model's tool call: `arguments` may be the JSON string (OpenAI) or an object (Anthropic
  * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError). 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 async function executeToolCall(tools, call, options = {}) {
     const tool = tools.find((t) => t.name === call.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",
@@ -60,6 +60,7 @@
     "ajv": "8.20.0",
     "eslint": "10.11.0",
     "langchain": "1.5.14",
+    "openai": "7.23.0",
     "openapi-typescript": "7.13.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.70.1",