@vellumai/assistant 0.3.7 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/src/__tests__/send-endpoint-busy.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Tests for POST /v1/messages queue-if-busy behavior and hub publishing.
+ *
+ * Validates that:
+ * - Messages are accepted (202) when the session is idle, with hub events published.
+ * - Messages are queued (202, queued: true) when the session is busy, not 409.
+ * - SSE subscribers receive events from messages sent via this endpoint.
+ */
+import { describe, test, expect, beforeEach, afterAll, mock } from 'bun:test';
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ServerMessage } from '../daemon/ipc-protocol.js';
+import type { Session } from '../daemon/session.js';
+
+const testDir = realpathSync(mkdtempSync(join(tmpdir(), 'send-endpoint-busy-test-')));
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => testDir,
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => ({
+    model: 'test',
+    provider: 'test',
+    apiKeys: {},
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    secretDetection: { enabled: false },
+  }),
+}));
+
+import { initializeDb, getDb, resetDb } from '../memory/db.js';
+import { RuntimeHttpServer } from '../runtime/http-server.js';
+import { AssistantEventHub } from '../runtime/assistant-event-hub.js';
+import type { AssistantEvent } from '../runtime/assistant-event.js';
+
+initializeDb();
+
+// ---------------------------------------------------------------------------
+// Session helpers
+// ---------------------------------------------------------------------------
+
+/** Session that completes its agent loop quickly and emits a text delta + message_complete. */
+function makeCompletingSession(): Session {
+  let processing = false;
+  return {
+    isProcessing: () => processing,
+    persistUserMessage: (_content: string, _attachments: unknown[], requestId?: string) => {
+      processing = true;
+      return requestId ?? 'msg-1';
+    },
+    memoryPolicy: { scopeId: 'default', includeDefaultFallback: false, strictSideEffects: false },
+    setChannelCapabilities: () => {},
+    setAssistantId: () => {},
+    setGuardianContext: () => {},
+    setCommandIntent: () => {},
+    updateClient: () => {},
+    enqueueMessage: () => ({ queued: false, requestId: 'noop' }),
+    runAgentLoop: async (_content: string, _messageId: string, onEvent: (msg: ServerMessage) => void) => {
+      onEvent({ type: 'assistant_text_delta', text: 'Hello!' });
+      onEvent({ type: 'message_complete', sessionId: 'test-session' });
+      processing = false;
+    },
+    handleConfirmationResponse: () => {},
+    handleSecretResponse: () => {},
+  } as unknown as Session;
+}
+
+/** Session that hangs forever in the agent loop (simulates a busy session). */
+function makeHangingSession(): Session {
+  let processing = false;
+  const enqueuedMessages: Array<{ content: string; onEvent: (msg: ServerMessage) => void; requestId: string }> = [];
+  return {
+    isProcessing: () => processing,
+    persistUserMessage: (_content: string, _attachments: unknown[], requestId?: string) => {
+      processing = true;
+      return requestId ?? 'msg-1';
+    },
+    memoryPolicy: { scopeId: 'default', includeDefaultFallback: false, strictSideEffects: false },
+    setChannelCapabilities: () => {},
+    setAssistantId: () => {},
+    setGuardianContext: () => {},
+    setCommandIntent: () => {},
+    updateClient: () => {},
+    enqueueMessage: (content: string, _attachments: unknown[], onEvent: (msg: ServerMessage) => void, requestId: string) => {
+      enqueuedMessages.push({ content, onEvent, requestId });
+      return { queued: true, requestId };
+    },
+    runAgentLoop: async () => {
+      // Hang forever
+      await new Promise<void>(() => {});
+    },
+    handleConfirmationResponse: () => {},
+    handleSecretResponse: () => {},
+    _enqueuedMessages: enqueuedMessages,
+  } as unknown as Session;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+const TEST_TOKEN = 'test-bearer-token-send';
+const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+
+describe('POST /v1/messages — queue-if-busy and hub publishing', () => {
+  let server: RuntimeHttpServer;
+  let port: number;
+  let eventHub: AssistantEventHub;
+
+  beforeEach(() => {
+    const db = getDb();
+    db.run('DELETE FROM messages');
+    db.run('DELETE FROM conversations');
+    db.run('DELETE FROM conversation_keys');
+    eventHub = new AssistantEventHub();
+  });
+
+  afterAll(() => {
+    resetDb();
+    try { rmSync(testDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  });
+
+  async function startServer(sessionFactory: () => Session): Promise<void> {
+    port = 19000 + Math.floor(Math.random() * 1000);
+    server = new RuntimeHttpServer({
+      port,
+      bearerToken: TEST_TOKEN,
+      sendMessageDeps: {
+        getOrCreateSession: async () => sessionFactory(),
+        assistantEventHub: eventHub,
+        resolveAttachments: () => [],
+      },
+    });
+    await server.start();
+  }
+
+  async function stopServer(): Promise<void> {
+    await server?.stop();
+  }
+
+  function messagesUrl(): string {
+    return `http://127.0.0.1:${port}/v1/messages`;
+  }
+
+  // ── Idle session: immediate processing ──────────────────────────────
+
+  test('returns 202 with accepted: true and messageId when session is idle', async () => {
+    await startServer(() => makeCompletingSession());
+
+    const res = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ conversationKey: 'conv-idle', content: 'Hello', sourceChannel: 'macos' }),
+    });
+    const body = await res.json() as { accepted: boolean; messageId: string };
+
+    expect(res.status).toBe(202);
+    expect(body.accepted).toBe(true);
+    expect(body.messageId).toBeDefined();
+
+    await stopServer();
+  });
+
+  test('publishes events to assistantEventHub when session is idle', async () => {
+    const publishedEvents: AssistantEvent[] = [];
+
+    await startServer(() => makeCompletingSession());
+
+    eventHub.subscribe(
+      { assistantId: 'self' },
+      (event) => { publishedEvents.push(event); },
+    );
+
+    const res = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ conversationKey: 'conv-hub', content: 'Hello hub', sourceChannel: 'macos' }),
+    });
+    expect(res.status).toBe(202);
+
+    // Wait for the async agent loop to complete and events to be published
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Should have received assistant_text_delta and message_complete
+    const types = publishedEvents.map((e) => e.message.type);
+    expect(types).toContain('assistant_text_delta');
+    expect(types).toContain('message_complete');
+
+    await stopServer();
+  });
+
+  // ── Busy session: queue-if-busy ─────────────────────────────────────
+
+  test('returns 202 with queued: true when session is busy (not 409)', async () => {
+    const session = makeHangingSession();
+    await startServer(() => session);
+
+    // First message starts the agent loop and makes the session busy
+    const res1 = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ conversationKey: 'conv-busy', content: 'First', sourceChannel: 'macos' }),
+    });
+    expect(res1.status).toBe(202);
+    const body1 = await res1.json() as { accepted: boolean; messageId: string };
+    expect(body1.accepted).toBe(true);
+    expect(body1.messageId).toBeDefined();
+
+    // Wait for the agent loop to start
+    await new Promise((r) => setTimeout(r, 30));
+
+    // Second message should be queued, not rejected
+    const res2 = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ conversationKey: 'conv-busy', content: 'Second', sourceChannel: 'macos' }),
+    });
+    const body2 = await res2.json() as { accepted: boolean; queued: boolean };
+
+    expect(res2.status).toBe(202);
+    expect(body2.accepted).toBe(true);
+    expect(body2.queued).toBe(true);
+
+    await stopServer();
+  });
+
+  // ── Validation ──────────────────────────────────────────────────────
+
+  test('returns 400 when sourceChannel is missing', async () => {
+    await startServer(() => makeCompletingSession());
+
+    const res = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ conversationKey: 'conv-val', content: 'Hello' }),
+    });
+    expect(res.status).toBe(400);
+
+    await stopServer();
+  });
+
+  test('returns 400 when content is empty', async () => {
+    await startServer(() => makeCompletingSession());
+
+    const res = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ conversationKey: 'conv-empty', content: '', sourceChannel: 'macos' }),
+    });
+    expect(res.status).toBe(400);
+
+    await stopServer();
+  });
+
+  test('returns 400 when conversationKey is missing', async () => {
+    await startServer(() => makeCompletingSession());
+
+    const res = await fetch(messagesUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ content: 'Hello', sourceChannel: 'macos' }),
+    });
+    expect(res.status).toBe(400);
+
+    await stopServer();
+  });
+});

package/src/__tests__/subagent-manager-notify.test.ts

@@ -397,8 +397,8 @@ describe('SubagentManager sendMessage validation', () => {
     const subagentId = 'sub-1';
     injectFakeSubagent(manager, subagentId, makeState(subagentId));
 
-    expect(manager.sendMessage(subagentId, '')).toBe(false);
-    expect(manager.sendMessage(subagentId, '   ')).toBe(false);
-    expect(manager.sendMessage(subagentId, '\n\t')).toBe(false);
+    expect(manager.sendMessage(subagentId, '')).toBe('empty');
+    expect(manager.sendMessage(subagentId, '   ')).toBe('empty');
+    expect(manager.sendMessage(subagentId, '\n\t')).toBe('empty');
   });
 });

package/src/config/bundled-skills/media-processing/SKILL.md

@@ -34,11 +34,11 @@ Preprocess a video asset: detect dead time via mpdecimate, segment the video int
 
 Parameters:
 - `asset_id` (required) — ID of the media asset.
-- `interval_seconds` — Interval between keyframes (default: 3s).
-- `segment_duration` — Duration of each segment window (default: 20s).
+- `interval_seconds` — Interval between keyframes (default: 1s). Use 0.5s for sports/action content where frame density matters.
+- `segment_duration` — Duration of each segment window (default: 15s).
 - `dead_time_threshold` — Sensitivity for dead-time detection (default: 0.02).
 - `section_config` — Path to a JSON file with manual section boundaries.
-- `skip_dead_time` — Whether to detect and skip dead time (default: true).
+- `skip_dead_time` — Whether to detect and skip dead time (default: false). Dead-time detection can be too aggressive for continuous action video like sports — it may incorrectly skip live play. Enable only for content with clear idle periods (e.g., lectures, surveillance footage).
 - `short_edge` — Short edge resolution for downscaled frames in pixels (default: 480).
 
 ### analyze_keyframes
@@ -74,7 +74,7 @@ Get a diagnostic report for a media asset. Returns:
 - **Processing stats**: total keyframes extracted.
 - **Per-stage status and timing**: which stages (preprocess, map, reduce) have run, how long each took, current progress.
 - **Failure reasons**: last error from any failed stage.
-- **Cost estimation**: based on segment count and Gemini 2.5 Flash pricing, plus a note about Claude reduce costs.
+- **Cost estimation**: based on segment count and current Gemini pricing.
 
 ## Services
 
@@ -110,6 +110,82 @@ Limits concurrent API calls during the Map phase to avoid rate limiting.
 
 Tracks estimated API costs during pipeline execution.
 
+## Best Practices
+
+### Map Prompt Strategy: Go Broad, Not Targeted
+
+The single most important insight: **always use a broad, descriptive map prompt** instead of a targeted one.
+
+A targeted prompt like "find turnovers" locks you into one topic. If the user later wants to ask about defense, formations, or specific players, you'd need to reprocess the entire video. Instead, run a general-purpose descriptive prompt that captures everything visible, creating a rich, reusable dataset. Then all follow-up questions can be handled via `query_media` with no reprocessing.
+
+**One map run, many queries.**
+
+The map output will be larger (more tokens per segment), but Gemini Flash is cheap enough that this is a good tradeoff. Only use a targeted prompt if the user explicitly asks for something narrow.
+
+#### Sample General-Purpose Map Prompt
+
+Use this as a starting point for the `system_prompt` parameter in `analyze_keyframes`:
+
+```
+You are analyzing keyframes from a video. For each segment, describe everything you can observe:
+
+- People visible: count, positions, identifying features (jersey numbers, clothing, names if visible)
+- Actions and movements: what people are doing, direction of movement, interactions
+- Objects of interest: ball location, equipment, vehicles, on-screen graphics
+- Environment: setting, lighting, weather if outdoors
+- Text on screen: scores, captions, titles, signs, timestamps
+- Scene composition: camera angle, zoom level, any transitions between shots
+- Any stoppages, pauses, or changes in activity
+
+Be specific and factual. Describe what you see, not what you infer happened between frames.
+```
+
+#### Sample Output Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "scene_description": { "type": "string" },
+    "people": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string" },
+          "position": { "type": "string" },
+          "action": { "type": "string" }
+        }
+      }
+    },
+    "objects_of_interest": { "type": "array", "items": { "type": "string" } },
+    "on_screen_text": { "type": "array", "items": { "type": "string" } },
+    "camera": { "type": "string" },
+    "notable_events": { "type": "array", "items": { "type": "string" } }
+  }
+}
+```
+
+### Clip Delivery
+
+The `generate_clip` tool outputs clips as temporary files. These may not deliver reliably via sandbox attachments. For reliable delivery, use `host_bash` + ffmpeg to save clips to a user-specified location as a fallback.
+
+## Known Limitations — Vision Analysis
+
+Gemini performs well at **spatial/descriptive analysis** from static keyframes:
+- Player positions, formations, and spacing
+- Jersey numbers and identifying features
+- Ball location and which team has possession
+- Score and on-screen text
+- Camera angles and scene composition
+
+Gemini **hallucinates when asked to detect fast temporal events** from static frames, regardless of frame density:
+- Turnovers, steals, fouls, and specific plays
+- Fast transitions and split-second actions
+- Causality between frames (what "happened" vs. what's visible)
+
+The model is good at describing **what is there** but bad at detecting **what happened**. Structure your map prompts and queries accordingly — ask the model to describe scenes, then use `query_media` (Claude) to reason about patterns and events across the descriptive data.
+
 ## Operator Runbook
 
 ### Monitoring Progress
@@ -137,16 +213,7 @@ After fixing the root cause, re-run the failed stage. The pipeline is resumable
 
 ### Cost Expectations
 
-The Map phase (Gemini 2.5 Flash) is the primary cost driver. Cost scales with video duration, keyframe interval, and segment size:
-
-| Video Duration | Interval | Keyframes | Segments (~10 frames each) | Estimated Map Cost |
-|----------------|----------|-----------|----------------------------|--------------------|
-| 30 min         | 3s       | ~600      | ~60                        | ~$0.06             |
-| 60 min         | 3s       | ~1,200    | ~120                       | ~$0.12             |
-| 90 min         | 3s       | ~1,800    | ~180                       | ~$0.18             |
-| 90 min         | 5s       | ~1,080    | ~108                       | ~$0.11             |
-
-The Reduce phase (Claude) adds a small additional cost per query. The `media_diagnostics` tool provides per-asset cost estimates.
+Use `media_diagnostics` to get per-asset cost estimates. The Map phase (Gemini) is the primary cost driver — it scales with video duration and keyframe interval. The Q&A phase (Claude) is negligible per query.
 
 ### Known Limitations
 

package/src/config/bundled-skills/media-processing/TOOLS.json

@@ -67,11 +67,11 @@
           },
           "interval_seconds": {
             "type": "number",
-            "description": "Interval between keyframes in seconds. Default: 3"
+            "description": "Interval between keyframes in seconds. Default: 1. Use 0.5 for sports/action content."
           },
           "segment_duration": {
             "type": "number",
-            "description": "Duration of each segment window in seconds. Default: 20"
+            "description": "Duration of each segment window in seconds. Default: 15"
           },
           "dead_time_threshold": {
             "type": "number",
@@ -83,7 +83,7 @@
           },
           "skip_dead_time": {
             "type": "boolean",
-            "description": "Whether to detect and skip dead time. Default: true"
+            "description": "Whether to detect and skip dead time. Default: false. Can be too aggressive for continuous action video like sports."
           },
           "short_edge": {
             "type": "number",

package/src/config/bundled-skills/media-processing/services/preprocess.ts

@@ -355,13 +355,13 @@ export async function preprocessForAsset(
   onProgress?: (msg: string) => void,
 ): Promise<PreprocessManifest> {
   const config: PreprocessConfig = {
-    intervalSeconds: options.intervalSeconds ?? 3,
-    segmentDuration: options.segmentDuration ?? 20,
+    intervalSeconds: options.intervalSeconds ?? 1,
+    segmentDuration: options.segmentDuration ?? 15,
     deadTimeThreshold: options.deadTimeThreshold ?? 0.02,
     shortEdge: options.shortEdge ?? 480,
   };
 
-  const skipDeadTime = options.skipDeadTime ?? true;
+  const skipDeadTime = options.skipDeadTime ?? false;
 
   const asset = getMediaAssetById(assetId);
   if (!asset) {

package/src/daemon/daemon-control.ts

@@ -19,6 +19,10 @@ const DAEMON_TIMEOUT_DEFAULTS = {
   sigkillGracePeriodMs: 2000,
 };
 
+function isPositiveInteger(v: unknown): v is number {
+  return typeof v === 'number' && Number.isInteger(v) && v > 0;
+}
+
 /**
  * Read daemon timeout values directly from the config JSON file, bypassing
  * loadConfig() and its ensureMigratedDataDir()/ensureDataDir() side effects.
@@ -30,18 +34,15 @@ function readDaemonTimeouts(): typeof DAEMON_TIMEOUT_DEFAULTS {
     const raw = JSON.parse(readFileSync(getWorkspaceConfigPath(), 'utf-8'));
     if (raw.daemon && typeof raw.daemon === 'object') {
       return {
-        startupSocketWaitMs:
-          typeof raw.daemon.startupSocketWaitMs === 'number'
-            ? raw.daemon.startupSocketWaitMs
-            : DAEMON_TIMEOUT_DEFAULTS.startupSocketWaitMs,
-        stopTimeoutMs:
-          typeof raw.daemon.stopTimeoutMs === 'number'
-            ? raw.daemon.stopTimeoutMs
-            : DAEMON_TIMEOUT_DEFAULTS.stopTimeoutMs,
-        sigkillGracePeriodMs:
-          typeof raw.daemon.sigkillGracePeriodMs === 'number'
-            ? raw.daemon.sigkillGracePeriodMs
-            : DAEMON_TIMEOUT_DEFAULTS.sigkillGracePeriodMs,
+        startupSocketWaitMs: isPositiveInteger(raw.daemon.startupSocketWaitMs)
+          ? raw.daemon.startupSocketWaitMs
+          : DAEMON_TIMEOUT_DEFAULTS.startupSocketWaitMs,
+        stopTimeoutMs: isPositiveInteger(raw.daemon.stopTimeoutMs)
+          ? raw.daemon.stopTimeoutMs
+          : DAEMON_TIMEOUT_DEFAULTS.stopTimeoutMs,
+        sigkillGracePeriodMs: isPositiveInteger(raw.daemon.sigkillGracePeriodMs)
+          ? raw.daemon.sigkillGracePeriodMs
+          : DAEMON_TIMEOUT_DEFAULTS.sigkillGracePeriodMs,
       };
     }
   } catch {

package/src/daemon/handlers/subagents.ts

@@ -109,10 +109,17 @@ export function handleSubagentMessage(
     return;
   }
 
-  const sent = manager.sendMessage(msg.subagentId, msg.content);
+  const result = manager.sendMessage(msg.subagentId, msg.content);
 
-  if (!sent) {
-    log.warn({ subagentId: msg.subagentId }, 'Client sent message to terminal subagent');
+  if (result === 'queue_full') {
+    log.warn({ subagentId: msg.subagentId }, 'Subagent message rejected — queue full');
+    ctx.send(socket, {
+      type: 'error',
+      message: `Subagent "${msg.subagentId}" message queue is full. Please wait for current messages to be processed.`,
+      category: 'queue_full',
+    });
+  } else if (result !== 'sent') {
+    log.warn({ subagentId: msg.subagentId, reason: result }, 'Client sent message to terminal subagent');
     ctx.send(socket, {
       type: 'error',
       message: `Subagent "${msg.subagentId}" not found or in terminal state.`,

package/src/daemon/lifecycle.ts

@@ -35,6 +35,8 @@ import { QdrantManager } from '../memory/qdrant-manager.js';
 import { initQdrantClient } from '../memory/qdrant-client.js';
 import { startScheduler } from '../schedule/scheduler.js';
 import { RuntimeHttpServer } from '../runtime/http-server.js';
+import { assistantEventHub } from '../runtime/assistant-event-hub.js';
+import * as attachmentsStore from '../memory/attachments-store.js';
 import { getHookManager } from '../hooks/manager.js';
 import { installTemplates } from '../hooks/templates.js';
 import { installCliLaunchers } from './install-cli-launchers.js';
@@ -46,6 +48,7 @@ import { createApprovalCopyGenerator, createApprovalConversationGenerator } from
 import { initializeProvidersAndTools, registerWatcherProviders, registerMessagingProviders } from './providers-setup.js';
 import { installShutdownHandlers } from './shutdown-handlers.js';
 import { writePid, cleanupPidFile } from './daemon-control.js';
+import { initPairingHandlers } from './handlers/pairing.js';
 
 // Re-export public API so existing consumers don't need to change imports
 export {
@@ -259,11 +262,24 @@ export async function runDaemon(): Promise<void> {
     interfacesDir: getInterfacesDir(),
     approvalCopyGenerator: createApprovalCopyGenerator(),
     approvalConversationGenerator: createApprovalConversationGenerator(),
+    sendMessageDeps: {
+      getOrCreateSession: (conversationId) =>
+        server.getSessionForMessages(conversationId),
+      assistantEventHub,
+      resolveAttachments: (attachmentIds) =>
+        attachmentsStore.getAttachmentsByIds(attachmentIds).map((a) => ({
+          id: a.id,
+          filename: a.originalFilename,
+          mimeType: a.mimeType,
+          data: a.dataBase64,
+        })),
+    },
   });
   try {
     await runtimeHttp.start();
     setRelayBroadcast((msg) => server.broadcast(msg));
     runtimeHttp.setPairingBroadcast((msg) => server.broadcast(msg));
+    initPairingHandlers(runtimeHttp.getPairingStore(), bearerToken);
     server.setHttpPort(httpPort);
     log.info({ port: httpPort, hostname }, 'Daemon startup: runtime HTTP server listening');
   } catch (err) {

package/src/daemon/server.ts

@@ -819,6 +819,14 @@ export class DaemonServer {
     return { messageId };
   }
 
+  /**
+   * Expose session lookup for the POST /v1/messages handler.
+   * The handler manages busy-state checking and queueing itself.
+   */
+  async getSessionForMessages(conversationId: string): Promise<Session> {
+    return this.getOrCreateSession(conversationId, undefined, true);
+  }
+
   createRunOrchestrator(): RunOrchestrator {
     return new RunOrchestrator({
       getOrCreateSession: (conversationId, transport) =>

package/src/memory/migrations/016-memory-segments-indexes.ts

@@ -8,4 +8,5 @@ import type { DrizzleDb } from '../db-connection.js';
  */
 export function migrateMemorySegmentsIndexes(database: DrizzleDb): void {
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_memory_segments_scope_id ON memory_segments(scope_id)`);
+  database.run(/*sql*/ `DROP INDEX IF EXISTS idx_memory_segments_conversation_id`);
 }

package/src/memory/schema.ts

@@ -64,7 +64,6 @@ export const memorySegments = sqliteTable('memory_segments', {
   updatedAt: integer('updated_at').notNull(),
 }, (table) => [
   index('idx_memory_segments_scope_id').on(table.scopeId),
-  index('idx_memory_segments_conversation_id').on(table.conversationId),
 ]);
 
 export const memoryItems = sqliteTable('memory_items', {

package/src/runtime/http-server.ts

@@ -121,6 +121,7 @@ export type {
   RuntimeAttachmentMetadata,
   ApprovalCopyGenerator,
   ApprovalConversationGenerator,
+  SendMessageDeps,
 } from './http-types.js';
 
 import type {
@@ -129,6 +130,7 @@ import type {
   RuntimeHttpServerOptions,
   ApprovalCopyGenerator,
   ApprovalConversationGenerator,
+  SendMessageDeps,
 } from './http-types.js';
 
 const log = getLogger('runtime-http');
@@ -156,6 +158,7 @@ export class RuntimeHttpServer {
   private sweepInProgress = false;
   private pairingStore = new PairingStore();
   private pairingBroadcast?: (msg: ServerMessage) => void;
+  private sendMessageDeps?: SendMessageDeps;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
     this.port = options.port ?? DEFAULT_PORT;
@@ -167,6 +170,7 @@ export class RuntimeHttpServer {
     this.approvalCopyGenerator = options.approvalCopyGenerator;
     this.approvalConversationGenerator = options.approvalConversationGenerator;
     this.interfacesDir = options.interfacesDir ?? null;
+    this.sendMessageDeps = options.sendMessageDeps;
   }
 
   /** The port the server is actually listening on (resolved after start). */
@@ -558,6 +562,7 @@ export class RuntimeHttpServer {
         return await handleSendMessage(req, {
           processMessage: this.processMessage,
           persistAndProcessMessage: this.persistAndProcessMessage,
+          sendMessageDeps: this.sendMessageDeps,
         });
       }
 

package/src/runtime/http-types.ts

@@ -5,6 +5,8 @@ import type { ChannelId } from '../channels/types.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 import type { ApprovalMessageContext, ComposeApprovalMessageGenerativeOptions } from './approval-message-composer.js';
+import type { Session } from '../daemon/session.js';
+import type { AssistantEventHub } from './assistant-event-hub.js';
 
 /**
  * Daemon-injected function that generates approval copy using a provider.
@@ -84,6 +86,24 @@ export type NonBlockingMessageProcessor = (
   sourceChannel?: ChannelId,
 ) => Promise<{ messageId: string }>;
 
+/**
+ * Dependencies for the POST /v1/messages handler.
+ *
+ * The handler needs direct access to the session so it can check busy state,
+ * persist user messages, fire the agent loop, or queue messages when busy.
+ * Hub publishing wires outbound events to the SSE stream.
+ */
+export interface SendMessageDeps {
+  getOrCreateSession: (conversationId: string) => Promise<Session>;
+  assistantEventHub: AssistantEventHub;
+  resolveAttachments: (attachmentIds: string[]) => Array<{
+    id: string;
+    filename: string;
+    mimeType: string;
+    data: string;
+  }>;
+}
+
 export interface RuntimeHttpServerOptions {
   port?: number;
   /** Hostname / IP to bind to. Defaults to '127.0.0.1' (loopback-only). */
@@ -101,6 +121,8 @@ export interface RuntimeHttpServerOptions {
   approvalCopyGenerator?: ApprovalCopyGenerator;
   /** Daemon-injected generator for conversational approval flow (provider-backed). */
   approvalConversationGenerator?: ApprovalConversationGenerator;
+  /** Dependencies for the POST /v1/messages queue-if-busy handler. */
+  sendMessageDeps?: SendMessageDeps;
 }
 
 export interface RuntimeAttachmentMetadata {

package/src/runtime/routes/conversation-routes.ts

@@ -18,7 +18,13 @@ import type {
   NonBlockingMessageProcessor,
   RuntimeAttachmentMetadata,
   RuntimeMessagePayload,
+  SendMessageDeps,
 } from '../http-types.js';
+import type { ServerMessage } from '../../daemon/ipc-protocol.js';
+import { buildAssistantEvent } from '../assistant-event.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('conversation-routes');
 
 const SUGGESTION_CACHE_MAX = 100;
 
@@ -134,11 +140,40 @@ export function handleListMessages(
   return Response.json({ messages });
 }
 
+/**
+ * Build an `onEvent` callback that publishes every outbound event to the
+ * assistant event hub, maintaining ordered delivery through a serial chain.
+ */
+function makeHubPublisher(
+  deps: SendMessageDeps,
+  conversationId: string,
+): (msg: ServerMessage) => void {
+  let hubChain: Promise<void> = Promise.resolve();
+  return (msg: ServerMessage) => {
+    const msgRecord = msg as unknown as Record<string, unknown>;
+    const msgSessionId =
+      'sessionId' in msg && typeof msgRecord.sessionId === 'string'
+        ? (msgRecord.sessionId as string)
+        : undefined;
+    const resolvedSessionId = msgSessionId ?? conversationId;
+    const event = buildAssistantEvent('self', msg, resolvedSessionId);
+    hubChain = (async () => {
+      await hubChain;
+      try {
+        await deps.assistantEventHub.publish(event);
+      } catch (err) {
+        log.warn({ err }, 'assistant-events hub subscriber threw during POST /messages');
+      }
+    })();
+  };
+}
+
 export async function handleSendMessage(
   req: Request,
   deps: {
     processMessage?: MessageProcessor;
     persistAndProcessMessage?: NonBlockingMessageProcessor;
+    sendMessageDeps?: SendMessageDeps;
   },
 ): Promise<Response> {
   const body = await req.json() as {
@@ -204,6 +239,47 @@ export async function handleSendMessage(
 
   const mapping = getOrCreateConversation(conversationKey);
 
+  // ── Queue-if-busy path (preferred when sendMessageDeps is wired) ────
+  if (deps.sendMessageDeps) {
+    const smDeps = deps.sendMessageDeps;
+    const session = await smDeps.getOrCreateSession(mapping.conversationId);
+    const onEvent = makeHubPublisher(smDeps, mapping.conversationId);
+
+    const attachments = hasAttachments
+      ? smDeps.resolveAttachments(attachmentIds)
+      : [];
+
+    if (session.isProcessing()) {
+      // Queue the message so it's processed when the current turn completes
+      const requestId = crypto.randomUUID();
+      const result = session.enqueueMessage(
+        content ?? '',
+        attachments,
+        onEvent,
+        requestId,
+      );
+      if (result.rejected) {
+        return Response.json(
+          { error: 'Message queue is full. Please retry later.' },
+          { status: 429 },
+        );
+      }
+      return Response.json({ accepted: true, queued: true }, { status: 202 });
+    }
+
+    // Session is idle — persist and fire agent loop immediately
+    const requestId = crypto.randomUUID();
+    const messageId = session.persistUserMessage(content ?? '', attachments, requestId);
+
+    // Fire-and-forget the agent loop; events flow to the hub via onEvent
+    session.runAgentLoop(content ?? '', messageId, onEvent).catch((err) => {
+      log.error({ err, conversationId: mapping.conversationId }, 'Agent loop failed (POST /messages)');
+    });
+
+    return Response.json({ accepted: true, messageId }, { status: 202 });
+  }
+
+  // ── Legacy path (fallback when sendMessageDeps not wired) ───────────
   const processor = deps.persistAndProcessMessage ?? deps.processMessage;
   if (!processor) {
     return Response.json({ error: 'Message processing not configured' }, { status: 503 });
@@ -217,7 +293,7 @@ export async function handleSendMessage(
       undefined,
       sourceChannel,
     );
-    return Response.json({ accepted: true, messageId: result.messageId });
+    return Response.json({ accepted: true, messageId: result.messageId }, { status: 202 });
   } catch (err) {
     if (err instanceof Error && err.message === 'Session is already processing a message') {
       return Response.json(

package/src/subagent/manager.ts

@@ -343,20 +343,20 @@ export class SubagentManager {
 
   // ── Send message to subagent ──────────────────────────────────────────
 
-  sendMessage(subagentId: string, content: string): boolean {
+  sendMessage(subagentId: string, content: string): 'sent' | 'empty' | 'not_found' | 'terminal' | 'queue_full' {
     const trimmed = content?.trim();
-    if (!trimmed) return false;
+    if (!trimmed) return 'empty';
 
     const managed = this.subagents.get(subagentId);
-    if (!managed) return false;
-    if (TERMINAL_STATUSES.has(managed.state.status)) return false;
+    if (!managed) return 'not_found';
+    if (TERMINAL_STATUSES.has(managed.state.status)) return 'terminal';
 
     const onEvent = managed.session.sendToClient;
     const requestId = uuid();
 
     // If the session is busy, queue the message; otherwise process immediately.
     const result = managed.session.enqueueMessage(trimmed, [], onEvent, requestId);
-    if (result.rejected) return false;
+    if (result.rejected) return 'queue_full';
     if (!result.queued) {
       // Session is idle — send directly.  Fire-and-forget so we don't block.
       const messageId = managed.session.persistUserMessage(trimmed, []);
@@ -364,7 +364,7 @@ export class SubagentManager {
         log.error({ subagentId, err }, 'Subagent message processing failed');
       });
     }
-    return true;
+    return 'sent';
   }
 
   // ── Queries ───────────────────────────────────────────────────────────

package/src/tools/subagent/message.ts

@@ -23,9 +23,16 @@ export async function executeSubagentMessage(
     };
   }
 
-  const sent = manager.sendMessage(subagentId, content);
+  const result = manager.sendMessage(subagentId, content);
 
-  if (!sent) {
+  if (result === 'queue_full') {
+    return {
+      content: `Subagent "${subagentId}" message queue is full. Please wait for current messages to be processed.`,
+      isError: true,
+    };
+  }
+
+  if (result !== 'sent') {
     return {
       content: `Could not send message to subagent "${subagentId}". It may not exist or be in a terminal state.`,
       isError: true,