stack/docs/scratchpads/ms19-chat-terminal-20260225.md

Mission Scratchpad — MS19 Chat & Terminal System

Append-only log. NEVER delete entries. NEVER overwrite sections. This is the orchestrator's working memory across sessions.

Original Mission Prompt

Plan MS19+, update mission artifacts for Coolify → Portainer transition.
MS18 is complete. Coolify deprecated, Portainer migration in progress with another agent.

Planning Decisions

2026-02-25 — Infrastructure Assessment

Existing chat infrastructure (~95% complete):

• ChatOverlay.tsx, ConversationSidebar.tsx, ChatInput.tsx, MessageList.tsx
• useChat hook with conversation management and LLM interaction
• Backend LLM controller with SSE streaming support
• Providers: Ollama, Claude, OpenAI
• Chat persistence via Ideas API

Existing terminal infrastructure (UI-only):

• TerminalPanel.tsx with tabs, rich output styling, animations
• No backend connection — purely mock UI

Existing orchestrator infrastructure:

• Orchestrator service (NestJS, port 3002) with agent spawn/kill/status
• SSE stream at /agents/events for real-time agent status
• Web proxy routes at /api/orchestrator/*
• Coordinator integration in API for job tracking

Key pattern reference:

• Speech gateway (apps/api/src/speech/speech.gateway.ts) shows namespace WebSocket pattern with session management

2026-02-25 — Architecture Decisions

Decision: node-pty for terminal backend

• Standard PTY management for Node.js (used by VS Code)
• Spawns real shell processes (bash/zsh)
• Handles resize, input/output streams
• WebSocket namespace /terminal for communication

Decision: Terminal sessions in PostgreSQL

• Consistent with workspace isolation pattern
• Prisma model: TerminalSession (id, workspaceId, name, status, createdAt, closedAt)
• Sessions survive page reload, recover on reconnect

Decision: SSE for chat streaming (not WebSocket)

• Backend already has SSE setup in LLM controller
• Only frontend wiring missing (streamChatMessage() is TODO)
• SSE is simpler and sufficient for unidirectional token streaming

Decision: Orchestrator commands as chat prefixes

• /spawn, /status, /jobs, /kill parsed in frontend
• Route through existing /api/orchestrator/* proxy
• Display structured responses inline in chat

2026-02-25 — Portainer Migration

Context: Coolify has been deprecated and shut down. Infrastructure migration to Portainer is being handled by another agent. All deployment references updated from Coolify to Portainer in PRD and mission manifest.

Impact on MS19:

• Deployment target is now Portainer (was Coolify)
• No code changes needed — only infrastructure config
• Smoke testing blocked until Portainer stack is running

Session Log

S1 — 2026-02-25

• Read mission state (MS18 complete, all 16 tasks done)
• Explored codebase for MS19 infrastructure (chat, terminal, WebSocket, orchestrator)
• Updated PRD: Coolify → Portainer, added MS18 completion, added MS19 FRs and acceptance criteria
• Created new MISSION-MANIFEST.md for MS19+ mission
• Created TASKS.md with 12-task breakdown (~250K token estimate)
• Created this scratchpad
• Archived MS18 TASKS.md to docs/tasks/MS18-ThemeWidgets-tasks.md