163 lines
7.0 KiB
Markdown
163 lines
7.0 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#L438)
|
|
|
|
### ctx.tools.register(definition)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Register globally or in the calling agent scope. Scoped tools shadow
|
|
* globals; duplicates within one layer and the reserved `run_code` name fail.
|
|
* @param definition - the tool schema, execution, and optional presentation functions.
|
|
* @returns the exact disposer that unregisters the tool.
|
|
*/
|
|
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#L538)
|
|
|
|
### ctx.tools.restrict(filter)
|
|
|
|
```ts website-api
|
|
/**
|
|
* 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.
|
|
* @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
|
|
* @returns the exact disposer that lifts this restriction.
|
|
*/
|
|
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#L578)
|
|
|
|
### ctx.tools.guard(guard)
|
|
|
|
```ts website-api
|
|
/**
|
|
* 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.
|
|
* @param guard - synchronous check; a returned string denies the execution.
|
|
* @returns the exact disposer that unregisters the guard.
|
|
*/
|
|
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#L629)
|
|
|
|
### ctx.tools.get(name, scope?)
|
|
|
|
```ts website-api
|
|
/**
|
|
* 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.
|
|
* @param name - the tool name as registered.
|
|
* @param scope - the viewing scope (the agent); omitted = the global view.
|
|
* @returns the definition the scope resolves, or undefined when none is visible.
|
|
*/
|
|
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#L731)
|
|
|
|
### ctx.tools.schemas(scope?)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Project visible definitions onto the allowlisted model-facing schema fields,
|
|
* excluding execution and presentation callbacks.
|
|
* @param scope - the viewing scope (the agent); omitted = the global view.
|
|
* @returns one deep-cloned schema per visible tool.
|
|
*/
|
|
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#L741)
|
|
|
|
### ctx.tools.executionMode(exec)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Classify a pending call through the caller's visible tool definition. Only
|
|
* an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
|
|
* throwing classifiers are exclusive.
|
|
* @param exec - call name, parsed arguments, and optional agent scope.
|
|
* @returns the fail-closed scheduling mode.
|
|
*/
|
|
executionMode(exec: ToolExecutionInput): ToolExecutionMode
|
|
```
|
|
|
|
Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.
|
|
|
|
- `exec` — call name, parsed arguments, and optional agent scope.
|
|
|
|
**Returns** the fail-closed scheduling mode.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L762)
|
|
|
|
### ctx.tools.execute(exec)
|
|
|
|
```ts website-api
|
|
/**
|
|
* 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.
|
|
* @param exec - the typed same-process call input. The registry assigns its
|
|
* correlation token before policy begins.
|
|
* @returns the materialized final result.
|
|
*/
|
|
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#L782)
|