메뉴
Use when adding or changing a Canvas Agent tool (canvas_* / workspace_node_* in src/main/agent/tools/). Covers the two registration surfaces, the ZodObject trap, the tool-name compatibility contract, defer_loading, and the execute-class security gate.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Select and run proportionate validation for changes to apps/canvas-workspace. Use when iterating on Canvas Workspace code, finishing a feature or fix, preparing release evidence, or deciding whether a full performance report is necessary.
Deep-research a topic and build a structured Pulse Canvas workspace with approved research depth, source-backed findings, progressive or final canvas creation, spatially organized frames, content nodes, and connections. Use when the user asks to bootstrap, generate, research, organize, or build an AI-created canvas.
Extend an existing Pulse Canvas frame with local, source-backed research while preserving the surrounding canvas. Use when the user asks to research, enrich, expand, verify, update, or add sources/details inside a selected or named frame, rather than bootstrapping a whole new canvas.
Operate Pulse Canvas workspaces — read user-curated context, write results, create nodes
Add or change a Pulse Canvas capability that must be available through structured agent tools and the pulse-canvas CLI. Use for cross-workspace Capability Runtime changes spanning apps/canvas-workspace, packages/canvas-cli, or packages/cli, including new live read, operate, or unsafe application actions.
Run the canvas-workspace performance evaluation, publish the latest static dashboard through the local nginx/Cloudflare Tunnel route, capture a screenshot, and summarize the report. Use when the user asks to run Pulse Canvas/canvas-workspace perf checks, deploy the performance dashboard, refresh https://jasperhu.art/apps/canvas-perf/, or send a dashboard screenshot from Feishu/remote-server.
| name | add-agent-tool |
| description | Use when adding or changing a Canvas Agent tool (canvas_* / workspace_node_* in src/main/agent/tools/). Covers the two registration surfaces, the ZodObject trap, the tool-name compatibility contract, defer_loading, and the execute-class security gate. |
An ordered procedure. Gives the SEQUENCE and the landmines; FACTS live in the sources it points to — do not restate them here.
Snapshot the registry first. node apps/canvas-workspace/harness/tools/describe-canvas.mjs — see the current 45+ tools, the naming conventions per file, and whether your name collides (duplicate names are a hard error there). Note: describe-canvas checks NAMES only — it does NOT verify the global-chat surface (landmine 3 below), so passing it is necessary, not sufficient.
Implement the tool in the matching per-capability module under src/main/agent/tools/ (nodes/edges/sessions/terminals/… — match your capability's siblings' shape: name, description, zod inputSchema, execute).
Register on BOTH surfaces if the tool should work in global chat. src/main/agent/tools/index.ts has TWO factories: createCanvasTools(workspaceId) (workspace-scoped chat) and createGlobalCanvasTools() (global chat, no ambient workspace). A tool only added to the first silently does not exist in global chat. Global-surface tools must be wrapped in requireWorkspaceId(...) so the LLM supplies the workspace explicitly.
The ZodObject trap. requireWorkspaceId (tools/index.ts:28) only .extends the schema when inputSchema instanceof z.ZodObject — any non-object schema is silently NOT extended, and the global-chat variant breaks without a compile error. Keep tool input schemas object-shaped.
The tool name is a compatibility contract. harness/knowledge/main-domain-modules.md Compatibility Rules lists "canvas-agent tool names" as must-not-change — persisted sessions and skills reference them. Naming convention: canvas_* / workspace_node_*, snake_case. Renaming an existing tool is a breaking change, not a refactor.
Decide defer_loading consciously. A deferred tool (see terminals.ts:17) is hidden from the LLM until a tool_search_* call loads it. Defer heavy/rare tools; load-immediately for core ones.
Execute-class tools go through the security gate. If the tool spawns/executes/writes outside the canvas store (anything bash-shaped, PTY-shaped, or filesystem-shaped), read harness/knowledge/security-posture.md ("When you change things here") and the canvas_create_terminal_node precedent in terminals.ts BEFORE implementing — you are widening what a prompt-injected LLM can do at main-process privilege.
Verify. Re-run describe-canvas (name registered, no dup); pnpm --filter canvas-workspace typecheck && pnpm --filter canvas-workspace test.
The tool appears in describe-canvas's registry; it is on both factories (or the workspace-only choice is stated in the PR); schema is a ZodObject; name follows the convention; defer_loading is a conscious choice; execute-class gate consulted if applicable; typecheck + test green.
