agentgui 1.0.385 → 1.0.387

package/.prd

@@ -0,0 +1,255 @@
+# AgentGUI ACP Compliance PRD
+
+## Overview
+Transform AgentGUI into a fully ACP (Agent Connect Protocol) v0.2.3 compliant server while fixing UI consistency issues and optimizing WebSocket usage.
+
+**Current Status**: ~30% ACP compliant (basic conversation/message CRUD exists)
+**Target**: 100% ACP compliant with all endpoints, thread management, stateless runs, and run control
+
+**Note on "Slash Commands"**: ACP spec contains no slash command concept. This is purely a client-side UI feature outside ACP scope. If user wants slash commands implemented, that would be a separate UI enhancement task.
+
+---
+
+## Dependency Graph & Execution Waves
+
+### WAVE 3: Streaming & Run Control (2 items - after Wave 2)
+
+**3.1** SSE (Server-Sent Events) Streaming
+- BLOCKS: 2.1, 2.2, 2.3
+- BLOCKED_BY: 4.1
+- Implement SSE endpoint format (Content-Type: text/event-stream)
+- Stream run outputs as ACP `RunOutputStream` format
+- Support both `ValueRunResultUpdate` and `CustomRunResultUpdate` modes
+- Event types: data, error, done
+- Keep-alive pings every 15 seconds
+- Handle client disconnect gracefully
+- Convert existing chunk/event stream to SSE format
+- Parallel SSE + WebSocket support (both work simultaneously)
+
+**3.2** Run Cancellation & Control
+- BLOCKS: 1.1, 1.2
+- BLOCKED_BY: 4.1
+- Implement run status state machine: pending → active → completed/error/cancelled
+- Cancel endpoint kills agent process (SIGTERM then SIGKILL)
+- Update run status to 'cancelled' in database
+- Broadcast cancellation via WebSocket
+- Clean up active execution tracking
+- Return 409 if run already completed/cancelled
+- Wait endpoint implements long-polling (30s timeout, return current status)
+- Handle graceful degradation if agent doesn't support cancellation
+
+### WAVE 4: UI Fixes & Optimization (3 items - after Wave 3)
+
+**4.1** Thread Sidebar UI Consistency
+- BLOCKS: 2.1, 2.2, 3.1
+- BLOCKED_BY: nothing
+- Audit conversation list rendering: verify agent display matches conversation.agentId
+- Ensure model selection persists when loading existing conversation
+- On conversation resume: restore last-used agent and model to UI selectors
+- Fix any duplicate agent/model displays in sidebar or header
+- Test: create conversation with agent A, reload page, verify agent A shown
+- Test: switch to agent B mid-conversation, reload, verify agent B shown
+- Store agent/model in conversation record, use as source of truth
+
+**4.2** WebSocket Usage Optimization
+- BLOCKS: 3.1
+- BLOCKED_BY: nothing
+- Audit all broadcastSync calls: identify high-frequency low-value messages
+- Batch streaming_progress events (max 10 events per 100ms window)
+- Only broadcast to subscribed clients (per sessionId or conversationId)
+- Compress large payloads before WebSocket send
+- Add message priority: high (errors, completion), normal (progress), low (status)
+- Rate limit per client: max 100 msg/sec
+- Implement message deduplication for identical consecutive events
+- Monitor: track bytes sent per client, log if >1MB/sec sustained
+
+**4.3** Consolidate Duplicate Displays
+- BLOCKS: 4.1
+- BLOCKED_BY: nothing
+- Identify all places where agent/model info is displayed
+- Remove duplicate displays: keep one authoritative location per UI section
+- Sidebar: show agent name only (remove if duplicated elsewhere)
+- Header/toolbar: show model + agent if conversation active
+- Message bubbles: show agent avatar/name per message only if multi-agent conversation
+- Test: verify no redundant agent/model text after changes
+
+---
+
+## Additional Enhancements (Non-blocking)
+
+### NICE-TO-HAVE 1: Webhook Callbacks
+- Implement webhook support for run status changes
+- POST to webhook URL when run status changes (pending → active → completed)
+- Retry logic: 3 attempts with exponential backoff
+- Store webhook config in run_metadata table
+- Validate webhook URL format on run creation
+
+### NICE-TO-HAVE 2: Run Interrupts
+- Support interrupt mechanism for agents that implement it
+- Interrupt types: user feedback request, tool approval, configuration needed
+- Store interrupt state in sessions table
+- API endpoints: GET /runs/{id}/interrupts, POST /runs/{id}/resume with interrupt response
+- UI: show interrupt prompt, collect user input, resume run
+
+### NICE-TO-HAVE 3: Enhanced Search & Filtering
+- Full-text search on thread content (messages, agent responses)
+- Filter by agent type, date range, status, metadata fields
+- Search history: recent searches saved per user
+- Autocomplete for search filters
+- Export search results as JSON
+
+### NICE-TO-HAVE 4: Thread Templates
+- Save thread configuration as template
+- Templates include: agent, model, initial prompt, working directory
+- Clone thread from template
+- Share templates between users (if multi-user support added)
+
+---
+
+## Testing Requirements (Per Item)
+
+Each implementation item must include:
+1. Execute in plugin:gm:dev: create test run for every endpoint/function
+2. Success paths: valid inputs, expected outputs verified
+3. Error paths: invalid inputs, 404s, 409s, 422s verified
+4. Edge cases: empty results, large payloads, concurrent requests
+5. Integration tests: end-to-end flow (create thread → run → stream → cancel)
+6. Database verification: inspect tables after operations, verify foreign keys
+7. WebSocket verification: subscribe, receive events, verify payload format
+8. SSE verification: curl endpoint, verify event-stream format
+
+---
+
+## Acceptance Criteria (All Must Pass)
+
+### Core ACP Compliance
+- [ ] All 23 ACP endpoints implemented and tested
+- [ ] All ACP data models match spec (Thread, ThreadState, Run, Agent, etc.)
+- [ ] Error responses follow ACP format (ErrorResponse schema)
+- [ ] SSE streaming works with curl: `curl -N /threads/{id}/runs/stream`
+- [ ] Stateless runs work without thread context
+- [ ] Run cancellation kills agent process within 5 seconds
+- [ ] Thread copy duplicates all states and checkpoints
+- [ ] Agent descriptors return valid JSON matching AgentACPDescriptor schema
+
+### Database Integrity
+- [ ] No orphaned records after thread/run deletion
+- [ ] Foreign key constraints enforced
+- [ ] Thread status correctly reflects run states
+- [ ] Checkpoint sequences monotonically increase
+- [ ] WAL mode enabled, queries under 100ms for typical operations
+
+### UI Consistency
+- [ ] Sidebar shows correct agent for each conversation
+- [ ] Model selection persists after page reload
+- [ ] No duplicate agent/model displays found
+- [ ] Agent/model changes reflected in database immediately
+
+### WebSocket Optimization
+- [ ] Streaming progress events batched (max 10/100ms)
+- [ ] Only subscribed clients receive messages
+- [ ] No client exceeds 1MB/sec sustained WebSocket traffic
+- [ ] Message deduplication prevents identical consecutive events
+
+### Integration & E2E
+- [ ] Full flow: create thread → start run → stream events → cancel → verify cancelled
+- [ ] Stateless run: create run → stream → complete → verify output
+- [ ] Thread search: create 10 threads → search by metadata → verify correct results
+- [ ] Agent search: search by capability "streaming" → verify all streaming agents returned
+- [ ] Thread copy: create thread with 5 runs → copy → verify new thread has all history
+- [ ] Concurrent runs blocked: start run on thread → start second run → verify 409 conflict
+
+---
+
+## Migration Strategy
+
+### Backward Compatibility
+- Existing conversations map to threads (1:1)
+- Existing sessions map to thread runs
+- `/api/conversations/*` endpoints remain functional (alias to `/threads/*`)
+- Old WebSocket message formats supported alongside new ACP formats
+- No breaking changes to current client code
+
+### Rollout Plan
+1. Deploy database schema changes (additive only, no drops)
+2. Deploy new ACP endpoints alongside existing endpoints
+3. Update client to use ACP endpoints where beneficial
+4. Deprecation notice for old endpoints (6 month window)
+5. Remove old endpoints after deprecation period
+
+---
+
+## Out of Scope
+
+- Multi-user authentication/authorization
+- Slash command implementation (not in ACP spec, pure client feature)
+- Agent marketplace or discovery service
+- Real-time collaboration on threads
+- Thread branching/forking (beyond simple copy)
+- Custom agent development framework
+- Billing/metering for agent usage
+
+---
+
+## Technical Notes
+
+### ACP Terminology Mapping
+- AgentGUI "conversations" = ACP "threads"
+- AgentGUI "sessions" = ACP "runs" (stateful, on a thread)
+- AgentGUI "chunks/events" = ACP "run output stream"
+- AgentGUI "claudeSessionId" = ACP checkpoint ID concept
+
+### Known Gotchas
+- ACP requires UUID format for thread_id, run_id, agent_id (current AgentGUI uses strings)
+- SSE requires newline-delimited format, different from current JSON streaming
+- Run cancellation must handle agents that don't support it gracefully
+- Thread status "idle" means no pending runs; must validate on run creation
+- Webhook URLs must be validated to prevent SSRF attacks
+
+### Performance Targets
+- Thread search: <200ms for 10,000 threads
+- Run creation: <50ms (background processing)
+- SSE streaming: <10ms latency per event
+- WebSocket batch: <100ms accumulation window
+- Database writes: <20ms per transaction
+
+---
+
+## Dependencies
+
+**External**:
+- None (all features implemented with existing dependencies)
+
+**Internal**:
+- database.js (extended with new tables/queries)
+- server.js (new route handlers)
+- lib/claude-runner.js (run cancellation support)
+- static/js/client.js (UI consistency fixes)
+- static/js/conversations.js (agent/model persistence)
+- static/js/websocket-manager.js (optimization)
+
+**Configuration**:
+- No new env vars required
+- Existing BASE_URL, PORT, STARTUP_CWD remain unchanged
+
+---
+
+## Success Metrics
+
+- ACP compliance score: 0% → 100%
+- API endpoint coverage: 20 → 43 endpoints
+- WebSocket bandwidth: <50% reduction in bytes/sec per client
+- UI consistency issues: 4 identified → 0 remaining
+- Database tables: 5 → 8 (conversations, messages, sessions, events, chunks, thread_states, checkpoints, run_metadata)
+- Test coverage: endpoint tests for all 43 routes, integration tests for all critical flows
+
+---
+
+## Timeline Estimate
+
+- Wave 1 (Foundation): 3 parallel tasks = 1 completion cycle
+- Wave 2 (Core APIs): 3 parallel tasks = 1 completion cycle
+- Wave 3 (Streaming): 2 tasks = 1 completion cycle
+- Wave 4 (UI Fixes): 3 tasks = 1 completion cycle
+
+**Total**: 4 completion cycles (waves executed sequentially, items within wave executed in parallel with max 3 concurrent subagents per wave)

package/lib/sse-stream.js

@@ -0,0 +1,125 @@
+import crypto from 'crypto';
+
+export function formatSSEEvent(eventType, data) {
+  const lines = [];
+  if (eventType) {
+    lines.push(`event: ${eventType}`);
+  }
+  if (data) {
+    const jsonData = typeof data === 'string' ? data : JSON.stringify(data);
+    lines.push(`data: ${jsonData}`);
+  }
+  lines.push('');
+  return lines.join('\n') + '\n';
+}
+
+export function convertToACPRunOutputStream(sessionId, block, runStatus = 'active') {
+  const eventId = crypto.randomUUID();
+  return {
+    id: eventId,
+    event: 'agent_event',
+    data: {
+      type: 'custom',
+      run_id: sessionId,
+      status: runStatus,
+      update: block
+    }
+  };
+}
+
+export function createErrorEvent(runId, errorMessage, errorCode = 'execution_error') {
+  const eventId = crypto.randomUUID();
+  return {
+    id: eventId,
+    event: 'agent_event',
+    data: {
+      type: 'error',
+      run_id: runId,
+      error: errorMessage,
+      code: errorCode,
+      status: 'error'
+    }
+  };
+}
+
+export function createCompletionEvent(runId, values = {}, metadata = {}) {
+  const eventId = crypto.randomUUID();
+  return {
+    id: eventId,
+    event: 'agent_event',
+    data: {
+      type: 'result',
+      run_id: runId,
+      status: 'completed',
+      values,
+      metadata
+    }
+  };
+}
+
+export function createKeepAlive() {
+  return ': ping\n\n';
+}
+
+export class SSEStreamManager {
+  constructor(res, runId) {
+    this.res = res;
+    this.runId = runId;
+    this.keepAliveInterval = null;
+    this.closed = false;
+  }
+
+  start() {
+    this.res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no'
+    });
+
+    this.keepAliveInterval = setInterval(() => {
+      if (!this.closed) {
+        this.writeRaw(createKeepAlive());
+      }
+    }, 15000);
+
+    this.res.on('close', () => {
+      this.cleanup();
+    });
+  }
+
+  writeRaw(text) {
+    if (!this.closed) {
+      this.res.write(text);
+    }
+  }
+
+  sendProgress(block, runStatus = 'active') {
+    const acpEvent = convertToACPRunOutputStream(this.runId, block, runStatus);
+    const sse = formatSSEEvent('message', acpEvent.data);
+    this.writeRaw(sse);
+  }
+
+  sendError(errorMessage, errorCode = 'execution_error') {
+    const errorEvent = createErrorEvent(this.runId, errorMessage, errorCode);
+    const sse = formatSSEEvent('error', errorEvent.data);
+    this.writeRaw(sse);
+  }
+
+  sendComplete(values = {}, metadata = {}) {
+    const completionEvent = createCompletionEvent(this.runId, values, metadata);
+    const sse = formatSSEEvent('done', completionEvent.data);
+    this.writeRaw(sse);
+  }
+
+  cleanup() {
+    if (this.keepAliveInterval) {
+      clearInterval(this.keepAliveInterval);
+      this.keepAliveInterval = null;
+    }
+    this.closed = true;
+    if (!this.res.writableEnded) {
+      this.res.end();
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.385",
+  "version": "1.0.387",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -12,10 +12,10 @@ import { OAuth2Client } from 'google-auth-library';
 import express from 'express';
 import Busboy from 'busboy';
 import fsbrowse from 'fsbrowse';
-import { queries, db, prepare } from './database.js';
-import { createACPQueries } from './acp-queries.js';
+import { queries } from './database.js';
 import { runClaudeWithStreaming } from './lib/claude-runner.js';
 import { initializeDescriptors, getAgentDescriptor } from './lib/agent-descriptors.js';
+import { SSEStreamManager } from './lib/sse-stream.js';
 
 const ttsTextAccumulators = new Map();
 
@@ -215,6 +215,8 @@ const activeExecutions = new Map();
 const activeScripts = new Map();
 const messageQueues = new Map();
 const rateLimitState = new Map();
+const activeProcessesByRunId = new Map();
+const acpQueries = queries;
 const STUCK_AGENT_THRESHOLD_MS = 600000;
 const NO_PID_GRACE_PERIOD_MS = 60000;
 const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60000;
@@ -341,8 +343,6 @@ function discoverAgents() {
 
 const discoveredAgents = discoverAgents();
 initializeDescriptors(discoveredAgents);
-const acpQueries = createACPQueries(db, prepare);
-acpQueries.getAgentDescriptor = getAgentDescriptor;
 
 const modelCache = new Map();
 
@@ -1772,7 +1772,7 @@ const server = http.createServer(async (req, res) => {
 
     if (pathOnly === '/api/agents/search' && req.method === 'POST') {
       const body = await parseBody(req);
-      const result = acpQueries.searchAgents(discoveredAgents, body);
+      const result = queries.searchAgents(discoveredAgents, body);
       sendJSON(req, res, 200, result);
       return;
     }
@@ -1906,14 +1906,14 @@ const server = http.createServer(async (req, res) => {
         sendJSON(req, res, 404, { error: 'Agent not found' });
         return;
       }
-      const run = acpQueries.createRun(agent_id, null, input, config, webhook_url);
+      const run = queries.createRun(agent_id, null, input, config, webhook_url);
       sendJSON(req, res, 201, run);
       return;
     }
 
     if (pathOnly === '/api/runs/search' && req.method === 'POST') {
       const body = await parseBody(req);
-      const result = acpQueries.searchRuns(body);
+      const result = queries.searchRuns(body);
       sendJSON(req, res, 200, result);
       return;
     }
@@ -1930,27 +1930,42 @@ const server = http.createServer(async (req, res) => {
         sendJSON(req, res, 404, { error: 'Agent not found' });
         return;
       }
-      const run = acpQueries.createRun(agent_id, null, input, config);
-      res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        'Connection': 'keep-alive'
-      });
-      res.write('data: ' + JSON.stringify({ type: 'run_created', run_id: run.run_id }) + '\n\n');
+      const run = queries.createRun(agent_id, null, input, config);
+      const sseManager = new SSEStreamManager(res, run.run_id);
+      sseManager.start();
+      sseManager.sendProgress({ type: 'run_created', run_id: run.run_id });
+
       const eventHandler = (eventData) => {
         if (eventData.sessionId === run.run_id || eventData.conversationId === run.thread_id) {
-          res.write('data: ' + JSON.stringify(eventData) + '\n\n');
+          if (eventData.type === 'streaming_progress' && eventData.block) {
+            sseManager.sendProgress(eventData.block);
+          } else if (eventData.type === 'streaming_error') {
+            sseManager.sendError(eventData.error || 'Execution error');
+          } else if (eventData.type === 'streaming_complete') {
+            sseManager.sendComplete({ eventCount: eventData.eventCount }, { timestamp: eventData.timestamp });
+            sseManager.cleanup();
+          }
         }
       };
-      const cleanup = () => {
-        res.end();
-      };
-      req.on('close', cleanup);
-      const statelessThreadId = acpQueries.getRun(run.run_id)?.thread_id;
+
+      sseStreamHandlers.set(run.run_id, eventHandler);
+      req.on('close', () => {
+        sseStreamHandlers.delete(run.run_id);
+        sseManager.cleanup();
+      });
+
+      const statelessThreadId = queries.getRun(run.run_id)?.thread_id;
       if (statelessThreadId) {
         const conv = queries.getConversation(statelessThreadId);
         if (conv && input?.content) {
-          runClaudeWithStreaming(agent_id, statelessThreadId, input.content, config?.model || null).catch(() => {});
+          const session = queries.createSession(statelessThreadId);
+          acpQueries.updateRunStatus(run.run_id, 'active');
+          activeExecutions.set(statelessThreadId, { pid: null, startTime: Date.now(), sessionId: session.id, lastActivity: Date.now() });
+          activeProcessesByRunId.set(run.run_id, { threadId: statelessThreadId, sessionId: session.id });
+          queries.setIsStreaming(statelessThreadId, true);
+          processMessageWithStreaming(statelessThreadId, null, session.id, input.content, agent_id, config?.model || null)
+            .then(() => { acpQueries.updateRunStatus(run.run_id, 'success'); activeProcessesByRunId.delete(run.run_id); })
+            .catch((err) => { acpQueries.updateRunStatus(run.run_id, 'error'); activeProcessesByRunId.delete(run.run_id); sseManager.sendError(err.message); sseManager.cleanup(); });
         }
       }
       return;
@@ -1968,15 +1983,15 @@ const server = http.createServer(async (req, res) => {
         sendJSON(req, res, 404, { error: 'Agent not found' });
         return;
       }
-      const run = acpQueries.createRun(agent_id, null, input, config);
-      const statelessThreadId = acpQueries.getRun(run.run_id)?.thread_id;
+      const run = queries.createRun(agent_id, null, input, config);
+      const statelessThreadId = queries.getRun(run.run_id)?.thread_id;
       if (statelessThreadId && input?.content) {
         try {
           await runClaudeWithStreaming(agent_id, statelessThreadId, input.content, config?.model || null);
-          const finalRun = acpQueries.getRun(run.run_id);
+          const finalRun = queries.getRun(run.run_id);
           sendJSON(req, res, 200, finalRun);
         } catch (err) {
-          acpQueries.updateRunStatus(run.run_id, 'error');
+          queries.updateRunStatus(run.run_id, 'error');
           sendJSON(req, res, 500, { error: err.message });
         }
       } else {
@@ -1990,7 +2005,7 @@ const server = http.createServer(async (req, res) => {
       const runId = oldRunByIdMatch1[1];
 
       if (req.method === 'GET') {
-        const run = acpQueries.getRun(runId);
+        const run = queries.getRun(runId);
         if (!run) {
           sendJSON(req, res, 404, { error: 'Run not found' });
           return;
@@ -2001,7 +2016,7 @@ const server = http.createServer(async (req, res) => {
 
       if (req.method === 'POST') {
         const body = await parseBody(req);
-        const run = acpQueries.getRun(runId);
+        const run = queries.getRun(runId);
         if (!run) {
           sendJSON(req, res, 404, { error: 'Run not found' });
           return;
@@ -2019,7 +2034,7 @@ const server = http.createServer(async (req, res) => {
 
       if (req.method === 'DELETE') {
         try {
-          acpQueries.deleteRun(runId);
+          queries.deleteRun(runId);
           res.writeHead(204);
           res.end();
         } catch (err) {
@@ -2032,17 +2047,22 @@ const server = http.createServer(async (req, res) => {
     const runWaitMatch = pathOnly.match(/^\/api\/runs\/([^/]+)\/wait$/);
     if (runWaitMatch && req.method === 'GET') {
       const runId = runWaitMatch[1];
-      const run = acpQueries.getRun(runId);
+      const run = queries.getRun(runId);
       if (!run) {
         sendJSON(req, res, 404, { error: 'Run not found' });
         return;
       }
       const startTime = Date.now();
       const pollInterval = setInterval(() => {
-        const currentRun = acpQueries.getRun(runId);
-        if (!currentRun || ['success', 'error', 'cancelled'].includes(currentRun.status) || (Date.now() - startTime) > 30000) {
+        const currentRun = queries.getRun(runId);
+        const elapsed = Date.now() - startTime;
+        const done = currentRun && ['success', 'error', 'cancelled'].includes(currentRun.status);
+        if (done) {
           clearInterval(pollInterval);
-          sendJSON(req, res, 200, currentRun || run);
+          sendJSON(req, res, 200, currentRun);
+        } else if (elapsed > 30000) {
+          clearInterval(pollInterval);
+          sendJSON(req, res, 408, { error: 'Run still pending after 30s', run_id: runId, status: currentRun?.status || run.status });
         }
       }, 500);
       req.on('close', () => clearInterval(pollInterval));
@@ -2052,26 +2072,34 @@ const server = http.createServer(async (req, res) => {
     const runStreamMatch = pathOnly.match(/^\/api\/runs\/([^/]+)\/stream$/);
     if (runStreamMatch && req.method === 'GET') {
       const runId = runStreamMatch[1];
-      const run = acpQueries.getRun(runId);
+      const run = queries.getRun(runId);
       if (!run) {
         sendJSON(req, res, 404, { error: 'Run not found' });
         return;
       }
-      res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        'Connection': 'keep-alive'
-      });
-      res.write('data: ' + JSON.stringify({ type: 'joined', run_id: runId }) + '\n\n');
+
+      const sseManager = new SSEStreamManager(res, runId);
+      sseManager.start();
+      sseManager.sendProgress({ type: 'joined', run_id: runId });
+
       const eventHandler = (eventData) => {
         if (eventData.sessionId === runId || eventData.conversationId === run.thread_id) {
-          res.write('data: ' + JSON.stringify(eventData) + '\n\n');
+          if (eventData.type === 'streaming_progress' && eventData.block) {
+            sseManager.sendProgress(eventData.block);
+          } else if (eventData.type === 'streaming_error') {
+            sseManager.sendError(eventData.error || 'Execution error');
+          } else if (eventData.type === 'streaming_complete') {
+            sseManager.sendComplete({ eventCount: eventData.eventCount }, { timestamp: eventData.timestamp });
+            sseManager.cleanup();
+          }
         }
       };
-      const cleanup = () => {
-        res.end();
-      };
-      req.on('close', cleanup);
+
+      sseStreamHandlers.set(runId, eventHandler);
+      req.on('close', () => {
+        sseStreamHandlers.delete(runId);
+        sseManager.cleanup();
+      });
       return;
     }
 
@@ -2079,17 +2107,144 @@ const server = http.createServer(async (req, res) => {
     if (oldRunCancelMatch1 && req.method === 'POST') {
       const runId = oldRunCancelMatch1[1];
       try {
-        const run = acpQueries.cancelRun(runId);
-        const execution = activeExecutions.get(run.thread_id);
-        if (execution?.process) {
-          execution.process.kill('SIGTERM');
+        const run = queries.getRun(runId);
+        if (!run) {
+          sendJSON(req, res, 404, { error: 'Run not found' });
+          return;
+        }
+
+        if (['success', 'error', 'cancelled'].includes(run.status)) {
+          sendJSON(req, res, 409, { error: 'Run already completed or cancelled' });
+          return;
+        }
+
+        const cancelledRun = queries.cancelRun(runId);
+
+        const threadId = run.thread_id;
+        if (threadId) {
+          const execution = activeExecutions.get(threadId);
+          if (execution?.pid) {
+            try {
+              process.kill(-execution.pid, 'SIGTERM');
+            } catch {
+              try {
+                process.kill(execution.pid, 'SIGTERM');
+              } catch (e) {
+                console.error(`[cancel] Failed to SIGTERM PID ${execution.pid}:`, e.message);
+              }
+            }
+
+            setTimeout(() => {
+              try {
+                process.kill(-execution.pid, 'SIGKILL');
+              } catch {
+                try {
+                  process.kill(execution.pid, 'SIGKILL');
+                } catch (e) {}
+              }
+            }, 3000);
+          }
+
+          if (execution?.sessionId) {
+            queries.updateSession(execution.sessionId, {
+              status: 'error',
+              error: 'Cancelled by user',
+              completed_at: Date.now()
+            });
+          }
+
+          activeExecutions.delete(threadId);
+          queries.setIsStreaming(threadId, false);
+
+          broadcastSync({
+            type: 'streaming_cancelled',
+            sessionId: execution?.sessionId || runId,
+            conversationId: threadId,
+            runId: runId,
+            timestamp: Date.now()
+          });
+        }
+
+        sendJSON(req, res, 200, cancelledRun);
+      } catch (err) {
+        if (err.message === 'Run not found') {
+          sendJSON(req, res, 404, { error: err.message });
+        } else if (err.message.includes('already completed')) {
+          sendJSON(req, res, 409, { error: err.message });
+        } else {
+          sendJSON(req, res, 500, { error: err.message });
+        }
+      }
+      return;
+    }
+
+    const threadRunCancelMatch = pathOnly.match(/^\/api\/threads\/([^/]+)\/runs\/([^/]+)\/cancel$/);
+    if (threadRunCancelMatch && req.method === 'POST') {
+      const threadId = threadRunCancelMatch[1];
+      const runId = threadRunCancelMatch[2];
+
+      try {
+        const run = queries.getRun(runId);
+        if (!run) {
+          sendJSON(req, res, 404, { error: 'Run not found' });
+          return;
+        }
+
+        if (run.thread_id !== threadId) {
+          sendJSON(req, res, 400, { error: 'Run does not belong to specified thread' });
+          return;
+        }
+
+        if (['success', 'error', 'cancelled'].includes(run.status)) {
+          sendJSON(req, res, 409, { error: 'Run already completed or cancelled' });
+          return;
+        }
+
+        const cancelledRun = queries.cancelRun(runId);
+
+        const execution = activeExecutions.get(threadId);
+        if (execution?.pid) {
+          try {
+            process.kill(-execution.pid, 'SIGTERM');
+          } catch {
+            try {
+              process.kill(execution.pid, 'SIGTERM');
+            } catch (e) {
+              console.error(`[cancel] Failed to SIGTERM PID ${execution.pid}:`, e.message);
+            }
+          }
+
           setTimeout(() => {
-            if (execution.process && !execution.process.killed) {
-              execution.process.kill('SIGKILL');
+            try {
+              process.kill(-execution.pid, 'SIGKILL');
+            } catch {
+              try {
+                process.kill(execution.pid, 'SIGKILL');
+              } catch (e) {}
             }
-          }, 5000);
+          }, 3000);
         }
-        sendJSON(req, res, 200, run);
+
+        if (execution?.sessionId) {
+          queries.updateSession(execution.sessionId, {
+            status: 'error',
+            error: 'Cancelled by user',
+            completed_at: Date.now()
+          });
+        }
+
+        activeExecutions.delete(threadId);
+        queries.setIsStreaming(threadId, false);
+
+        broadcastSync({
+          type: 'streaming_cancelled',
+          sessionId: execution?.sessionId || runId,
+          conversationId: threadId,
+          runId: runId,
+          timestamp: Date.now()
+        });
+
+        sendJSON(req, res, 200, cancelledRun);
       } catch (err) {
         if (err.message === 'Run not found') {
           sendJSON(req, res, 404, { error: err.message });
@@ -2102,6 +2257,34 @@ const server = http.createServer(async (req, res) => {
       return;
     }
 
+    const threadRunWaitMatch = pathOnly.match(/^\/api\/threads\/([^/]+)\/runs\/([^/]+)\/wait$/);
+    if (threadRunWaitMatch && req.method === 'GET') {
+      const threadId = threadRunWaitMatch[1];
+      const runId = threadRunWaitMatch[2];
+
+      const run = queries.getRun(runId);
+      if (!run) {
+        sendJSON(req, res, 404, { error: 'Run not found' });
+        return;
+      }
+
+      if (run.thread_id !== threadId) {
+        sendJSON(req, res, 400, { error: 'Run does not belong to specified thread' });
+        return;
+      }
+
+      const startTime = Date.now();
+      const pollInterval = setInterval(() => {
+        const currentRun = queries.getRun(runId);
+        if (!currentRun || ['success', 'error', 'cancelled'].includes(currentRun.status) || (Date.now() - startTime) > 30000) {
+          clearInterval(pollInterval);
+          sendJSON(req, res, 200, currentRun || run);
+        }
+      }, 500);
+      req.on('close', () => clearInterval(pollInterval));
+      return;
+    }
+
     if (pathOnly === '/api/gemini-oauth/start' && req.method === 'POST') {
       try {
         const result = await startGeminiOAuth(req);
@@ -2608,6 +2791,7 @@ const server = http.createServer(async (req, res) => {
 
     // POST /threads - Create empty thread
     if (pathOnly === '/api/threads' && req.method === 'POST') {
+      console.log('[ACP] POST /api/threads HIT');
       try {
         const body = await parseBody(req);
         const metadata = body.metadata || {};
@@ -2744,6 +2928,179 @@ const server = http.createServer(async (req, res) => {
       return;
     }
 
+    // POST /threads/{thread_id}/runs/stream - Create run on thread and stream output
+    const threadRunsStreamMatch = pathOnly.match(/^\/api\/threads\/([a-f0-9-]{36})\/runs\/stream$/);
+    if (threadRunsStreamMatch && req.method === 'POST') {
+      const threadId = threadRunsStreamMatch[1];
+      try {
+        const body = await parseBody(req);
+        const { agent_id, input, config } = body;
+
+        const thread = queries.getThread(threadId);
+        if (!thread) {
+          sendJSON(req, res, 404, { error: 'Thread not found', type: 'not_found' });
+          return;
+        }
+
+        if (thread.status !== 'idle') {
+          sendJSON(req, res, 409, { error: 'Thread has pending runs', type: 'conflict' });
+          return;
+        }
+
+        const agent = discoveredAgents.find(a => a.id === agent_id);
+        if (!agent) {
+          sendJSON(req, res, 404, { error: 'Agent not found', type: 'not_found' });
+          return;
+        }
+
+        const run = queries.createRun(agent_id, threadId, input, config);
+        const sseManager = new SSEStreamManager(res, run.run_id);
+        sseManager.start();
+        sseManager.sendProgress({ type: 'run_created', run_id: run.run_id, thread_id: threadId });
+
+        const eventHandler = (eventData) => {
+          if (eventData.sessionId === run.run_id || eventData.conversationId === threadId) {
+            if (eventData.type === 'streaming_progress' && eventData.block) {
+              sseManager.sendProgress(eventData.block);
+            } else if (eventData.type === 'streaming_error') {
+              sseManager.sendError(eventData.error || 'Execution error');
+            } else if (eventData.type === 'streaming_complete') {
+              sseManager.sendComplete({ eventCount: eventData.eventCount }, { timestamp: eventData.timestamp });
+              sseManager.cleanup();
+            }
+          }
+        };
+
+        sseStreamHandlers.set(run.run_id, eventHandler);
+        req.on('close', () => {
+          sseStreamHandlers.delete(run.run_id);
+          sseManager.cleanup();
+        });
+
+        const conv = queries.getConversation(threadId);
+        if (conv && input?.content) {
+          const session = queries.createSession(threadId);
+          queries.updateRunStatus(run.run_id, 'active');
+          activeExecutions.set(threadId, { pid: null, startTime: Date.now(), sessionId: session.id, lastActivity: Date.now() });
+          activeProcessesByRunId.set(run.run_id, { threadId, sessionId: session.id });
+          queries.setIsStreaming(threadId, true);
+          processMessageWithStreaming(threadId, null, session.id, input.content, agent_id, config?.model || null)
+            .then(() => { queries.updateRunStatus(run.run_id, 'success'); activeProcessesByRunId.delete(run.run_id); })
+            .catch((err) => { queries.updateRunStatus(run.run_id, 'error'); activeProcessesByRunId.delete(run.run_id); sseManager.sendError(err.message); sseManager.cleanup(); });
+        }
+      } catch (err) {
+        sendJSON(req, res, 422, { error: err.message, type: 'validation_error' });
+      }
+      return;
+    }
+
+    // GET /threads/{thread_id}/runs/{run_id}/stream - Stream output from run on thread
+    const threadRunStreamMatch = pathOnly.match(/^\/api\/threads\/([a-f0-9-]{36})\/runs\/([a-f0-9-]{36})\/stream$/);
+    if (threadRunStreamMatch && req.method === 'GET') {
+      const threadId = threadRunStreamMatch[1];
+      const runId = threadRunStreamMatch[2];
+
+      const thread = queries.getThread(threadId);
+      if (!thread) {
+        sendJSON(req, res, 404, { error: 'Thread not found', type: 'not_found' });
+        return;
+      }
+
+      const run = queries.getRun(runId);
+      if (!run || run.thread_id !== threadId) {
+        sendJSON(req, res, 404, { error: 'Run not found on thread', type: 'not_found' });
+        return;
+      }
+
+      const sseManager = new SSEStreamManager(res, runId);
+      sseManager.start();
+      sseManager.sendProgress({ type: 'joined', run_id: runId, thread_id: threadId });
+
+      const eventHandler = (eventData) => {
+        if (eventData.sessionId === runId || eventData.conversationId === threadId) {
+          if (eventData.type === 'streaming_progress' && eventData.block) {
+            sseManager.sendProgress(eventData.block);
+          } else if (eventData.type === 'streaming_error') {
+            sseManager.sendError(eventData.error || 'Execution error');
+          } else if (eventData.type === 'streaming_complete') {
+            sseManager.sendComplete({ eventCount: eventData.eventCount }, { timestamp: eventData.timestamp });
+            sseManager.cleanup();
+          }
+        }
+      };
+
+      sseStreamHandlers.set(runId, eventHandler);
+      req.on('close', () => {
+        sseStreamHandlers.delete(runId);
+        sseManager.cleanup();
+      });
+      return;
+    }
+
+    // POST /threads/{thread_id}/runs/{run_id}/cancel - Cancel a run on a thread
+    const threadRunCancelMatch = pathOnly.match(/^\/api\/threads\/([a-f0-9-]{36})\/runs\/([a-f0-9-]{36})\/cancel$/);
+    if (threadRunCancelMatch && req.method === 'POST') {
+      const threadId = threadRunCancelMatch[1];
+      const runId = threadRunCancelMatch[2];
+      try {
+        const run = queries.getRun(runId);
+        if (!run || run.thread_id !== threadId) {
+          sendJSON(req, res, 404, { error: 'Run not found on thread', type: 'not_found' });
+          return;
+        }
+        if (['success', 'error', 'cancelled'].includes(run.status)) {
+          sendJSON(req, res, 409, { error: 'Run already completed or cancelled', type: 'conflict' });
+          return;
+        }
+        const cancelledRun = queries.cancelRun(runId);
+        const execution = activeExecutions.get(threadId);
+        if (execution?.pid) {
+          try { process.kill(-execution.pid, 'SIGTERM'); } catch { try { process.kill(execution.pid, 'SIGTERM'); } catch (e) {} }
+          setTimeout(() => {
+            try { process.kill(-execution.pid, 'SIGKILL'); } catch { try { process.kill(execution.pid, 'SIGKILL'); } catch (e) {} }
+          }, 3000);
+        }
+        if (execution?.sessionId) {
+          queries.updateSession(execution.sessionId, { status: 'error', error: 'Cancelled by user', completed_at: Date.now() });
+        }
+        activeExecutions.delete(threadId);
+        activeProcessesByRunId.delete(runId);
+        queries.setIsStreaming(threadId, false);
+        broadcastSync({ type: 'run_cancelled', runId, threadId, sessionId: execution?.sessionId, timestamp: Date.now() });
+        sendJSON(req, res, 200, cancelledRun);
+      } catch (err) {
+        sendJSON(req, res, 500, { error: err.message, type: 'internal_error' });
+      }
+      return;
+    }
+
+    // GET /threads/{thread_id}/runs/{run_id}/wait - Long-poll for run completion on thread
+    const threadRunWaitMatch = pathOnly.match(/^\/api\/threads\/([a-f0-9-]{36})\/runs\/([a-f0-9-]{36})\/wait$/);
+    if (threadRunWaitMatch && req.method === 'GET') {
+      const threadId = threadRunWaitMatch[1];
+      const runId = threadRunWaitMatch[2];
+      const run = queries.getRun(runId);
+      if (!run || run.thread_id !== threadId) {
+        sendJSON(req, res, 404, { error: 'Run not found on thread', type: 'not_found' });
+        return;
+      }
+      const startTime = Date.now();
+      const pollInterval = setInterval(() => {
+        const currentRun = queries.getRun(runId);
+        const elapsed = Date.now() - startTime;
+        const done = currentRun && ['success', 'error', 'cancelled'].includes(currentRun.status);
+        if (done) {
+          clearInterval(pollInterval);
+          sendJSON(req, res, 200, currentRun);
+        } else if (elapsed > 30000) {
+          clearInterval(pollInterval);
+          sendJSON(req, res, 408, { error: 'Run still pending after 30s', run_id: runId, status: currentRun?.status || run.status });
+        }
+      }, 500);
+      req.on('close', () => clearInterval(pollInterval));
+      return;
+    }
+
     if (routePath.startsWith('/api/image/')) {
       const imagePath = routePath.slice('/api/image/'.length);
       const decodedPath = decodeURIComponent(imagePath);
@@ -3318,6 +3675,7 @@ const wss = new WebSocketServer({
 const hotReloadClients = [];
 const syncClients = new Set();
 const subscriptionIndex = new Map();
+const sseStreamHandlers = new Map();
 
 wss.on('connection', (ws, req) => {
   // req.url in WebSocket is just the path (e.g., '/gm/sync'), not a full URL
@@ -3491,25 +3849,33 @@ function sendToClient(ws, data) {
 }
 
 function broadcastSync(event) {
-  if (syncClients.size === 0) return;
   const data = JSON.stringify(event);
   const isBroadcast = BROADCAST_TYPES.has(event.type);
 
-  if (isBroadcast) {
-    for (const ws of syncClients) sendToClient(ws, data);
-    return;
+  // Send to WebSocket clients
+  if (syncClients.size > 0) {
+    if (isBroadcast) {
+      for (const ws of syncClients) sendToClient(ws, data);
+    } else {
+      const targets = new Set();
+      if (event.sessionId) {
+        const subs = subscriptionIndex.get(event.sessionId);
+        if (subs) for (const ws of subs) targets.add(ws);
+      }
+      if (event.conversationId) {
+        const subs = subscriptionIndex.get(`conv-${event.conversationId}`);
+        if (subs) for (const ws of subs) targets.add(ws);
+      }
+      for (const ws of targets) sendToClient(ws, data);
+    }
   }
 
-  const targets = new Set();
-  if (event.sessionId) {
-    const subs = subscriptionIndex.get(event.sessionId);
-    if (subs) for (const ws of subs) targets.add(ws);
-  }
-  if (event.conversationId) {
-    const subs = subscriptionIndex.get(`conv-${event.conversationId}`);
-    if (subs) for (const ws of subs) targets.add(ws);
+  // Send to SSE handlers
+  if (sseStreamHandlers.size > 0) {
+    for (const [runId, handler] of sseStreamHandlers.entries()) {
+      handler(event);
+    }
   }
-  for (const ws of targets) sendToClient(ws, data);
 }
 
 // Heartbeat interval to detect stale connections

package/test-acp-endpoints.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+const http = require('http');
+
+const BASE_URL = '/gm';
+const PORT = 3000;
+
+function makeRequest(method, path, body = null) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'localhost',
+      port: PORT,
+      path: BASE_URL + path,
+      method: method,
+      headers: body ? {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(JSON.stringify(body))
+      } : {}
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          resolve({ status: res.statusCode, data: data ? JSON.parse(data) : null, raw: data });
+        } catch {
+          resolve({ status: res.statusCode, data: null, raw: data });
+        }
+      });
+    });
+
+    req.on('error', reject);
+
+    if (body) {
+      req.write(JSON.stringify(body));
+    }
+    req.end();
+  });
+}
+
+async function runTests() {
+  console.log('Testing ACP Agents & Stateless Runs Endpoints\n');
+
+  const tests = [
+    {
+      name: 'POST /api/agents/search - empty search',
+      test: async () => {
+        const res = await makeRequest('POST', '/api/agents/search', {});
+        return res.status === 200 && res.data.agents !== undefined;
+      }
+    },
+    {
+      name: 'POST /api/agents/search - search by name',
+      test: async () => {
+        const res = await makeRequest('POST', '/api/agents/search', { name: 'Claude' });
+        return res.status === 200 && Array.isArray(res.data.agents);
+      }
+    },
+    {
+      name: 'GET /api/agents/claude-code',
+      test: async () => {
+        const res = await makeRequest('GET', '/api/agents/claude-code');
+        return res.status === 200 || res.status === 404;
+      }
+    },
+    {
+      name: 'GET /api/agents/claude-code/descriptor',
+      test: async () => {
+        const res = await makeRequest('GET', '/api/agents/claude-code/descriptor');
+        return (res.status === 200 && res.data.metadata && res.data.specs) || res.status === 404;
+      }
+    },
+    {
+      name: 'POST /api/runs/search',
+      test: async () => {
+        const res = await makeRequest('POST', '/api/runs/search', {});
+        return res.status === 200 && res.data.runs !== undefined;
+      }
+    },
+    {
+      name: 'POST /api/runs - missing agent_id',
+      test: async () => {
+        const res = await makeRequest('POST', '/api/runs', {});
+        return res.status === 422;
+      }
+    }
+  ];
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const t of tests) {
+    try {
+      const success = await t.test();
+      if (success) {
+        console.log(`✓ ${t.name}`);
+        passed++;
+      } else {
+        console.log(`✗ ${t.name}`);
+        failed++;
+      }
+    } catch (err) {
+      console.log(`✗ ${t.name} - ${err.message}`);
+      failed++;
+    }
+  }
+
+  console.log(`\nResults: ${passed} passed, ${failed} failed`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+http.get(`http://localhost:${PORT}${BASE_URL}/`, (res) => {
+  console.log('Server is running\n');
+  runTests();
+}).on('error', () => {
+  console.log('Server is not running. Please start with: npm run dev');
+  process.exit(1);
+});

package/test-cancel.mjs

@@ -0,0 +1,185 @@
+// Integration test for run cancellation and control
+import http from 'http';
+import { randomUUID } from 'crypto';
+import Database from 'better-sqlite3';
+import path from 'path';
+import os from 'os';
+import { createACPQueries } from './acp-queries.js';
+
+const dbPath = path.join(os.homedir(), '.gmgui', 'data.db');
+const db = new Database(dbPath);
+const prep = (sql) => db.prepare(sql);
+const acpQueries = createACPQueries(db, prep);
+
+const BASE_URL = 'http://localhost:3000/gm';
+const testResults = {
+  passed: [],
+  failed: []
+};
+
+function testPass(name) {
+  testResults.passed.push(name);
+  console.log(`✓ ${name}`);
+}
+
+function testFail(name, error) {
+  testResults.failed.push({ name, error });
+  console.log(`✗ ${name}: ${error}`);
+}
+
+async function makeRequest(method, path, body = null) {
+  return new Promise((resolve, reject) => {
+    const fullPath = `/gm${path}`;
+    const options = {
+      method,
+      hostname: 'localhost',
+      port: 3000,
+      path: fullPath,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = data ? JSON.parse(data) : null;
+          resolve({ status: res.statusCode, data: parsed, headers: res.headers });
+        } catch {
+          resolve({ status: res.statusCode, data: data, headers: res.headers });
+        }
+      });
+    });
+
+    req.on('error', reject);
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+async function runTests() {
+  console.log('=== RUNNING INTEGRATION TESTS ===\n');
+
+  try {
+    // Test 1: Create a thread
+    console.log('[Test 1] Creating thread...');
+    const threadResp = await makeRequest('POST', '/api/threads', {});
+    if ((threadResp.status === 200 || threadResp.status === 201) && threadResp.data.thread_id) {
+      testPass('Thread creation');
+    } else {
+      testFail('Thread creation', `Status ${threadResp.status}`);
+      return;
+    }
+
+    const threadId = threadResp.data.thread_id;
+
+    // Test 2: Create a run (stateless, without thread)
+    console.log('[Test 2] Creating stateless run...');
+    const runResp = await makeRequest('POST', '/api/runs', {
+      agent_id: 'claude-code',
+      input: 'test input'
+    });
+    if (runResp.status === 200 && runResp.data.run_id) {
+      testPass('Stateless run creation');
+    } else {
+      testFail('Stateless run creation', `Status ${runResp.status}`);
+      return;
+    }
+
+    const runId = runResp.data.run_id;
+
+    // Test 3: Verify run status is pending
+    console.log('[Test 3] Verifying run status...');
+    const run = acpQueries.getRun(runId);
+    if (run && run.status === 'pending') {
+      testPass('Run status is pending');
+    } else {
+      testFail('Run status is pending', `Status is ${run?.status}`);
+    }
+
+    // Test 4: Cancel the run using /api/runs/{run_id}/cancel
+    console.log('[Test 4] Cancelling run via /api/runs/{run_id}/cancel...');
+    const cancelResp = await makeRequest('POST', `/api/runs/${runId}/cancel`);
+    if (cancelResp.status === 200 && cancelResp.data.status === 'cancelled') {
+      testPass('Run cancellation via /api/runs');
+    } else {
+      testFail('Run cancellation via /api/runs', `Status ${cancelResp.status}, run status ${cancelResp.data?.status}`);
+    }
+
+    // Test 5: Verify run status is cancelled in database
+    console.log('[Test 5] Verifying cancelled status in DB...');
+    const cancelledRun = acpQueries.getRun(runId);
+    if (cancelledRun && cancelledRun.status === 'cancelled') {
+      testPass('Cancelled status persisted in database');
+    } else {
+      testFail('Cancelled status persisted in database', `Status is ${cancelledRun?.status}`);
+    }
+
+    // Test 6: Try to cancel again - should get 409 conflict
+    console.log('[Test 6] Testing 409 conflict on re-cancel...');
+    const recancel = await makeRequest('POST', `/api/runs/${runId}/cancel`);
+    if (recancel.status === 409) {
+      testPass('409 conflict on already-cancelled run');
+    } else {
+      testFail('409 conflict on already-cancelled run', `Got status ${recancel.status}`);
+    }
+
+    // Test 7: Test wait endpoint with already-completed run
+    console.log('[Test 7] Testing wait endpoint with completed run...');
+    const waitStart = Date.now();
+    const waitResp = await makeRequest('GET', `/api/runs/${runId}/wait`);
+    const waitDuration = Date.now() - waitStart;
+    if (waitResp.status === 200 && waitDuration < 5000) {
+      testPass('Wait endpoint returns immediately for completed run');
+    } else {
+      testFail('Wait endpoint returns immediately for completed run', `Took ${waitDuration}ms`);
+    }
+
+    // Test 8: Test cancellation of non-existent run
+    console.log('[Test 8] Testing 404 on non-existent run...');
+    const fakeRunId = randomUUID();
+    const notFound = await makeRequest('POST', `/api/runs/${fakeRunId}/cancel`);
+    if (notFound.status === 404) {
+      testPass('404 on non-existent run');
+    } else {
+      testFail('404 on non-existent run', `Got status ${notFound.status}`);
+    }
+
+    // Cleanup
+    console.log('\n[Cleanup] Deleting test thread...');
+    try {
+      acpQueries.deleteThread(threadId);
+      console.log('Cleanup complete');
+    } catch (e) {
+      console.log('Cleanup warning:', e.message);
+    }
+
+  } catch (error) {
+    console.error('Test suite error:', error);
+    testFail('Test suite execution', error.message);
+  }
+
+  db.close();
+
+  // Summary
+  console.log('\n=== TEST SUMMARY ===');
+  console.log(`Passed: ${testResults.passed.length}`);
+  console.log(`Failed: ${testResults.failed.length}`);
+  if (testResults.failed.length > 0) {
+    console.log('\nFailed tests:');
+    testResults.failed.forEach(f => console.log(`  - ${f.name}: ${f.error}`));
+  }
+
+  return testResults.passed.length > 0 && testResults.failed.length === 0;
+}
+
+// Run the tests
+runTests().then(success => {
+  console.log(`\n${success ? '✓ ALL TESTS PASSED' : '✗ SOME TESTS FAILED'}`);
+  process.exit(success ? 0 : 1);
+}).catch(err => {
+  console.error('Fatal test error:', err);
+  process.exit(1);
+});