Tianyi Cui
7f024a1a9d
Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# 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): () => void`
|
|
Register a tool. Disposed with the calling fiber.
|
|
- `ctx.tools.get(name: string): ToolDefinition | undefined`
|
|
- `ctx.tools.schemas(): ToolSchema[]`
|
|
Schemas of all registered tools (without the `execute` functions).
|
|
- `ctx.tools.execute(exec: ToolExecution): Promise<ToolExecutionResult>`
|
|
Execute one tool call through the `tools/execute` waterfall.
|
|
|
|
### 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/execute` waterfall is the single seam for sandbox, permission,
|
|
hooks, and plan-mode plugins to wrap or veto a call. Listeners receive
|
|
`(exec, next)`: call `next()` to proceed, or return a result without calling
|
|
`next()` 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:
|
|
|
|
```ts
|
|
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.
|