Tianyi Cui
225ed051b1
Nominal string types via a unique-symbol brand (zero runtime cost): an AgentId can no longer be passed where a CallId is expected. Each core package brands the IDs it owns — CallId in dsh-llm (tool-call correlation across blocks, chunks, session events, and execution results), SessionId in dsh-session, AgentId in dsh-agent. Construction goes through same-named factory functions; public string-in APIs (sessions.create, agentLoop.create) keep accepting plain strings and brand internally. Policy note in the brand module: brand IDs that cross package boundaries, not every string.
dsh-tools
Tool registry and execution waterfall. Tool plugins register their schemas and
executors; the agent loop executes calls through the tools/execute waterfall.
Service: ToolRegistry (ctx key: tools)
Public API
ctx.tools.register(definition: ToolDefinition): () => voidRegister a tool. Disposed with the calling fiber.ctx.tools.get(name: string): ToolDefinition | undefinedctx.tools.schemas(): ToolSchema[]Schemas of all registered tools (without theexecutefunctions).ctx.tools.execute(exec: ToolExecution): Promise<ToolExecutionResult>Execute one tool call through thetools/executewaterfall.
Injected services
SystemPrompt — the registry automatically feeds its tool schemas into the
system-prompt assembly via ctx.systemPrompt.tools().
Events
| Event | Mode | Purpose |
|---|---|---|
tools/execute |
waterfall | Wrap/veto tool execution (sandbox, permission, hooks, plan mode) |
tools/change |
emit | A tool was registered or unregistered |
Key types
ToolDefinition—ToolSchema+execute(args, exec): Promise<ContentBlock[]>.ToolExecution— one pending tool call:{ callId, name, arguments, agent?, signal? }.ToolExecutionResult— outcome:{ callId, content, isError }.
Extension points
- Tool plugins call
ctx.tools.register()— schemas flow into the assembly automatically. - The
tools/executewaterfall is the single seam for sandbox, permission, hooks, and plan-mode plugins to wrap or veto a call. Listeners receive(exec, next): callnext()to proceed, or return a result without callingnext()to short-circuit (veto). - MCP servers: one plugin per server, discover tools, call
ctx.tools.register()with the server's schemas.
Typed tool parameter schemas
First-party plugin authors can use the defineTool() helper (exported from this
package) for typed tool parameter schemas:
import { defineTool } from '@deepseek-ai/dsh-tools'
ctx.tools.register(defineTool({
name: 'read_file',
description: 'Read a file from disk.',
parameters: {
path: { type: 'string', required: true, description: 'Absolute file path' },
offset: { type: 'number' },
limit: { type: 'number' },
},
async execute(args, exec) {
// args is typed: { path: string; offset?: number; limit?: number }
const text = await readFile(args.path, 'utf8')
return [{ type: 'text', text }]
},
}))
The helper converts the author-facing SchemaSpec (with required: true as a
per-property boolean) to standard JSON Schema for the wire format. Raw
JSON-Schema tool definitions (from MCP servers) are still accepted by the
registry directly.
See defineTool, SchemaSpec, InferArgs, and schemaSpecToJsonSchema in the
public API for details.
What is NOT here (TODO)
- Tool shapes review — when real tools land (e.g. a concurrency-safety hint for parallel execution); phase 1 executes tool calls sequentially.
- Parallel execution — the loop currently iterates tool calls sequentially.