vellum 0.2.9 → 0.2.11

package/src/__tests__/ipc-snapshot.test.ts

@@ -501,6 +501,21 @@ const clientMessages: Record<ClientMessageType, ClientMessage> = {
     subagentId: 'sub-001',
     content: 'Hello subagent',
   },
+  subagent_detail_request: {
+    type: 'subagent_detail_request',
+    subagentId: 'sub-001',
+    conversationId: 'conv-001',
+  },
+  workspace_files_list: {
+    type: 'workspace_files_list',
+  },
+  workspace_file_read: {
+    type: 'workspace_file_read',
+    path: 'IDENTITY.md',
+  },
+  identity_get: {
+    type: 'identity_get',
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -1136,6 +1151,7 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
   },
   ingress_config_response: {
     type: 'ingress_config_response',
+    enabled: true,
     publicBaseUrl: 'https://example.com',
     localGatewayTarget: 'http://127.0.0.1:7830',
     success: true,
@@ -1441,6 +1457,39 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
       sessionId: 'sub-sess-001',
     },
   },
+  subagent_detail_response: {
+    type: 'subagent_detail_response',
+    subagentId: 'sub-001',
+    objective: 'Search for documentation',
+    events: [
+      {
+        type: 'tool_use',
+        content: 'Reading file...',
+        toolName: 'read_file',
+        isError: false,
+      },
+    ],
+  },
+  workspace_files_list_response: {
+    type: 'workspace_files_list_response',
+    files: [
+      { path: 'IDENTITY.md', name: 'IDENTITY.md', exists: true },
+    ],
+  },
+  workspace_file_read_response: {
+    type: 'workspace_file_read_response',
+    path: 'IDENTITY.md',
+    content: '# My Identity',
+  },
+  identity_get_response: {
+    type: 'identity_get_response',
+    found: true,
+    name: 'Vex',
+    role: 'AI assistant',
+    personality: 'Friendly',
+    emoji: '✨',
+    home: '~/workspace',
+  },
 };
 
 // ---------------------------------------------------------------------------

package/src/__tests__/onboarding-starter-tasks.test.ts

@@ -134,14 +134,23 @@ describe('starter task playbook integration with buildSystemPrompt', () => {
     }
   });
 
-  test('buildSystemPrompt includes the starter task playbook section', () => {
+  test('buildSystemPrompt includes the starter task playbook section when BOOTSTRAP.md exists', () => {
     writeFileSync(join(TEST_DIR, 'IDENTITY.md'), 'I am Vellum.');
+    writeFileSync(join(TEST_DIR, 'BOOTSTRAP.md'), '# First run');
     const result = buildSystemPrompt();
     expect(result).toContain('## Starter Task Playbooks');
   });
 
+  test('buildSystemPrompt omits starter task playbooks after onboarding is complete', () => {
+    writeFileSync(join(TEST_DIR, 'IDENTITY.md'), 'I am Vellum.');
+    // No BOOTSTRAP.md → onboarding complete
+    const result = buildSystemPrompt();
+    expect(result).not.toContain('## Starter Task Playbooks');
+  });
+
   test('starter task playbook appears before channel awareness', () => {
     writeFileSync(join(TEST_DIR, 'IDENTITY.md'), 'I am Vellum.');
+    writeFileSync(join(TEST_DIR, 'BOOTSTRAP.md'), '# First run');
     const result = buildSystemPrompt();
     const starterIdx = result.indexOf('## Starter Task Playbooks');
     const channelIdx = result.indexOf('## Channel Awareness & Trust Gating');
@@ -150,8 +159,9 @@ describe('starter task playbook integration with buildSystemPrompt', () => {
     expect(starterIdx).toBeLessThan(channelIdx);
   });
 
-  test('all three kickoff intents present in full system prompt', () => {
+  test('all three kickoff intents present in full system prompt during onboarding', () => {
     writeFileSync(join(TEST_DIR, 'IDENTITY.md'), 'I am Vellum.');
+    writeFileSync(join(TEST_DIR, 'BOOTSTRAP.md'), '# First run');
     const result = buildSystemPrompt();
     expect(result).toContain('[STARTER_TASK:make_it_yours]');
     expect(result).toContain('[STARTER_TASK:research_topic]');

package/src/__tests__/prebuilt-home-base-seed.test.ts

@@ -40,18 +40,21 @@ describe('prebuilt home base seed', () => {
     const first = ensurePrebuiltHomeBaseSeeded();
     const second = ensurePrebuiltHomeBaseSeeded();
 
-    expect(first.created).toBe(true);
-    expect(second.created).toBe(false);
-    expect(second.appId).toBe(first.appId);
+    expect(first).not.toBeNull();
+    expect(second).not.toBeNull();
+    expect(first!.created).toBe(true);
+    expect(second!.created).toBe(false);
+    expect(second!.appId).toBe(first!.appId);
     expect(listApps().filter((app) => app.name === 'Home Base').length).toBe(1);
   });
 
   test('findSeededHomeBaseApp resolves the seeded app', () => {
     const seeded = ensurePrebuiltHomeBaseSeeded();
+    expect(seeded).not.toBeNull();
     const found = findSeededHomeBaseApp();
 
     expect(found).not.toBeNull();
-    expect(found?.id).toBe(seeded.appId);
+    expect(found?.id).toBe(seeded!.appId);
     // listApps() (used by findSeededHomeBaseApp) no longer stores htmlDefinition
     // in the JSON file — it is persisted as index.html on disk.
     // Use getApp() to load the full definition including htmlDefinition.
@@ -61,9 +64,10 @@ describe('prebuilt home base seed', () => {
 
   test('rejects updates that remove required Home Base anchors', () => {
     const seeded = ensurePrebuiltHomeBaseSeeded();
+    expect(seeded).not.toBeNull();
 
     expect(() => {
-      updateApp(seeded.appId, {
+      updateApp(seeded!.appId, {
         htmlDefinition: '<main id="home-base-root"></main>',
       });
     }).toThrow('missing required anchors');

package/src/__tests__/relay-server.test.ts

@@ -104,6 +104,7 @@ import {
   getCallSession,
   getCallEvents,
 } from '../calls/call-store.js';
+import { registerCallCompletionNotifier, unregisterCallCompletionNotifier } from '../calls/call-state.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
 
@@ -196,6 +197,8 @@ describe('relay-server', () => {
     const updated = getCallSession(session.id);
     expect(updated).not.toBeNull();
     expect(updated!.providerCallSid).toBe('CA_relay_setup_123');
+    expect(updated!.status).toBe('in_progress');
+    expect(updated!.startedAt).not.toBeNull();
 
     // Verify event was recorded
     const events = getCallEvents(session.id);
@@ -208,6 +211,58 @@ describe('relay-server', () => {
     relay.destroy();
   });
 
+  test('handleTransportClosed: normal close marks call completed and notifies completion', () => {
+    ensureConversation('conv-relay-close-normal');
+    const session = createCallSession({
+      conversationId: 'conv-relay-close-normal',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+    });
+
+    const { relay } = createMockWs(session.id);
+    let completionCount = 0;
+    registerCallCompletionNotifier('conv-relay-close-normal', () => {
+      completionCount += 1;
+    });
+
+    relay.handleTransportClosed(1000, 'Closing websocket session');
+
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('completed');
+    expect(updated!.endedAt).not.toBeNull();
+    const endedEvents = getCallEvents(session.id).filter((e) => e.eventType === 'call_ended');
+    expect(endedEvents.length).toBe(1);
+    expect(completionCount).toBe(1);
+
+    unregisterCallCompletionNotifier('conv-relay-close-normal');
+    relay.destroy();
+  });
+
+  test('handleTransportClosed: abnormal close marks call failed', () => {
+    ensureConversation('conv-relay-close-abnormal');
+    const session = createCallSession({
+      conversationId: 'conv-relay-close-abnormal',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+    });
+
+    const { relay } = createMockWs(session.id);
+    relay.handleTransportClosed(1006, 'abnormal closure');
+
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+    expect(updated!.endedAt).not.toBeNull();
+    expect(updated!.lastError).toContain('abnormal closure');
+    const failEvents = getCallEvents(session.id).filter((e) => e.eventType === 'call_failed');
+    expect(failEvents.length).toBe(1);
+
+    relay.destroy();
+  });
+
   test('handleMessage: setup message with custom parameters', async () => {
     ensureConversation('conv-relay-custom');
     const session = createCallSession({

package/src/__tests__/skills.test.ts

@@ -538,6 +538,89 @@ describe('bundled browser skill', () => {
   });
 });
 
+describe('bundled public-ingress skill', () => {
+  beforeEach(() => {
+    mkdirSync(join(TEST_DIR, 'skills'), { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  test('public-ingress skill appears in full catalog (including bundled)', () => {
+    const catalog = loadSkillCatalog();
+    const skill = catalog.find((s) => s.id === 'public-ingress');
+    expect(skill).toBeDefined();
+    expect(skill!.name).toBe('Public Ingress');
+    expect(skill!.bundled).toBe(true);
+  });
+
+  test('public-ingress skill has correct description', () => {
+    const catalog = loadSkillCatalog();
+    const skill = catalog.find((s) => s.id === 'public-ingress');
+    expect(skill).toBeDefined();
+    expect(skill!.description).toContain('ngrok');
+    expect(skill!.description).toContain('ingress.publicBaseUrl');
+  });
+
+  test('public-ingress skill is user-invocable', () => {
+    const catalog = loadSkillCatalog();
+    const skill = catalog.find((s) => s.id === 'public-ingress');
+    expect(skill).toBeDefined();
+    expect(skill!.userInvocable).toBe(true);
+  });
+
+  test('public-ingress skill has no tool manifest (instructions-only)', () => {
+    const catalog = loadSkillCatalog();
+    const skill = catalog.find((s) => s.id === 'public-ingress');
+    expect(skill).toBeDefined();
+    expect(skill!.toolManifest).toBeUndefined();
+  });
+});
+
+describe('ingress-dependent setup skills declare public-ingress', () => {
+  const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+  const VELLUM_SKILLS_DIR = join(import.meta.dir, '..', 'config', 'vellum-skills');
+
+  function readVellumSkillIncludes(skillId: string): string[] | undefined {
+    const content = require('node:fs').readFileSync(join(VELLUM_SKILLS_DIR, skillId, 'SKILL.md'), 'utf-8');
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) return undefined;
+    for (const line of match[1].split(/\r?\n/)) {
+      const sep = line.indexOf(':');
+      if (sep === -1) continue;
+      const key = line.slice(0, sep).trim();
+      if (key !== 'includes') continue;
+      const val = line.slice(sep + 1).trim();
+      try {
+        const parsed = JSON.parse(val);
+        if (Array.isArray(parsed)) return parsed as string[];
+      } catch { /* ignore */ }
+    }
+    return undefined;
+  }
+
+  test('telegram-setup includes public-ingress', () => {
+    const includes = readVellumSkillIncludes('telegram-setup');
+    expect(includes).toBeDefined();
+    expect(includes).toContain('public-ingress');
+  });
+
+  test('google-oauth-setup includes public-ingress', () => {
+    const includes = readVellumSkillIncludes('google-oauth-setup');
+    expect(includes).toBeDefined();
+    expect(includes).toContain('public-ingress');
+  });
+
+  test('slack-oauth-setup includes public-ingress', () => {
+    const includes = readVellumSkillIncludes('slack-oauth-setup');
+    expect(includes).toBeDefined();
+    expect(includes).toContain('public-ingress');
+  });
+});
+
 describe('bundled computer-use skill', () => {
   beforeEach(() => {
     mkdirSync(join(TEST_DIR, 'skills'), { recursive: true });

package/src/__tests__/system-prompt.test.ts

@@ -208,37 +208,15 @@ describe('buildSystemPrompt', () => {
   });
 
   describe('app-builder tool ownership guidance', () => {
-    test('does not list app_open as skill-provided', () => {
-      const result = buildSystemPrompt();
-      // The "Loading app tools" section should NOT include app_open in the skill-provided list
-      const skillProvidedMatch = result.match(/Most `app_\*` tools \([^)]+\) are provided by the `app-builder` skill\./);
-      expect(skillProvidedMatch).not.toBeNull();
-      expect(skillProvidedMatch![0]).not.toContain('app_open');
-    });
-
-    test('mentions app_open is always available as a core tool', () => {
-      const result = buildSystemPrompt();
-      expect(result).toContain('`app_open` is always available as a core tool');
-    });
-
     test('iteration guidance does not mention app_update for HTML changes', () => {
       const result = buildSystemPrompt();
       // The iteration line should not reference app_update for changing HTML
       expect(result).not.toContain('use `app_update` to change the HTML');
     });
 
-    test('iteration guidance recommends app_file_edit for code changes', () => {
-      const result = buildSystemPrompt();
-      expect(result).toContain('use `app_file_edit` for targeted code changes');
-    });
-
-    test('Home Base guidance uses app_file_edit or app_file_write, not app_update', () => {
-      const result = buildSystemPrompt();
-      expect(result).toContain('apply changes through `app_file_edit` or `app_file_write`');
-      expect(result).not.toContain('apply updates through normal `app_update` flows');
-    });
-
     test('onboarding playbook uses app_file_edit for accent color, not app_update', () => {
+      // Starter task playbooks only included during onboarding (BOOTSTRAP.md exists)
+      writeFileSync(join(TEST_DIR, 'BOOTSTRAP.md'), '# First run');
       const result = buildSystemPrompt();
       expect(result).toContain('using `app_file_edit` to update the theme styles');
       expect(result).not.toContain('using `app_update` to regenerate the Home Base HTML');

package/src/__tests__/twilio-provider.test.ts

@@ -30,10 +30,12 @@ mock.module('../util/logger.js', () => ({
 
 // Start with a configured auth token
 let mockAuthToken: string | undefined = 'test-auth-token-secret';
+let mockAccountSid: string | undefined = 'AC_test_account';
 
 mock.module('../security/secure-keys.js', () => ({
   getSecureKey: (account: string) => {
     if (account === 'credential:twilio:auth_token') return mockAuthToken;
+    if (account === 'credential:twilio:account_sid') return mockAccountSid;
     return undefined;
   },
 }));
@@ -60,6 +62,7 @@ function computeValidSignature(
 describe('TwilioConversationRelayProvider', () => {
   beforeEach(() => {
     mockAuthToken = 'test-auth-token-secret';
+    mockAccountSid = 'AC_test_account';
   });
 
   describe('verifyWebhookSignature', () => {
@@ -140,4 +143,37 @@ describe('TwilioConversationRelayProvider', () => {
       expect(token).toBeNull();
     });
   });
+
+  describe('initiateCall', () => {
+    test('sends repeated StatusCallbackEvent parameters', async () => {
+      const provider = new TwilioConversationRelayProvider();
+      const originalFetch = globalThis.fetch;
+      let capturedBody = '';
+
+      globalThis.fetch = (async (_url: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+        capturedBody = String(init?.body ?? '');
+        return new Response(JSON.stringify({ sid: 'CA_test_123' }), { status: 200 });
+      }) as typeof fetch;
+
+      try {
+        const result = await provider.initiateCall({
+          from: '+15550001111',
+          to: '+15550002222',
+          webhookUrl: 'https://example.com/webhooks/twilio/voice?callSessionId=s1',
+          statusCallbackUrl: 'https://example.com/webhooks/twilio/status',
+        });
+
+        expect(result.callSid).toBe('CA_test_123');
+        const params = new URLSearchParams(capturedBody);
+        expect(params.getAll('StatusCallbackEvent')).toEqual([
+          'initiated',
+          'ringing',
+          'answered',
+          'completed',
+        ]);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  });
 });

package/src/__tests__/twilio-routes.test.ts

@@ -119,6 +119,7 @@ import { RuntimeHttpServer } from '../runtime/http-server.js';
 import * as callStore from '../calls/call-store.js';
 import {
   createCallSession,
+  getCallSession,
   updateCallSession,
   getCallEvents,
   buildCallbackDedupeKey,
@@ -126,6 +127,7 @@ import {
   releaseCallbackClaim,
 } from '../calls/call-store.js';
 import { resolveRelayUrl, handleStatusCallback } from '../calls/twilio-routes.js';
+import { registerCallCompletionNotifier, unregisterCallCompletionNotifier } from '../calls/call-state.js';
 
 initializeDb();
 
@@ -535,6 +537,112 @@ describe('twilio webhook routes', () => {
     });
   });
 
+  describe('status mapping and completion notifications', () => {
+    test('initiated status callback is accepted and recorded as call_started', async () => {
+      const session = createTestSession('conv-status-init-1', 'CA_status_init_1');
+      const params = new URLSearchParams({
+        CallSid: 'CA_status_init_1',
+        CallStatus: 'initiated',
+        Timestamp: '2025-01-21T10:00:00Z',
+      });
+
+      const req = new Request('http://127.0.0.1/v1/calls/twilio/status', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+      });
+      const res = await handleStatusCallback(req);
+      expect(res.status).toBe(200);
+
+      const updated = getCallSession(session.id);
+      expect(updated).not.toBeNull();
+      expect(updated!.status).toBe('initiated');
+      const events = getCallEvents(session.id);
+      expect(events.filter((e) => e.eventType === 'call_started').length).toBe(1);
+    });
+
+    test('answered status callback transitions to in_progress', async () => {
+      const session = createTestSession('conv-status-answered-1', 'CA_status_answered_1');
+      const params = new URLSearchParams({
+        CallSid: 'CA_status_answered_1',
+        CallStatus: 'answered',
+        Timestamp: '2025-01-21T10:05:00Z',
+      });
+
+      const req = new Request('http://127.0.0.1/v1/calls/twilio/status', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+      });
+      const res = await handleStatusCallback(req);
+      expect(res.status).toBe(200);
+
+      const updated = getCallSession(session.id);
+      expect(updated).not.toBeNull();
+      expect(updated!.status).toBe('in_progress');
+      expect(updated!.startedAt).not.toBeNull();
+      const events = getCallEvents(session.id);
+      expect(events.filter((e) => e.eventType === 'call_connected').length).toBe(1);
+    });
+
+    test('completed status callback fires completion notifier when first entering terminal state', async () => {
+      const session = createTestSession('conv-status-complete-1', 'CA_status_complete_1');
+      updateCallSession(session.id, { status: 'in_progress', startedAt: Date.now() - 20_000 });
+      const params = new URLSearchParams({
+        CallSid: 'CA_status_complete_1',
+        CallStatus: 'completed',
+        Timestamp: '2025-01-21T10:10:00Z',
+      });
+
+      let fired = 0;
+      registerCallCompletionNotifier('conv-status-complete-1', () => {
+        fired += 1;
+      });
+
+      const req = new Request('http://127.0.0.1/v1/calls/twilio/status', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+      });
+      const res = await handleStatusCallback(req);
+      expect(res.status).toBe(200);
+
+      const updated = getCallSession(session.id);
+      expect(updated).not.toBeNull();
+      expect(updated!.status).toBe('completed');
+      expect(updated!.endedAt).not.toBeNull();
+      expect(fired).toBe(1);
+
+      unregisterCallCompletionNotifier('conv-status-complete-1');
+    });
+
+    test('completed callback does not re-fire completion notifier for already terminal call', async () => {
+      const session = createTestSession('conv-status-complete-2', 'CA_status_complete_2');
+      updateCallSession(session.id, { status: 'completed', startedAt: Date.now() - 20_000, endedAt: Date.now() - 5_000 });
+      const params = new URLSearchParams({
+        CallSid: 'CA_status_complete_2',
+        CallStatus: 'completed',
+        Timestamp: '2025-01-21T10:15:00Z',
+      });
+
+      let fired = 0;
+      registerCallCompletionNotifier('conv-status-complete-2', () => {
+        fired += 1;
+      });
+
+      const req = new Request('http://127.0.0.1/v1/calls/twilio/status', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+      });
+      const res = await handleStatusCallback(req);
+      expect(res.status).toBe(200);
+      expect(fired).toBe(0);
+
+      unregisterCallCompletionNotifier('conv-status-complete-2');
+    });
+  });
+
   // ── resolveRelayUrl unit tests ──────────────────────────────────────
 
   describe('resolveRelayUrl', () => {

package/src/calls/call-orchestrator.ts

@@ -18,7 +18,7 @@ import {
 } from './call-store.js';
 import { getMaxCallDurationMs, getUserConsultationTimeoutMs, SILENCE_TIMEOUT_MS } from './call-constants.js';
 import type { RelayConnection } from './relay-server.js';
-import { registerCallOrchestrator, unregisterCallOrchestrator, fireCallQuestionNotifier, fireCallCompletionNotifier } from './call-state.js';
+import { registerCallOrchestrator, unregisterCallOrchestrator, fireCallQuestionNotifier, fireCallCompletionNotifier, fireCallTranscriptNotifier } from './call-state.js';
 import type { PromptSpeakerContext } from './speaker-identification.js';
 
 const log = getLogger('call-orchestrator');
@@ -290,6 +290,13 @@ export class CallOrchestrator {
       // Record the assistant response
       this.conversationHistory.push({ role: 'assistant', content: responseText });
       recordCallEvent(this.callSessionId, 'assistant_spoke', { text: responseText });
+      const spokenText = responseText.replace(ASK_USER_REGEX, '').replace(END_CALL_MARKER, '').trim();
+      if (spokenText.length > 0) {
+        const session = getCallSession(this.callSessionId);
+        if (session) {
+          fireCallTranscriptNotifier(session.conversationId, this.callSessionId, 'assistant', spokenText);
+        }
+      }
 
       // Check for ASK_USER pattern
       const askMatch = responseText.match(ASK_USER_REGEX);
@@ -324,14 +331,19 @@ export class CallOrchestrator {
 
       // Check for END_CALL marker
       if (responseText.includes(END_CALL_MARKER)) {
+        const currentSession = getCallSession(this.callSessionId);
+        const shouldNotifyCompletion = currentSession
+          ? currentSession.status !== 'completed' && currentSession.status !== 'failed' && currentSession.status !== 'cancelled'
+          : false;
+
         this.relay.endSession('Call completed');
         updateCallSession(this.callSessionId, { status: 'completed', endedAt: Date.now() });
         recordCallEvent(this.callSessionId, 'call_ended', { reason: 'completed' });
 
-        // Notify the conversation that the call completed
-        const endSession = getCallSession(this.callSessionId);
-        if (endSession) {
-          fireCallCompletionNotifier(endSession.conversationId, this.callSessionId);
+        // Notify the conversation when this is the first transition
+        // into a terminal call state.
+        if (shouldNotifyCompletion && currentSession) {
+          fireCallCompletionNotifier(currentSession.conversationId, this.callSessionId);
         }
         this.state = 'idle';
         return;
@@ -373,9 +385,17 @@ export class CallOrchestrator {
       );
       // Give TTS a moment to play, then end
       this.durationEndTimer = setTimeout(() => {
+        const currentSession = getCallSession(this.callSessionId);
+        const shouldNotifyCompletion = currentSession
+          ? currentSession.status !== 'completed' && currentSession.status !== 'failed' && currentSession.status !== 'cancelled'
+          : false;
+
         this.relay.endSession('Maximum call duration reached');
         updateCallSession(this.callSessionId, { status: 'completed', endedAt: Date.now() });
         recordCallEvent(this.callSessionId, 'call_ended', { reason: 'max_duration' });
+        if (shouldNotifyCompletion && currentSession) {
+          fireCallCompletionNotifier(currentSession.conversationId, this.callSessionId);
+        }
       }, 3000);
     }, maxDurationMs);
   }

package/src/calls/call-state.ts

@@ -28,6 +28,29 @@ export function fireCallQuestionNotifier(conversationId: string, callSessionId:
   questionNotifiers.get(conversationId)?.(callSessionId, question);
 }
 
+// ── Transcript notifiers ────────────────────────────────────────────
+const transcriptNotifiers = new Map<string, (callSessionId: string, speaker: 'caller' | 'assistant', text: string) => void>();
+
+export function registerCallTranscriptNotifier(
+  conversationId: string,
+  callback: (callSessionId: string, speaker: 'caller' | 'assistant', text: string) => void,
+): void {
+  transcriptNotifiers.set(conversationId, callback);
+}
+
+export function unregisterCallTranscriptNotifier(conversationId: string): void {
+  transcriptNotifiers.delete(conversationId);
+}
+
+export function fireCallTranscriptNotifier(
+  conversationId: string,
+  callSessionId: string,
+  speaker: 'caller' | 'assistant',
+  text: string,
+): void {
+  transcriptNotifiers.get(conversationId)?.(callSessionId, speaker, text);
+}
+
 // ── Completion notifiers ────────────────────────────────────────────
 const completionNotifiers = new Map<string, (callSessionId: string) => void>();