109 lines
4.7 KiB
Markdown
109 lines
4.7 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#L447)
|
|
|
|
### 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#L547)
|
|
|
|
### 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#L587)
|
|
|
|
### 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#L638)
|
|
|
|
### 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#L740)
|
|
|
|
### 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#L750)
|
|
|
|
### ctx.tools.executionMode(exec)
|
|
|
|
```ts website-api
|
|
executionMode(exec: ToolExecutionInput): ToolExecutionMode
|
|
```
|
|
|
|
Classify how one pending call may be scheduled relative to its siblings in the same assistant step. Looks up the tool through the caller's visible scoped view and calls its `isConcurrencySafe(exec.arguments)` classifier. Only an explicit `true` yields `{ kind: 'parallel' }`; unknown, restricted-away, undeclared, falsey, or throwing checks fail closed to `{ kind: 'exclusive' }`.
|
|
|
|
- `exec` — the call to classify (name, parsed arguments, optional agent scope).
|
|
|
|
**Returns** the conservative scheduling mode for this call.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L774)
|
|
|
|
### 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. Scheduler staging preserves these semantics when dispatches overlap.
|
|
|
|
- `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#L795)
|