Tianyi Cui
63425a2b87
Per review feedback (use a real markdown parser with an AST linked to source positions), rewrite verify-md-wrap to parse each file with mdast-util-from-markdown (the CommonMark parser behind remark) + the GFM extension, then flag any `paragraph` node whose source span covers more than one line. Why a parser over the hand-rolled line scanner: - It is a checker, not a formatter — it reports and never rewrites, so zero cosmetic churn (no emphasis-marker or table-delimiter normalization, which is why Prettier was rejected for this). - The AST owns every structural exemption (fenced code of any fence length, tables, lists, blockquotes, HTML, headings, reference defs), fixing both bugs the regex version had: it now catches wrapped list-item / blockquote prose (a `paragraph` inside those nodes) and no longer false-positives on a longer ```` fence wrapping an inner ```. Also unwrap two pre-existing hard-wrapped blockquotes (architecture.md, adding-a-tool.md) that the stricter AST check correctly surfaced.
54 lines
3.5 KiB
Markdown
54 lines
3.5 KiB
Markdown
# Cookbook: adding a tool
|
|
|
|
How to give the model a new capability. Reference implementations: `examples/echo-agent/src/echo-tool.ts` (minimal) and `packages/tool-bash` (production-grade, three-package seam).
|
|
|
|
## The minimal shape
|
|
|
|
```ts
|
|
import { readFile } from 'node:fs/promises'
|
|
import type { Context } from 'cordis'
|
|
import { defineTool } from '@deepseek-ai/dsh-tools'
|
|
|
|
export const name = 'my-tool'
|
|
export const inject = ['tools']
|
|
|
|
export function apply(ctx: Context) {
|
|
ctx.tools.register(defineTool({
|
|
name: 'read_file',
|
|
description: 'Read a file from disk.', // what the model sees
|
|
parameters: {
|
|
path: { type: 'string', required: true, description: 'Absolute path' },
|
|
limit: { type: 'number' }, // optional by default
|
|
},
|
|
async execute(args, exec) {
|
|
// args is TYPED from the schema: { path: string; limit?: number }
|
|
// exec carries { callId, name, arguments, agent?, signal? }
|
|
return [{ type: 'text', text: await readFile(args.path, 'utf8') }]
|
|
},
|
|
}))
|
|
}
|
|
```
|
|
|
|
Registration is effect-based: disposing the plugin fiber unregisters the tool (write the HMR test). Schemas flow into the system-prompt assembly automatically.
|
|
|
|
## Rules of the execute() contract
|
|
|
|
- **Args are validated for you.** `defineTool` validates the model-generated `arguments` against the `SchemaSpec` before `execute` runs (type, required keys, enum membership, nested objects/arrays — ADR 0011), so inside `execute` the args already match `InferArgs`. You still hand-check value constraints the DSL can't express (non-empty strings, positive numbers, cross-field rules); throw a descriptive Error for those. Raw JSON-Schema tools registered directly (MCP) are NOT validated by the harness — they validate their own input.
|
|
- **Throwing means isError.** The registry catches anything `execute()` throws and returns `{isError: true}` to the model. Use that for infrastructure failures (bad input, spawn errors, aborts) — but REPORT domain failures in the result text instead (e.g. tool-bash returns `[exit code: 9]` with `isError: false`: the model decides what a failing command means).
|
|
- **Honor `exec.signal`.** Cancel in-flight work when it fires.
|
|
- **Use `exec.agent` for async notifications.** `agent.inject(content, {source: {kind: 'plugin', plugin: '<name>'}})` appends durable context the NEXT model request sees — it is not a wake-up (an idle agent stays idle). Guard against disposed agents (try/catch).
|
|
|
|
## Long-running work
|
|
|
|
Follow tool-bash's background pattern: a `run_in_background` flag returns a task id immediately; companion tools poll incrementally and kill; completion notices arrive via `agent.inject()`. Bound buffers and spill full output to disk so nothing is silently lost.
|
|
|
|
> TODO: each tool reimplements this background pattern by hand today. At some point we need a generic long-running-tool layer that handles task ids, incremental polling, kill, and completion notices uniformly.
|
|
|
|
## Permissions / sandboxing
|
|
|
|
Prefer not to build policy into the tool. The seam is the `tools/execute` waterfall (veto or wrap — see the permission-gate example in [extension-cookbook.md](./extension-cookbook.md)), or a sandboxing implementation behind the tool's executor seam.
|
|
|
|
## Tests every tool needs
|
|
|
|
Arg-validation rejections, result shaping for every outcome, the HMR disposal test, and — for tools with side effects — an integration spec that drives the tool through the agent loop with a scripted `MockAdapter` (`packages/agent-loop/tests/mock-adapter.ts`), asserting the `tool/call` / `tool/result` session events.
|