feat(artifacts): agent-registered files with operator annotations #31

Manually merged
lz merged 37 commits from feat/artifacts into main 2026-05-28 22:57:52 +02:00
Owner

Summary

Adds an Artifacts feature. Agents in worker containers register files (plans, design docs, reports) with Nexus via notify-artifact <path> [label]. The operator sees them in a new Artifacts tab, can annotate markdown with text-selection comments via mark.js overlays, and submits structured feedback back to the running Claude session as a .nexus/feedback/<ts>-<slug>.md file plus a tmux send-keys nudge.

Also adds Docker Desktop support via docker-compose.override.yml so docker compose up -d works on Windows/macOS — the base file's network_mode: host is Linux-only.

Design: docs/superpowers/specs/2026-05-27-artifacts-design.md. Plan: docs/superpowers/plans/2026-05-27-artifacts.md.

What ships

  • notify-artifact POSIX-sh helper + bridge-IP-guarded agent endpoint at /api/agent/artifacts. Re-registering the same path drops prior comments (they reference the old revision).
  • Artifacts tab: list + viewer panel; pin from File Explorer; unpin with confirm-if-comments; markdown viewer with selection → comment popover → anchored highlights; sidebar with open/submitted cards.
  • Pop-out window route (/sessions/[sessionId]/artifacts/[artifactId]) sharing the same viewer + controller as the in-app panel.
  • Submit flow: writes the feedback file via WorkerFsService (Nexus has no /workspace mount), tmux-nudges the live session window, flips comment statuses, defaults to auto-pressing Enter so the operator doesn't have to alt-tab into the terminal.
  • New-artifact toast + browser-tab title badge (burst-windowed).
  • public_url instance setting → notify-artifact response includes an Open: <url> line; @xterm/addon-web-links makes it ctrl-clickable in the session terminal. Updated default CLAUDE.md instructs Claude to paste that URL back into chat (operators can't see tool I/O).
  • Docker Desktop: override file drops host-mode, publishes 127.0.0.1:3001, attaches Nexus to the workers bridge with a static IP. New WORKER_CALLBACK_URL env var lets the operator override the workers-bridge-gateway URL derivation (required on Docker Desktop where the gateway routes to the Linux VM, and where host.docker.internal would NAT the worker's source IP and break agent-ip-guard).

Schema + size

  • Migration 0009_artifacts: artifacts (UNIQUE(session_id, path), FK CASCADE) + artifact_comments (FK CASCADE).
  • New settings registry entry: public_url (instance, ^https?://.+ or empty).
  • New deps: mark.js + @types/mark.js, @xterm/addon-web-links.
  • 423 tests pass, 0 typecheck errors (when the lockfile is in sync — see notes below).

Notes worth knowing during review

  • Filesystem boundary: Nexus has no bind-mount to /workspace. All worker-side file IO goes through WorkerFsService (docker exec with atomic temp-file + mv) or execAndCapture. The submit-artifact service is filesystem-agnostic — it injects a writeFeedback(relPath, content) callback for test isolation.
  • Multiplexed exec stream: Docker's exec stdout is 8-byte-framed when Tty=false. The submit endpoint uses the shared execAndCapture helper rather than raw byte concat — earlier inline implementations corrupted tmux list-windows output.
  • Source-line stamping: v1 saves comments with line_start/end: null and mark.js matches first occurrence. The marked renderer doesn't emit reliable per-block source-line attributes; the AnnotatableMarkdown component has an inert distance-heuristic ready for when this lands as a follow-up.
  • Polling latency: the in-app artifact list polls every 5s (followed by a 2s toast burst-window) — up to 7s between notify-artifact and the toast appearing. Tracked as #34; the broader SSE migration covering previews/sessions/workers too is #35.
  • Lockfile drift: nexus/pnpm-lock.yaml has been stale since branch commit be6b6ae (the @xterm/* scoped-package migration). Local pnpm run check shows 10 unresolved-import errors against @xterm/* and mark.js. Linux Docker build still works (--frozen-lockfile=false). Worth a separate chore: refresh lockfile after this merges.

Tested

Driven end-to-end on Docker Desktop (Windows 11):

  • notify-artifact roundtrip → row + toast → click → markdown renders.
  • Highlight passage → composer stays inside viewport even near edges → Ctrl+Enter to save → mark.js overlay paints + sidebar card appears live (in-panel AND pop-out).
  • Mid-word selections highlight (accuracy: partially); highlighted text readable on dark theme (color: inherit).
  • Approve & continue and Submit comments both auto-press Enter in the Claude session, then flip the right-pane tab back to Terminal.
  • Comment sidebar footer stays pinned with many comments (forced via DB inserts).
  • Pop-out markdown column uses the full viewport width (no global 640px cap leakage).
  • pnpm test: 423 passed, 79 skipped (the skipped are the pre-existing better-sqlite3 native-binding gate on Windows).

Not exercised: the base docker-compose.yml on a real Linux host (only the Docker Desktop override path was driven); pin/unpin/re-register flows (unchanged on this branch and previously verified).

Test plan for the merger

  • On Linux: docker compose up -d (with override file removed or absent) — confirm host-mode still works as before.
  • On Docker Desktop: docker compose up -d — confirm Nexus UI at http://localhost:3001.
  • Set public_url in Settings → Instance.
  • Spawn a worker, open a session, attach to its terminal.
  • echo "# my plan" > /tmp/p.md && notify-artifact /tmp/p.md "phase 1" — verify Open: <url> line, toast in Nexus, row in Artifacts tab.
  • Highlight a mid-word slice → Comment → Ctrl+Enter; verify overlay + sidebar card without F5.
  • Open the pop-out (↗); repeat near the bottom-right corner; verify composer doesn't clip.
  • Submit the comment; verify .nexus/feedback/<ts>-...md exists in the worktree AND Claude received the prompt + Enter; verify the tab auto-flips to Terminal.
  • Re-run notify-artifact /tmp/p.md "phase 1 v2"; verify prior comments cleared.
  • Pin from File Explorer; unpin a file with comments (confirm prompt); Approve & continue with zero comments.
  • Reset default CLAUDE.md to pick up the URL-reporting guidance.
## Summary Adds an **Artifacts** feature. Agents in worker containers register files (plans, design docs, reports) with Nexus via `notify-artifact <path> [label]`. The operator sees them in a new **Artifacts** tab, can annotate markdown with text-selection comments via mark.js overlays, and submits structured feedback back to the running Claude session as a `.nexus/feedback/<ts>-<slug>.md` file plus a tmux `send-keys` nudge. Also adds Docker Desktop support via `docker-compose.override.yml` so `docker compose up -d` works on Windows/macOS — the base file's `network_mode: host` is Linux-only. Design: [`docs/superpowers/specs/2026-05-27-artifacts-design.md`](docs/superpowers/specs/2026-05-27-artifacts-design.md). Plan: [`docs/superpowers/plans/2026-05-27-artifacts.md`](docs/superpowers/plans/2026-05-27-artifacts.md). ## What ships - `notify-artifact` POSIX-sh helper + bridge-IP-guarded agent endpoint at `/api/agent/artifacts`. Re-registering the same path drops prior comments (they reference the old revision). - Artifacts tab: list + viewer panel; pin from File Explorer; unpin with confirm-if-comments; markdown viewer with selection → comment popover → anchored highlights; sidebar with open/submitted cards. - Pop-out window route (`/sessions/[sessionId]/artifacts/[artifactId]`) sharing the same viewer + controller as the in-app panel. - Submit flow: writes the feedback file via `WorkerFsService` (Nexus has no `/workspace` mount), tmux-nudges the live session window, flips comment statuses, defaults to auto-pressing Enter so the operator doesn't have to alt-tab into the terminal. - New-artifact toast + browser-tab title badge (burst-windowed). - `public_url` instance setting → `notify-artifact` response includes an `Open: <url>` line; `@xterm/addon-web-links` makes it ctrl-clickable in the session terminal. Updated default CLAUDE.md instructs Claude to paste that URL back into chat (operators can't see tool I/O). - Docker Desktop: override file drops host-mode, publishes `127.0.0.1:3001`, attaches Nexus to the workers bridge with a static IP. New `WORKER_CALLBACK_URL` env var lets the operator override the workers-bridge-gateway URL derivation (required on Docker Desktop where the gateway routes to the Linux VM, and where `host.docker.internal` would NAT the worker's source IP and break `agent-ip-guard`). ## Schema + size - Migration `0009_artifacts`: `artifacts` (UNIQUE(session_id, path), FK CASCADE) + `artifact_comments` (FK CASCADE). - New settings registry entry: `public_url` (instance, `^https?://.+` or empty). - New deps: `mark.js` + `@types/mark.js`, `@xterm/addon-web-links`. - 423 tests pass, 0 typecheck errors (when the lockfile is in sync — see notes below). ## Notes worth knowing during review - **Filesystem boundary**: Nexus has no bind-mount to `/workspace`. All worker-side file IO goes through `WorkerFsService` (`docker exec` with atomic temp-file + mv) or `execAndCapture`. The submit-artifact service is filesystem-agnostic — it injects a `writeFeedback(relPath, content)` callback for test isolation. - **Multiplexed exec stream**: Docker's exec stdout is 8-byte-framed when `Tty=false`. The submit endpoint uses the shared `execAndCapture` helper rather than raw byte concat — earlier inline implementations corrupted `tmux list-windows` output. - **Source-line stamping**: v1 saves comments with `line_start/end: null` and mark.js matches first occurrence. The `marked` renderer doesn't emit reliable per-block source-line attributes; the `AnnotatableMarkdown` component has an inert distance-heuristic ready for when this lands as a follow-up. - **Polling latency**: the in-app artifact list polls every 5s (followed by a 2s toast burst-window) — up to 7s between `notify-artifact` and the toast appearing. Tracked as **#34**; the broader SSE migration covering previews/sessions/workers too is **#35**. - **Lockfile drift**: `nexus/pnpm-lock.yaml` has been stale since branch commit `be6b6ae` (the `@xterm/*` scoped-package migration). Local `pnpm run check` shows 10 unresolved-import errors against `@xterm/*` and `mark.js`. Linux Docker build still works (`--frozen-lockfile=false`). Worth a separate `chore: refresh lockfile` after this merges. ## Tested Driven end-to-end on Docker Desktop (Windows 11): - `notify-artifact` roundtrip → row + toast → click → markdown renders. - Highlight passage → composer stays inside viewport even near edges → Ctrl+Enter to save → mark.js overlay paints + sidebar card appears live (in-panel AND pop-out). - Mid-word selections highlight (`accuracy: partially`); highlighted text readable on dark theme (`color: inherit`). - Approve & continue and Submit comments both auto-press Enter in the Claude session, then flip the right-pane tab back to Terminal. - Comment sidebar footer stays pinned with many comments (forced via DB inserts). - Pop-out markdown column uses the full viewport width (no global 640px cap leakage). - `pnpm test`: 423 passed, 79 skipped (the skipped are the pre-existing `better-sqlite3` native-binding gate on Windows). Not exercised: the base `docker-compose.yml` on a real Linux host (only the Docker Desktop override path was driven); pin/unpin/re-register flows (unchanged on this branch and previously verified). ## Test plan for the merger - [x] On Linux: `docker compose up -d` (with override file removed or absent) — confirm host-mode still works as before. - [x] On Docker Desktop: `docker compose up -d` — confirm Nexus UI at `http://localhost:3001`. - [x] Set `public_url` in Settings → Instance. - [x] Spawn a worker, open a session, attach to its terminal. - [x] `echo "# my plan" > /tmp/p.md && notify-artifact /tmp/p.md "phase 1"` — verify `Open: <url>` line, toast in Nexus, row in Artifacts tab. - [x] Highlight a mid-word slice → Comment → Ctrl+Enter; verify overlay + sidebar card without F5. - [x] Open the pop-out (↗); repeat near the bottom-right corner; verify composer doesn't clip. - [x] Submit the comment; verify `.nexus/feedback/<ts>-...md` exists in the worktree AND Claude received the prompt + Enter; verify the tab auto-flips to Terminal. - [x] Re-run `notify-artifact /tmp/p.md "phase 1 v2"`; verify prior comments cleared. - [x] Pin from File Explorer; unpin a file with comments (confirm prompt); Approve & continue with zero comments. - [x] Reset default CLAUDE.md to pick up the URL-reporting guidance.
docs(agent-instructions): broaden dev-server host/origin guidance
All checks were successful
ci / nexus (pull_request) Successful in 2m17s
ci / images (./nexus, agent-nexus) (pull_request) Successful in 3m48s
ci / images (./worker, nexus-worker) (pull_request) Successful in 1m8s
5ed6d11056
Replace the narrow Vite-only paragraph with a Dev-server host/origin
checks subsection that explains the principle (operator's browser
carries the operator's hostname, not 127.0.0.1) and lists recipes for
Vite, SvelteKit/Astro/Nuxt/Remix, Next.js >=15.2, and CRA/webpack-dev-server.

Addresses the feedback on PR #22: pre-warn agents about
allowedDevOrigins / allowedHosts / WDS_SOCKET_HOST so dev-server origin
checks can be configured before the first browser request fails.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
lz force-pushed feat/artifacts from 19b5ea47f7
Some checks failed
ci / nexus (pull_request) Failing after 1m26s
ci / images (./nexus, agent-nexus) (pull_request) Has been skipped
ci / images (./worker, nexus-worker) (pull_request) Has been skipped
to 24758d27ae
Some checks failed
ci / nexus (pull_request) Failing after 1m42s
ci / images (./nexus, agent-nexus) (pull_request) Has been skipped
ci / images (./worker, nexus-worker) (pull_request) Has been skipped
2026-05-28 22:35:31 +02:00
Compare
lz force-pushed feat/artifacts from 24758d27ae
Some checks failed
ci / nexus (pull_request) Failing after 1m42s
ci / images (./nexus, agent-nexus) (pull_request) Has been skipped
ci / images (./worker, nexus-worker) (pull_request) Has been skipped
to efdaabe724
Some checks failed
ci / nexus (pull_request) Failing after 1m27s
ci / images (./nexus, agent-nexus) (pull_request) Has been skipped
ci / images (./worker, nexus-worker) (pull_request) Has been skipped
ci / nexus (push) Failing after 1m45s
ci / images (./nexus, agent-nexus) (push) Has been skipped
ci / images (./worker, nexus-worker) (push) Has been skipped
2026-05-28 22:57:13 +02:00
Compare
lz manually merged commit efdaabe724 into main 2026-05-28 22:57:52 +02:00
lz deleted branch feat/artifacts 2026-05-28 23:03:37 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus!31
No description provided.