2cde2a9032
Conflict resolution notes: - package.json/run-gates: both sides' new doc-sync gates kept (master's scoped-events/readme gates + this branch's website-api/website-yaml); js-yaml devDeps deduped (master added them independently). - pnpm-workspace/knip: website AND python/sdk-runtime entries kept. - doc-typecheck/verify-type-equiv: master's condensed headers kept, website glob retained in both scan scopes. - vendor/cordis/src/fiber.ts: master's lifecycle-hardening code taken; this branch's richer FiberState JSDoc reapplied on top. vendor/README.md logs both local modifications (hardening = 6, JSDoc enrichment = 7). - pnpm-lock: regenerated from master's side (pnpm install). Post-merge sync the gates forced (the system working as designed): - verify-website-yaml caught 4 stale plugin names from master's package reorg (dsh-stdio-agent -> dsh-stdio-demo, dsh-acp-agent -> dsh-acp-demo); 8 references fixed across guide/ and develop/. - gen-website-api picked up master's 6 new services automatically (ctx.approval/permission/sandbox/sessionQuery/skills/tasks -> 6 new pages + sidebar); api/index.md hub updated to list them. - AGENTS.md budget ceiling 1370 -> 1400: the website rows (layout line + two command lines) and master's own growth collided with the old ceiling; all three website rows are load-bearing (new top-level dir, new CI command).
95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
|
|
|
|
# ctx.tools
|
|
|
|
`ToolRegistry` — provided by `@deepseek-ai/dsh-tools`.
|
|
|
|
Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L363)
|
|
|
|
### ctx.tools.register(definition)
|
|
|
|
```ts website-api
|
|
register(definition: ToolDefinition): () => void
|
|
```
|
|
|
|
Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.
|
|
|
|
- `definition` — the tool schema, execution, and optional presentation functions.
|
|
|
|
**Returns** the exact disposer that unregisters the tool.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L453)
|
|
|
|
### ctx.tools.restrict(filter)
|
|
|
|
```ts website-api
|
|
restrict(filter: ToolRestriction): () => void
|
|
```
|
|
|
|
Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.
|
|
|
|
- `filter` — global-surface mask: `allow` (keep only) and/or `deny` (remove).
|
|
|
|
**Returns** the exact disposer that lifts this restriction.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L493)
|
|
|
|
### ctx.tools.guard(guard)
|
|
|
|
```ts website-api
|
|
guard(guard: ToolGuard): () => void
|
|
```
|
|
|
|
Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.
|
|
|
|
- `guard` — synchronous check; a returned string denies the execution.
|
|
|
|
**Returns** the exact disposer that unregisters the guard.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L544)
|
|
|
|
### ctx.tools.get(name, scope?)
|
|
|
|
```ts website-api
|
|
get(name: string, scope?: ScopeKey): ToolDefinition | undefined
|
|
```
|
|
|
|
Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.
|
|
|
|
- `name` — the tool name as registered.
|
|
- `scope` — the viewing scope (the agent); omitted = the global view.
|
|
|
|
**Returns** the definition the scope resolves, or undefined when none is visible.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L646)
|
|
|
|
### ctx.tools.schemas(scope?)
|
|
|
|
```ts website-api
|
|
schemas(scope?: ScopeKey): ToolSchema[]
|
|
```
|
|
|
|
Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.
|
|
|
|
- `scope` — the viewing scope (the agent); omitted = the global view.
|
|
|
|
**Returns** one deep-cloned schema per visible tool.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L656)
|
|
|
|
### ctx.tools.execute(exec)
|
|
|
|
```ts website-api
|
|
async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
|
|
```
|
|
|
|
Execute through pre-policy, guards, around-dispatch, post-policy, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive.
|
|
|
|
- `exec` — the typed same-process call input. The registry assigns its correlation token before policy begins.
|
|
|
|
**Returns** the materialized final result.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L679)
|