影 kaged
← back to status

@kaged/agent-tooling

Declarative tool definitions, registry, and permission enforcement for 31 built-in tools across file, search, LSP, DAP, and kaged namespaces

17
source files
5
test files
~3.6k
lines
✓ 147 pass
tests
pass
typecheck
clean
lint

Test results 147

✓ resolveToolConfig — no config > enabled by default when no config layers mention the tool [0.200ms]
✓ resolveToolConfig — no config > enabled by default when config layers exist but don't mention this tool [0.050ms]
✓ resolveToolConfig — single layer > explicit enabled: true [0.050ms]
✓ resolveToolConfig — single layer > explicit enabled: false [0.030ms]
✓ resolveToolConfig — single layer > description override [0.040ms]
✓ resolveToolConfig — ADR-0015 nullification > null value nullifies the tool (re-enabled by default) [0.030ms]
✓ resolveToolConfig — ADR-0015 nullification > null followed by new config re-establishes overrides [0.040ms]
✓ resolveToolConfig — deep merge across layers > later layers override earlier layers [0.040ms]
✓ resolveToolConfig — deep merge across layers > parameters deep-merge across layers [0.040ms]
✓ resolveToolConfig — deep merge across layers > later parameter values override earlier ones [0.030ms]
✓ resolveToolConfigBatch > resolves all tools in one pass [0.140ms]
✓ filterEnabledTools > filters out disabled tools [0.130ms]
✓ filterEnabledTools > returns all tools when no config disables any [0.270ms]
✓ filterEnabledTools > filters out nullified tools only if last layer is null [0.030ms]
✓ built-in tool counts > FILE_TOOLS has 5 tools [0.020ms]
✓ built-in tool counts > SEARCH_TOOLS has 3 tools [0.010ms]
✓ built-in tool counts > CODE_LSP_TOOLS has 1 tool [0.010ms]
✓ built-in tool counts > DEBUG_TOOLS has 1 tool [0.020ms]
✓ built-in tool counts > CHECKPOINT_TOOLS has 1 tool [0.010ms]
✓ built-in tool counts > SHELL_TOOLS has 1 tool [0.010ms]
✓ built-in tool counts > COMPUTE_TOOLS has 1 tool [0.010ms]
✓ built-in tool counts > PROJECT_RECIPE_TOOLS has 1 tool [0.020ms]
✓ built-in tool counts > ALL_BUILTIN_TOOLS is the union (18 total) [0.020ms]
✓ tool names follow naming convention > every tool name starts with its namespace [0.120ms]
✓ tool names follow naming convention > most tools use namespace.action[.sub] (debug is the singleton exception) [0.260ms]
✓ tool names are unique > no duplicate names in ALL_BUILTIN_TOOLS [0.070ms]
✓ all tools have required fields > file.read has description, parameters, returns, requires [0.110ms]
✓ all tools have required fields > file.write has description, parameters, returns, requires [0.010ms]
✓ all tools have required fields > edit.text has description, parameters, returns, requires [0.010ms]
✓ all tools have required fields > edit.ast has description, parameters, returns, requires [0ms]
✓ all tools have required fields > file.create has description, parameters, returns, requires [0ms]
✓ all tools have required fields > search.grep has description, parameters, returns, requires [0ms]
✓ all tools have required fields > search.glob has description, parameters, returns, requires [0ms]
✓ all tools have required fields > search.ast has description, parameters, returns, requires [0.010ms]
✓ all tools have required fields > code.lsp has description, parameters, returns, requires [0ms]
✓ all tools have required fields > debug has description, parameters, returns, requires [0ms]
✓ all tools have required fields > shell.bash has description, parameters, returns, requires [0ms]
✓ all tools have required fields > compute.calc has description, parameters, returns, requires [0ms]
✓ all tools have required fields > project.recipe has description, parameters, returns, requires [0ms]
✓ all tools have required fields > kaged.checkpoint has description, parameters, returns, requires [0.010ms]
✓ all tools have required fields > kaged.issue has description, parameters, returns, requires [0.010ms]
✓ all tools have required fields > kaged.todo has description, parameters, returns, requires [0.010ms]
✓ all tools have required fields > kaged.ask has description, parameters, returns, requires [0ms]
✓ all tools have required fields > kaged.form has description, parameters, returns, requires [0ms]
✓ file tools > file.read requires ro fs [0.050ms]
✓ file tools > file.write requires rw fs [0.030ms]
✓ file tools > edit.text requires rw fs [0.020ms]
✓ file tools > file.create requires rw fs [0.020ms]
✓ file tools > file.read has path as required param [0.040ms]
✓ file tools > edit.text has old_string, new_string as required params [0.070ms]
✓ search tools > search.grep requires ro fs [0.030ms]
✓ search tools > search.ast requires pattern and lang [0.020ms]
✓ code.lsp tool (unified) > code.lsp exists and is in code namespace [0.020ms]
✓ code.lsp tool (unified) > code.lsp requires rw fs (superset for rename) [0.030ms]
✓ code.lsp tool (unified) > code.lsp requires action param [0.020ms]
✓ code.lsp tool (unified) > getBuiltinsByNamespace returns code tools [0.060ms]
✓ debug tool (unified) > debug exists and is in debug namespace [0.020ms]
✓ debug tool (unified) > debug requires fs ro and exec capability [0.040ms]
✓ debug tool (unified) > debug requires action param [0.020ms]
✓ debug tool (unified) > getBuiltinsByNamespace returns debug tools [0.040ms]
✓ shell tools > shell.bash exists and is in shell namespace [0.030ms]
✓ shell tools > shell.bash requires command [0.020ms]
✓ shell tools > shell.bash requires rw fs and shell capability [0.030ms]
✓ shell tools > shell.bash returns stdout, stderr, exit_code, timed_out [0.030ms]
✓ shell tools > getBuiltinsByNamespace returns shell tools [0.030ms]
✓ kaged tools > kaged.checkpoint exists and is in kaged namespace [0.020ms]
✓ kaged tools > kaged.checkpoint has no permission requirements [0.020ms]
✓ kaged tools > kaged.checkpoint accepts optional reason param [0.020ms]
✓ kaged tools > kaged.checkpoint returns status and message [0.030ms]
✓ kaged tools > kaged.checkpoint description matches spec [0.030ms]
✓ kaged tools > getBuiltinsByNamespace returns kaged tools [0.080ms]
✓ getBuiltinTool > returns the tool for a known name [0.020ms]
✓ getBuiltinTool > returns undefined for unknown name [0.020ms]
✓ getBuiltinsByNamespace > returns file tools for 'file' namespace [0.040ms]
✓ getBuiltinsByNamespace > returns empty for unknown namespace [0.040ms]
✓ compute tools > compute.calc exists and is in compute namespace [0.040ms]
✓ compute tools > compute.calc has no permission requirements [0.020ms]
✓ compute tools > compute.calc requires calculations param [0.020ms]
✓ compute tools > compute.calc returns results array [0.020ms]
✓ compute tools > getBuiltinsByNamespace returns compute tools [0.030ms]
✓ project.recipe tool > project.recipe exists and is in project namespace [0.020ms]
✓ project.recipe tool > project.recipe requires op param [0.020ms]
✓ project.recipe tool > project.recipe requires rw fs and shell capability [0.030ms]
✓ project.recipe tool > project.recipe returns runner, command, stdout, stderr, exit_code, timed_out, available_tasks [0.120ms]
✓ project.recipe tool > getBuiltinsByNamespace returns project tools [0.050ms]
✓ checkPermission — primary agent (no cage) > always allowed for primary [0.200ms]
✓ checkPermission — disabled cage > allowed when cage is disabled [0.030ms]
✓ checkPermission — fs requirements > allows ro read within allowed path [0.150ms]
✓ checkPermission — fs requirements > denies ro read outside allowed path [0.060ms]
✓ checkPermission — fs requirements > allows rw write within rw mount [0.040ms]
✓ checkPermission — fs requirements > denies rw write within ro mount [0.030ms]
✓ checkPermission — fs requirements > denies when path param is missing [0.040ms]
✓ checkPermission — fs requirements > denies when path param is not a string [0.020ms]
✓ checkPermission — fs requirements > allows with multiple fs mounts [0.040ms]
✓ checkPermission — seccomp requirements > denies when tool needs relaxed but cage has default [0.040ms]
✓ checkPermission — seccomp requirements > allows when cage has relaxed seccomp [0.050ms]
✓ checkPermission — net requirements > denies when net target is not in allowlist [0.050ms]
✓ checkPermission — net requirements > allows when net target matches allowlist [0.070ms]
✓ checkPermission — net requirements > allows wildcard net [0.050ms]
✓ checkPermission — capability requirements > denies named capabilities for caged agents [0.050ms]
✓ checkPermission — no requires > always allowed for tools with empty requires [0.020ms]
✓ assertPermission > does not throw for allowed calls [0.070ms]
✓ assertPermission > throws ToolCallError for denied calls [0.120ms]
✓ ToolRegistry — construction > registers all builtins by default [0.130ms]
✓ ToolRegistry — construction > can skip builtin registration [0.030ms]
✓ ToolRegistry — register > registers a plugin tool [0.090ms]
✓ ToolRegistry — register > rejects duplicate registration [0.070ms]
✓ ToolRegistry — register > rejects plugin using reserved namespace [0.060ms]
✓ ToolRegistry — register > rejects kaged reserved namespace [0.050ms]
✓ ToolRegistry — unregister > removes a registered tool [0.040ms]
✓ ToolRegistry — unregister > returns false for non-existent tool [0.030ms]
✓ ToolRegistry — get > returns the definition for a registered tool [0.040ms]
✓ ToolRegistry — get > returns undefined for unknown tool [0.030ms]
✓ ToolRegistry — resolve > resolves wildcard namespace patterns [0.150ms]
✓ ToolRegistry — resolve > resolves multiple namespace patterns [0.060ms]
✓ ToolRegistry — resolve > resolves exact tool names [0.040ms]
✓ ToolRegistry — resolve > resolves * to all tools [0.050ms]
✓ ToolRegistry — resolve > deduplicates overlapping patterns [0.030ms]
✓ ToolRegistry — resolve > ignores non-existent exact names [0.030ms]
✓ ToolRegistry — resolve > ignores non-existent namespace wildcards [0.050ms]
✓ ToolRegistry — setHandler > sets a handler for a registered tool [0.070ms]
✓ ToolRegistry — setHandler > throws for non-existent tool [0.060ms]
✓ ToolRegistry — dispatch > returns tool_not_found for unknown tool [0.340ms]
✓ ToolRegistry — dispatch > returns tool_not_found when no handler is set [0.110ms]
✓ ToolRegistry — dispatch > dispatches to handler and returns result [0.120ms]
✓ ToolRegistry — dispatch > checks permissions before dispatch [0.130ms]
✓ ToolRegistry — dispatch > catches ToolCallError thrown by handler [0.200ms]
✓ ToolRegistry — dispatch > catches unexpected errors thrown by handler [0.130ms]
✓ ToolRegistry — listing > listAll returns all registered tools [0.250ms]
✓ ToolRegistry — listing > listByNamespace filters correctly [0.180ms]
✓ ToolRegistry — listing > listBySource returns builtins only [0.130ms]
✓ ToolRegistry — clear > empties the registry [0.050ms]
✓ ToolRegistry — principal_scope enforcement > primary caller can dispatch root-only tool [0.120ms]
✓ ToolRegistry — principal_scope enforcement > subagent caller gets principal_scope_violation [0.100ms]
✓ ToolRegistry — principal_scope enforcement > scope check runs before handler (handler never invoked) [0.090ms]
✓ ToolRegistry — principal_scope enforcement > scope check runs before cage permission check [0.090ms]
✓ ToolRegistry — principal_scope enforcement > tool without principal_scope allows subagent dispatch [0.130ms]
✓ BUILTIN_NAMESPACES > contains all nine built-in namespaces [0.040ms]
✓ BUILTIN_NAMESPACES > is readonly (frozen at type level) [0.020ms]
✓ RESERVED_NAMESPACE_PREFIXES > includes all built-in namespaces [0.040ms]
✓ ERROR_NUMERIC_CODES > maps dispatch errors to JSON-RPC codes [0.030ms]
✓ ToolCallError > constructs with code, message, and optional detail [0.040ms]
✓ ToolCallError > is an instance of Error [0.030ms]
✓ ToolCallError > toToolError returns structured ToolError [0.030ms]
✓ ToolCallError > toToolError omits detail when not provided [0.020ms]
✓ type assertions (compile-time) > ToolRequirement discriminated union covers all kinds [0.040ms]
✓ type assertions (compile-time) > ToolCallOutcome discriminated union [0.030ms]

Mentioned in

Type Document
adr ADR-0019: Workflows are operator-authored, parameterised DSL artifacts agents invoke
adr ADR-0022: Agents are recursive; tools and cage are per-agent
adr ADR-0032: Monaco Editor as the code editor for kaged UI
adr ADR-0033: Tool dot-namespace convention
adr ADR-0034: Sessions bind to one issue; the issue owns the agent's todos and drives closure
spec Spec: Agent Tooling
spec Spec: Agent Harness
spec Spec: Federated Project Configuration
spec Spec: HTTP + WebSocket API
spec Spec: Issues
spec Spec: Plugin Host
spec Spec: Project DSL
spec Spec: project.recipe
spec Spec: Session Manager
spec Spec: Workflows