@jambonz/schema 0.2.1 → 0.3.0

package/callbacks/call-status.schema.json

@@ -2,12 +2,17 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://jambonz.org/schema/callbacks/call-status",
   "title": "Call Status Webhook Payload",
-  "description": "Payload sent to the call status webhook URL whenever the call state changes (e.g. trying, in-progress, completed). The status webhook is configured at the application level in jambonz. Multiple status events are sent over the life of a call. The final event (completed or failed) includes additional fields like duration and termination cause.",
+  "description": "Payload sent to the call status webhook URL whenever the call state changes (e.g. trying, in-progress, completed). The status webhook is configured at the application level in jambonz. Multiple status events are sent over the life of a call. The final event (completed or failed) includes additional fields like duration and termination cause.\n\n**Capturing B-leg call_sid:** When using the dial verb to bridge calls, status events are sent for both legs. The A-leg (original inbound call) has `direction: 'inbound'`. The B-leg (outbound dialed call) has `direction: 'outbound'`. To capture the B-leg's call_sid for later use (e.g., injecting commands to the B-leg), listen for status events where `direction === 'outbound'` and extract the `call_sid` field.",
   "allOf": [
     { "$ref": "base" }
   ],
   "type": "object",
   "properties": {
+    "direction": {
+      "type": "string",
+      "enum": ["inbound", "outbound"],
+      "description": "Call direction. 'inbound' = A-leg (original incoming call to the application). 'outbound' = B-leg (call placed by the dial verb). Use this field to identify which leg generated the status event, especially when capturing the B-leg's call_sid for mid-call control."
+    },
     "call_termination_by": {
       "type": "string",
       "enum": ["caller", "jambonz"],

package/commands/llm-tool-output.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/commands/llm:tool-output",
+  "title": "LLM Tool Output Command",
+  "description": "Command sent from the application to feature-server over the session websocket, carrying the result of a tool invocation that the LLM initiated during an agent verb. Sent in response to an `agent:tool-call` event. The result is fed back into the LLM so it can continue generating using the tool output.",
+  "type": "object",
+  "required": ["type", "command", "tool_call_id", "data"],
+  "properties": {
+    "type": { "const": "command" },
+    "command": { "const": "llm:tool-output" },
+    "tool_call_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The tool_call_id echoed from the originating `agent:tool-call` event."
+    },
+    "data": {
+      "type": "object",
+      "description": "Tool output payload. `{result: ...}` is the canonical shape — the wrapped value is what the LLM sees as the tool's return value. Other object shapes are accepted (they're JSON-stringified as-is into the tool_result content block on the wire) but `result` is preferred for clarity.",
+      "properties": {
+        "result": {}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "type": "command",
+      "command": "llm:tool-output",
+      "tool_call_id": "toolu_017NKXtgnD7fuo1KaTeSM1ok",
+      "data": {
+        "result": "The current temperature in Boston is 9.3°C with wind speed 17 km/h."
+      }
+    }
+  ]
+}

package/components/recognizer-assemblyAiOptions.schema.json

@@ -28,15 +28,15 @@
     },
     "minEndOfTurnSilenceWhenConfident": {
       "type": "number",
-      "description": "Minimum silence duration (seconds) to trigger end-of-turn when confidence is met."
+      "description": "Minimum silence duration (milliseconds) to trigger end-of-turn when confidence is met. Default: 400."
     },
     "maxTurnSilence": {
       "type": "number",
-      "description": "Maximum silence duration (seconds) before forcing end-of-turn."
+      "description": "Maximum silence duration (milliseconds) before forcing end-of-turn. Default: 1280."
     },
     "minTurnSilence": {
       "type": "number",
-      "description": "Minimum silence duration (seconds) before allowing end-of-turn."
+      "description": "Minimum silence duration (milliseconds) before allowing end-of-turn."
     },
     "keyterms": {
       "type": "array",

package/docs/guides/bridged-call-patterns.md

@@ -0,0 +1,261 @@
+# Bridged Call Patterns
+
+This guide covers common patterns for building applications that bridge two call legs (A-leg and B-leg) and need to interact with each party independently—such as real-time translation, call coaching, or call monitoring.
+
+## Understanding A-leg and B-leg
+
+When an inbound call arrives and your application uses the `dial` verb to connect the caller to another party:
+
+- **A-leg**: The original inbound call (caller → jambonz)
+- **B-leg**: The outbound call placed by the `dial` verb (jambonz → callee)
+
+Each leg has its own `call_sid` identifier and can receive independent commands.
+
+## Capturing the B-leg call_sid
+
+Many patterns require knowing the B-leg's `call_sid` to inject commands to that leg. Capture it from `call:status` events:
+
+```typescript
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  // B-leg events have direction === 'outbound'
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+    console.log(`B-leg call_sid captured: ${dialCallSid}`);
+  }
+});
+```
+
+**When it fires:** The `call:status` event with `direction: 'outbound'` fires when the dial verb initiates the B-leg call. You'll receive status updates for both legs throughout the call lifecycle.
+
+## Setting Up Transcription on Both Legs
+
+To transcribe both parties separately (e.g., for translation), configure transcription on each leg:
+
+```typescript
+session
+  // Transcribe A-leg (caller)
+  .transcribe({
+    transcriptionHook: '/transcription/caller',
+    channel: 1,  // Near-end = caller's voice
+    recognizer: {
+      vendor: 'deepgram',
+      language: 'en-US',
+      deepgramOptions: { model: 'nova-2' }
+    }
+  })
+  // Bridge to B-leg with separate transcription
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    transcribe: {
+      transcriptionHook: '/transcription/callee',
+      channel: 2,  // Far-end from A-leg = callee's voice
+      recognizer: {
+        vendor: 'deepgram',
+        language: 'es-ES',
+        deepgramOptions: { model: 'nova-2' }
+      }
+    }
+  })
+  .send();
+```
+
+### Channel Values Explained
+
+| Location | Channel | What it captures |
+|----------|---------|------------------|
+| A-leg transcribe | `1` (near-end) | Caller's voice |
+| A-leg transcribe | `2` (far-end) | What caller hears (including B-leg) |
+| dial.transcribe | `2` (far-end) | Callee's voice (B-leg inbound audio) |
+| dial.transcribe | (omitted) | Both parties mixed |
+
+### Identifying the Speaker in Transcription Events
+
+Use the `call_sid` in transcription events to determine who spoke:
+
+```typescript
+session.on('/transcription/caller', (evt: Record<string, any>) => {
+  if (evt.speech?.is_final) {
+    const transcript = evt.speech.alternatives[0].transcript;
+    handleCallerSpeech(transcript);
+  }
+});
+
+session.on('/transcription/callee', (evt: Record<string, any>) => {
+  if (evt.speech?.is_final) {
+    const transcript = evt.speech.alternatives[0].transcript;
+    handleCalleeSpeech(transcript);
+  }
+});
+```
+
+Or with a single hook, use `call_sid` to differentiate:
+
+```typescript
+session.on('/transcription', (evt: Record<string, any>) => {
+  if (!evt.speech?.is_final) return;
+
+  const transcript = evt.speech.alternatives[0].transcript;
+  const speaker = evt.call_sid === dialCallSid ? 'callee' : 'caller';
+
+  console.log(`${speaker}: ${transcript}`);
+});
+```
+
+## Creating Dub Tracks for Audio Injection
+
+To inject audio to each party (e.g., translated speech), create tracks on each leg:
+
+```typescript
+session
+  // Track on A-leg — caller hears it
+  .dub({ action: 'addTrack', track: 'caller-audio' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    // Track on B-leg — callee hears it
+    dub: [
+      { action: 'addTrack', track: 'callee-audio' }
+    ]
+  })
+  .send();
+```
+
+**Track routing rule:** Tracks are heard by the party on whose call leg they exist.
+
+## Injecting Commands to Specific Legs
+
+### Default: Commands go to A-leg
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-audio',
+  say: 'This message is for the caller'
+});
+```
+
+### Targeting B-leg: Pass call_sid as third argument
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-audio',
+  say: 'This message is for the callee'
+}, dialCallSid);  // Third argument routes to B-leg
+```
+
+**Important:** The `call_sid` is passed as a separate third argument, not inside the data object.
+
+## Complete Example: Real-Time Translator
+
+This example bridges an English caller with a Spanish-speaking callee, providing real-time translation in both directions.
+
+```typescript
+import { createEndpoint, Session } from '@jambonz/sdk/websocket';
+import http from 'http';
+
+const server = http.createServer();
+const makeService = createEndpoint({ server, port: 3000 });
+const svc = makeService({ path: '/' });
+
+svc.on('session:new', (session: Session) => {
+  let dialCallSid: string;
+
+  // Capture B-leg call_sid
+  session.on('call:status', (evt: Record<string, any>) => {
+    if (evt.direction === 'outbound') {
+      dialCallSid = evt.call_sid;
+    }
+  });
+
+  // Handle caller's speech (English → Spanish for callee)
+  session.on('/transcription/caller', async (evt: Record<string, any>) => {
+    session.reply();
+    if (!evt.speech?.is_final) return;
+
+    const transcript = evt.speech.alternatives[0].transcript;
+    const translated = await translateToSpanish(transcript);
+
+    // Inject to B-leg track (callee hears it)
+    session.injectCommand('dub', {
+      action: 'sayOnTrack',
+      track: 'callee-audio',
+      say: {
+        text: translated,
+        synthesizer: { vendor: 'elevenlabs', language: 'es-ES' }
+      }
+    }, dialCallSid);
+  });
+
+  // Handle callee's speech (Spanish → English for caller)
+  session.on('/transcription/callee', async (evt: Record<string, any>) => {
+    session.reply();
+    if (!evt.speech?.is_final) return;
+
+    const transcript = evt.speech.alternatives[0].transcript;
+    const translated = await translateToEnglish(transcript);
+
+    // Inject to A-leg track (caller hears it)
+    session.injectCommand('dub', {
+      action: 'sayOnTrack',
+      track: 'caller-audio',
+      say: {
+        text: translated,
+        synthesizer: { vendor: 'elevenlabs', language: 'en-US' }
+      }
+    });
+  });
+
+  // Set up the call
+  session
+    .dub({ action: 'addTrack', track: 'caller-audio' })
+    .transcribe({
+      transcriptionHook: '/transcription/caller',
+      channel: 1,
+      recognizer: { vendor: 'deepgram', language: 'en-US' }
+    })
+    .dial({
+      target: [{ type: 'phone', number: process.env.CALLEE_NUMBER! }],
+      dub: [
+        { action: 'addTrack', track: 'callee-audio' }
+      ],
+      transcribe: {
+        transcriptionHook: '/transcription/callee',
+        channel: 2,
+        recognizer: { vendor: 'deepgram', language: 'es-ES' }
+      }
+    })
+    .send();
+});
+
+async function translateToSpanish(text: string): Promise<string> {
+  // Implement translation logic
+  return text;
+}
+
+async function translateToEnglish(text: string): Promise<string> {
+  // Implement translation logic
+  return text;
+}
+```
+
+## Summary: Key Patterns
+
+| Pattern | Implementation |
+|---------|----------------|
+| Capture B-leg call_sid | Listen for `call:status` where `direction === 'outbound'` |
+| Transcribe caller | `transcribe` with `channel: 1` on A-leg |
+| Transcribe callee | `transcribe` with `channel: 2` nested in `dial` |
+| Audio track for caller | `dub` with `addTrack` on A-leg |
+| Audio track for callee | `dub` with `addTrack` in `dial.dub` array |
+| Inject to A-leg | `session.injectCommand(verb, data)` |
+| Inject to B-leg | `session.injectCommand(verb, data, dialCallSid)` |
+
+## See Also
+
+- `docs/verbs/transcribe.md` - Transcribe verb usage guide
+- `docs/verbs/dub.md` - Dub verb usage guide
+- `docs/guides/session-commands.md` - Session commands reference
+- `callback:call-status` - Call status webhook schema
+- `verb:dial` - Dial verb schema

package/docs/guides/session-commands.md

@@ -143,6 +143,44 @@ For any command not covered by a specific method:
 session.injectCommand('commandName', { ...data });
 ```
 
+### Targeting Specific Call Legs
+
+When bridging calls with the `dial` verb, you may need to inject commands to a specific call leg (A-leg or B-leg). By default, `injectCommand` targets the current session's call (A-leg). To target the B-leg (or any other call), pass the target `call_sid` as the third argument.
+
+**Capturing the B-leg call_sid:**
+
+Listen for `call:status` events with `direction === 'outbound'` to capture the B-leg's call_sid:
+
+```typescript
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+  }
+});
+```
+
+**Injecting commands to specific legs:**
+
+```typescript
+// Target A-leg (current session) — omit the third argument:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-track',
+  say: 'Message for the caller'
+});
+
+// Target B-leg — pass call_sid as third argument:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-track',
+  say: 'Message for the callee'
+}, dialCallSid);
+```
+
+This pattern is essential for applications like real-time translation, where you need to inject translated speech to each party separately based on which leg's audio was transcribed.
+
 ## Agent Update
 
 The `updateAgent()` method sends mid-conversation updates to an active `agent` verb. Four operation types are supported:

package/docs/verbs/dub.md

@@ -0,0 +1,219 @@
+# Dub Verb Usage Guide
+
+The `dub` verb manages auxiliary audio tracks that are mixed into the call audio. Tracks can play background music, coaching whispers, or inject synthesized speech—useful for real-time translation, agent assistance, or audio overlays.
+
+## Track Routing: Who Hears What
+
+**Critical concept:** Dub tracks are heard by the party on whose call leg they are created.
+
+| Where track is created | Who hears it |
+|------------------------|--------------|
+| Main verb stack (A-leg) | Caller |
+| Nested in dial verb's `dub` array | Callee |
+
+When using `injectCommand` to play/say on a track, the command routes to the call leg where the track was created—unless you specify a different `call_sid` as the third argument.
+
+## Basic Usage
+
+### Creating Tracks
+
+Create a track before playing audio on it:
+
+```typescript
+// Track on A-leg (caller hears it)
+session
+  .dub({ action: 'addTrack', track: 'caller-audio' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    dub: [
+      // Track on B-leg (callee hears it)
+      { action: 'addTrack', track: 'callee-audio' }
+    ]
+  })
+  .send();
+```
+
+### Playing Audio on Tracks
+
+```typescript
+// Play audio file
+session
+  .dub({
+    action: 'playOnTrack',
+    track: 'bgm',
+    play: 'https://example.com/music.mp3',
+    loop: true,
+    gain: -15  // Reduce volume by 15dB
+  })
+  .send();
+
+// Synthesize and play speech
+session
+  .dub({
+    action: 'sayOnTrack',
+    track: 'coach',
+    say: 'Ask about their timeline'
+  })
+  .send();
+```
+
+### Controlling Tracks
+
+```typescript
+// Silence a track (mute without removing)
+session.dub({ action: 'silenceTrack', track: 'bgm' }).send();
+
+// Remove a track entirely
+session.dub({ action: 'removeTrack', track: 'bgm' }).send();
+```
+
+## Mid-Call Audio Injection with injectCommand
+
+The most powerful use of dub tracks is injecting audio mid-call via `injectCommand`. This is how you implement real-time features like translation or coaching.
+
+### Injecting to the Current Call Leg (A-leg)
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-audio',
+  say: 'Translated text for the caller'
+});
+```
+
+### Injecting to a Specific Call Leg (B-leg)
+
+When the target track exists on a different call leg, pass the target `call_sid` as the third argument:
+
+```typescript
+// First, capture the B-leg call_sid from call:status events
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+  }
+});
+
+// Then inject to the B-leg
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-audio',
+  say: 'Translated text for the callee'
+}, dialCallSid);
+```
+
+**Important:** The third argument is the `call_sid` of the call leg where the track exists, not part of the data object.
+
+## Common Use Cases
+
+### Real-Time Translation
+
+Set up tracks for each party, then inject translated speech based on transcriptions:
+
+```typescript
+session
+  .dub({ action: 'addTrack', track: 'caller-translation' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    dub: [
+      { action: 'addTrack', track: 'callee-translation' }
+    ],
+    transcribe: {
+      transcriptionHook: '/transcription',
+      recognizer: { vendor: 'deepgram' }
+    }
+  })
+  .send();
+
+// When callee speaks, translate and play to caller:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'caller-translation',
+  say: { text: translatedText, synthesizer: { language: 'en-US' } }
+});
+
+// When caller speaks, translate and play to callee:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'callee-translation',
+  say: { text: translatedText, synthesizer: { language: 'es-ES' } }
+}, dialCallSid);
+```
+
+### Agent Coaching / Whisper
+
+Play prompts only the agent hears (A-leg is the agent):
+
+```typescript
+session
+  .dub({ action: 'addTrack', track: 'coach' })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }]
+  })
+  .send();
+
+// Supervisor sends a coaching message:
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'coach',
+  say: 'Offer them a 20% discount'
+});
+```
+
+### Background Music / Hold Music
+
+```typescript
+session
+  .dub({ action: 'addTrack', track: 'bgm' })
+  .dub({
+    action: 'playOnTrack',
+    track: 'bgm',
+    play: 'https://example.com/hold-music.mp3',
+    loop: true,
+    gain: -20
+  })
+  .send();
+```
+
+## Say Configuration Object
+
+The `say` property can be a string or a configuration object for more control:
+
+```typescript
+session.injectCommand('dub', {
+  action: 'sayOnTrack',
+  track: 'translation',
+  say: {
+    text: 'Hello, how can I help you?',
+    synthesizer: {
+      vendor: 'elevenlabs',
+      voice: 'EXAVITQu4vr4xnSDxMaL',
+      language: 'en-US'
+    }
+  }
+});
+```
+
+## Gain Control
+
+Use the `gain` property to adjust track volume in dB:
+
+- Negative values reduce volume (e.g., `-15` for quiet background music)
+- Positive values increase volume (use carefully to avoid clipping)
+- `0` is the default (no change)
+
+```typescript
+session.dub({
+  action: 'playOnTrack',
+  track: 'bgm',
+  play: 'https://example.com/music.mp3',
+  gain: -15
+}).send();
+```
+
+## See Also
+
+- `verb:dub` - Full schema with all properties
+- `docs/guides/session-commands.md` - injectCommand documentation
+- `docs/guides/bridged-call-patterns.md` - Complete guide to bridged call scenarios

package/docs/verbs/transcribe.md

@@ -0,0 +1,167 @@
+# Transcribe Verb Usage Guide
+
+The `transcribe` verb enables real-time speech-to-text on a call. Transcription runs as a background process—subsequent verbs execute immediately while transcription continues. Results are streamed to your `transcriptionHook` webhook as they are produced.
+
+## Basic Usage
+
+```typescript
+session
+  .transcribe({
+    transcriptionHook: '/transcription',
+    recognizer: {
+      vendor: 'deepgram',
+      language: 'en-US',
+      deepgramOptions: {
+        model: 'nova-2',
+        smartFormatting: true
+      }
+    }
+  })
+  .dial({ target: [{ type: 'phone', number: '+15551234567' }] })
+  .send();
+```
+
+## Channel Isolation for Bridged Calls
+
+When transcribing a bridged call (A-leg connected to B-leg via `dial`), you can isolate which party's audio to transcribe using the `channel` property:
+
+| Channel | Description |
+|---------|-------------|
+| (omitted) | Both parties' audio, mixed |
+| `1` | Near-end audio (local party—caller on A-leg, callee on B-leg) |
+| `2` | Far-end audio (remote party) |
+
+### Transcribing Both Legs Separately
+
+To get separate transcriptions for each party in a bridged call:
+
+```typescript
+session
+  .transcribe({
+    transcriptionHook: '/transcription/caller',
+    channel: 1,  // Caller's audio (A-leg near-end)
+    recognizer: { vendor: 'deepgram', language: 'en-US' }
+  })
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    transcribe: {
+      transcriptionHook: '/transcription/callee',
+      channel: 2,  // Callee's audio (B-leg far-end from A-leg perspective)
+      recognizer: { vendor: 'deepgram', language: 'es-ES' }
+    }
+  })
+  .send();
+```
+
+**Important:** When `transcribe` is nested in the `dial` verb, channel 2 isolates the B-leg's inbound audio (what the callee is saying).
+
+## Transcription Hook Payload
+
+Your webhook receives transcription results with these key fields:
+
+```typescript
+session.on('/transcription', (evt: Record<string, any>) => {
+  const {
+    call_sid,           // Which call leg generated this transcript
+    speech,             // Speech recognition results
+    is_final,           // true for final results, false for interim
+    transcription_sid,  // Unique ID for this transcription session
+  } = evt;
+
+  if (speech?.is_final) {
+    const { transcript, confidence } = speech.alternatives[0];
+    console.log(`[${call_sid}] ${transcript} (${confidence})`);
+  }
+});
+```
+
+## Identifying Which Party Spoke
+
+The `call_sid` in transcription events identifies which call leg generated the transcript. If you're tracking the B-leg's call_sid (captured from `call:status` events), you can identify the speaker:
+
+```typescript
+let dialCallSid: string;
+
+session.on('call:status', (evt: Record<string, any>) => {
+  if (evt.direction === 'outbound') {
+    dialCallSid = evt.call_sid;
+  }
+});
+
+session.on('/transcription', (evt: Record<string, any>) => {
+  const speaker = evt.call_sid === dialCallSid ? 'callee' : 'caller';
+  console.log(`${speaker}: ${evt.speech?.alternatives[0]?.transcript}`);
+});
+```
+
+## Nested Transcribe in Config vs Dial
+
+You can enable transcription in two places:
+
+### In the main verb stack (or config)
+
+Transcribes the A-leg. Without `channel`, captures caller audio. With `channel: 2`, captures far-end (what caller hears).
+
+```typescript
+session
+  .config({
+    transcribe: {
+      enable: true,
+      transcriptionHook: '/transcription',
+      recognizer: { vendor: 'deepgram' }
+    }
+  })
+  .send();
+```
+
+### Nested in dial
+
+Transcribes during the bridged call. Without `channel`, captures both parties mixed. With `channel: 2`, isolates B-leg audio.
+
+```typescript
+session
+  .dial({
+    target: [{ type: 'phone', number: '+15551234567' }],
+    transcribe: {
+      transcriptionHook: '/transcription',
+      channel: 2,  // Just the callee's voice
+      recognizer: { vendor: 'deepgram', language: 'es-ES' }
+    }
+  })
+  .send();
+```
+
+## Interim vs Final Results
+
+Most STT vendors provide both interim (partial) and final transcription results:
+
+- **Interim results** (`is_final: false`): Real-time partial transcripts that update as speech continues. Useful for live displays.
+- **Final results** (`is_final: true`): Complete utterance transcripts after the speaker pauses. Use these for processing/translation.
+
+```typescript
+session.on('/transcription', (evt: Record<string, any>) => {
+  if (evt.speech?.is_final) {
+    // Process complete utterance
+    processTranscript(evt.speech.alternatives[0].transcript);
+  }
+  // Optionally handle interim results for live display
+});
+```
+
+## Enabling/Disabling Transcription
+
+Use `enable: false` to stop background transcription:
+
+```typescript
+session
+  .config({
+    transcribe: { enable: false }
+  })
+  .send();
+```
+
+## See Also
+
+- `callback:transcribe` - Full transcription webhook payload schema
+- `component:recognizer` - STT configuration options per vendor
+- `docs/guides/bridged-call-patterns.md` - Complete guide to bridged call scenarios

package/index.js

@@ -1,9 +1,10 @@
-const {validate, validateVerb, validateApp} = require('./lib/validator');
+const {validate, validateVerb, validateApp, validateCommand} = require('./lib/validator');
 const {normalizeJambones} = require('./lib/normalize');
 
 module.exports = {
   validate,
   validateVerb,
   validateApp,
+  validateCommand,
   normalizeJambones,
 };

package/lib/validator.js

@@ -54,6 +54,12 @@ function getAjv() {
     _ajv.addSchema(schema);
   }
 
+  /* register command schemas (app → server over the session websocket) */
+  for (const name of discoverSchemas('commands')) {
+    const schema = loadSchema(`commands/${name}.schema.json`);
+    _ajv.addSchema(schema);
+  }
+
   /* compile the root app schema */
   const appSchema = loadSchema('jambonz-app.schema.json');
   _validateApp = _ajv.compile(appSchema);
@@ -103,6 +109,45 @@ function validateVerb(name, data, logger) {
   }
 }
 
+/**
+ * Validate a command message sent from the app to feature-server over the
+ * session websocket.
+ *
+ * Commands are the inverse of callbacks: callbacks flow server → app; commands
+ * flow app → server. Currently defined commands:
+ *   - llm:tool-output — response to an agent:tool-call event.
+ *
+ * @param {string} name - Command name (e.g. 'llm:tool-output').
+ * @param {object} message - The full command message including `type` and `command`.
+ * @param {object} logger - Logger instance.
+ * @throws {Error} If the command is unknown or validation fails.
+ */
+function validateCommand(name, message, logger) {
+  const ajv = getAjv();
+  const schemaId = `https://jambonz.org/schema/commands/${name}`;
+  const validate = ajv.getSchema(schemaId);
+  if (!validate) {
+    throw new Error(`invalid command: ${name}`);
+  }
+  const valid = validate(message);
+  if (!valid) {
+    const errors = validate.errors || [];
+    const details = errors.map((e) => {
+      const path = e.instancePath || '(root)';
+      let msg = `'${path}': ${e.message}`;
+      if (e.params) {
+        if (e.params.type) msg += ` (expected ${e.params.type})`;
+        if (e.params.allowedValues) msg += ` (allowed: ${e.params.allowedValues.join(', ')})`;
+        if (e.params.missingProperty) msg += ` (missing: ${e.params.missingProperty})`;
+      }
+      return msg;
+    }).join('; ');
+    const errMsg = `command '${name}' validation failed — ${details}. Schema: ${schemaId}`;
+    debug(errMsg);
+    throw new Error(errMsg);
+  }
+}
+
 /**
  * Validate a complete jambonz application (array of verbs).
  *
@@ -144,4 +189,4 @@ function validateApp(app) {
   };
 }
 
-module.exports = {validate, validateVerb, validateApp};
+module.exports = {validate, validateVerb, validateApp, validateCommand};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/schema",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "JSON Schema definitions and validation for jambonz verb applications",
   "main": "index.js",
   "scripts": {
@@ -32,6 +32,7 @@
     "verbs/",
     "components/",
     "callbacks/",
+    "commands/",
     "docs/",
     "jambonz-app.schema.json",
     "AGENTS.md"

package/verbs/agent.schema.json

@@ -86,8 +86,89 @@
     },
     "llm": {
       "type": "object",
-      "description": "LLM configuration for the agent. See the 'llm' verb schema for details.",
-      "additionalProperties": true
+      "description": "LLM configuration for the agent.",
+      "required": ["vendor", "model"],
+      "properties": {
+        "vendor": {
+          "type": "string",
+          "enum": [
+            "openai",
+            "anthropic",
+            "google",
+            "vertex-gemini",
+            "vertex-openai",
+            "bedrock",
+            "deepseek"
+          ],
+          "description": "LLM vendor id. Must match a `@jambonz/llm` registered adapter."
+        },
+        "model": {
+          "type": "string",
+          "description": "Vendor-specific model id (e.g. 'gpt-4o', 'claude-sonnet-4-5-20250929')."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional label to disambiguate when the account has multiple credentials for the same vendor."
+        },
+        "auth": {
+          "type": "object",
+          "description": "Optional inline credentials. When omitted, feature-server looks up credentials by (vendor, label) from the database.",
+          "properties": {
+            "apiKey": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        "connectOptions": {
+          "type": "object",
+          "description": "SDK-level client options.",
+          "properties": {
+            "timeout": { "type": "number", "minimum": 0 },
+            "maxRetries": { "type": "integer", "minimum": 0 },
+            "endpoint": { "type": "string" },
+            "baseURL": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "llmOptions": {
+          "type": "object",
+          "description": "Per-call LLM configuration.",
+          "properties": {
+            "systemPrompt": {
+              "type": "string",
+              "description": "System prompt for the model. Placed vendor-appropriately (top-level for Anthropic/Bedrock, config.systemInstruction for Gemini, role:'system' for OpenAI-compatibles)."
+            },
+            "messages": {
+              "type": "array",
+              "description": "Seed conversation history. A role:'system' entry is extracted into systemPrompt internally.",
+              "items": { "$ref": "#/$defs/llmMessage" }
+            },
+            "initialMessages": {
+              "type": "array",
+              "description": "Alias of 'messages' (historical).",
+              "items": { "$ref": "#/$defs/llmMessage" }
+            },
+            "maxTokens": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum tokens the model may generate per turn."
+            },
+            "temperature": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Sampling temperature."
+            },
+            "tools": {
+              "type": "array",
+              "description": "Tool / function definitions available to the model. The MCP-flat shape `{name, description, parameters}` is canonical; the OpenAI-wrapped form `{type:'function', function:{...}}` is also accepted.",
+              "items": {
+                "type": "object"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     },
     "actionHook": {
       "$ref": "../components/actionHook",
@@ -177,6 +258,21 @@
   "required": [
     "llm"
   ],
+  "$defs": {
+    "llmMessage": {
+      "type": "object",
+      "description": "A conversation-history message. The library normalizes content to a string; adapters may carry vendor-native shapes internally.",
+      "required": ["role", "content"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "enum": ["system", "user", "assistant", "tool"]
+        },
+        "content": {}
+      },
+      "additionalProperties": true
+    }
+  },
   "examples": [
     {
       "verb": "agent",

package/verbs/dub.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://jambonz.org/schema/verbs/dub",
   "minVersion": "0.9.6",
   "title": "Dub",
-  "description": "Manages audio dubbing tracks on a call. Allows adding, removing, and controlling auxiliary audio tracks that are mixed into the call audio. Used for background music, coaching whispers, or injecting audio from external sources.",
+  "description": "Manages audio dubbing tracks on a call. Allows adding, removing, and controlling auxiliary audio tracks that are mixed into the call audio. Used for background music, coaching whispers, or injecting audio from external sources.\n\n**Track Routing:** Tracks are heard by the party on whose call leg they are created. A dub verb in the main verb stack (A-leg) creates tracks heard by the caller. A dub verb nested in the dial verb's `dub` array creates tracks heard by the callee. When using injectCommand to play/say on a track from a different call leg, pass the target call's `call_sid` as the third argument to `session.injectCommand()` to route the command to the correct leg.",
   "type": "object",
   "properties": {
     "verb": {

package/verbs/transcribe.schema.json

@@ -37,7 +37,8 @@
     },
     "channel": {
       "type": "number",
-      "description": "Specific audio channel to transcribe."
+      "enum": [1, 2],
+      "description": "Specific audio channel to transcribe. Channel 1 = near-end (local party's audio, i.e. caller on A-leg or callee on B-leg). Channel 2 = far-end (remote party's audio). When transcribe is nested in the dial verb, omitting channel captures both legs mixed; specifying channel: 2 isolates the B-leg's inbound audio."
     }
   },
   "examples": [