Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: unwrap hard-wrapped Markdown to one line per paragraph

Browse Source 
Hard line breaks mid-paragraph make docs harder to edit and diff — a
one-word change reflows and re-diffs the whole paragraph. Reflow all
tracked non-vendor Markdown (plus vendor/AGENTS.md) so each prose
paragraph is a single line; soft-wrapping is the editor's job. Fenced
code, tables, and list structure are preserved (wrapped list items fold
to one line per bullet). Documents the convention in AGENTS.md.
This commit is contained in:
Tianyi Cui
2026-06-13 18:39:20 +08:00
parent e98c1c5d42
commit 066f94c7e0
39 changed files with 348 additions and 1206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
packages/tools/README.md
View File

@@ -1,24 +1,19 @@
# dsh-tools
Tool registry and execution waterfall. Tool plugins register their schemas and
executors; the agent loop executes calls through the `tools/execute` waterfall.
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.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.
- `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()`.
`SystemPrompt` — the registry automatically feeds its tool schemas into the system-prompt assembly via `ctx.systemPrompt.tools()`.
### Events
@@ -35,19 +30,13 @@ system-prompt assembly via `ctx.systemPrompt.tools()`.
### 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.
- 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:
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'
@@ -68,16 +57,11 @@ ctx.tools.register(defineTool({
}))
```
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.
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.
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.
- **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.