@jambonz/mcp-schema-server 0.1.0

package/AGENTS.md

@@ -0,0 +1,305 @@
+# jambonz Agent Toolkit
+
+jambonz is an open-source CPaaS (Communications Platform as a Service) for building voice and messaging applications. It handles telephony infrastructure — SIP, carriers, phone numbers, media processing — so you can focus on application logic.
+
+## How jambonz Applications Work
+
+A jambonz application controls phone calls by returning **arrays of verbs** — JSON instructions that execute sequentially. The runtime processes each verb in order: speak text, play audio, collect input, dial a number, connect to an AI model, etc.
+
+### The Webhook Lifecycle
+
+1. An incoming call arrives. jambonz invokes your application's URL with call details (caller, called number, SIP headers, etc.).
+2. Your application returns a JSON array of verbs.
+3. jambonz executes the verbs in order.
+4. When a verb with an `actionHook` completes (e.g. `gather` collects speech input), jambonz invokes the actionHook URL with the result.
+5. The actionHook response (a new verb array) replaces the remaining verb stack.
+6. This continues until the call ends or a `hangup` verb is executed.
+
+### Transport Modes
+
+jambonz supports two transport modes for delivering verb arrays:
+
+- **Webhook (HTTP)**: Your server receives HTTP POST requests with call data and returns JSON verb arrays in the response body. Stateless and simple. Good for IVR menus, call routing, and straightforward flows.
+- **WebSocket**: Your server maintains a persistent websocket connection with jambonz. Verb arrays are sent as JSON messages in both directions. Required for real-time features like LLM conversations, audio streaming, and event-driven flows.
+
+The verb schemas and JSON structure are identical in both modes. The difference is the transport.
+
+### When to Use Which
+
+- **Webhook**: Simple IVR, call routing, voicemail, basic gather-and-respond patterns.
+- **WebSocket**: LLM-powered voice agents, real-time audio streaming, complex conversational flows, anything requiring bidirectional communication, or asynchronous logic, or streaming tts.
+
+## Schema
+
+The complete verb schema is at `schema/jambonz-app.schema.json`. This is a JSON Schema (draft 2020-12) that defines the structure of a jambonz application.
+
+Individual verb schemas are in `schema/verbs/`. Shared component types (synthesizer, recognizer, target, etc.) are in `schema/components/`.
+
+## Core Verbs
+
+### Audio & Speech
+- **say** — Speak text using TTS. Supports SSML, streaming, multiple voices.
+- **play** — Play an audio file from a URL.
+- **gather** — Collect speech (STT) and/or DTMF input. The workhorse for interactive menus and voice input.
+
+### AI & Real-time
+- **llm** — Connect the caller to an LLM for real-time voice conversation. Handles the full STT→LLM→TTS pipeline.
+- **pipeline** — Higher-level voice AI pipeline with integrated turn detection.
+- **listen** / **stream** — Stream raw audio to a websocket endpoint for custom processing.
+- **transcribe** — Real-time call transcription sent to a webhook.
+
+### Call Control
+- **dial** — Place an outbound call and bridge it to the current caller.
+- **conference** — Multi-party conference room.
+- **enqueue** / **dequeue** — Call queuing.
+- **hangup** — End the call.
+- **redirect** — Transfer control to a different webhook.
+- **pause** — Wait for a specified duration.
+
+### SIP
+- **sip:decline** — Reject an incoming call with a SIP error.
+- **sip:request** — Send a SIP request within the dialog.
+- **sip:refer** — Transfer the call via SIP REFER.
+
+### Utility
+- **config** — Set session-level defaults (TTS vendor/voice, STT vendor, VAD, etc.).
+- **tag** — Attach metadata to the call.
+- **dtmf** — Send DTMF tones.
+- **dub** — Mix auxiliary audio tracks into the call.
+- **message** — Send SMS/MMS.
+- **alert** — Send a SIP 180 with Alert-Info.
+- **answer** — Explicitly answer the call.
+- **leave** — Leave a conference or queue.
+
+## Common Patterns
+
+### Simple Greeting and Gather
+```json
+[
+  { "verb": "say", "text": "Welcome. Press 1 for sales, 2 for support." },
+  { "verb": "gather", "input": ["digits"], "numDigits": 1, "actionHook": "/menu" }
+]
+```
+
+### LLM Voice Agent
+```json
+[
+  {
+    "verb": "config",
+    "synthesizer": { "vendor": "elevenlabs", "voice": "Rachel" },
+    "recognizer": { "vendor": "deepgram", "language": "en-US" }
+  },
+  {
+    "verb": "llm",
+    "vendor": "openai",
+    "model": "gpt-4o",
+    "llmOptions": {
+      "messages": [{ "role": "system", "content": "You are a helpful assistant." }]
+    },
+    "actionHook": "/llm-done",
+    "toolHook": "/tool-call"
+  }
+]
+```
+
+### Dial with Fallback
+```json
+[
+  { "verb": "say", "text": "Connecting you now." },
+  {
+    "verb": "dial",
+    "target": [{ "type": "phone", "number": "+15085551212" }],
+    "answerOnBridge": true,
+    "timeout": 30,
+    "actionHook": "/dial-result"
+  },
+  { "verb": "say", "text": "The agent is unavailable. Goodbye." },
+  { "verb": "hangup" }
+]
+```
+
+### Call Queue
+```json
+[
+  { "verb": "say", "text": "All agents are busy. You are in the queue." },
+  {
+    "verb": "enqueue",
+    "name": "support",
+    "waitHook": "/hold-music",
+    "actionHook": "/queue-exit"
+  }
+]
+```
+
+## ActionHook Payloads
+
+When a verb completes, jambonz invokes the `actionHook` URL (webhook) or sends an event (WebSocket) with result data. Every actionHook payload includes these base fields:
+
+| Field | Description |
+|-------|-------------|
+| `call_sid` | Unique identifier for this call |
+| `account_sid` | Your account identifier |
+| `application_sid` | The application handling this call |
+| `direction` | `inbound` or `outbound` |
+| `from` | Caller phone number or SIP URI |
+| `to` | Called phone number or SIP URI |
+| `call_id` | SIP Call-ID |
+| `call_status` | Current call state (`trying`, `ringing`, `early-media`, `in-progress`, `completed`, `failed`, `busy`, `no-answer`) |
+| `sip_status` | SIP response code (e.g. `200`, `486`) |
+
+### Verb-Specific Payload Fields
+
+**gather**: `speech` (object with `alternatives[].transcript`), `digits` (string), `reason` (`speechDetected`, `dtmfDetected`, `timeout`)
+
+**dial**: `dial_call_sid`, `dial_call_status`, `dial_sip_status`, `duration`
+
+**llm**: `completion_reason` (`normal`, `timeout`, `error`), `llm_usage` (token counts)
+
+**enqueue**: `queue_result` (`dequeued`, `hangup`, `error`)
+
+**transcribe**: `transcription` (object with transcript text)
+
+## Mid-Call Control
+
+Active calls can be modified asynchronously — inject verbs, mute, redirect, or start recording while the call is in progress.
+
+### REST API (Webhook Apps)
+
+Use `PUT /v1/Accounts/{accountSid}/Calls/{callSid}` to modify an active call:
+
+```json
+{ "whisper": { "verb": "say", "text": "Supervisor is listening." } }
+{ "mute_status": "mute" }
+{ "call_hook": "https://example.com/new-flow" }
+{ "call_status": "completed" }
+{ "listen_status": "pause" }
+```
+
+The SDK provides typed methods:
+```typescript
+import { JambonzClient } from '@jambonz/sdk/client';
+const client = new JambonzClient({ baseUrl, accountSid, apiKey });
+
+await client.calls.whisper(callSid, { verb: 'say', text: 'Hello' });
+await client.calls.mute(callSid, 'mute');
+await client.calls.redirect(callSid, 'https://example.com/new-flow');
+await client.calls.update(callSid, { call_status: 'completed' });
+```
+
+### Inject Commands (WebSocket Apps)
+
+WebSocket sessions can inject commands for immediate execution:
+
+```typescript
+// Recording
+session.injectRecord('startCallRecording', { siprecServerURL: 'sip:recorder@example.com' });
+session.injectRecord('stopCallRecording');
+
+// Whisper a verb to one party
+session.injectWhisper({ verb: 'say', text: 'You have 5 minutes remaining.' });
+
+// Mute/unmute
+session.injectMute('mute');
+session.injectMute('unmute');
+
+// Pause/resume audio streaming
+session.injectListenStatus('pause');
+
+// Send DTMF
+session.injectDtmf('1');
+
+// Attach metadata
+session.injectTag({ supervisor: 'jane', priority: 'high' });
+
+// Generic inject (for any command)
+session.injectCommand('redirect', { call_hook: '/new-flow' });
+```
+
+## WebSocket Protocol
+
+### Message Types (jambonz → app)
+
+| Type | Description |
+|------|-------------|
+| `session:new` | New call session established. Contains call details. |
+| `session:redirect` | Call was redirected to this app. |
+| `verb:status` | A verb completed or changed status. Contains actionHook data. |
+| `call:status` | Call state changed (e.g. `completed`). |
+| `llm:tool-call` | LLM requested a tool/function call. |
+| `llm:event` | LLM lifecycle event (connected, tokens, etc.). |
+| `tts:tokens-result` | Ack for a TTS token streaming message. |
+| `tts:streaming-event` | TTS streaming lifecycle event (e.g. user interruption). |
+
+### Message Types (app → jambonz)
+
+| Type | Description |
+|------|-------------|
+| `ack` | Acknowledge a received message. Include verbs in the `data` array to replace the current verb stack. |
+| `command` | Send a command (e.g. inject a verb, control recording). |
+| `llm:tool-output` | Return the result of a tool call to the LLM. |
+| `tts:tokens` | Stream TTS text tokens for incremental speech synthesis. |
+| `tts:flush` | Signal end of a TTS token stream. |
+
+### Session Events (SDK)
+
+The SDK `Session` object emits events for common message types:
+
+```typescript
+session.on('session:new', (session) => { /* new call */ });
+session.on('verb:status', (data) => { /* verb completed */ });
+session.on('call:status', (data) => { /* call state change */ });
+session.on('llm:tool-call', (data) => { /* tool call from LLM */ });
+session.on('llm:event', (data) => { /* LLM event */ });
+session.on('tts:user_interrupt', () => { /* user interrupted TTS */ });
+session.on('close', (code, reason) => { /* connection closed */ });
+session.on('error', (err) => { /* error */ });
+```
+
+## Recording
+
+jambonz supports SIPREC-based call recording. Recording is controlled mid-call via inject commands (WebSocket) or future REST API extensions.
+
+### WebSocket Recording
+```typescript
+// Start recording — sends audio via SIPREC to a recording server
+session.injectRecord('startCallRecording', {
+  siprecServerURL: 'sip:recorder@example.com',
+  recordingID: 'my-recording-123',  // optional
+});
+
+// Pause/resume recording
+session.injectRecord('pauseCallRecording');
+session.injectRecord('resumeCallRecording');
+
+// Stop recording
+session.injectRecord('stopCallRecording');
+```
+
+**Important**: The `dial` verb must use `anchorMedia: true` for recording to work during bridged calls. Without media anchoring, audio doesn't flow through the jambonz media server.
+
+## REST API
+
+jambonz provides a REST API for platform management and active call control. The API client is available in the SDK at `@jambonz/sdk/client`.
+
+Key resources:
+- **Calls** — Create outbound calls, query active calls, modify in-progress calls (redirect, whisper, mute, hangup)
+- **Messages** — Send SMS/MMS messages
+
+## Examples
+
+Complete working examples are in the `examples/` directory:
+- **hello-world** — Minimal greeting (webhook + WebSocket)
+- **ivr-menu** — Interactive menu with speech and DTMF input (webhook)
+- **voice-agent** — LLM-powered conversational AI (webhook + WebSocket)
+- **queue-with-hold** — Call queue with hold music and agent dequeue (webhook + WebSocket)
+- **call-recording** — Mid-call recording control via REST API and inject commands (webhook + WebSocket)
+
+## Key Concepts
+
+- **Verb**: A JSON object with a `verb` property that tells jambonz what to do. Verbs execute sequentially.
+- **ActionHook**: A webhook URL that jambonz calls when a verb completes. Returns the next verb array. Payload includes call details and verb-specific results.
+- **Synthesizer**: TTS configuration (vendor, voice, language).
+- **Recognizer**: STT configuration (vendor, language, model).
+- **Target**: A call destination (phone number, SIP URI, registered user, Teams user).
+- **Session**: A single phone call. Session-level settings (set via `config`) persist across verbs.
+- **Inject Command**: Asynchronous mid-call modification (WebSocket). Executes immediately without replacing the verb stack.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/resources.ts
+import { readFileSync, readdirSync } from "fs";
+import { resolve, basename, dirname } from "path";
+import { fileURLToPath } from "url";
+function findSchemaDir() {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(__dirname, "../schema"),
+    // npm: mcp-server/schema/
+    resolve(__dirname, "../../schema"),
+    // dev: from dist/ or src/
+    resolve(__dirname, "../../../schema")
+    // dev: nested
+  ];
+  for (const dir of candidates) {
+    try {
+      readdirSync(dir);
+      return dir;
+    } catch {
+    }
+  }
+  throw new Error("Could not locate schema directory");
+}
+function findAgentsMd() {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(__dirname, "../AGENTS.md"),
+    // npm: mcp-server/AGENTS.md
+    resolve(__dirname, "../../AGENTS.md"),
+    // dev: from dist/ or src/
+    resolve(__dirname, "../../../AGENTS.md")
+    // dev: nested
+  ];
+  for (const path of candidates) {
+    try {
+      readFileSync(path, "utf-8");
+      return path;
+    } catch {
+    }
+  }
+  throw new Error("Could not locate AGENTS.md");
+}
+function registerResources(server2) {
+  const schemaDir = findSchemaDir();
+  const agentsMdPath = findAgentsMd();
+  server2.resource(
+    "agents-guide",
+    "jambonz://docs/agents-guide",
+    {
+      description: "jambonz Agent Toolkit guide \u2014 explains the verb model, transport modes, core verbs, and common patterns",
+      mimeType: "text/markdown"
+    },
+    async (uri) => ({
+      contents: [{
+        uri: uri.href,
+        text: readFileSync(agentsMdPath, "utf-8"),
+        mimeType: "text/markdown"
+      }]
+    })
+  );
+  const appSchemaPath = resolve(schemaDir, "jambonz-app.schema.json");
+  server2.resource(
+    "app-schema",
+    "jambonz://schema/jambonz-app",
+    {
+      description: "Root JSON Schema for a jambonz application \u2014 an array of verbs",
+      mimeType: "application/schema+json"
+    },
+    async (uri) => ({
+      contents: [{
+        uri: uri.href,
+        text: readFileSync(appSchemaPath, "utf-8"),
+        mimeType: "application/schema+json"
+      }]
+    })
+  );
+  const verbsDir = resolve(schemaDir, "verbs");
+  const verbFiles = readdirSync(verbsDir).filter((f) => f.endsWith(".schema.json"));
+  for (const file of verbFiles) {
+    const verbName = basename(file, ".schema.json");
+    const filePath = resolve(verbsDir, file);
+    server2.resource(
+      `verb-${verbName}`,
+      `jambonz://schema/verbs/${verbName}`,
+      {
+        description: `JSON Schema for the "${verbName}" verb`,
+        mimeType: "application/schema+json"
+      },
+      async (uri) => ({
+        contents: [{
+          uri: uri.href,
+          text: readFileSync(filePath, "utf-8"),
+          mimeType: "application/schema+json"
+        }]
+      })
+    );
+  }
+  const componentsDir = resolve(schemaDir, "components");
+  const componentFiles = readdirSync(componentsDir).filter((f) => f.endsWith(".schema.json"));
+  for (const file of componentFiles) {
+    const componentName = basename(file, ".schema.json");
+    const filePath = resolve(componentsDir, file);
+    server2.resource(
+      `component-${componentName}`,
+      `jambonz://schema/components/${componentName}`,
+      {
+        description: `JSON Schema for the "${componentName}" component`,
+        mimeType: "application/schema+json"
+      },
+      async (uri) => ({
+        contents: [{
+          uri: uri.href,
+          text: readFileSync(filePath, "utf-8"),
+          mimeType: "application/schema+json"
+        }]
+      })
+    );
+  }
+}
+
+// src/index.ts
+var server = new McpServer({
+  name: "jambonz-schema-server",
+  version: "0.1.0"
+});
+registerResources(server);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/resources.ts"],"sourcesContent":["/**\n * jambonz MCP Schema Server\n *\n * Serves jambonz verb schemas and documentation as MCP resources.\n * Designed for AI agents that build jambonz voice applications.\n *\n * Usage:\n *   npx @jambonz/mcp-schema-server\n *\n * Or in Claude Desktop config:\n *   { \"command\": \"npx\", \"args\": [\"@jambonz/mcp-schema-server\"] }\n */\n\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { registerResources } from './resources.js';\n\nconst server = new McpServer({\n  name: 'jambonz-schema-server',\n  version: '0.1.0',\n});\n\nregisterResources(server);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n","/**\n * Registers jambonz schema files and documentation as MCP resources.\n */\n\nimport { readFileSync, readdirSync } from 'fs';\nimport { resolve, basename, dirname } from 'path';\nimport { fileURLToPath } from 'url';\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\n/** Locate the schema directory. Checks:\n *  1. Bundled in npm package: mcp-server/schema/ (copied by prepack)\n *  2. Development: sibling to mcp-server/ at agent-toolkit/schema/\n */\nfunction findSchemaDir(): string {\n  const __dirname = dirname(fileURLToPath(import.meta.url));\n  const candidates = [\n    resolve(__dirname, '../schema'),          // npm: mcp-server/schema/\n    resolve(__dirname, '../../schema'),       // dev: from dist/ or src/\n    resolve(__dirname, '../../../schema'),     // dev: nested\n  ];\n  for (const dir of candidates) {\n    try {\n      readdirSync(dir);\n      return dir;\n    } catch {\n      // continue\n    }\n  }\n  throw new Error('Could not locate schema directory');\n}\n\n/** Locate AGENTS.md. Checks:\n *  1. Bundled in npm package: mcp-server/AGENTS.md (copied by prepack)\n *  2. Development: sibling to mcp-server/ at agent-toolkit/AGENTS.md\n */\nfunction findAgentsMd(): string {\n  const __dirname = dirname(fileURLToPath(import.meta.url));\n  const candidates = [\n    resolve(__dirname, '../AGENTS.md'),       // npm: mcp-server/AGENTS.md\n    resolve(__dirname, '../../AGENTS.md'),    // dev: from dist/ or src/\n    resolve(__dirname, '../../../AGENTS.md'), // dev: nested\n  ];\n  for (const path of candidates) {\n    try {\n      readFileSync(path, 'utf-8');\n      return path;\n    } catch {\n      // continue\n    }\n  }\n  throw new Error('Could not locate AGENTS.md');\n}\n\nexport function registerResources(server: McpServer): void {\n  const schemaDir = findSchemaDir();\n  const agentsMdPath = findAgentsMd();\n\n  // 1. AGENTS.md — the main documentation resource\n  server.resource(\n    'agents-guide',\n    'jambonz://docs/agents-guide',\n    {\n      description: 'jambonz Agent Toolkit guide — explains the verb model, transport modes, core verbs, and common patterns',\n      mimeType: 'text/markdown',\n    },\n    async (uri) => ({\n      contents: [{\n        uri: uri.href,\n        text: readFileSync(agentsMdPath, 'utf-8'),\n        mimeType: 'text/markdown',\n      }],\n    }),\n  );\n\n  // 2. Root application schema\n  const appSchemaPath = resolve(schemaDir, 'jambonz-app.schema.json');\n  server.resource(\n    'app-schema',\n    'jambonz://schema/jambonz-app',\n    {\n      description: 'Root JSON Schema for a jambonz application — an array of verbs',\n      mimeType: 'application/schema+json',\n    },\n    async (uri) => ({\n      contents: [{\n        uri: uri.href,\n        text: readFileSync(appSchemaPath, 'utf-8'),\n        mimeType: 'application/schema+json',\n      }],\n    }),\n  );\n\n  // 3. Verb schemas\n  const verbsDir = resolve(schemaDir, 'verbs');\n  const verbFiles = readdirSync(verbsDir).filter((f) => f.endsWith('.schema.json'));\n\n  for (const file of verbFiles) {\n    const verbName = basename(file, '.schema.json');\n    const filePath = resolve(verbsDir, file);\n\n    server.resource(\n      `verb-${verbName}`,\n      `jambonz://schema/verbs/${verbName}`,\n      {\n        description: `JSON Schema for the \"${verbName}\" verb`,\n        mimeType: 'application/schema+json',\n      },\n      async (uri) => ({\n        contents: [{\n          uri: uri.href,\n          text: readFileSync(filePath, 'utf-8'),\n          mimeType: 'application/schema+json',\n        }],\n      }),\n    );\n  }\n\n  // 4. Component schemas\n  const componentsDir = resolve(schemaDir, 'components');\n  const componentFiles = readdirSync(componentsDir).filter((f) => f.endsWith('.schema.json'));\n\n  for (const file of componentFiles) {\n    const componentName = basename(file, '.schema.json');\n    const filePath = resolve(componentsDir, file);\n\n    server.resource(\n      `component-${componentName}`,\n      `jambonz://schema/components/${componentName}`,\n      {\n        description: `JSON Schema for the \"${componentName}\" component`,\n        mimeType: 'application/schema+json',\n      },\n      async (uri) => ({\n        contents: [{\n          uri: uri.href,\n          text: readFileSync(filePath, 'utf-8'),\n          mimeType: 'application/schema+json',\n        }],\n      }),\n    );\n  }\n}\n"],"mappings":"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","names":["server"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jambonz/mcp-schema-server",
+  "version": "0.1.0",
+  "description": "MCP server that provides jambonz verb schemas and documentation as resources",
+  "author": "Dave Horton",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jambonz/agent-toolkit.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://github.com/jambonz/agent-toolkit#readme",
+  "keywords": ["jambonz", "mcp", "model-context-protocol", "schema", "voip", "ai-agent"],
+  "type": "module",
+  "bin": {
+    "jambonz-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepack": "cp -r ../schema . && cp ../AGENTS.md .",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "zod": "^3.25.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/schema/components/actionHook.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/actionHook",
+  "title": "ActionHook",
+  "description": "A webhook or websocket callback that jambonz invokes during call processing. Most jambonz verbs use actionHooks to report results (e.g. speech recognition results from 'gather') and to receive the next set of verbs to execute. Can be specified as a simple URL string or as an object with additional options.",
+  "oneOf": [
+    {
+      "type": "string",
+      "format": "uri",
+      "description": "A URL to invoke. For webhook applications this is an HTTP(S) URL. For websocket applications this is typically a relative path or event name.",
+      "examples": ["https://myapp.example.com/gather-result", "/gather-result"]
+    },
+    {
+      "type": "object",
+      "description": "A hook specification with URL and additional options.",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The URL to invoke."
+        },
+        "method": {
+          "type": "string",
+          "description": "The HTTP method to use. Only applies to webhook applications.",
+          "enum": ["GET", "POST"],
+          "default": "POST"
+        },
+        "basicAuth": {
+          "$ref": "auth",
+          "description": "Basic authentication credentials to include in the request."
+        }
+      },
+      "required": ["url"]
+    }
+  ]
+}

package/schema/components/actionHookDelayAction.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/actionHookDelayAction",
+  "title": "ActionHookDelayAction",
+  "description": "Configuration for what to do when an actionHook (webhook) takes a long time to respond. Allows playing interim content (e.g. 'please wait' messages, hold music) while waiting for the webhook response, with configurable retry and give-up behavior.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether to enable delay handling for actionHooks."
+    },
+    "noResponseTimeout": {
+      "type": "number",
+      "description": "Time in seconds to wait before executing the delay actions. If the webhook responds before this timeout, the delay actions are skipped.",
+      "examples": [3, 5]
+    },
+    "noResponseGiveUpTimeout": {
+      "type": "number",
+      "description": "Total time in seconds to wait for a webhook response before giving up and executing the giveUpActions.",
+      "examples": [30, 60]
+    },
+    "retries": {
+      "type": "number",
+      "description": "Number of times to retry the delay actions while still waiting for the webhook response."
+    },
+    "actions": {
+      "type": "array",
+      "description": "An array of jambonz verbs to execute while waiting for the webhook response. Typically 'say' or 'play' verbs with messages like 'please hold'.",
+      "items": { "type": "object" }
+    },
+    "giveUpActions": {
+      "type": "array",
+      "description": "An array of jambonz verbs to execute if the webhook never responds within the giveUpTimeout. Typically an error message and/or hangup.",
+      "items": { "type": "object" }
+    }
+  }
+}

package/schema/components/auth.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/auth",
+  "title": "Auth",
+  "description": "Basic authentication credentials, used for authenticating with external services such as websocket endpoints or SIP registrars.",
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string",
+      "description": "The username for authentication."
+    },
+    "password": {
+      "type": "string",
+      "description": "The password for authentication."
+    }
+  },
+  "required": ["username", "password"]
+}

package/schema/components/bidirectionalAudio.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/bidirectionalAudio",
+  "title": "BidirectionalAudio",
+  "description": "Configuration for bidirectional audio streaming over a websocket connection. When enabled, the remote websocket endpoint can send audio back to jambonz to be played to the caller.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether to enable bidirectional audio on the websocket connection."
+    },
+    "streaming": {
+      "type": "boolean",
+      "description": "If true, audio is streamed continuously rather than sent as complete messages."
+    },
+    "sampleRate": {
+      "type": "number",
+      "description": "The sample rate in Hz for bidirectional audio.",
+      "examples": [8000, 16000, 24000]
+    }
+  }
+}

package/schema/components/fillerNoise.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/fillerNoise",
+  "title": "FillerNoise",
+  "description": "Configuration for playing background filler noise (e.g. keyboard typing, hold music) while the application is processing and the caller would otherwise hear silence. Commonly used during LLM response generation to indicate the system is working.",
+  "type": "object",
+  "properties": {
+    "enable": {
+      "type": "boolean",
+      "description": "Whether to enable filler noise."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the audio file to play as filler noise. Should be a short, loopable audio clip.",
+      "examples": ["https://example.com/sounds/typing.wav"]
+    },
+    "startDelaySecs": {
+      "type": "number",
+      "description": "Number of seconds to wait before starting filler noise. Prevents filler noise from playing during brief processing pauses.",
+      "examples": [1, 2]
+    }
+  },
+  "required": ["enable"]
+}