Skip to content

Self-improving AI Employees for everyone

7.4 KB
Raw Blame

Canvas (canvas)

Field Value
Category tool / ai
Backend server/nodes/tool/canvas/__init__.py::CanvasNode.display (plugin folder: _store.py durable board, _handlers.py panel WS API, _events.py broadcast)
WS handlers canvas_list / canvas_remove / canvas_clear (self-registered; simple_memory security preamble: external socket + owner + graph-ownership checks)
Tests server/tests/nodes/test_canvas_node.py
Skill (if any) none
Dual-purpose tool ToolNode - tool name canvas (tool_schema_locked = True)

Purpose

A display board workflows and agents push content onto — the platform's Claude/ChatGPT-Canvas-style viewing surface. Agents call the canvas tool after producing something the user should see (a screenshot, a chart, a report, a URL); workflow edges push upstream file outputs automatically. The board renders in three hosts sharing one component: the node's full-height parameter panel (uiHints.isCanvasPanel), the docked right-side canvas sidebar (auto-opens on push, resizable, ephemeral click-to-preview mode), and the Canvas tab of Home's Workspace dock, which shows one employee's board. Hire gives every new employee a Canvas node, and its instructions ask it to put finished work there. Items are references (serialized FileRefs, URLs) and small markdown notes — never file bytes (media-transport contract).

Inputs (handles)

Handle Connection type Required Purpose
input-main main no Upstream output to display. Explicit params win; otherwise a structural FileRef scan of connected_outputs collects up to 20 refs (tts -> canvas works zero-config).
output-tool (source, top) tools no Connect to an agent's input-tools so the model can call canvas(...) mid-run.

Parameters

Name Type Default Required displayOptions.show Description
title string null no - Caption for the first item added by the call
paths string[] null no - Workspace-relative file paths (max 20/call). Coercions: JSON-string array, bare string, ref dicts -> their path
url string null no - External http(s) URL (scheme-validated)
content string null no - Markdown note, truncated at 64KB with a visible marker
language string null no - Syntax-highlight hint when content is code
mode append | replace append no - replace clears the board first

Outputs (handles)

Handle Shape Description
(tool result / node result) object Small by contract: ids and counts only, never bodies or refs — node results are persisted 3x, broadcast, and replayed into LLM context

Output payload (TypeScript shape)

{
  message: string;
  count: number;      // board size after the call (FIFO cap 200)
  revision: number;
  added: Array<{ id: string; kind: 'file' | 'url' | 'note'; title: string | null }>;
}

Logic Flow

flowchart TD
  A[display op] --> B[Scope: owner + workflow-or-unsaved + node_id]
  B --> C{Explicit params?}
  C -- paths --> D[resolve_media containment + stat -> FileRef, never read bytes]
  C -- url --> E[http/https scheme check]
  C -- content --> F[truncate_note 64KB]
  C -- none --> G[Structural FileRef scan of connected_outputs]
  D & E & F & G --> H{Any items?}
  H -- no --> I[NodeUserError: Nothing to display]
  H -- yes --> J[CanvasStore.append / replace - one transaction, revision++, FIFO evict at 200]
  J --> K[broadcast canvas_updated - identity + revision only]
  K --> L[Small output envelope]

Decision Logic

  • Validation: >20 paths -> NodeUserError; non-http(s) url -> NodeUserError; empty call (no params, no scanned refs) -> NodeUserError; unknown item kind -> CanvasStoreError -> NodeUserError.
  • Branches: explicit params vs connected-outputs scan (scan runs only when no explicit item was produced); mode=replace deletes the board's rows in the same transaction.
  • Fallbacks: workflow_id or "unsaved" scope; note truncation degrades instead of failing; source labeled agent iff _tool_config is on ctx.raw (the execute_as_tool marker), else workflow.
  • Error paths: containment failure inside resolve_media and missing files surface as one-WARN-line NodeUserErrors naming the path.

Side Effects

  • Database writes: canvas_boards (revision head) + canvas_items rows — plugin-owned tables (mount_store mechanism: import-time SQLModel registration + ensure_schema(checkfirst=True)), no core/database.py edits.
  • Broadcasts: canvas_updated CloudEvents envelope (com.opencompany.canvas.updated, subject = node_id, data = {workflow_id, node_id, revision} only) via get_status_broadcaster().broadcast directly — no canary consumer, so dispatch.emit would run a guaranteed-empty Visibility query.
  • External API calls: none.
  • File I/O: stat-only on displayed paths; never reads content to register a pointer.

External Dependencies

  • Credentials: none.
  • Services: services.media (resolve_media, workspace_file_url), services.plugin.deps.get_database.
  • Frontend: client/src/components/parameterPanel/CanvasPanel.tsx (panel host), client/src/components/ui/CanvasDock.tsx (docked sidebar + ephemeral preview), client/src/features/home/workspace/WorkspaceCanvas.tsx (Home's Workspace dock, loaded lazily), shared parameterPanel/canvas/CanvasContent.tsx (carousel, follow-latest image poll, markdown/code/JSON/text via capped client fetch, sandboxed iframes for external URLs + workspace HTML, inline PDF).

Edge cases & known limits

  • Board caps at 200 items (FIFO eviction) and notes at 64KB (visible truncation marker).
  • Panel handlers require a saved workflow (graph-ownership check needs the DB row); an unsaved canvas can push to the unsaved scope but the panel reads it only after save — same trade-off as simpleMemory.
  • connected_outputs is keyed by source node type (engine behavior): two same-type upstreams collide and the scan sees one output.
  • The viewer node is in _NEEDS_CONNECTED_OUTPUTS (services/node_executor.py) — the one core edit, sanctioned by that frozenset's own comment.
  • Removing an item never deletes the underlying workspace file.
  • Workspace HTML renders only in a sandbox="allow-scripts" srcDoc iframe (opaque origin, no cookies); NEVER_INLINE on the workspace route is untouched. application/pdf joined INLINE_EXACT in services/media/preview.py for the inline PDF surface.

Related

  • Skills using this as a tool: none yet (a paired skill would need a visuals.json alias for tool name canvas).
  • Other nodes that consume this output: none — the board is a sink; the Browser node's screenshot operation persists workspace FileRefs (nodes/browser/_screenshots.py) so this node can display them. Live browser viewing and control use the separate Browser tab, not Canvas screenshot items.
  • Architecture docs: browser.md, browser_workspace.md, media_transport.md, plugin_system.md, status_broadcaster.md.