4.7 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(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(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)
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?)
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?)
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)
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.
ctx.tools.execute(exec)
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.