@siduri-x/api 1.0.1 → 1.0.2

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "@siduri-x/api",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "dependencies": {
-    "cors": "^2.8.5",
-    "dotenv": "^16.3.1",
-    "express": "^4.18.2",
     "@siduri-x/behavior": "1.0.5",
     "@siduri-x/body": "1.0.4",
-    "@siduri-x/brain": "1.0.3",
-    "@siduri-x/core": "1.0.4",
-    "@siduri-x/ear": "1.0.2",
-    "@siduri-x/hands": "1.0.2",
+    "@siduri-x/brain": "1.0.4",
+    "@siduri-x/core": "1.0.5",
+    "@siduri-x/ear": "1.0.3",
+    "@siduri-x/hands": "1.0.3",
     "@siduri-x/knowledge": "1.0.2",
-    "@siduri-x/memory": "1.0.3",
+    "@siduri-x/memory": "1.0.4",
     "@siduri-x/observation": "1.0.2",
     "@siduri-x/vision": "1.0.2",
-    "@siduri-x/voice": "1.0.5"
+    "@siduri-x/voice": "1.0.6",
+    "@siduri-x/mouth": "1.0.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",

package/src/app.ts

@@ -4,17 +4,48 @@ import { createCorsOptions } from './cors';
 import { SiduriRuntime, dispatchCompanionChat } from './runtime';
 import { OpenAICompatibleBrain, OpenRouterBrain } from '@siduri-x/brain';
 import { PostgresMemoryOrgan } from '@siduri-x/memory';
-import { VoiceAdapter } from '@siduri-x/voice';
-import { EKnowledgeAdapter } from '@siduri-x/knowledge';
-import { OpenRouterVisionAdapter } from '@siduri-x/vision';
+import { VoiceAdapter, VoiceConfig } from '@siduri-x/voice';
+import { EKnowledgeAdapter, EKnowledgeConfig } from '@siduri-x/knowledge';
+import { OpenRouterVisionAdapter, OpenRouterVisionConfig } from '@siduri-x/vision';
 import { ActiveSelfCompiler } from '@siduri-x/behavior';
-import { Live2DAdapter } from '@siduri-x/body';
+import { Live2DAdapter, Live2DAdapterConfig } from '@siduri-x/body';
 import { FixtureObservationOrgan } from '@siduri-x/observation';
-import { DefaultHandsOrgan } from '@siduri-x/hands';
-import { DefaultEarOrgan } from '@siduri-x/ear';
+import { DefaultHandsOrgan, DefaultHandsOrganConfig } from '@siduri-x/hands';
+import { DefaultEarOrgan, EarOrganConfig } from '@siduri-x/ear';
+import { DefaultMouthOrgan, DefaultMouthOrganConfig } from '@siduri-x/mouth';
 import { attachIdentity, requireRole, Identity } from './auth';
 import { mapRequestContext } from './context-mapper';
 
+export interface AppBrainConfig {
+  provider?: 'openrouter' | 'openai-compatible' | string;
+  model?: string;
+  apiKey?: string;
+  apiKeyEnv?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  [key: string]: unknown;
+}
+
+export interface AppBehaviorConfig {
+  provider?: 'active_self' | 'none' | string;
+  preset?: string;
+  [key: string]: unknown;
+}
+
+export interface AppBootCompanionConfig {
+  name: string;
+  brain?: AppBrainConfig;
+  voice?: VoiceConfig;
+  knowledge?: EKnowledgeConfig;
+  vision?: OpenRouterVisionConfig;
+  behavior?: AppBehaviorConfig;
+  body?: Live2DAdapterConfig;
+  hands?: DefaultHandsOrganConfig;
+  ear?: EarOrganConfig;
+  mouth?: DefaultMouthOrganConfig;
+  [key: string]: unknown;
+}
+
 export interface AppInstance {
   app: Express;
   runtimes: Map<string, SiduriRuntime>;
@@ -28,62 +59,77 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
 
   let observationOrgan: FixtureObservationOrgan | undefined;
 
-  function createBrain(config: any) {
-    const provider = config.provider || 'openrouter';
+  function createBrain(config?: AppBrainConfig) {
+    const provider = config?.provider || 'openrouter';
     const defaultKeyEnv = provider === 'openai-compatible' ? 'OPENAI_COMPATIBLE_API_KEY' : 'OPENROUTER_API_KEY';
-    const apiKey = config.apiKey || process.env[config.apiKeyEnv || defaultKeyEnv] || '';
+    const apiKey = config?.apiKey || process.env[config?.apiKeyEnv || defaultKeyEnv] || '';
     if (provider === 'openai-compatible') {
       return new OpenAICompatibleBrain({
         apiKey,
-        model: config.model || 'local-model',
-        baseUrl: config.baseUrl || 'http://127.0.0.1:1234/v1',
+        model: config?.model || 'local-model',
+        baseUrl: config?.baseUrl || 'http://127.0.0.1:1234/v1',
       });
     }
-    return new OpenRouterBrain({ apiKey, model: config.model || 'gpt-4o-mini' });
+    return new OpenRouterBrain({ apiKey, model: config?.model || 'gpt-4o-mini' });
   }
 
-  function isDisabled(config: any): boolean {
+  function isDisabled(config?: { provider?: string }): boolean {
     return !config || config.provider === 'none';
   }
 
-  function createVoice(config: any) {
+  function createVoice(config?: VoiceConfig) {
     return isDisabled(config)
       ? undefined
-      : new VoiceAdapter({ provider: config.provider || 'voicevox', baseUrl: process.env.VOICEVOX_URL || 'http://localhost:50021', speakerId: config.speakerId || 1 });
+      : new VoiceAdapter({
+          provider: (config?.provider as any) || 'voicevox',
+          baseUrl: config?.baseUrl || process.env.VOICEVOX_URL || 'http://localhost:50021',
+          speakerId: config?.speakerId || 1,
+          ...config,
+        });
   }
 
-  function createKnowledge(config: any) {
-    return isDisabled(config) ? undefined : new EKnowledgeAdapter(config);
+  function createKnowledge(config?: EKnowledgeConfig) {
+    return isDisabled(config) ? undefined : new EKnowledgeAdapter(config || {});
   }
 
-  function createVision(config: any) {
+  function createVision(config?: OpenRouterVisionConfig & { provider?: string }) {
     return isDisabled(config)
       ? undefined
-      : new OpenRouterVisionAdapter({ apiKey: process.env.OPENROUTER_API_KEY || '', model: config.model || 'gpt-4-vision' });
+      : new OpenRouterVisionAdapter({
+          apiKey: config?.apiKey || process.env.OPENROUTER_API_KEY || '',
+          model: config?.model || 'gpt-4-vision',
+          ...config,
+        });
   }
 
-  function createBehavior(config: any) {
+  function createBehavior(config?: AppBehaviorConfig) {
     return isDisabled(config) ? undefined : new ActiveSelfCompiler();
   }
 
-  function createBody(config: any) {
+  function createBody(config?: Live2DAdapterConfig & { provider?: string }) {
     return isDisabled(config)
       ? undefined
       : new Live2DAdapter(config);
   }
 
-  function createHands(config: any) {
+  function createHands(config?: DefaultHandsOrganConfig & { provider?: string }) {
     return isDisabled(config)
       ? new DefaultHandsOrgan()
       : new DefaultHandsOrgan(config);
   }
 
-  function createEar(config: any) {
+  function createEar(config?: EarOrganConfig & { provider?: string }) {
     return isDisabled(config)
       ? new DefaultEarOrgan()
       : new DefaultEarOrgan(config);
   }
 
+  function createMouth(config?: DefaultMouthOrganConfig & { provider?: string }, voice?: any) {
+    return isDisabled(config)
+      ? new DefaultMouthOrgan({ voice })
+      : new DefaultMouthOrgan({ ...config, voice });
+  }
+
   app.post('/boot', requireRole(['OWNER']), async (req, res) => {
     try {
       const { id, config } = req.body;
@@ -100,8 +146,21 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       const body = createBody(config.body);
       const hands = createHands(config.hands);
       const ear = createEar(config.ear);
-
-      const runtime = new SiduriRuntime(id, config, { brain, memory, voice, knowledge, vision, behavior, body, hands, ear });
+      const mouth = createMouth(config.mouth, voice);
+
+      const runtime = new SiduriRuntime(id, config, {
+        brain,
+        memory,
+        voice,
+        knowledge,
+        vision,
+        behavior,
+        body,
+        hands,
+        ear,
+        mouth,
+        observation: observationOrgan,
+      });
       await runtime.initialize();
 
       runtimes.set(id, runtime);
@@ -126,7 +185,22 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     const hasVoice = Array.from(runtimes.values()).some((r) => Boolean(r.voice));
     res.json({ provider: "siduri-voice", configured: hasVoice });
   });
-  app.get('/obs/health', (req, res) => res.json({ connected: Boolean(observationOrgan) }));
+  app.get('/obs/health', (req, res) => {
+    const connected = Boolean(observationOrgan) || Array.from(runtimes.values()).some((r) => Boolean(r.observation));
+    res.json({ connected });
+  });
+  app.get('/mouth/health', (req, res) => {
+    const hasMouth = Array.from(runtimes.values()).some((r) => Boolean(r.mouth));
+    res.json({ provider: "siduri-mouth", configured: hasMouth });
+  });
+  app.get('/mouth/channels', (req, res) => {
+    const id = (req.query.id as string) || Array.from(runtimes.keys())[0];
+    const runtime = runtimes.get(id);
+    if (!runtime || !runtime.mouth || typeof runtime.mouth.getRegisteredChannels !== 'function') {
+      return res.json({ channels: [] });
+    }
+    res.json({ channels: runtime.mouth.getRegisteredChannels() });
+  });
   app.get('/me', attachIdentity, (req, res) => {
     const identity = (req as any).identity as Identity;
     res.json({
@@ -182,6 +256,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
         message,
         context: mappingResult.context,
         history,
+        ...(req.body?.medium ? { medium: req.body.medium } : {}),
       });
       res.json(response);
     } catch (e: any) {
@@ -189,6 +264,147 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     }
   });
 
+  // REAL-TIME SSE STREAMING (Mouth transport)
+  app.post('/chat/stream', attachIdentity, async (req, res) => {
+    const { id, message, history } = req.body;
+    const identity = (req as any).identity as Identity;
+
+    const effectiveRole = req.body?.role === 'VIEWER' || req.body?.context?.actor?.authorizationRole === 'viewer'
+      ? 'VIEWER'
+      : (identity?.role === 'OPERATOR' ? 'OPERATOR' : 'OWNER');
+    const isOwner = effectiveRole === 'OWNER';
+
+    const mappingResult = mapRequestContext(
+      {
+        ...req.body,
+        id: id || req.body.companionId,
+        role: effectiveRole,
+        authenticated: isOwner,
+        generateCorrelationId: true,
+      },
+      {
+        endpointPolicy: 'public',
+        defaultPublicAudience: 'audience-public',
+      }
+    );
+
+    if (!mappingResult.accepted) {
+      return res.status(400).json({
+        accepted: false,
+        error: mappingResult.error,
+      });
+    }
+
+    const companionId = mappingResult.context!.companionId;
+    const runtime = runtimes.get(companionId);
+    if (!runtime) return res.status(404).json({ error: "Companion not found" });
+
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders?.();
+
+    const abortController = new AbortController();
+    const onClose = () => {
+      abortController.abort('client_disconnect');
+      if (typeof runtime.interruptMouth === 'function') {
+        runtime.interruptMouth('client_disconnect');
+      }
+    };
+    req.on('close', onClose);
+
+    try {
+      const response = await dispatchCompanionChat(runtime, {
+        id: companionId,
+        companionId,
+        message,
+        context: mappingResult.context,
+        history,
+        medium: 'web',
+        signal: abortController.signal,
+      });
+
+      res.write(`event: staged\ndata: ${JSON.stringify({ response_id: response.response_id, correlation_id: response.correlation_id, status: response.status })}\n\n`);
+
+      const avatarEvent = response.metadata?.events?.find(
+        (e: any) => (e.kind === 'avatar' || e.kind === 'body') && (e.approval === 'APPROVED' || !e.approval)
+      );
+      if (avatarEvent) {
+        res.write(`event: avatar\ndata: ${JSON.stringify(avatarEvent)}\n\n`);
+      }
+
+      const speechText = response.delivery?.text || response.response?.subtitle_en || response.response?.spoken_ja || '';
+      const utterance = {
+        utteranceId: response.response_id || 'utt-stream',
+        companionId,
+        responseId: response.response_id,
+        correlationId: response.correlation_id,
+        text: speechText,
+        medium: 'web' as const,
+        expression: avatarEvent?.expression,
+        action: avatarEvent?.action,
+        signal: abortController.signal,
+      };
+
+      if (runtime.mouth && typeof runtime.mouth.stream === 'function') {
+        for await (const chunk of runtime.mouth.stream(utterance)) {
+          if (abortController.signal.aborted) {
+            res.write(`event: chunk\ndata: ${JSON.stringify({ ...chunk, interrupted: true })}\n\n`);
+            break;
+          }
+          res.write(`event: chunk\ndata: ${JSON.stringify(chunk)}\n\n`);
+        }
+      } else {
+        res.write(`event: chunk\ndata: ${JSON.stringify({ utteranceId: utterance.utteranceId, index: 1, deltaText: speechText, isComplete: true, medium: 'web' })}\n\n`);
+      }
+
+      res.write(`event: done\ndata: ${JSON.stringify(response)}\n\n`);
+      res.end();
+    } catch (e: any) {
+      if (abortController.signal.aborted) {
+        res.write(`event: interrupted\ndata: ${JSON.stringify({ reason: abortController.signal.reason })}\n\n`);
+      } else {
+        res.write(`event: error\ndata: ${JSON.stringify({ error: e.message })}\n\n`);
+      }
+      res.end();
+    } finally {
+      req.removeListener('close', onClose);
+    }
+  });
+
+  // INTERRUPTION / BARGE-IN
+  app.post('/chat/interrupt', attachIdentity, (req, res) => {
+    const companionId = req.body?.companionId || req.body?.id || Array.from(runtimes.keys())[0];
+    const runtime = companionId ? runtimes.get(companionId) : undefined;
+    const reason = req.body?.reason || 'user_barge_in';
+
+    if (runtime) {
+      runtime.interruptMouth(reason);
+      return res.json({ success: true, interrupted: true, companionId, reason });
+    }
+
+    for (const r of runtimes.values()) {
+      r.interruptMouth(reason);
+    }
+    return res.json({ success: true, interrupted: true, reason });
+  });
+
+  app.post('/mouth/interrupt', attachIdentity, (req, res) => {
+    const companionId = req.body?.companionId || req.body?.id || Array.from(runtimes.keys())[0];
+    const runtime = companionId ? runtimes.get(companionId) : undefined;
+    const reason = req.body?.reason || 'user_barge_in';
+
+    if (runtime) {
+      runtime.interruptMouth(reason);
+      return res.json({ success: true, interrupted: true, companionId, reason });
+    }
+
+    for (const r of runtimes.values()) {
+      r.interruptMouth(reason);
+    }
+    return res.json({ success: true, interrupted: true, reason });
+  });
+
   // MEMORY GETTERS
   app.get('/memory/proposals', requireRole(['OWNER', 'OPERATOR']), async (req, res) => {
     const id = req.query.id as string || Array.from(runtimes.keys())[0];
@@ -196,7 +412,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.json({ proposals: [] });
     try {
-      const proposals = await runtime.memory.getPendingClaims();
+      const proposals = await runtime.getPendingClaims();
       res.json({ proposals });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -209,7 +425,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.json({ items: [] });
     try {
-      const items = await runtime.memory.getClaims();
+      const items = await runtime.getClaims();
       res.json({ items });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -222,7 +438,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.json({ claims: [] });
     try {
-      const claims = await runtime.memory.getClaims();
+      const claims = await runtime.getClaims();
       res.json({ claims });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -235,7 +451,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.json({ directives: [] });
     try {
-      const directives = await runtime.memory.getDirectives();
+      const directives = await runtime.getDirectives();
       res.json({ directives });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -255,7 +471,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       if (!claimId) {
         return res.status(400).json({ error: "Missing required claim id" });
       }
-      const updated = await runtime.memory.updateClaim(claimId, req.body.updates || req.body);
+      const updated = await runtime.updateClaim(claimId, req.body.updates || req.body);
       res.json({ success: true, claim: updated });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -268,7 +484,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.status(400).json({ error: "Memory organ not configured" });
     try {
-      await runtime.memory.approveClaim(req.body.id);
+      await runtime.approveClaim(req.body.id);
       res.json({ approved: true });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -281,7 +497,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.status(400).json({ error: "Memory organ not configured" });
     try {
-      await runtime.memory.rejectClaim(req.body.id);
+      await runtime.rejectClaim(req.body.id);
       res.json({ rejected: true });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -295,7 +511,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.status(400).json({ error: "Memory organ not configured" });
     try {
-      await runtime.memory.approveDirective(req.body.id);
+      await runtime.approveDirective(req.body.id);
       res.json({ approved: true });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -308,7 +524,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.status(400).json({ error: "Memory organ not configured" });
     try {
-      await runtime.memory.rejectDirective(req.body.id);
+      await runtime.rejectDirective(req.body.id);
       res.json({ rejected: true });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -321,7 +537,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.status(400).json({ error: "Memory organ not configured" });
     try {
-      await runtime.memory.revokeDirective(req.body.id);
+      await runtime.revokeDirective(req.body.id);
       res.json({ revoked: true });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -334,7 +550,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     if (!runtime) return res.status(404).json({ error: "Companion not found" });
     if (!runtime.memory) return res.status(400).json({ error: "Memory organ not configured" });
     try {
-      await runtime.memory.disableDirective(req.body.id);
+      await runtime.disableDirective(req.body.id);
       res.json({ disabled: true });
     } catch (e: any) {
       res.status(500).json({ error: e.message });
@@ -351,7 +567,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
         return res.status(400).json({ error: "Memory organ does not support reset" });
       }
       try {
-        await runtime.memory.resetMemory();
+        await runtime.resetMemory();
         res.json({ reset: true });
       } catch (e: any) {
         res.status(500).json({ error: e.message });
@@ -362,7 +578,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       const companionId = req.body?.companionId || Array.from(runtimes.keys())[0] || 'default';
       const runtime = runtimes.get(companionId);
       if (!runtime) return res.status(404).json({ accepted: false, error: 'Companion not found' });
-      const staged = runtime.gating.stageResponse({
+      const staged = runtime.stageResponse({
         requestContext: {
           companionId,
           actor: {
@@ -401,12 +617,12 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       let correlationId = req.body?.correlation_id;
 
       if (!responseId && correlationId) {
-        const found = runtime.gating.findStagedPlanByCorrelation(companionId, correlationId);
+        const found = runtime.findStagedPlanByCorrelation(companionId, correlationId);
         if (found) {
           responseId = found.responseId;
         }
       } else if (responseId && !correlationId) {
-        const found = runtime.gating.getStagedPlan(responseId);
+        const found = runtime.getStagedPlan(responseId);
         if (found) {
           correlationId = found.correlationId;
         }
@@ -416,7 +632,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
         return res.status(400).json({ approved: false, error: 'UNKNOWN_APPROVAL_ID' });
       }
 
-      const result = runtime.gating.approveResponse({
+      const result = runtime.approveResponse({
         responseId,
         companionId,
         correlationId: correlationId || '',
@@ -428,7 +644,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       }
 
       // Now evaluated as approved
-      const evaluation = runtime.gating.evaluateGate(result.plan!);
+      const evaluation = runtime.evaluateGate(result.plan!);
       res.json({
         approved: true,
         status: evaluation.disposition,
@@ -447,12 +663,12 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
       let correlationId = req.body?.correlation_id;
 
       if (!responseId && correlationId) {
-        const found = runtime.gating.findStagedPlanByCorrelation(companionId, correlationId);
+        const found = runtime.findStagedPlanByCorrelation(companionId, correlationId);
         if (found) {
           responseId = found.responseId;
         }
       } else if (responseId && !correlationId) {
-        const found = runtime.gating.getStagedPlan(responseId);
+        const found = runtime.getStagedPlan(responseId);
         if (found) {
           correlationId = found.correlationId;
         }
@@ -462,7 +678,7 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
         return res.status(400).json({ rejected: false, error: 'UNKNOWN_APPROVAL_ID' });
       }
 
-      const result = runtime.gating.rejectResponse({
+      const result = runtime.rejectResponse({
         responseId,
         companionId,
         correlationId: correlationId || '',
@@ -481,8 +697,10 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     });
 
     app.post('/dev/mock-observation', async (req, res) => {
-      if (!observationOrgan) return res.status(503).json({ accepted: false, reason: 'observation_unavailable' });
-      const result = await observationOrgan.ingest(
+      const activeRuntime = Array.from(runtimes.values())[0];
+      const targetObs = activeRuntime?.observation || observationOrgan;
+      if (!targetObs) return res.status(503).json({ accepted: false, reason: 'observation_unavailable' });
+      const result = await targetObs.ingest(
         new Uint8Array([115, 121, 110, 116, 104, 101, 116, 105, 99]),
         'fixture-observation',
         'configured-vision',
@@ -492,5 +710,14 @@ export function createApp(runtimes: Map<string, SiduriRuntime> = new Map()): App
     });
   }
 
-  return { app, runtimes, setObservationOrgan: (org: FixtureObservationOrgan) => { observationOrgan = org; } };
+  return {
+    app,
+    runtimes,
+    setObservationOrgan: (org: FixtureObservationOrgan) => {
+      observationOrgan = org;
+      for (const r of runtimes.values()) {
+        r.observation = org;
+      }
+    },
+  };
 }

package/src/index.test.ts

@@ -126,4 +126,57 @@ describe('API Boundary Context Validation (P2 Route Integration)', () => {
     expect(res.body.error.code).toBe('FORBIDDEN_CONTEXT');
     expect(fakeRuntime.handleUserMessage).not.toHaveBeenCalled();
   });
+
+  test('streams response chunks via POST /chat/stream', async () => {
+    fakeRuntime.mouth = {
+      stream: async function* () {
+        yield { utteranceId: 'utt-1', index: 1, deltaText: 'Hello', isComplete: false, medium: 'web' };
+        yield { utteranceId: 'utt-1', index: 2, deltaText: ' world', isComplete: false, medium: 'web' };
+        yield { utteranceId: 'utt-1', index: 3, deltaText: '', isComplete: true, medium: 'web' };
+      },
+    };
+
+    const res = await request(app)
+      .post('/chat/stream')
+      .send({
+        id: 'companion-a',
+        message: 'Stream me',
+      });
+
+    expect(res.status).toBe(200);
+    expect(res.headers['content-type']).toContain('text/event-stream');
+    expect(res.text).toContain('event: staged');
+    expect(res.text).toContain('event: chunk');
+    expect(res.text).toContain('event: done');
+  });
+
+  test('handles barge-in interruption via POST /chat/interrupt', async () => {
+    fakeRuntime.interruptMouth = jest.fn();
+
+    const res = await request(app)
+      .post('/chat/interrupt')
+      .send({
+        companionId: 'companion-a',
+        reason: 'user_stop',
+      });
+
+    expect(res.status).toBe(200);
+    expect(res.body.interrupted).toBe(true);
+    expect(fakeRuntime.interruptMouth).toHaveBeenCalledWith('user_stop');
+  });
+
+  test('handles mouth interruption via POST /mouth/interrupt', async () => {
+    fakeRuntime.interruptMouth = jest.fn();
+
+    const res = await request(app)
+      .post('/mouth/interrupt')
+      .send({
+        companionId: 'companion-a',
+        reason: 'user_barge_in',
+      });
+
+    expect(res.status).toBe(200);
+    expect(res.body.interrupted).toBe(true);
+    expect(fakeRuntime.interruptMouth).toHaveBeenCalledWith('user_barge_in');
+  });
 });