feat: client side tool calls

[cgilly2fast]

Summary

Adds client-side tool support for DedalusRunner, enabling tools that require user interaction or browser APIs to be handled on the client rather than executed by the runner.

Key Changes

New types and exports

• Tool is now a union type: ToolFunction | ToolDefinition
• ToolFunction - plain callable function (always server-side, original tool definition)
• ToolDefinition - structured tool with explicit schema, optional execute. Closely mirrors the Dedalus API tools schema (name, description, parameters, strict), with an added execute function for server-side execution
• ToolHandler - interface for tool registration and execution
• ToolParametersSchema - JSON Schema type for parameters

Client-side tool execution pattern

• Tools WITH an execute function are server-side tools (executed by the runner)
• Tools WITHOUT an execute function are client-side tools (forwarded to the client via stream)
• When a turn contains both types, server tools execute first, then the runner pauses and returns control to the client to handle the remaining tool calls

Zod schema support

• Tool parameters now accept Zod schemas in addition to JSON Schema objects
• Added shared zodToJsonSchema() utility used by both ToolDefinition and the existing zodResponseFormat helper

Documentation

• Added DedalusRunner section to README covering basic usage, tool definitions, client-side tools, streaming, RunResult properties, and configuration options

Usage Example

// ToolFunction (original plain function)
function helloWorld() {
  return 'Hello, world!';
}

// ToolDefinition - server-side (has execute)
const getWeather: ToolDefinition = {
  name: 'getWeather',
  description: 'Get current weather for a location',
  parameters: z.object({ location: z.string() }),
  execute: async ({ location }) => fetchWeather(location),
};

// ToolDefinition - client-side (no execute)
const askConfirmation: ToolDefinition = {
  name: 'askConfirmation',
  parameters: z.object({ message: z.string() }),
  // No execute - handled on client
};

const result = await runner.run({
  model: 'openai/gpt-4o',
  tools: [helloWorld, getWeather, askConfirmation],
  input: 'What is the weather in NYC?',
});

Testing

• Added 19 tests for tool handler (tools.test.ts)
• Added 10 tests for runner client tool behavior (runner-client-tools.test.ts)
• All 377 tests pass

---

Note

Adds client-side tool handling to DedalusRunner, introduces ToolDefinition/ToolFunction typing with Zod/JSON Schema support, updates execution flow, and documents usage with comprehensive tests.

• Runner:
  • Supports client-side tools by separating tool calls into server-executed vs client-handled; executes server tools then pauses for client tools.
  • Logs server vs client tools; uses toolHandler.schemas/toolNames; fixes MCP/local tool name checks.
• Tools & Types:
  • Introduces ToolDefinition, ToolFunction, ToolParametersSchema, and ToolHandler; Tool is now a union.
  • New createToolHandler() registers tools, exposes schemas, toolNames, isClientTool(), and guarded exec().
• Utils:
  • Adds toSchemaFromDefinition() to convert ToolDefinition (JSON Schema or Zod) to API schema.
  • Adds utils/zod with isZodSchema() and zodToJsonSchema() used across helpers.
  • Re-exports toSchemaFromDefinition from public indexes.
• Zod Helpers:
  • Refactor zodResponseFormat() and zodFunction() to use shared Zod utils and simplify JSON Schema conversion.
• Docs:
  • README: new DedalusRunner section with usage, tool definitions, client-side tools, streaming, RunResult, and config.
• Tests:
  • Add suites for client-side tool behavior in runner and for tool handler registration/execution; add mock client utility.

^{Written by Cursor Bugbot for commit f5cd48c. This will update automatically on new commits. Configure here.}

[cgilly2fast]

Of course open to any feedback

[windsornguyen]

Tracking with TYSDK-1