lintianle
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).
3.9 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.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.
exec— the typed same-process call input. The registry assigns its correlation token before policy begins.
Returns the materialized final result.