molecule-core/docs/edit-history/2026-04-04.md

Edit History — 2026-04-04

Summary

Major session covering file explorer, template import/replace, bundle drop zone, team expansion, canvas toolbar, viewport persistence, hot-reload, WebSocket events, Docker Compose, plugin system (ECC + Superpowers), production hardening (graceful shutdown, rate limiting, AES-256 secrets), human-in-the-loop approval chain, HMA memory (L1/L2/L3), coordinator pattern, code sandbox, memory consolidation, Langfuse trace preview, search dialog, toast notifications, OpenRouter provider, skill installer, ClawHub integration, team zoom-in, connection breakage visualization, and 15 code review rounds. UI E2E tested via browser: 95/104 plan items done (91%).

File Explorer Tab (FilesTab)

• Tree view with collapsible directories and file type icons
• Inline code editor with monospace font, Ctrl/Cmd+S save, Tab inserts spaces
• Create new files with path input, delete with confirmation
• Platform endpoints: GET/PUT/DELETE /workspaces/:id/files/*path for individual files, GET /workspaces/:id/files for tree listing
• Path traversal protection via validateRelPath()
• useMemo for tree building, ref-based cursor positioning

Agent Import & Replace via UI

• Import Agent Folder: button in template palette, uses webkitdirectory file picker, uploads to POST /templates/import
• Replace Agent Files: button in DetailsTab, uploads folder to PUT /workspaces/:id/files, auto-restarts, confirmation before destructive replace
• Auto-generates config.yaml detecting prompt_files and skills from uploaded files
• CLI script import-agent.sh also available

Canvas Visual Overhaul

• Toolbar: fixed top-center bar with Molecule AI logo, live status counts, workspace total
• WorkspaceNode redesign: status gradient bar, team badge (child count), pill-shaped handles, 4 skill badges
• SidePanel: slide-in animation, tab icons, UUID footer, darker backdrop blur
• ContextMenu: status dot header, expand/collapse team actions
• Animations: node fade-in on mount, panel slide-in from right
• Scrollbar: custom thin zinc styling

Bundle & Team Features

• BundleDropZone: drag .bundle.json onto canvas to import, visual overlay, progress spinner, toast
• Context menu: Export Bundle downloads file, Duplicate exports+re-imports
• Team expansion APIs: POST /workspaces/:id/expand creates sub-workspaces from config, POST /collapse removes them
• Context menu: Expand to Team / Collapse Team
• bundle-compile.sh: compiles all templates to .bundle.json artifacts

Runtime & Infrastructure

• Viewport persistence: GET/PUT /canvas/viewport, debounced save on pan/zoom, restore on load
• Hot-reload watcher (watcher.py): polls config dir for hash changes, debounced reload
• WebSocket subscriber (events.py): connects to platform /ws, triggers prompt rebuild on peer events
• Langfuse auto-injection: detects env vars, creates CallbackHandler
• Cross-workspace trace linking: delegation tool passes parent_task_id in A2A metadata
• Workspace forwarding: discovery follows forwarded_to chain (max 5 hops)
• Full Docker Compose: 6 services with health checks on shared molecule-monorepo-net
• Auto-discover configs dir: findConfigsDir() searches parent directories

Bug Fixes

• A2A executor: switched from astream to ainvoke for reliable responses across models
• Chat response parsing: handle result.parts[] with kind field (a2a-sdk v0.3 format)
• Terminal handler: tries multiple container name patterns (ws-{id}, workspace-name)
• A2A proxy: injects messageId into params.message (required by a2a-sdk)
• Path traversal: validateRelPath() blocks ../ and absolute paths in file uploads
• Shared utilities: normalizeName(), writeFiles(), generateDefaultConfig() extracted to eliminate 3x duplication

ECC & Superpowers Integration

Workspace Templates

• ecc-coding-agent: Everything Claude Code with 10 curated skills (coding-standards, tdd-workflow, e2e-testing, security-review, api-design, backend-patterns, frontend-patterns, deep-research, shell-exec), CLAUDE.md + AGENTS.md + WORKING-CONTEXT.md as prompt files
• superpowers-agent: obra/superpowers with 16 skills (14 from superpowers + shell-exec + file-ops), code-reviewer agent, 3 commands (brainstorm, write-plan, execute-plan)
• import-ecc.sh: CLI script to import individual or all 156 ECC skills as templates

Plugin System (integrated into every workspace)

• workspace/plugins.py: scans /plugins/ for installed plugins, loads rules/*.md, prompt fragments, and skills directories
• plugins/ecc/: ECC guardrails rules + 5 shared skills (coding-standards, tdd-workflow, security-review, api-design, deep-research) + AGENTS.md prompt fragment
• plugins/superpowers/: 5 shared skills (test-driven-development, systematic-debugging, writing-plans, executing-plans, verification-before-completion)
• Every workspace agent auto-inherits plugin rules + skills (deduplicated by ID, workspace skills take priority)
• Provisioner mounts /plugins:ro into every container
• docker-compose.yml mounts ./plugins for platform

Prompt Integration

• prompt.py: accepts plugin_rules and plugin_prompts parameters
• Rules injected as "Platform Rules" section
• Prompt fragments injected as "Platform Guidelines" section
• Plugin skills merged after workspace skills (deduplicated)

Code Review Fixes (Rounds 7-9)

• Round 7: path traversal fix, dedup normalization/config generation, file upload limit (200), delete confirmation for replace
• Round 8: remove unused getLang, success timer ref cleanup, delete confirmation for files, textarea ref for Tab key, useMemo for tree
• Round 9: deduplicate plugin skills by ID (workspace takes priority), remove arbitrary 50-char prompt size filter
• Round 10: rate limiter goroutine leak (accept context), crypto key warning on invalid, .env.example sync
• Round 11: unused useReactFlow import, search state lifted to store, synthetic event replaced
• Round 12: remove unnecessary comment in Toolbar
• Round 13: N+1 approval polling → single endpoint, auto-expiry, TEAM scope query fix, configurable poll env vars
• Round 14: sandbox shell injection (mount temp file), consolidation fallback path, SandboxConfig wired to load_config
• Round 15: executor returns only AI messages (skip tool results), locale middleware narrowed to known codes
• Round 16: MCP server network error handling + startup platform validation
• Round 17: parallel file downloads in Files tab

MCP Server

• mcp-server/ — TypeScript MCP server using @modelcontextprotocol/sdk, stdio transport
• 20 tools: list/create/get/delete/restart workspaces, chat with agent, assign model, set/list secrets, list/read/write/delete files, commit/search memory, list templates, expand/collapse team, list/decide approvals
• Works with Claude Code, Cursor, Codex, OpenCode — any MCP client
• Added to .mcp.json for immediate Claude Code integration
• Startup validates platform connectivity, logs warning with fix instructions
• Network errors return friendly messages instead of crashing

Embedded Sub-Workspaces

• WorkspaceNode redesign: parent nodes expand in size (320-450px) when they have children. Children render as embedded mini-cards in a "Team Members" 2-column grid inside the parent node.
• No separate nodes/edges: child nodes set hidden: true in React Flow, no parent→child edges created. Children exist in store for data access but render visually inside the parent.
• Click child chip: selects the child and opens its side panel.
• Toolbar: shows "4 workspaces + 1 sub" to distinguish root vs embedded counts.
• Fix: children selector memoized with useMemo to prevent infinite render loop (Zustand .filter() creates new array reference every render).

Files Tab Enhancements

• Upload: folder picker to upload multiple files into workspace
• Export: download all workspace files as JSON bundle (parallel via Promise.allSettled)
• Clear: delete all files with red confirmation dialog
• Download: ↓ button for currently open file
• Folder delete: ✕ on hover for directories, confirmation shows "and all its contents", platform uses os.RemoveAll

Memory Consolidation Loop (Phase 9, 15g)

• consolidation.py: runs every 5min, checks if LOCAL memories exceed threshold (10), uses agent to summarize into dense TEAM knowledge, deletes originals. Falls back to concatenation if agent unavailable/rate-limited with error-level logging.
• Configurable via CONSOLIDATION_INTERVAL and CONSOLIDATION_THRESHOLD env vars.

Code Sandbox (Phase 12, 18a-18b, 18e)

• tools/sandbox.py: run_code(code, language) tool
• Subprocess backend: direct execution with timeout (default for Tier 1-2)
• Docker backend: code written to temp file, mounted read-only at /sandbox/code.py (no shell injection). Container runs with --network none --memory 256m --cpus 0.5 --read-only --tmpfs /tmp:size=32m.
• Supports python, javascript, shell/bash
• SandboxConfig dataclass in config.py, loaded from sandbox: in config.yaml
• Configurable via SANDBOX_BACKEND, SANDBOX_TIMEOUT, SANDBOX_MEMORY_LIMIT env vars

Connection Breakage Visualization (Phase 11, 17p)

• Edges in canvas styled by child workspace status:
  • Online: animated, dark zinc stroke
  • Degraded: amber stroke, thicker (2px), no animation
  • Offline/Failed: dashed gray stroke, no animation

Interactive Canvas Improvements

• Search dialog (⌘K): SearchDialog.tsx — fuzzy search across name/role/status, click to select + open Details, state managed in Zustand store
• Toast notifications: Toaster.tsx — global showToast() callable anywhere, success/error/info variants, auto-dismiss 4s, slide-up animation. Context menu actions show toasts.
• Empty state: EmptyState.tsx — shown when no workspaces, visual guide with keyboard shortcuts
• Keyboard shortcuts: Escape cascades (close context menu → close panel), ⌘K opens search
• Toolbar search button: magnifying glass + ⌘K badge, calls store.setSearchOpen(true)

Human-in-the-Loop Approval Chain (Phase 8, 14a-14f)

• Migration 007_approvals.sql: approval_requests table with status (pending/approved/denied/escalated)
• handlers/approvals.go: POST create, GET list, GET /approvals/pending (single query for all), POST decide. Auto-expires pending requests older than 10 minutes.
• Platform events: APPROVAL_REQUESTED, APPROVAL_ESCALATED (to parent), APPROVAL_APPROVED, APPROVAL_DENIED
• tools/approval.py: request_approval(action, reason) tool. Pauses agent, polls for decision (configurable via APPROVAL_POLL_INTERVAL/APPROVAL_TIMEOUT env vars).
• ApprovalBanner.tsx: polls single /approvals/pending endpoint, shows approve/deny cards with workspace name, slide-in-from-top animation, toast feedback.
• Agent decides when to call request_approval based on system prompt guidelines.

Hierarchical Memory Architecture (Phase 9, 15a-15f)

• Migration 008_agent_memories.sql: agent_memories table with pgvector extension, scope (LOCAL/TEAM/GLOBAL)
• handlers/memories.go: POST commit, GET search (with text ILIKE), DELETE
  • LOCAL: workspace_id only
  • TEAM: parent + siblings via parent_id join, CanCommunicate check, excludes removed workspaces
  • GLOBAL: readable by all, write restricted to root (no parent_id)
• tools/memory.py: commit_memory(content, scope) and search_memory(query, scope) tools
• Every agent now has 4 built-in tools: delegate, approve, commit_memory, search_memory

OpenRouter Provider + E2E Testing

• agent.py: added OpenRouter as 5th LLM provider (uses langchain-openai with custom base URL)
• requirements.txt: added langchain-openai>=0.3.0
• Supported providers: anthropic, openai, openrouter, google_genai, ollama
• E2E test results: 40/41 pass (SEO + Echo agents via OpenRouter claude-3.5-haiku). Tests: workspace CRUD, agent management, registry/discovery, heartbeat/status, A2A chat, secrets, HMA memory, approvals, config, templates, viewport, events, files, cascade delete.

Langfuse Trace Preview (Phase 10, 16c)

• handlers/traces.go: GET /workspaces/:id/traces proxies to Langfuse API
• TracesTab.tsx: expandable trace list with input/output, latency, tokens, cost
• SidePanel: 9 tabs now (added Traces)

Team Zoom-in + Skill Installer + ClawHub

• Canvas zoom-in (13g): double-click team node → fitBounds animation
• SkillInstaller (17n): type skill name → creates SKILL.md in workspace files
• ClawHub (17q): "Install from ClawHub" button sends install command via A2A

Coordinator Pattern (Phase 7, 13c)

• workspace/coordinator.py: auto-detects children on startup, injects team description into prompt, adds route_task_to_team tool
• When workspace has children → becomes coordinator that routes A2A messages to best-suited child based on capabilities
• Coordination rules injected: analyze task, choose member, delegate, aggregate, fallback

Production Hardening (Phase 14)

Graceful Shutdown (20e)

• main.go: signal handler for SIGINT/SIGTERM, context cancellation stops liveness monitor + Redis subscriber, HTTP server drains connections (30s timeout), WebSocket hub Close() disconnects all clients
• ws/hub.go: added Close() method

Rate Limiting (20d)

• middleware/ratelimit.go: token bucket rate limiter (100 req/min/IP), accepts context for clean shutdown, auto-cleanup of stale buckets every 5min
• Applied globally via router middleware

Secrets Encryption (20c)

• crypto/aes.go: AES-256-GCM encrypt/decrypt, enabled via SECRETS_ENCRYPTION_KEY env var (32 bytes raw or base64), graceful degradation to plaintext if not set, warnings on invalid key
• secrets.go: encrypt on write, decrypt on read
• workspace.go: decrypt secrets before injecting into provisioned containers

Delete Team Cascade (13h)

• workspace.go Delete handler: without ?confirm=true returns children list for confirmation, with confirm cascades delete to all sub-workspaces (stops containers, removes from DB, broadcasts events)
• DetailsTab.tsx: passes ?confirm=true after user confirms