Merge branch 'main' into hey-august-patch-1

Author: hey-august

docker-compose.yml

@@ -0,0 +1,64 @@
+version: '3.9'
+
+services:
+  # TypeSense search server (ephemeral - no data persistence)
+  typesense:
+    image: typesense/typesense:29.0
+    container_name: typesense-local
+    ports:
+      - "8108:8108"
+    volumes:
+      - typesense-data:/data  # Named volume for ephemeral storage
+    command: '--data-dir /data --api-key=local-dev-api-key-12345 --enable-cors'
+    healthcheck:
+      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/localhost/8108 && printf 'GET /health HTTP/1.1\r\nConnection: close\r\n\r\n' >&3 && head -n1 <&3 | grep '200' && exec 3>&-"]
+      interval: 10s
+      timeout: 1s
+      retries: 5
+      start_period: 10s
+    networks:
+      - docs-network
+
+  # TypeSense documentation scraper
+  # NOTE: Requires local dev server running at localhost:3000 (run 'yarn start --host 0.0.0.0' first)
+  docs-scraper:
+    image: typesense/docsearch-scraper:0.9.1
+    container_name: docs-scraper
+    entrypoint: []  # Override default entrypoint to run custom setup
+    volumes:
+      - ./website:/tmp/search:ro
+    environment:
+      - TYPESENSE_API_KEY=local-dev-api-key-12345
+      - TYPESENSE_HOST=typesense
+      - TYPESENSE_PORT=8108
+      - TYPESENSE_PROTOCOL=http
+      - CONFIG=/tmp/typesense.local.json
+    depends_on:
+      typesense:
+        condition: service_healthy
+    # Auto-generate local config and scrape from host dev server
+    command: >
+      sh -c "
+        echo 'Generating typesense.local.json from typesense.json...' &&
+        sed -e 's|https\?://developer.signalwire.com|http://host.docker.internal:3000|g' /tmp/search/typesense.json > /tmp/typesense.local.json &&
+        echo 'Config generated. Waiting for local dev server at http://host.docker.internal:3000...' &&
+        until wget --spider --quiet http://host.docker.internal:3000 2>/dev/null; do
+          echo 'Dev server not ready yet, waiting 5s... (Make sure you run: yarn start)' &&
+          sleep 5;
+        done &&
+        echo 'Dev server is ready! Starting documentation scraper...' &&
+        pipenv run python -m src.index &&
+        echo 'Scraping complete! Search is now available at http://localhost:3000'
+      "
+    networks:
+      - docs-network
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+networks:
+  docs-network:
+    name: docs-local-network
+    driver: bridge
+
+volumes:
+  typesense-data:

package.json

@@ -12,6 +12,10 @@
     "serve": "yarn --cwd website serve",
     "start": "yarn --cwd website start",
     "start-fresh": "yarn --cwd website start-fresh",
+    "start:search": "TYPESENSE_HOST=localhost TYPESENSE_EXPORTS=8108 TYPESENSE_PROTOCOL=http TYPESENSE_API_SEARCH_KEY=local-dev-api-key-12345 TYPESENSE_COLLECTION_NAME=signalwire-docs yarn --cwd website start",
+    "search:up": "docker compose up -d",
+    "search:down": "docker compose down -v",
+    "search:logs": "docker compose logs -f",
     "build:website": "yarn --cwd website build",
     "build:specs": "yarn --cwd specs build",
     "build:tools": "yarn --cwd tools build",

specs/signalwire-rest/calling-api/calls/main.tsp

@@ -16,7 +16,7 @@ namespace CallingAPI.Calls {
   interface Calls {
     @summary("Send Call Commands")
     @doc("""
-    Unified OpenRPC-style endpoint for executing call methods through command-based dispatch.
+    Unified JSON-RPC style endpoint for executing call methods through command-based dispatch.
     Send a request with the appropriate `command` field to invoke the desired call operation.
     This endpoint provides a single interface for all call-related methods including creation, updates, termination, and AI conversation control.
     """)

specs/signalwire-rest/calling-api/calls/models/requests.tsp

@@ -50,7 +50,19 @@ model CallHoldRequest {
   command: "calling.ai_hold";
 
   @doc(paramsDescription)
-  params: {};
+  params: {
+    @doc("The duration to hold the caller in seconds.")
+    @example(300)
+    @maxValue(300)
+    timeout?: int32 = 300;
+
+    @doc("""
+      A system message added to the AI conversation before placing the caller on hold.
+      The AI will speak this message to the caller before hold music begins.
+      """)
+    @example("Please hold while I transfer you to a specialist.")
+    prompt?: string = "Tell the user you are putting them on hold.";
+  };
 }
 
 @summary("Unhold call")
@@ -64,7 +76,14 @@ model CallUnholdRequest {
   command: "calling.ai_unhold";
 
   @doc(paramsDescription)
-  params: {};
+  params: {
+    @doc("""
+      A system message added to the AI conversation when taking the caller off hold.
+      The AI will use this context when resuming the conversation.
+      """)
+    @example("The user has been connected to a specialist.")
+    prompt?: string = "The user has been taken off hold.";
+  };
 }
 
 @summary("Inject AI message")
@@ -202,7 +221,7 @@ model CallUpdateCurrentCallRequest {
 
 @discriminated(#{discriminatorPropertyName: "command", envelope: "none"})
 @doc("""
-Call request union for OpenRPC-style method dispatch. Use the `command` field to specify which call method to invoke:
+Call request union for JSON-RPC style method dispatch. Use the `command` field to specify which call method to invoke:
 
 - **`dial`** - Create and initiate a new outbound call to a destination. Returns immediately with call details while the call is being established in the background.
 

specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml

@@ -26,7 +26,7 @@ paths:
       operationId: call-commands
       summary: Send Call Commands
       description: |-
-        Unified OpenRPC-style endpoint for executing call methods through command-based dispatch.
+        Unified JSON-RPC style endpoint for executing call methods through command-based dispatch.
         Send a request with the appropriate `command` field to invoke the desired call operation.
         This endpoint provides a single interface for all call-related methods including creation, updates, termination, and AI conversation control.
       parameters: []
@@ -352,6 +352,21 @@ components:
           example: calling.ai_hold
         params:
           type: object
+          properties:
+            timeout:
+              type: integer
+              format: int32
+              maximum: 300
+              description: The duration to hold the caller in seconds.
+              example: 300
+              default: 300
+            prompt:
+              type: string
+              description: |-
+                A system message added to the AI conversation before placing the caller on hold.
+                The AI will speak this message to the caller before hold music begins.
+              example: Please hold while I transfer you to a specialist.
+              default: Tell the user you are putting them on hold.
           description: An object of parameters that will be utilized by the active command.
       title: Hold call
     CallRequest:
@@ -373,7 +388,7 @@ components:
           calling.ai_unhold: '#/components/schemas/CallUnholdRequest'
           calling.ai_message: '#/components/schemas/CallAIMessageRequest'
       description: |-
-        Call request union for OpenRPC-style method dispatch. Use the `command` field to specify which call method to invoke:
+        Call request union for JSON-RPC style method dispatch. Use the `command` field to specify which call method to invoke:
 
         - **`dial`** - Create and initiate a new outbound call to a destination. Returns immediately with call details while the call is being established in the background.
 
@@ -508,6 +523,14 @@ components:
           example: calling.ai_unhold
         params:
           type: object
+          properties:
+            prompt:
+              type: string
+              description: |-
+                A system message added to the AI conversation when taking the caller off hold.
+                The AI will use this context when resuming the conversation.
+              example: The user has been connected to a specialist.
+              default: The user has been taken off hold.
           description: An object of parameters that will be utilized by the active command.
       title: Unhold call
     CallUpdateCurrentCallRequest:

specs/signalwire-rest/fabric-api/ai-agent/models/ai/ai_params.tsp

@@ -11,16 +11,47 @@ enum Direction {
   outbound,
 }
 
+@summary("Conversation message role")
+enum ConversationRole {
+  @doc("A message from the user.")
+  user,
+
+  @doc("A message from the AI assistant.")
+  assistant,
+
+  @doc("A system message providing instructions or context.")
+  system,
+}
+
+@summary("Conversation message object")
+@doc("A message object representing a single turn in the conversation history.")
+model ConversationMessage {
+  @doc("The role of the message sender.")
+  role: ConversationRole;
+
+  @doc("The text content of the message.")
+  content: string;
+
+  @doc("Optional language code for the message (e.g., 'en', 'es', 'fr').")
+  lang?: string;
+}
+
 @summary("params object")
 model AIParams {
   @doc("Instructs the agent to acknowledge crosstalk and confirm user input when the user speaks over the agent.")
   acknowledge_interruptions?: boolean;
 
+  @doc("Sets the name the AI agent responds to for wake/activation purposes. When using `enable_pause`, `start_paused`, or `speak_when_spoken_to`, the user must say this name to get the agent's attention.")
+  ai_name?: string = "computer";
+
   @doc("Adjust the volume of the AI. Allowed values from `-50` - `50`.")
   @minValue(-50)
   @maxValue(50)
   ai_volume?: integer;
 
+  @doc("A custom identifier for the AI application instance. This name is included in webhook payloads.")
+  app_name?: string = "swml app";
+
   @doc("Amount of time, in ms, to wait before prompting the user to respond. Allowed values from `10,000` - `600,000`. Set to `0` to disable.")
   attention_timeout?: IntegerOrZero | 0;
 
@@ -57,6 +88,9 @@ model AIParams {
   @example("Place an order")
   conscience?: string;
 
+  @doc("Injects pre-existing conversation history into the AI session at startup. This allows you to seed the AI agent with context from a previous conversation or provide example interactions.")
+  convo?: ConversationMessage[];
+
   @doc("Used by `check_for_input` and `save_conversation` to identify an individual conversation.")
   @example("Conversation ID")
   conversation_id?: string;
@@ -70,6 +104,9 @@ model AIParams {
   @example("https://example.com")
   debug_webhook_url?: url;
 
+  @doc("Enables debug mode for the AI session.")
+  debug?: boolean | integer;
+
   @doc("Forces the direction of the call to the assistant. Valid values are `inbound` and `outbound`.")
   direction?: Direction[];
 
@@ -87,6 +124,15 @@ model AIParams {
   @maxValue(10000)
   end_of_speech_timeout?: integer;
 
+  @doc("Enables the inner dialog feature for background conversation analysis.")
+  enable_inner_dialog?: boolean = false;
+
+  @doc("Enables the pause/resume functionality for the AI agent.")
+  enable_pause?: boolean = false;
+
+  @doc("Enables intelligent turn detection that monitors partial speech transcripts.")
+  enable_turn_detection?: boolean = true;
+
   @doc("The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice.")
   eleven_labs_stability?: float;
 
@@ -110,6 +156,15 @@ model AIParams {
   @maxValue(3600000)
   inactivity_timeout?: integer;
 
+  @doc("Specifies the AI model to use for the inner dialog feature.")
+  inner_dialog_model?: string;
+
+  @doc("The system prompt that guides the inner dialog AI's behavior.")
+  inner_dialog_prompt?: string = "The assistant is intelligent and straightforward, does its job well and is not excessively polite.";
+
+  @doc("When enabled, synchronizes the inner dialog with the main conversation flow.")
+  inner_dialog_synced?: boolean = false;
+
   @doc("""
     Check for input function with check_for_input.
     Example use case: Feeding an inbound SMS to AI on a voice call, eg., for collecting an email address or other complex information.
@@ -130,18 +185,35 @@ model AIParams {
   @example("America/Ensenada")
   local_tz?: string;
 
+  @doc("Sets the maximum number of tokens the AI model can generate in a single response.")
+  @minValue(1)
+  @maxValue(16384)
+  max_response_tokens?: integer;
+
   @doc("Sets a time duration for the outbound call recipient to respond to the AI agent before timeout, in a range from `10000` to `600000`.")
   @minValue(10000)
   @maxValue(600000)
   outbound_attention_timeout?: integer;
 
+  @doc("When enabled, global_data persists across multiple AI agent invocations within the same call.")
+  persist_global_data?: boolean = true;
+
+  @doc("Specifies the output format for structured prompts. Valid values are `markdown` or `xml`.")
+  pom_format?: "markdown" | "xml" = "markdown";
+
   @doc("""
     Send a summary of the conversation after the call ends.
     This requires a `post_url` to be set in the ai parameters and the `conversation_id` defined below.
     This eliminates the need for a `post_prompt` in the ai parameters.
     """)
   save_conversation?: boolean;
 
+  @doc("When enabled, the AI agent remains silent until directly addressed by name.")
+  speak_when_spoken_to?: boolean = false;
+
+  @doc("When enabled, the AI agent starts in a paused state.")
+  start_paused?: boolean = false;
+
   @doc("Allows tweaking any of the indicated settings, such as `barge_match_string`, using the returned SWML from the SWAIG function.")
   swaig_allow_settings?: boolean;
 
@@ -151,12 +223,26 @@ model AIParams {
   @doc("Post entire conversation to any SWAIG call.")
   swaig_post_conversation?: boolean;
 
+  @doc("Controls whether SWML variables are included in SWAIG function webhook payloads.")
+  swaig_post_swml_vars?: boolean | string[];
+
   @doc("Pass a summary of a conversation from one AI agent to another. For example, transfer a call summary between support agents in two departments.")
   transfer_summary?: boolean;
 
+  @doc("Time in milliseconds to wait after detecting a potential end-of-turn before finalizing speech recognition.")
+  @minValue(0)
+  @maxValue(10000)
+  turn_detection_timeout?: integer = 250;
+
+  @doc("Configures Silero Voice Activity Detection (VAD) settings. Format: `threshold` or `threshold:frame_ms`. The threshold (0-100) sets sensitivity for detecting voice activity. The optional frame_ms (16-40) sets frame duration in milliseconds.")
+  vad_config?: string;
+
   @doc("Enable verbose logging.")
   verbose_logs?: boolean;
 
   @doc("When false, AI agent will initialize dialogue after call is setup. When true, agent will wait for the user to speak first.")
   wait_for_user?: boolean;
+
+  @doc("Specifies an additional prefix that must be spoken along with the agent's name to wake the agent.")
+  wake_prefix?: string;
 }

specs/signalwire-rest/fabric-api/ai-agent/models/ai/swaig/functions/data_map/actions/hangup.tsp

@@ -0,0 +1,6 @@
+@summary("HangupAction object")
+model HangupAction {
+  @doc("Whether to hang up the call. When set to `true`, the call will be terminated after the AI agent finishes speaking.")
+  @summary("hangup")
+  hangup: boolean;
+}

specs/signalwire-rest/fabric-api/ai-agent/models/ai/swaig/functions/data_map/actions/hold.tsp

@@ -0,0 +1,16 @@
+@summary("HoldAction object")
+model HoldAction {
+  @doc("""
+    Places the caller on hold while playing hold music (configured via params.hold_music).
+    During hold, speech detection is paused and the AI agent will not respond to the caller.
+    The value specifies the hold timeout in seconds.
+    Can be a number or an object with timeout property.
+    """)
+  @summary("hold")
+  @maxValue(900)
+  hold: int32 | {
+    @doc("The duration to hold the caller in seconds. Can be a number or an object with timeout property.")
+    @maxValue(900)
+    timeout?: int32 = 300;
+  };
+}

specs/signalwire-rest/fabric-api/ai-agent/models/ai/swaig/functions/data_map/actions/main.tsp

@@ -1,6 +1,8 @@
 import "./change_context.tsp";
 import "./change_step.tsp";
 import "./context_switch.tsp";
+import "./hangup.tsp";
+import "./hold.tsp";
 import "./playback_bg.tsp";
 import "./say.tsp";
 import "./set_global_data.tsp";
@@ -17,6 +19,8 @@ union Action {
   ChangeContextAction,
   ChangeStepAction,
   ContextSwitchAction,
+  HangupAction,
+  HoldAction,
   PlaybackBGAction,
   SayAction,
   SetGlobalDataAction,