7.0 KiB
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.
ctx.tools.register(definition)
/**
* 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.
ctx.tools.restrict(filter)
/**
* 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/ordeny(remove).
Returns the exact disposer that lifts this restriction.
ctx.tools.guard(guard)
/**
* 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.
ctx.tools.get(name, scope?)
/**
* 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.
ctx.tools.schemas(scope?)
/**
* 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.
ctx.tools.executionMode(exec)
/**
* 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.
ctx.tools.execute(exec)
/**
* 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.