@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

package/skills/trtc-ai-service/references/business-contract-spec.md

@@ -0,0 +1,263 @@
+# `business_contract` Field Specification (v1.0)
+
+> Scope: the `business_contract` section in `capabilities/<name>/manifest.yaml`.
+>
+> Purpose: enable capability packages to **structurally** declare the business interface contracts they call / are called by,
+> so that `scripts/contract-adapt.py` (Phase 3 Stage 4) can generate executable adapters based on them,
+> and the assembly guide (Path A / Path B) can proactively list the contract manifest at the end.
+
+---
+
+## 1. Top-Level Structure
+
+```yaml
+business_contract:
+  port_class: "<dotted.path>"             # Full dotted path to ABC abstract base class
+  default_adapter: "<dotted.path>"        # Default implementation (production)
+  mock_adapter: "<dotted.path>"           # Mock implementation (demo / video recording)
+  external_apis:                          # outbound / inbound interface contract list
+    - <ExternalApi>
+  customization_sop: "INTERFACE_ADAPT.md" # Path to interface adaptation SOP (relative to capability root)
+```
+
+**Special case**: `tool-calling` does not use the port/adapter abstraction; it uses the alpha/beta dual-track contract section defined in §5 instead.
+
+---
+
+## 2. `external_apis[]` Field Definition
+
+```yaml
+- name: <string>                  # Contract name (snake_case dot-delimited), globally unique
+  direction: outbound | inbound   # outbound = we call the business side; inbound = business side calls back to us
+  method: GET | POST | PUT | DELETE | PATCH
+  path: <string>                  # Path template, may contain {placeholder}
+  description: <string>           # One-line description (for assembly wrap-up printing)
+  request_schema:                 # Request schema (simplified JSON Schema)
+    <field>: <type | enum[...] | object | array>
+  response_schema:                # Response schema
+    <field>: <type | enum[...] | object | array>
+  adapter_slots:                  # Field paths allowed for user remapping (dot-delimited)
+    - <request|response>.<field-path>
+  auth:                           # (optional) Auth method
+    type: bearer | api_key | none
+    location: header | query
+    name: <header-name | query-key>
+  retry:                          # (optional) Retry policy
+    max: <int>
+    backoff_ms: <int>
+  timeout_ms: <int>               # (optional) Timeout
+```
+
+### 2.1 `type` Value Convention
+
+| Type | Meaning |
+|---|---|
+| `string` | String |
+| `int` / `integer` | Integer |
+| `float` / `number` | Float |
+| `bool` / `boolean` | Boolean |
+| `string[]` / `int[]` / `<T>[]` | Homogeneous array |
+| `enum[a, b, c]` | Enum literal |
+| `object` | Nested object (can be further expanded as sub-schema) |
+| Nested dict | Write nested structure directly |
+
+### 2.2 `adapter_slots` Field Path Rules
+
+- Starts with `request.` or `response.`
+- Nested levels use dot separation: `response.data.ticket_id`
+- Arrays use `[]`: `request.transcript[]`
+- Only lists fields **allowed for user remapping**; unlisted fields are treated as "our contract is fixed, user modification forbidden"
+
+### 2.3 Special Nature of `direction = inbound`
+
+An inbound contract means "the business side calls back to us", in which case:
+- `path` is the endpoint we expose (e.g.: `/api/v1/handoff/callback/ticket-status`)
+- `request_schema` is the payload structure sent by the business side
+- `response_schema` is the ack structure we return (typically `{code: int, message: string}`)
+- `adapter_slots` declares "business side field names may differ from our expectations", used by contract-adapt to generate inbound field mappers
+
+---
+
+## 3. Naming Conventions
+
+| Element | Rule | Example |
+|---|---|---|
+| `name` | `<domain>.<action>` snake_case | `ticket.create`, `faq.search`, `crm.write` |
+| `port_class` | `src.ports.<file>.<ClassName>` | `src.ports.handoff_client.HandoffClient` |
+| `default_adapter` / `mock_adapter` | `src.adapters.<file>.<ClassName>` | `src.adapters.local_queue.LocalQueueHandoffClient` |
+
+---
+
+## 4. Full Example: `human-handoff`
+
+```yaml
+business_contract:
+  port_class: "src.ports.handoff_client.HandoffClient"
+  default_adapter: "src.adapters.local_queue.LocalQueueHandoffClient"
+  mock_adapter: "src.adapters.mock.MockHandoffClient"
+  customization_sop: "INTERFACE_ADAPT.md"
+  external_apis:
+    - name: ticket.create
+      direction: outbound
+      method: POST
+      path: /tickets
+      description: "Create a new ticket in the ticketing system when user triggers handoff"
+      request_schema:
+        user_id: string
+        subject: string
+        description: string
+        priority: enum[low, normal, high, urgent]
+        transcript: string[]
+      response_schema:
+        ticket_id: string
+        queue_position: int
+        eta_seconds: int
+      adapter_slots:
+        - request.subject
+        - request.priority
+        - response.ticket_id
+        - response.queue_position
+        - response.eta_seconds
+      auth:
+        type: bearer
+        location: header
+        name: Authorization
+      timeout_ms: 5000
+
+    - name: ticket.status_query
+      direction: outbound
+      method: GET
+      path: /tickets/{ticket_id}
+      description: "Poll ticket status for queue progress updates"
+      request_schema:
+        ticket_id: string
+      response_schema:
+        ticket_id: string
+        status: enum[pending, processing, closed, canceled]
+        agent_id: string
+        updated_at: int
+      adapter_slots:
+        - response.status
+        - response.agent_id
+      timeout_ms: 3000
+
+    - name: ticket.cancel
+      direction: outbound
+      method: POST
+      path: /tickets/{ticket_id}/cancel
+      description: "Notify ticketing system when user cancels handoff"
+      request_schema:
+        ticket_id: string
+        reason: string
+      response_schema:
+        ticket_id: string
+        canceled: bool
+      adapter_slots:
+        - request.reason
+      timeout_ms: 3000
+
+    - name: ticket.status_callback
+      direction: inbound
+      method: POST
+      path: /api/v1/handoff/callback/ticket-status
+      description: "Callback from ticketing system to notify status changes (optional; when disabled, status_query polling is used instead)"
+      request_schema:
+        ticket_id: string
+        status: enum[pending, processing, closed, canceled]
+        agent_id: string
+      response_schema:
+        code: int
+        message: string
+      adapter_slots:
+        - request.status
+        - request.agent_id
+```
+
+---
+
+## 5. `tool-calling` Exclusive Contract Section (replaces §1 port/adapter triple)
+
+```yaml
+business_contract:
+  alpha_track:                          # Alpha track: local function registration spec
+    interface: "src.ports.local_tool.LocalTool"
+    registration_schema:
+      name: string                     # Tool name (globally unique)
+      description: string
+      parameters: object               # JSON Schema describing parameter structure
+      handler: callable                # Function object (runtime-only)
+    invocation_schema:
+      input: object                    # Same schema as parameters
+      output: object                   # User-defined return structure
+    fail_fast: bool                    # Default true: local exceptions thrown immediately for arbitration decisions
+
+  beta_track:                           # Beta track: remote business API integration spec
+    interface: "src.ports.remote_tool.RemoteToolClient"
+    api_schema:
+      method: enum[GET, POST, PUT, DELETE, PATCH]
+      path: string
+      request_schema: object
+      response_schema: object
+      auth: enum[bearer, api_key, none]
+    timeout_ms: 5000
+    retry: { max: 1, backoff_ms: 200 }
+
+  arbitration:                          # Arbitration rules
+    default_priority: enum[alpha, beta, manifest_order]
+    fallback_on_failure: bool
+    timeout_ms: int                     # Single-track call timeout; triggers fallback on expiry
+    merge_strategy: enum[first_success, alpha_then_beta_diff]
+```
+
+`merge_strategy` values:
+
+| Value | Behavior |
+|---|---|
+| `first_success` | Return immediately on priority track success; backup track not called (default) |
+| `alpha_then_beta_diff` | Both tracks called; diff log recorded when results differ (for canary comparison) |
+
+---
+
+## 6. How `contract-adapt.py` Consumes This Field
+
+1. Read `business_contract.external_apis[].request_schema` / `response_schema`
+2. Parse user-submitted curl / OpenAPI, extract the user API's schema
+3. Compare against `adapter_slots` list to generate field mapping `mapping.yaml`
+4. Render adapter template (inheriting `port_class`), output to `src/adapters/user_custom.py`
+5. Three-level degradation:
+   - **L1**: Only `adapter_slots` field differences → fully executable adapter
+   - **L2**: Schema nesting or type differences exist → adapter template + TODO comments
+   - **L3**: Protocol-level differences (webhook / MQ / gRPC) or parse failure → output corresponding `INTERFACE_ADAPT.md` section path
+
+---
+
+## 7. Validation Rules (mandatory at resolver stage)
+
+| Rule | Error Code | Behavior |
+|---|---|---|
+| `port_class` / `default_adapter` / `mock_adapter` any not importable | `BC001` | Resolve failure, block install |
+| `external_apis[].name` duplicate | `BC002` | Same as above |
+| `direction = outbound` without `method` or `path` | `BC003` | Same as above |
+| `adapter_slots` path not found in `request_schema` / `response_schema` | `BC004` | Warning only, does not block |
+| `tool-calling.arbitration.default_priority` invalid value | `BC005` | Resolve failure |
+| `auth.type = bearer` but no env variable source declared | `BC006` | Warning only |
+
+Implementation location: `scripts/lib/contract_resolver.py` (Phase 3 Stage 4 implementation).
+In Phase 1, only the field definitions are agreed upon; resolver validation will be implemented in Stage 4.
+
+---
+
+## 8. Relationship with Existing Manifest Fields
+
+- `business_contract` and existing `extensions` / `endpoints` / `integration` fields **do not affect each other**; can be independently added/removed
+- `endpoints` describes "the REST endpoints we expose to the frontend / user"
+- `business_contract.external_apis` describes "the interfaces we call / are called back by the business side"
+- Both coexist without conflict, serving different consumers (frontend / Agent / business side)
+
+---
+
+## 9. Version Compatibility
+
+- Current spec version: `v1.0`
+- No forward compatibility; if a future breaking change is needed, it will be marked with a `business_contract.spec_version: "2.0"` field
+- The resource resolver (`manifest_resolver.py`) currently ignores unknown fields; adding this field will not break existing Phase 1/2 functionality

package/skills/trtc-ai-service/scenarios/custom-builder/README.md

@@ -0,0 +1,86 @@
+# scenarios/custom-builder —— Path B Custom Flow
+
+> Companion doc: repo root `SKILL.md` (Path B SOP §6).
+
+This directory contains all artifacts for **Path B** ("Custom"). It has **no executable scripts** —
+the 4-round Q&A is entirely facilitated by the Coding Agent using `ask_followup_question`.
+This directory provides only two types of static materials:
+
+```
+scenarios/custom-builder/
+├── README.md                              ← This file
+├── prompts/                               ← Question templates for AI (does not modify user's project)
+│   ├── q1-business-scenario.md            ←  Q1: Business description (free text)
+│   ├── q2-io-modality.md                  ←  Q2: I/O modality (4 choose 1)
+│   ├── q3-ui-form.md                      ←  Q3: UI form (3 choose 1)
+│   └── q4-capabilities.md                 ←  Q4: Capability selection (multi-select; defaults to none)
+└── output-templates/
+    └── recipe.yaml.j2                     ← AI rendering artifact template (output to <workspace>/recipe.yaml)
+```
+
+---
+
+## AI Execution Flow (aligned with SKILL.md §6)
+
+| Step | Tool | Source |
+|---|---|---|
+| 6.1 | `ask_followup_question` (free text) | `prompts/q1-business-scenario.md` |
+| 6.2 | `ask_followup_question` (single-select 4 items) | `prompts/q2-io-modality.md` |
+| 6.3 | `ask_followup_question` (single-select 3 items) | `prompts/q3-ui-form.md` |
+| 6.4 | `ask_followup_question` (multi-select 4 items) | `prompts/q4-capabilities.md` |
+| 6.5 | `write_to_file` render `recipe.yaml` | `output-templates/recipe.yaml.j2` |
+| 6.6 | `execute_command("python3 scripts/add-capability.py <Q4 selections> --apply --json")` | Q4 selections; skip if none |
+| 6.7 | Remaining steps same as Path A (§7 Keys → §8 Contract → §9 Launch) | SKILL.md |
+
+---
+
+## Constraints / Red Lines
+
+- **No builder.py**: The 4-round Q&A is **entirely** facilitated by AI; do not turn this into a local script (the user experience would drop out of the chat window)
+- **No manifest.yaml generation**: Each capability already has its own `manifest.yaml`; Path B does not need to regenerate
+- **prompts/q*.md are static materials**: AI **reads** them only; no content modification / re-formatting
+- **recipe.yaml.j2 uses Jinja2 syntax**: But the AI does not need to actually invoke a Jinja2 interpreter; it can do string replacement mentally and then `write_to_file` the final yaml. The template is just a **structural contract** for the AI
+
+---
+
+## After Collecting All Answer Variables, AI Constructs This Context
+
+```python
+context = {
+    # Q1
+    "business_desc": "<user's original text>",
+    "business_name": "<optional; defaults to 'we' if user didn't specify>",
+
+    # Q2 option → internal enum
+    "io_modality": "text_with_tts",     # text_only | text_with_tts | omni | voice_only
+
+    # Q3 option → internal enum
+    "ui_form": "floating",              # floating | fullscreen | headless
+
+    # Q4 user-selected capability array
+    "extra_capabilities": [             # any subset; empty array installs skeleton only
+        "knowledge-base",
+        "human-handoff",
+        # "tool-calling",
+        # "session-summary",
+    ],
+
+    # Meta info (AI fills in)
+    "render_time": "<ISO 8601>",
+    "rendered_by": "Coding Agent",
+}
+```
+
+Feed this to `output-templates/recipe.yaml.j2` to get the customized `<workspace>/recipe.yaml`.
+
+---
+
+## Differences from Path A (reference table)
+
+| Dimension | Path A | Path B |
+|---|---|---|
+| Entry | "Build me an AI customer service agent with TRTC" | Same, SKILL.md §4 choose B |
+| Installed capabilities | Default `knowledge-base + human-handoff` | Default none; user selects via Q4 |
+| Business prompt | Just ask "describe your business" before launch | Q1 is required (more explicit) |
+| UI | Floating widget + ticket dashboard (default) | Controlled by Q3: floating / fullscreen / headless |
+| recipe.yaml location | `scenarios/customer-service/recipe.yaml` (static in repo) | `<workspace>/recipe.yaml` (generated each time; can be manually edited and re-installed) |

package/skills/trtc-ai-service/scenarios/custom-builder/output-templates/recipe.yaml.j2

@@ -0,0 +1,194 @@
+{# =========================================================================
+   Path B Custom Recipe Render Template (Jinja2)
+
+   Output: <workspace>/recipe.yaml
+   Input (collected by AI in Q1~Q4):
+     business_desc       string    Q1 user answer (required, raw text)
+     business_name       string    Optional (default "Our Company")
+     io_modality         enum      Q2 option → internal enum:
+                                     text_only | text_with_tts | omni | voice_only
+     ui_form             enum      Q3 option → floating | fullscreen | headless
+     extra_capabilities  list      Q4 selected subset; values:
+                                     knowledge-base | human-handoff | tool-calling | session-summary
+
+   AI rendering notes:
+     - Do not push rendering logic down to Python; prefer the AI to perform string replacement / Jinja eval
+       mentally, then write the final recipe.yaml all at once with write_to_file
+     - If a boolean field cannot be mapped (vague user answer), fallback to the defaults below and confirm with the user
+========================================================================= #}
+# =====================================================================
+# Path B Custom Recipe — {{ business_name | default("Our Company") }} AI Customer Service
+#
+# Generated by SKILL.md §7 flow + custom-builder/output-templates/recipe.yaml.j2
+# Render time: {{ render_time | default("(AI writes ISO timestamp)") }}
+# Rendered by: {{ rendered_by | default("Coding Agent") }}
+# =====================================================================
+apiVersion: ai-customer-service/v1
+kind: Recipe
+metadata:
+  name: customer-service-custom
+  scenario: customer-service
+  source: custom-builder
+  version: "1.0.0"
+  description: "Generated from Path B 4-round Q&A; can be manually edited and reassembled"
+
+# ---------------------------------------------------------------------------
+# Q1: Business description (drives system prompt rendering)
+# ---------------------------------------------------------------------------
+agent_runtime:
+  language: "{{ language | default('en') }}"
+  voice_id: "{{ voice_id | default('') }}"
+  greeting: "{{ greeting | default('Hello, this is the AI customer service for ' ~ (business_name | default('Our Company')) ~ '. How can we help you?') }}"
+  max_idle_time: 60
+  system_prompt:
+    template_file: "../customer-service/system-prompt.template.md"
+    variables:
+      business_desc: |
+        {{ business_desc | trim | replace('\n', '\n        ') }}
+      business_name: "{{ business_name | default('Our Company') }}"
+
+# ---------------------------------------------------------------------------
+# Q2: I/O Modality
+# ---------------------------------------------------------------------------
+runtime_modality:
+  preset: "{{ io_modality }}"     # text_only | text_with_tts | omni | voice_only
+{%- if io_modality == "text_only" %}
+  voice_input: false
+  voice_output: false
+  text_input: true
+  text_output: true
+{%- elif io_modality == "text_with_tts" %}
+  voice_input: false
+  voice_output: true
+  text_input: true
+  text_output: true
+{%- elif io_modality == "omni" %}
+  voice_input: true
+  voice_output: true
+  text_input: true
+  text_output: true
+{%- elif io_modality == "voice_only" %}
+  voice_input: true
+  voice_output: true
+  text_input: false
+  text_output: false
+{%- else %}
+  # Unknown modality enum; fallback to text_with_tts
+  voice_input: false
+  voice_output: true
+  text_input: true
+  text_output: true
+{%- endif %}
+
+# ---------------------------------------------------------------------------
+# Q3: UI Form
+#
+# UI base notes (important):
+#   widget-floating has been upgraded to a "real connection" implementation — it reuses
+#   conversation-core's TRTC + agent/start pipeline via agent-link.js; AI replies come
+#   from LLM subtitle stream, and capabilities (handoff / tools / summaries) are
+#   dynamically mounted based on actual backend enablement.
+#   (The old hardcoded IM approach is deprecated; always include agent-link.js when
+#   overlaying the widget-floating directory.)
+#
+#   B2 custom UI: The AI takes the widget-floating "real connection base" and generates
+#   a customized skin (business panel / copy / token values) based on the user's business
+#   info and color preferences. The core pipeline is unchanged, ensuring the AI is always
+#   genuinely connected and satisfies design-system hard constraints (fonts / icons /
+#   no emoji / via tokens).
+# ---------------------------------------------------------------------------
+ui:
+  form: "{{ ui_form }}"           # floating | fullscreen | headless
+{%- if ui_form == "headless" %}
+  overlay_required: false
+  ui_overlay: null
+{%- else %}
+  overlay_required: true
+  ui_overlay:
+    source_root: "scenarios/customer-service/ui"
+    target: "capabilities/conversation-core/web-demo"
+    layers:
+      - source: "widget-floating"
+        target: "."
+        replace: true
+{%- if "human-handoff" in extra_capabilities %}
+      - source: "admin-board"
+        target: "admin"
+        replace: true
+{%- endif %}
+{%- if ui_form == "fullscreen" %}
+    layout_hint: "fullscreen"     # 浮窗模板 + body 上挂 fullscreen class（CSS 强制铺满）
+{%- endif %}
+{%- endif %}
+
+# ---------------------------------------------------------------------------
+# Q4: Capabilities Checklist
+# Assembly command (AI executes in §7.3):
+#   python3 scripts/add-capability.py {{ extra_capabilities | join(' ') }} --apply --json
+# Skip assembly when extra_capabilities is empty
+# ---------------------------------------------------------------------------
+capabilities:
+  required:
+    - name: conversation-core
+      role: skeleton
+  install:
+{%- for cap in extra_capabilities %}
+{%- if cap == "knowledge-base" %}
+    - name: knowledge-base
+      role: capability
+      adapter: mock                # Default mock; switch to local_json or default_rest before launch
+      env:
+        KB_ADAPTER: mock
+        KB_TOP_K: "3"
+        KB_MIN_SCORE: "0.1"
+{%- elif cap == "human-handoff" %}
+    - name: human-handoff
+      role: capability
+      adapter: local_queue         # Default local queue; switch to default_rest to connect to real ticketing system
+      env:
+        HH_ADAPTER: local_queue
+{%- elif cap == "tool-calling" %}
+    - name: tool-calling
+      role: capability
+      # For tool-calling alpha/beta dual-track details, see capabilities/tool-calling/INTERFACE_ADAPT.md
+{%- elif cap == "session-summary" %}
+    - name: session-summary
+      role: capability
+      # Depends on LLM_API_KEY; ensure §5 LLM Key configuration is complete
+{%- endif %}
+{%- endfor %}
+{%- if not extra_capabilities %}
+    []                             # No capability selected; install skeleton only
+{%- endif %}
+  optional: []
+  excluded:
+    - name: digital-human          # Not in current scope
+
+# ---------------------------------------------------------------------------
+# Post-launch must-do: contract checklist reminder (see SKILL.md §9)
+# ---------------------------------------------------------------------------
+post_assembly:
+  contract_review:
+    enabled: true
+    capabilities:
+{%- for cap in extra_capabilities %}
+      - "{{ cap }}"
+{%- endfor %}
+{%- if not extra_capabilities %}
+      []
+{%- endif %}
+    sop_section: "SKILL.md#8"
+  health_check:
+    url: "http://localhost:3000/api/v1/health"
+    expect_field: "status"
+    expect_value: "ok"
+
+# ---------------------------------------------------------------------------
+# Design language lock (consistent with Path A)
+# ---------------------------------------------------------------------------
+design:
+  tokens_file: "../../design_tokens.json"
+  guidelines: "../customer-service/ui/design-system/DESIGN_GUIDELINES.md"
+  theme: "dark"
+  emoji_in_ui: false
+  font_family: "SF Pro, Inter, 'Helvetica Neue', sans-serif"

package/skills/trtc-ai-service/scenarios/custom-builder/prompts/q1-business-scenario.md

@@ -0,0 +1,43 @@
+# Q1 —— Business Description (free text)
+
+> Path B Question 1. AI uses `ask_followup_question` as a standalone question, **without options**, letting the user type freely.
+>
+> AI saves the user's answer to the internal variable `business_desc`, for later use in:
+> 1. Rendering `{{business_desc}}` in `scenarios/customer-service/system-prompt.template.md`
+> 2. Writing to `<workspace>/recipe.yaml` at `agent_runtime.system_prompt.variables.business_desc`
+>
+> AI must **not** guess the industry; leave unsaid fields blank and backfill after Q4.
+
+---
+
+## What the AI should say
+
+> Question 1 (of 4): What business is your customer service bot for?
+> Just describe the **business scope** and **typical questions** in a sentence or two. For example:
+>
+> - "We are an e-commerce store selling smart home appliances — air fryers, robot vacuums, humidifiers. Users usually ask about warranty, returns, and shipping."
+> - "I run customer support for a SaaS HR platform. Common issues are login failures, org structure sync, and plan upgrades."
+> - "A restaurant delivery service. Users mainly ask about order status, refunds, menu stock, and delivery fees."
+>
+> The more specific your business, the better the final system prompt will match your real scenario.
+
+---
+
+## Validation after receiving the answer
+
+- Length ≥ 8 and ≤ 600 characters. If too short, follow up: "That's quite brief — could you add a bit more about typical issues or industry keywords?"
+- Must contain at least one noun phrase (industry name, product name, user type); pure interjections or casual chat → **re-ask**
+- Do not ask the user to provide brand name / company name (if needed, the template uses placeholder `{{business_name | default('we')}}`)
+
+---
+
+## Answer write-back
+
+```yaml
+# Render to <workspace>/recipe.yaml
+agent_runtime:
+  system_prompt:
+    variables:
+      business_desc: |
+        <user's original text>
+```

package/skills/trtc-ai-service/scenarios/custom-builder/prompts/q2-io-modality.md

@@ -0,0 +1,57 @@
+# Q2 —— I/O Modality (4 choose 1)
+
+> Path B Question 2. AI uses `ask_followup_question` in **single-select** mode.
+>
+> Answer written to internal variable `io_modality` (mapped to English enums in the table below), later used to:
+> 1. Determine whether `agent_runtime.greeting` uses TTS audio
+> 2. Set conversation-core `io_modality.*.enabled` fields
+> 3. Decide whether the floating widget UI exposes a microphone button
+
+---
+
+## What the AI should say (recommend copy-pasting directly into ask_followup_question)
+
+> Question 2: What I/O modality should be used between end users and the AI agent?
+
+`options` (keep order; order corresponds one-to-one with enums below):
+
+```text
+① Text-only IM (user types → AI replies in text; no voice)
+② Text + TTS (user types → AI replies in text + reads aloud, recommended)
+③ Omni-modal (voice + text, bidirectional; user can also speak)
+④ Voice-only call (user dials → AI answers → full voice; no demo UI in this release)
+```
+
+`multiSelect: false`
+
+---
+
+## Option → Backend Config Mapping
+
+| User Option | Internal Enum (`io_modality`) | conversation-core io_modality Config | UI Impact |
+|---|---|---|---|
+| ① Text-only | `text_only` | voice_input=disabled, voice_output=disabled | Widget shows input box only; mic hidden |
+| ② Text + TTS (recommended) | `text_with_tts` | voice_input=disabled, voice_output=enabled (trtc-tts) | Widget shows input box + "read aloud" toggle; mic hidden |
+| ③ Omni-modal | `omni` | voice_input=enabled (trtc-asr), voice_output=enabled | Widget shows input box + mic (push-to-talk) |
+| ④ Voice-only call | `voice_only` | voice_input=enabled, voice_output=enabled, text_input=disabled | No UI; backend phone gateway only (no floating widget in this release) |
+
+---
+
+## Validation / Fallback
+
+- User picks ④ but Q3 picks "floating" → warn about conflict, guide user to change Q3 to "headless"
+- User picks ② / ③ but LLM verification fails → save the choice, still write to recipe per user's intent; after launch, the widget will show "voice output depends on TTS key, currently unavailable"
+
+---
+
+## Answer write-back
+
+```yaml
+# Render to <workspace>/recipe.yaml
+runtime_modality:
+  preset: text_with_tts          # From "Internal Enum" column above
+  voice_input: false
+  voice_output: true
+  text_input: true
+  text_output: true
+```