feat(artifacts): agent-registered files with operator annotations #31
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/artifacts"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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>.mdfile plus a tmuxsend-keysnudge.Also adds Docker Desktop support via
docker-compose.override.ymlsodocker compose up -dworks on Windows/macOS — the base file'snetwork_mode: hostis Linux-only.Design:
docs/superpowers/specs/2026-05-27-artifacts-design.md. Plan:docs/superpowers/plans/2026-05-27-artifacts.md.What ships
notify-artifactPOSIX-sh helper + bridge-IP-guarded agent endpoint at/api/agent/artifacts. Re-registering the same path drops prior comments (they reference the old revision)./sessions/[sessionId]/artifacts/[artifactId]) sharing the same viewer + controller as the in-app panel.WorkerFsService(Nexus has no/workspacemount), 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.public_urlinstance setting →notify-artifactresponse includes anOpen: <url>line;@xterm/addon-web-linksmakes 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).127.0.0.1:3001, attaches Nexus to the workers bridge with a static IP. NewWORKER_CALLBACK_URLenv var lets the operator override the workers-bridge-gateway URL derivation (required on Docker Desktop where the gateway routes to the Linux VM, and wherehost.docker.internalwould NAT the worker's source IP and breakagent-ip-guard).Schema + size
0009_artifacts:artifacts(UNIQUE(session_id, path), FK CASCADE) +artifact_comments(FK CASCADE).public_url(instance,^https?://.+or empty).mark.js+@types/mark.js,@xterm/addon-web-links.Notes worth knowing during review
/workspace. All worker-side file IO goes throughWorkerFsService(docker execwith atomic temp-file + mv) orexecAndCapture. The submit-artifact service is filesystem-agnostic — it injects awriteFeedback(relPath, content)callback for test isolation.Tty=false. The submit endpoint uses the sharedexecAndCapturehelper rather than raw byte concat — earlier inline implementations corruptedtmux list-windowsoutput.line_start/end: nulland mark.js matches first occurrence. Themarkedrenderer doesn't emit reliable per-block source-line attributes; theAnnotatableMarkdowncomponent has an inert distance-heuristic ready for when this lands as a follow-up.notify-artifactand the toast appearing. Tracked as #34; the broader SSE migration covering previews/sessions/workers too is #35.nexus/pnpm-lock.yamlhas been stale since branch commitbe6b6ae(the@xterm/*scoped-package migration). Localpnpm run checkshows 10 unresolved-import errors against@xterm/*andmark.js. Linux Docker build still works (--frozen-lockfile=false). Worth a separatechore: refresh lockfileafter this merges.Tested
Driven end-to-end on Docker Desktop (Windows 11):
notify-artifactroundtrip → row + toast → click → markdown renders.accuracy: partially); highlighted text readable on dark theme (color: inherit).pnpm test: 423 passed, 79 skipped (the skipped are the pre-existingbetter-sqlite3native-binding gate on Windows).Not exercised: the base
docker-compose.ymlon 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
docker compose up -d(with override file removed or absent) — confirm host-mode still works as before.docker compose up -d— confirm Nexus UI athttp://localhost:3001.public_urlin Settings → Instance.echo "# my plan" > /tmp/p.md && notify-artifact /tmp/p.md "phase 1"— verifyOpen: <url>line, toast in Nexus, row in Artifacts tab..nexus/feedback/<ts>-...mdexists in the worktree AND Claude received the prompt + Enter; verify the tab auto-flips to Terminal.notify-artifact /tmp/p.md "phase 1 v2"; verify prior comments cleared.19b5ea47f724758d27ae24758d27aeefdaabe724