Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(canvas): versions, notes as documents, and document cards in chat
trohitga81702980baf
diff --git a/CLAUDE.md b/CLAUDE.mdindex 9e17ea91..3c62ec18 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -43,7 +43,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Speech Provider RFC](./docs-internal/speech_provider_rfc.md)** | Provider-abstracted speech — two nodes (`textToSpeech`, `speechToText`) with a `provider` dropdown, backed by **two registries, one per direction** (registry membership IS the capability: a synthesis-only vendor simply never appears in the transcription enum). Everything vendor-specific lives in the plugin folder [`server/nodes/speech/`](./server/nodes/speech/) — protocol, registries, dispatch, per-vendor modules; only the generic `services/provider_registry.py` and the vendor-neutral `services/media/` are shared. v1 providers: OpenAI (both directions), ElevenLabs (TTS), Deepgram + Groq (STT), Sarvam (both). Capabilities are JSON (`server/config/speech_defaults.json`) with per-model overrides, so no shared code branches on a provider name. **Audio never travels as bytes** — nodes return an `AudioRef` (a ~400 B reference) because a 12 MB base64 result blows Temporal's 2 MiB blob limit and retries 3× re-billing the provider each time. Backing routes: `GET/POST /api/workspace/{workflow_id}/…` in [`routers/workspace.py`](./server/routers/workspace.py). || **[Media Transport](./docs-internal/media_transport.md)** | How files move through the engine, and why they move as **references rather than bytes**. `services/media/` — `FileRef` (the base; `FileKind = file\|audio\|image\|video\|document`) with `AudioRef(FileRef)` as the probed-container narrowing (~400 B, `extra="forbid"` so adding a bytes field is a `ValidationError` rather than a silent regression), `write_audio` / `resolve_media` / `coerce_file_param` (the one nodes should call — accepts a `FileRef`/`AudioRef`, a bare path, or the legacy base64 envelope), `inspect_audio` (tinytag → stdlib `wave` → PCM arithmetic, **never raises**), `limits.py`, and **`preview.py` — the single owner of the inline-vs-attachment rule**, with two consumers: `routers/workspace.py` picks its `Content-Disposition` from `serves_inline`, and the gallery listing sets each row's `preview` from `preview_kind`, so the panel can never offer a preview the route refuses to serve. Containment runs through `resolve_within`, which closed a live vulnerability: a node joined a user path onto the workspace root unchecked, so `audio_file="../../credentials.db"` read the encrypted credential store and uploaded it. **The id/slug asymmetry is the trap** — workspace dirs are named by the mutable `Workflow.slug` while a ref stores the immutable `workflow_id` so refs survive rename; the lookup lives in [`services/workspace_locator.py`](./server/services/workspace_locator.py) (`resolve_workspace_root(..., allow_default=)`), and **every mutating caller must pass `allow_default=False`** or an unresolvable id silently lands the write in the shared anonymous workspace. HTTP surface in [`routers/workspace.py`](./server/routers/workspace.py): Range support comes free from Starlette's `FileResponse`; `NEVER_INLINE` is `{image/svg+xml, text/html, text/xml, application/xhtml+xml}` because `shell` / `fileDownloader` / `fileModify` can write arbitrary files into a workspace. || **[Data Node & Vision](./docs-internal/data_node.md)** | The `dataSource` agent tool (raw local data over two namespaces: workspace paths + operator-approved `mnt/<name>/...` external mounts with per-mount writable flags; typed bounded read tiers text/csv/json/pdf/html/xlsx/image-metadata/binary; write/append but **no delete**; `copy_to_workspace` imports mount files as real FileRefs), the machine-wide `data_mounts` allowlist (`services/data/mount_store.py` — refuses `DATA_DIR` overlap, drive roots, home dir), the `visionAnalyze` delegate tool (vision for every host model via openai/anthropic/gemini official SDK shapes + the `services/media/image_fit.py` visual-token budget), and the first native-image-blocks increment: `ContentBlock.source` (durable `file_ref` vs transient `bytes` — the wire codec raises on bytes), the `llm_media` tool-result opt-in, capability-gated `hydrate_image_blocks` in `run_native_llm_step`, Anthropic `tool_result` image encoding (openai/gemini encoders pending; their `vision.enabled` stays false until then). |-| **[Canvas Node](./docs-internal/canvas_node.md)** | The `canvas` node — pushed-content display board (the Claude/ChatGPT-Canvas analog) in [`server/nodes/tool/canvas/`](./server/nodes/tool/canvas/). Dual control: agents call the locked `canvas(...)` tool (paths / url / 64KB-capped markdown notes, append/replace), workflow edges auto-display upstream FileRefs via a structural scan of `connected_outputs` (`tts → canvas` is a zero-config edge; the node is the one addition to `NodeExecutor._NEEDS_CONNECTED_OUTPUTS`). Board = plugin-owned `canvas_boards`/`canvas_items` tables (mount_store mechanism, 200-item FIFO), identity-only `canvas_updated` broadcast (direct, no canary consumer), `canvas_list/remove/clear` WS handlers with the simple_memory security preamble. **Three frontend hosts share one renderer**: the `isCanvasPanel` parameter panel, the docked resizable right sidebar (`CanvasDock` + `canvasDockStore`; auto-open via `notifyPushed`, ephemeral click-to-preview from the gallery dialog, `usePanelResize` extracted from ConsolePanel), and the Canvas tab of Home's Workspace dock (`features/home/workspace/`). Renders media carousel with follow-latest image poll, markdown/code/JSON via the repo's first capped client-side text fetch (`useWorkspaceText`, 512KB), external URLs + workspace HTML in strictly sandboxed iframes (never `allow-same-origin`; `NEVER_INLINE` untouched), and inline PDF via the `INLINE_EXACT` exact-match addition to `preview.py`. The current Browser node persists screenshots as workspace FileRefs through `nodes/browser/_screenshots.py`; live viewing uses the separate Browser workspace stream. |+| **[Canvas Node](./docs-internal/canvas_node.md)** | The `canvas` node — pushed-content display board (the Claude/ChatGPT-Canvas analog) in [`server/nodes/tool/canvas/`](./server/nodes/tool/canvas/). Dual control: agents call the locked `canvas(...)` tool (paths / url / 64KB-capped markdown notes, append/replace), workflow edges auto-display upstream FileRefs via a structural scan of `connected_outputs` (`tts → canvas` is a zero-config edge; the node is the one addition to `NodeExecutor._NEEDS_CONNECTED_OUTPUTS`). Board = plugin-owned `canvas_boards`/`canvas_items` tables (mount_store mechanism, 200-item FIFO), identity-only `canvas_updated` broadcast (direct, no canary consumer), `canvas_list/remove/clear` WS handlers with the simple_memory security preamble. **Three frontend hosts share one renderer**: the `isCanvasPanel` parameter panel, the docked resizable right sidebar (`CanvasDock` + `canvasDockStore`; auto-open via `notifyPushed`, ephemeral click-to-preview from the gallery dialog, `usePanelResize` extracted from ConsolePanel), and the Canvas tab of Home's Workspace dock (`features/home/workspace/`). Renders media carousel with follow-latest image poll, markdown/code/JSON via the repo's first capped client-side text fetch (`useWorkspaceText`, 512KB), external URLs + workspace HTML in strictly sandboxed iframes (never `allow-same-origin`; `NEVER_INLINE` untouched), and inline PDF via the `INLINE_EXACT` exact-match addition to `preview.py`. The current Browser node persists screenshots as workspace FileRefs through `nodes/browser/_screenshots.py`; live viewing uses the separate Browser workspace stream. Items have versions (the tool's `update_id` saves the next one; `canvas_item_versions` keeps the newest 50 per item; `canvas_versions` / `canvas_version` read them) and a note shows as a document (`NoteView`: ‹ v2/3 ›, Preview/Markdown, Copy, Download); a note the agent answering the owner writes is named on its reply (`services/chat/parts.show_artifact`) as a card that opens the board at that version (Home: `homeStore.openCanvasItem`; Dev: `canvasDockStore.focusItem`). || **[Translate / Transliterate / Detect](./docs-internal/speech_provider_rfc.md#8-what-this-pattern-should-absorb-next)** | The second application of the multi-vendor pattern, and the one that retired `nodes/sarvam/`. Three nodes (`translateText`, `transliterateText`, `detectLanguage`) in [`server/nodes/translate/`](./server/nodes/translate/), backed by **three registries — one per capability**, because the asymmetry is sharper than speech's: DeepL translates and does nothing else, while Sarvam and LLM-backed providers do all three. Membership makes an unsupported selection unrepresentable rather than a runtime failure inside a paid call. Providers: **deepl** (`Authorization: DeepL-Auth-Key`, `text` is an array, free keys ending `:fx` route to a different host, and it returns `billed_characters` so cost is the provider's own figure), **sarvam** (all three over dedicated REST), **openai** (all three via `ChatUnifier` — proves the Protocol does not care what a provider does internally; billing deliberately NOT recorded because that path bills tokens the LLM layer already costs). Capabilities in `server/config/translate_defaults.json`. || **[Desktop App](./docs-internal/desktop_app.md)** | Electron shell in [`desktop/`](./desktop/) — a standalone bun package (NOT a root workspace member; `cli/tests/test_release_pipeline_config.py` locks `workspaces`). Bundles pinned `uv`, python-build-standalone CPython 3.12 and bun 1.4.0 — the only JavaScript runtime shipped; no Node, no npm (`desktop/runtimes.json`, verified against upstream checksum manifests by `scripts/fetch-runtimes.ts`, which also fetches bun's `LICENSE.md` from the bun repo — the release zip carries none — and prunes stale runtime dirs such as a leftover `node/`), stages the backend sibling layout from `bun pm pack --dry-run` (`scripts/stage.ts`, which runs the sidecar package's own `bun run build` — `bun build --target=bun`, express inlined — and copies `dist/index.js`), sets `OPENCOMPANY_BUN_BIN` / `BUN_INSTALL=<userData>/bun` / `BUN_INSTALL_CACHE_DIR` and prepends the bundled bun dir (then uv) to PATH for the backend (`env.ts`; `OPENCOMPANY_NODE_BIN` no longer exists), provisions the venv into Electron `userData` on first launch with `uv sync --frozen --python <bundled>` (stamp = sha256 of uv.lock + pyproject + Python + uv versions; falls back to `uv python install 3.12`), pre-warms `PYTHONPYCACHEPREFIX` (with a prefix set Python ignores in-tree .pyc — 32 s vs 3 s first boot), spawns uvicorn on `127.0.0.1:5678` (persisted port; attaches to a running `company serve` instead of double-spawning), waits on `/health/ready`, loads the backend-served SPA (zero frontend changes), routes `window.open` / `_blank` to the OS browser. Quit = `POST /api/desktop/shutdown` + stdin EOF, 30 s, then tree-kill. electron-builder: NSIS x64, DMG+zip arm64/x64, AppImage+deb x64, unsigned first (`mac.identity: null`; macOS auto-update notify-only until signed — Squirrel.Mac refuses unsigned). CI: `desktop-release.yml` (tag-triggered: `prepare` drafts the GitHub Release from the annotated tag's message, three legs build and upload version-less OS-named installers such as `OpenCompany-windows-x64.exe` / `OpenCompany-macos-arm64.dmg` / `OpenCompany-linux-x86_64.AppImage` so the README can link `releases/latest/download/<file>`, each leg refuses a desktop version that differs from the tag, `finalize` undrafts) and `desktop-ci.yml` (typecheck/unit/invariants/Playwright smoke). **Gotcha: editor-hosted terminals export `ELECTRON_RUN_AS_NODE=1`, which makes Electron boot as plain Node (`electron.app` undefined) — strip it before launching; the e2e test does.** || **[Desktop Host Contract](./docs-internal/desktop_host_contract.md)** | The backend's side of being owned by a GUI shell. `core/approot.py` is the ONE module that locates the app tree (`OPENCOMPANY_APP_ROOT` / `OPENCOMPANY_CLIENT_DIST` / `OPENCOMPANY_ENV_FILE` / `OPENCOMPANY_ENV_TEMPLATE`); `tests/test_no_root_climb.py` forbids any other `Path(__file__).parents[N]` climb above `server/` and any `"client"/"dist"` / `.env.template` / `package.json` path join. `core/env_defaults.apply_file_defaults_to_environ()` does the CLI's `.env.template < .env < process env` layering at the top of `main.py`, and `Settings.env_file` is the absolute `(template, .env)` tuple — so a shell spawns `python -m uvicorn` from any cwd without the CLI package. Desktop mode (`OPENCOMPANY_DESKTOP=1`, `core/desktop.py`): parent-PID watchdog with create-time PID-reuse guard, stdin-EOF watchdog (polling via `PeekNamedPipe`/`select`, never a blocking read — a daemon thread parked in `ReadFile` at finalisation crashed exit with 0xC0000005), ctypes Job Object so children die with the backend (no pywin32 in the server venv), token-gated `POST /api/desktop/shutdown` (`routers/desktop.py`, public path; raises the signal uvicorn handles so the lifespan reaps Temporal/the bun sidecar/edgymeow), 45 s hard deadline. `GET /health/ready` (public) = DB up AND (Temporal disabled OR worker manager started), with `phase` written by `services/temporal/lifecycle.py` (`installing_temporal` / `starting_temporal` / `connecting` / `starting_workers` / `ready`). Plugin shutdown hooks now run under a 10 s per-hook timeout (`HOOK_TIMEOUT_SECONDS`), and the current browser hook uses `peek_browser_runtime()` so shutdown never constructs or installs the runtime. Historical incident: the retired `get_browser_service()` lazily installed agent-browser at shutdown and wedged graceful exit (masked under the CLI by its 5 s grace + tree-kill). `server/uv.lock` is committed; `predeploy.yml` runs `uv lock --check`. |diff --git a/docs-internal/canvas_node.md b/docs-internal/canvas_node.mdindex 098adc54..a474b0ed 100644--- a/docs-internal/canvas_node.md+++ b/docs-internal/canvas_node.md@@ -119,12 +119,29 @@ lone op regardless of `parameters["operation"]`). Item sources, in order:An empty call raises `NodeUserError("Nothing to display — pass paths, url,or content …")` so the LLM gets a one-line correctable error.+**Revising an item** (`update_id`): with the id of an item already on the+board (from an earlier result's `added`), the call's one item (one path,+url or content, of the same kind) becomes that item's next version instead+of a new item; `mode` is ignored. More than one item, another kind, or an+id this board does not hold is a `NodeUserError`. The result is `{message,+revision, added: [{id, kind, title, version}]}`. An update keeps the title+unless the call passes one.+**Output payload discipline**: the op returns `{message, count, revision,added: [{id, kind, title}]}` — ids and counts only, never note bodies andnever echoed refs, because a node result is persisted three ways, broadcast,retained in the status cache, copied into downstream activity inputs, andreplayed into LLM context every turn.+**Documents in the chat**: when the call comes from the agent answering the+owner's chat (`ctx.raw["chat_stream"]` is set), each note it writes or+revises is named on that reply through `services.chat.parts.show_artifact`+as `{workflow_id, canvas_node_id, item_id, version, title, format}` (title:+the call's, else the note's first line; format `code` when a language is+given). The reply shows it as a document card that opens the board on the+item at that version ([chat_protocol.md](./chat_protocol.md)). Files and+URLs are not named. Best effort: the board has the item either way.+`source` labeling (`"agent"` vs `"workflow"`) keys on `_tool_config` beingpresent in `ctx.raw` — `execute_as_tool` sets it around the op body andnothing else does. Cosmetic; a wrong label misleads nobody about security.@@ -147,13 +164,26 @@ schema description the model reads. Boundary coercions:### The store — [`_store.py`](../server/nodes/tool/canvas/_store.py)Plugin-owned tables, mount_store mechanism: importing the plugin registers-`CanvasBoard` (`canvas_boards`: board id, identity columns, `revision`) and+`CanvasBoard` (`canvas_boards`: board id, identity columns, `revision`),`CanvasItemRow` (`canvas_items`: kind/title/`ref` JSON/url/`content`-Text/language/source/position) into SQLModel metadata before-`Database.startup()`'s `create_all`; `ensure_schema()` (per-engine set +-lock + `checkfirst=True`) covers late importers. No migration framework, no+Text/language/source/position/`version`/`updated_at`) and+`CanvasItemVersion` (`canvas_item_versions`: one row per version of an item,+the current one too) into SQLModel metadata before `Database.startup()`'s+`create_all`; `ensure_schema()` (per-engine set + lock + `checkfirst=True`)+covers late importers, and adds `version` / `updated_at` to a+`canvas_items` table saved before items had versions (`PRAGMA table_info` ++`ALTER TABLE`, existing items become version 1). No migration framework, no`core/database.py` edits.+**Versions**: an item starts at version 1; `update(scope, item_id, item)`+saves the next one (same kind) and bumps `revision`. Each item keeps its+newest `CANVAS_MAX_VERSIONS = 50` versions. Removing an item, clearing the+board, a `replace` and FIFO eviction drop the item's versions with it.+`versions(scope, item_id)` lists them newest first (`{item_id, versions:+[{version, title, created_at, source, size_bytes}], latest}`);+`version(scope, item_id, n)` returns one in the item's wire shape plus+`latest`.+Scope is `CanvasScope(owner_id, workflow_id, node_id)` with the`"unsaved"` workflow fallback; the board id is`"canv_" + sha256("canvas:v1\0owner\0workflow\0node")[:48]` — the version@@ -168,7 +198,8 @@ Every mutation is one transaction that bumps `revision`. Caps:### Panel WS handlers — [`_handlers.py`](../server/nodes/tool/canvas/_handlers.py)-`canvas_list` / `canvas_remove` / `canvas_clear`, all `@ws_response` (never+`canvas_list` / `canvas_remove` / `canvas_clear` / `canvas_versions` /+`canvas_version` (the last two read an item's versions), all `@ws_response` (never`@ws_handler` — a user-correctable failure must be one WARN line, not anERROR with a traceback), self-registered via `register_ws_handlers` from thepackage `__init__`. Security preamble copied verbatim from simple_memory:@@ -219,6 +250,8 @@ interface CanvasItem {language: string | null;source: 'agent' | 'workflow' | string;created_at: string | null;+ version: number; // 1, then one more per update+ updated_at: string | null; // the last update}```@@ -227,8 +260,10 @@ interface CanvasItem {| `canvas_list {workflow_id, node_id}` | `{success, items: CanvasItem[], revision}` || `canvas_remove {workflow_id, node_id, item_id}` | `{success, removed, revision}` + broadcast || `canvas_clear {workflow_id, node_id}` | `{success, cleared, revision}` + broadcast |+| `canvas_versions {workflow_id, node_id, item_id}` | `{success, item_id, versions: [{version, title, created_at, source, size_bytes}], latest}` (newest first) |+| `canvas_version {workflow_id, node_id, item_id, version}` | `{success, item: CanvasItem-at-that-version & {latest}}` || broadcast `canvas_updated` | `{type: 'canvas_updated', data: <WorkflowEvent>}`, data.data = `{workflow_id, node_id, revision}` |-| tool `canvas(title?, paths?, url?, content?, language?, mode)` | flat schema, no `$defs`; `mode: 'append' \| 'replace'` |+| tool `canvas(title?, paths?, url?, content?, language?, mode, update_id?)` | flat schema, no `$defs`; `mode: 'append' \| 'replace'`; `update_id` revises an item |Client-side types + query keys live in[`client/src/lib/canvasBoard.ts`](../client/src/lib/canvasBoard.ts):@@ -267,6 +302,13 @@ prefix `['canvasBoard']` for broadcast-driven invalidation.passes an owner-facing empty hint. Hires get a Canvas node from theHire builder.+A document card in a chat reply opens its item through the host:+`homeStore.openCanvasItem` (Home: opens the Workspace on that employee's+Canvas tab, `workspaceFocus`) and `canvasDockStore.focusItem` (the editor's+chat: opens the dock on that node's board, `focus`; only for the open+workflow). Both pass a focus request `{itemId, version, nonce}` to the+renderer; a new nonce asks again for the same item.+### Dock state — [`stores/canvasDockStore.ts`](../client/src/stores/canvasDockStore.ts)A small Zustand store (slice-selector reads; `getState()` writes from the WS@@ -300,6 +342,22 @@ back; navigating onto the last item resumes following). Arrow/Home/End keyswork on the focused `role="group"` only — no document-level listeners,which would fight React Flow node nudging.+**Focus**: `focus` (a reply's document card) pins its item once the item is+on the board (it waits for a board that has not caught up yet), and holds+it while newer items arrive, until the user moves to another item. `nodeId`+names the board's Canvas node, which a note's earlier versions are read+from.++**Notes as documents**+([`NoteView.tsx`](../client/src/components/parameterPanel/canvas/NoteView.tsx)):+a note shows with a header: the version stepper ‹ v2/3 › (when it has more+than one version and the host gave a `nodeId`; an earlier version is read+once through `canvas_version` and cached, read-only), Preview or Markdown+(the source in a `pre`), Copy, and Download as a `.md` file (a blob named+after the title and version). A newer version arriving shows itself unless+the user stepped back to an earlier one; a focus request opens it at its+version.+**Follow-latest** (workspace image polling): when the active itemis a workspace image, a Switch enables a visibility-gated 5 s poll of theexisting `list_workspace_files` handler on the image's folder, rendering the@@ -315,7 +373,7 @@ text tiers:| Verdict | Condition | Renders ||---|---|---|-| `note` | `kind === 'note'` | ReactMarkdown prose (no fetch) |+| `note` | `kind === 'note'` | `NoteView`: ReactMarkdown prose or the source, versions, Copy, Download (no fetch for the latest) || `web-external` | `kind === 'url'` | sandboxed iframe (below) || `media-image/video/audio` | mime prefix or ref.kind | native element, FilePreviewDialog's honest-fallback idiom || `pdf` | `application/pdf` / `.pdf` | plain same-origin iframe (browser viewer) |@@ -407,14 +465,15 @@ write_todos/simple_memory/gallery before it, are out of its scope).| Surface | File | Locks ||---|---|---|-| Store | [`server/tests/nodes/test_canvas_node.py`](../server/tests/nodes/test_canvas_node.py) | scope isolation, append/replace + revision monotonicity, FIFO eviction, kind rejection, stable wire key set, note truncation, versioned board id |-| Display op | same | contained ref build (`../` rejected), url scheme, truncation notice, empty-call `NodeUserError`, connected-outputs scan (near-miss dicts skipped, nested refs found), agent/workflow source labeling, replace mode, output payload discipline |-| Handlers | same | internal-socket denial, owner mismatch, wrong-node-type, list/remove/clear round trip + broadcast-per-mutation |+| Store | [`server/tests/nodes/test_canvas_node.py`](../server/tests/nodes/test_canvas_node.py) | scope isolation, append/replace + revision monotonicity, FIFO eviction, kind rejection, stable wire key set, note truncation, versioned board id; versions: update + history + one version, kind and board checks, newest 50 kept, remove/clear/replace/eviction drop them, a board saved before versions gets the columns |+| Display op | same | contained ref build (`../` rejected), url scheme, truncation notice, empty-call `NodeUserError`, connected-outputs scan (near-miss dicts skipped, nested refs found), agent/workflow source labeling, replace mode, output payload discipline, `update_id` (one item of its kind), notes in a chat run named on the reply (files, URLs and runs without a chat are not) |+| Handlers | same | internal-socket denial, owner mismatch, wrong-node-type, list/remove/clear round trip + broadcast-per-mutation, versions/version reads and their refusals || Event + schema | same | identity-only envelope (`subject`, type, exact data keys), `as_tool_schema()["name"] == "canvas"`, structurally no `$defs`/`$ref`, locked hints/annotations || Screenshots | [`test_browser_screenshots.py`](../server/tests/nodes/test_browser_screenshots.py) | base64/path/unrecognized shapes, size bounds, missing-workspace tolerance, harness containment || FE dispatch | `canvas/__tests__/canvasKinds.test.ts` | full verdict matrix, mime-over-extension, language override |-| FE carousel + sandbox | `canvas/__tests__/CanvasContent.test.tsx` | follow-newest vs pinned semantics, keyboard, remove; **sandbox regression**: external iframe exactly `allow-scripts allow-forms`, srcDoc lacks `allow-same-origin` and has no `src` |-| FE dock store | `stores/__tests__/canvasDockStore.test.ts` | notifyPushed truth table, width clamp, prefs round-trip + corrupt-JSON fallback, session-only fields never persisted |+| FE carousel + sandbox | `canvas/__tests__/CanvasContent.test.tsx` | follow-newest vs pinned semantics, keyboard, remove; **sandbox regression**: external iframe exactly `allow-scripts allow-forms`, srcDoc lacks `allow-same-origin` and has no `src`; notes: preview/source, version stepper (needs a node), following a newer version unless stepped back, an unreadable version, focus (waits for the item, holds, lets go on navigation), Copy and Download |+| FE dock store | `stores/__tests__/canvasDockStore.test.ts` | notifyPushed truth table, width clamp, prefs round-trip + corrupt-JSON fallback, session-only fields never persisted, `focusItem` |+| FE document cards | `features/chat/__tests__/artifacts.test.tsx`, `features/home/__tests__/workspace.test.tsx` | reading and merging a reply's documents, the card, a card streaming in and opening through the host; Home's `openCanvasItem` || FE text fetch | `hooks/__tests__/useWorkspaceText.test.ts` | cap + reader cancel, status error, no-body fallback, cookie + buildApiUrl || FE panel | `__tests__/CanvasPanel.test.tsx` | `canvas_list/remove/clear` round trip, no-workflow guard, denied-listing surfacing |diff --git a/docs-internal/chat_protocol.md b/docs-internal/chat_protocol.mdindex cb278c76..e04818b8 100644--- a/docs-internal/chat_protocol.md+++ b/docs-internal/chat_protocol.md@@ -218,11 +218,21 @@ parts: {Approvals are joined live from the approvals store; the part only names them (`{approval_id, tool_call_id}`).+Artifacts name the documents (Canvas notes) the run wrote or revised, one entry per item at the latest version+the run left it: the canvas tool calls `show_artifact` (`artifact:<item_id>`, so a later version replaces the+earlier one) and publishes an `activity.snapshot` with `activity_type: "artifact"` and `message_id:+"artifact_<item_id>"`. The card (`features/chat/turns/ArtifactCard.tsx`) shows the title, Document or Code, the+version, and Open, which asks the host to show the item at that version (Home: the Workspace's Canvas tab; the+editor: the Canvas dock; see [canvas_node.md](./canvas_node.md)). The client shows each saved document at the newer+of its saved and live versions.+A run's tools record parts on the run as they go (`chat_run_parts`, keyed so a retried activity writes the samerow; `services/chat/parts.py`). Reply in Chat saves its reply with the parts recorded so far, and the run's end seals-any later ones into it, creating an empty-text reply when the run showed an interface but wrote nothing (sources-alone make none: they show only where a reply cites them); the end is published after the seal, so its-`result.reply_message_id` names a reply that holds them.+any later ones into it, creating an empty-text reply when the run showed an interface, made a draft or wrote a+document but wrote no text (sources alone make none: they show only where a reply cites them); the end is published+after the seal, so its `result.reply_message_id` names a reply that holds them. A sealed item the reply already holds+stays as it is there (the owner may have changed an interface's state since), except a document's, where the run's+newer version wins in place.## Generated UI@@ -409,7 +419,9 @@ What an employee sends to someone waits for the owner's OK while its workflow as- **The employee hears how it went**: an `[update]{...}[/update]` note (`approval:<id>`) at the start of its nextturn in the chat, for a send that went, failed or was discarded.- **In the chat.** A draft made answering the owner is recorded on the run (`parts.approvals`) and shown at once (an- `activity.snapshot` with `activity_type: "approval"`); its card sits on that reply. Drafts no reply in view made (a+ `activity.snapshot` with `activity_type: "approval"`); its card sits on that reply. A draft made in a run a button+ press started (its owner message carries `meta.ui_event`) records that interface (`ui_part_id`,+ `ledger.ui_part_of_run`), and the card says "Linked to the form above". Drafts no reply in view made (agate's, from the employee's own work) show after the conversation. The card (`features/chat/approval/`): Discard /Edit / Send while it waits, "Sends in Ns" with Undo, Sending, Sent (and when, and whether Ask first was off),Restore while it can, Try again (asking first when it may have gone), and "Sends when you resume" for a gate'sdiff --git a/docs-internal/normal_mode.md b/docs-internal/normal_mode.mdindex 1413860c..f0e7d9ab 100644--- a/docs-internal/normal_mode.md+++ b/docs-internal/normal_mode.md@@ -176,7 +176,10 @@ Help in browser), else the first on the team.It loads in its own chunk, which keeps the board's markdown, code andJSON viewers out of Home's, and refreshes on `canvas_updated` like theeditor's hosts. An employee without a Canvas gets a note and Open- workflow.+ workflow. A note shows as a document: its versions (‹ v2/3 ›), Preview or+ Markdown, Copy and Download. A document card in a reply (a note the+ employee wrote or revised while answering) opens the Workspace here, on+ that employee and item at that version (`homeStore.openCanvasItem`).- **Browser**: the shared `components/browser/BrowserWorkspace` attaches tothe employee's saved Browser nodes, supplied by `browser_nodes` in itssummary. Multiple nodes get a selector. Running sessions appear automatically;