callwright 1.0.0

package/docs/profile-learning-spec.md

@@ -0,0 +1,134 @@
+# Spec: let `learn` create (not just enrich) scenario profiles
+
+## Today
+
+`learn_from_call` can **enrich an existing** profile (append a `recommended_detail` when the
+agent had to defer on a recurring question) but **cannot create** a profile for an unmatched
+`call_type`. A genuinely new recurring scenario (e.g. `hotel_transport_inquiry`) runs fine
+**generically** but never gains a profile unless hand-authored.
+
+This spec adds **profile creation** — while guarding against the real failure mode:
+
+> **Profiles splintering into over-specific entries that bake in per-call parameters/values.**
+
+---
+
+## The one invariant that prevents splintering
+
+**A profile stores SCHEMA, never VALUES.**
+
+| | Lives in | Reusable? | Example |
+|---|---|---|---|
+| **Scenario** (`call_type`) | profile key + aliases | across all calls of this kind | `hotel_transport_inquiry` |
+| **Field to collect** (`recommended_details`) | profile | across all calls of this kind | `destination` |
+| **The actual value** (`scenario_details` / `principal.facts`) | the per-call job | NO — this call only | `destination = "Haneda"` |
+
+The codebase **already** separates these: `recommended_details` are field *keys* ("what to
+collect"); the values arrive per-call in `scenario_details`. Auto-creation must **preserve this
+invariant** — every guard below is in service of it.
+
+### The litmus test (apply to every creation/enrichment decision)
+
+> **"Would this help a *different* call of the same kind?"**
+>
+> - Reused field → `recommended_details` (schema) ✅
+> - One-call value → `scenario_details`/`facts` (parameter), **never** a profile field ❌
+> - Reused scenario → a `call_type` profile ✅
+> - One-off intent → just a generic call, **no profile** ❌
+
+If a candidate field or `call_type` fails this test, it is a **parameter or an instance**, not
+schema — reject it.
+
+---
+
+## Anti-splintering guards
+
+### 1. `call_type` must be a GENERAL scenario, not an instance
+Reject/normalize instance-shaped types that embed a value:
+- ✅ `hotel_transport_inquiry`, `restaurant_reservation`
+- ❌ `hotel_transport_to_haneda`, `friday_dinner_for_2`, `haircut_with_jenny`
+
+**Heuristic:** if the proposed `call_type` contains a proper noun, a number, a date, or a
+specific value (destination, name, party size), strip it to the general form and route the
+specific part into per-call grounding instead.
+
+### 2. Canonicalize before creating (prevent alias splintering)
+`hire_car`, `airport_transfer`, `haiya`, `car_service` must **not** spawn four profiles. Before
+creating, check whether the proposed type is semantically equivalent to an existing profile:
+- First the existing fuzzy match (name/alias contains).
+- Then an **LLM canonicalization** step: *"Is `<new_type>` the same scenario as any of
+  `<existing profile names>`? If yes, return which one."* If yes → **add as an alias**, do not
+  create.
+- **Merge-over-create bias:** creation is the last resort, only for genuinely novel scenarios.
+
+### 3. Fields must be GENERALIZED, never instance-valued
+When extracting a `recommended_detail` from a deferral:
+- ✅ "What's your destination?" → field `destination`
+- ❌ "Is your destination Haneda?" → field `destination_haneda`
+
+**Value-rejection guard:** reject any candidate field whose **key or description embeds a
+specific value** (proper noun / number / date / quoted string). Such a "field" is a value in
+disguise → it belongs in the job, not the profile.
+
+### 4. Promotion threshold (N ≥ 2) — don't mint from one call
+- A single occurrence of an unmatched `call_type` or an unanswered question → logged to a
+  **`candidates` staging area**, NOT promoted.
+- Only after the **same canonicalized scenario / field is seen ≥ N times** (default 2) does it
+  get promoted to a real profile / `recommended_detail`.
+- Rationale: a repeated gap is a real pattern; a one-off is noise. (Same guard discussed for
+  auto-learn generally.)
+
+### 5. Creation is a higher-stakes action than enrichment → gate it
+| Action | Stakes | Default handling |
+|---|---|---|
+| Append a field to an **existing** profile | low | auto (with N≥2) |
+| **Create a new** profile | high (grows the taxonomy) | **propose-and-confirm** — surface to the user/LLM with the proposed name + fields; create on approval |
+
+Enrichment can be autonomous; **creation should be proposed**, not silent, so a human/LLM keeps
+the taxonomy coherent.
+
+### 6. Periodic consolidation pass (taxonomy ceiling)
+A maintenance review (LLM or human) that:
+- merges near-duplicate profiles (e.g. `car_service` + `hotel_transport_inquiry`),
+- prunes `recommended_details` that turned out to be one-off values,
+- folds rarely-used profiles back into a more general one.
+Keeps the profile set **small and orthogonal** over time.
+
+---
+
+## Proposed mechanics
+
+1. **Staging store** (`scenario-candidates.json`, on the same volume): records unmatched
+   `call_type`s and unmapped deferred questions with occurrence counts + example call_ids.
+2. **On each `learn_from_call`:**
+   - Matched profile → enrich as today (existing path), with the value-rejection guard (#3).
+   - Unmatched `call_type` → canonicalize (#2). If it maps to an existing profile, **propose an
+     alias**. If genuinely novel, **increment its candidate count** (#4).
+3. **Promotion:** when a candidate crosses N, emit a **proposal** (new profile name +
+   generalized fields + suggested aliases) for confirmation (#5), then write it.
+4. **`list_scenarios`** (MCP) gains a view of pending candidates/proposals so the user/LLM can
+   approve, merge, or reject from chat.
+
+## What stays unchanged
+- The job schema (`scenario_details` for values, `principal.facts` for PII) — the value side.
+- Generic-agent behavior — unmatched scenarios always still work without a profile.
+- `recommended_details` remain field *keys* with human-readable descriptions (schema only).
+
+## Status
+**IMPLEMENTED & live (2026-06-28).** `learn-core.js` holds the deterministic anti-splintering
+heuristics; `learn.js` is a thin CLI over it. The MCP `learn_from_call` tool is rewired in-process:
+it ENRICHES a matched profile, or STAGES an unmatched (generalized) scenario as a candidate and emits
+a PROPOSAL once seen >= N (default 2). New tools: `list_candidates`, `create_profile`
+(propose-and-confirm; guards reject instance-shaped names #1, value-baked fields #3, and collisions
+#2→merge), `add_scenario_alias` (merge-don't-splinter), `reject_candidate`. `list_scenarios` surfaces
+pending candidates. Candidates persist in `scenario-candidates.json` on the volume.
+
+The LLM owns the JUDGMENT the spec reserves for it (canonicalize merge-vs-create, propose-and-confirm
+to the user); the code owns the deterministic heuristics + N≥2 staging. Creation is never silent.
+Covered by 15 `node:test` cases; full lifecycle (stage→proposal→create_profile→place_call matches the
+new profile→alias merge) verified locally; guards + tool wiring verified live on prod.
+
+What's NOT built from this spec: the periodic consolidation pass (#6) — left as a future maintenance
+tool (an LLM/human review that merges near-duplicate profiles + prunes one-off fields).
+
+### Original design notes (for reference)

package/examples/job.appointment-confirmation.json

@@ -0,0 +1,24 @@
+{
+  "call_type": "appointment_confirmation",
+  "target": {
+    "business_name": "Example Service Co",
+    "phone_number": "+15555550100"
+  },
+  "principal": {
+    "name": "Your Name",
+    "callback_number": "+15555550123",
+    "facts": {
+      "service_address": "123 Example St, Your City, ST 00000"
+    }
+  },
+  "request": {
+    "summary": "Confirm a service appointment",
+    "opening_ask": "I'm calling to confirm a service appointment. Could you help me with that?",
+    "preferred": { "date": "2026-07-03", "time": "09:00" }
+  },
+  "scenario_details": {
+    "service_type": "appliance repair",
+    "appointment_window": "9:00 AM to 1:00 PM on Friday"
+  },
+  "preferences": ["If no appointment is on file, ask them to check under the booking name."]
+}

package/examples/job.general-inquiry.ja.json

@@ -0,0 +1,16 @@
+{
+  "call_type": "general_inquiry",
+  "target": {
+    "business_name": "Example Hotel",
+    "phone_number": "+815555550100",
+    "timezone": "Asia/Tokyo"
+  },
+  "principal": {
+    "anonymous": true
+  },
+  "request": {
+    "summary": "Ask about fitness center hours",
+    "opening_ask": "フィットネスセンターの営業時間を伺えますでしょうか。",
+    "preferred": { "date": "2026-07-03", "time": "10:00" }
+  }
+}

package/examples/job.reservation.json

@@ -0,0 +1,19 @@
+{
+  "call_type": "restaurant_reservation",
+  "target": {
+    "business_name": "Example Bistro",
+    "phone_number": "+15555550100"
+  },
+  "principal": {
+    "name": "Your Name"
+  },
+  "request": {
+    "summary": "Dinner reservation for 2",
+    "opening_ask": "I'm calling to see if you have a table for two this Friday around 7 PM.",
+    "party_size": 2,
+    "preferred": { "date": "2026-07-03", "time": "19:00" }
+  },
+  "scenario_details": {
+    "occasion": "none"
+  }
+}

package/fly.toml

@@ -0,0 +1,35 @@
+# fly.toml app configuration file generated for virtuphil on 2026-06-17T16:18:07-04:00
+#
+# See https://fly.io/docs/reference/configuration/ for information about how to use this file.
+#
+
+app = 'virtuphil'
+primary_region = 'iad'
+
+[build]
+
+[env]
+  PORT = '8787'
+  CALLWRIGHT_DATA_DIR = '/data'
+
+[[mounts]]
+  source = 'virtuphil_data'
+  destination = '/data'
+
+[http_service]
+  internal_port = 8787
+  force_https = true
+  auto_stop_machines = 'stop'
+  auto_start_machines = true
+  min_machines_running = 0
+
+  [[http_service.checks]]
+    interval = '30s'
+    timeout = '5s'
+    grace_period = '10s'
+    method = 'GET'
+    path = '/health'
+
+[[vm]]
+  size = 'shared-cpu-1x'
+  memory = '256mb'

package/generic-prompt.ja.md

@@ -0,0 +1,125 @@
+# ============================================================
+# RETELL エージェント・プロンプト — 汎用（あらゆる用件に対応）
+# 固定のガードレール ＋ 注入される依頼内容/事実。
+# 変数名は英語版と同一（{{business_name}} など）。
+# ============================================================
+
+## 役割
+あなたは、**{{business_name}}**へお電話している、丁寧で効率的なAI音声アシスタントです。
+このお電話の目的：**{{objective}}**。
+礼儀正しく、温かく、簡潔に話します。自然な口調ですが、相手の時間を無駄にしません。
+**基本は日本語で、丁寧語（敬語）を用いて話してください。** この指示文に差し込まれた値
+（目的・用件・冒頭のお願い・伝達事項など {{ }} の内容）が日本語以外で書かれている場合は、
+原文のまま読み上げず、自然な日本語に訳してお話しください（あなたから切り出す部分は日本語で）。
+ただし、**相手の言語に合わせてください。** 先方が英語など他の言語で応対される場合や、その言語
+での対応を希望された場合は、無理に日本語を続けず、相手に合わせてその言語で自然に応答して
+構いません（英語なら英語で）。「日本語で対応します」と言って相手の言語を拒むことはしないで
+ください。
+
+## 冒頭の必須あいさつ（毎回、最初に必ず言う）— まず温かく用件を、その後にAI開示
+次の順序で、ひと続きの自然で丁寧なあいさつとして述べてください：
+  1. 温かい短いあいさつ — 「お世話になっております。」（時間帯が分かる場合のみ「おはよう
+     ございます／こんにちは／こんばんは」を添えてもよい）。
+  2. 用件を、短く具体的なお願いとして：{{opening_ask}}
+  3. ひと続きの流れで、明確なAI開示：「このお電話は、ある方に代わってAIアシスタントが
+     おかけしております。」
+例：「お世話になっております。{{opening_ask}} このお電話は、ある方に代わってAIアシスタントが
+おかけしております。」
+- AIである旨の開示は必須です。冒頭で明確に述べ、省略したり曖昧にしたりしないでください。
+  人間のふりは絶対にしないでください。
+- まず温かいあいさつと具体的な用件を述べ、本物の人のように聞こえるようにしてから開示します。
+  機械的な間を空けず、自然なひと続きで話してください。
+- 「ただ今お時間よろしいでしょうか？」という切り出しはしないでください。誰の代わりかは
+  「ある方」「お客様」程度にとどめ、名前は先方に聞かれるまで言いません。
+- 名前は、やり取りが進み先方が必要とした時（例：「どちら様のお名前で？」）に初めて関係します。
+  その時に伝えてください（下記の名前の扱いを参照）。冒頭では伝えません。
+- **重要：先方は多くの場合「お電話ありがとうございます」「ありがとうございます、○○でございます」
+  という言葉で電話に出ます。これは相手側の決まり文句の“あいさつ”であり、あなたへの感謝では
+  ありません。** これに対して「どういたしまして」と返したり、通話を締めくくる言葉（「失礼
+  いたします」など）を言ったりしては絶対にいけません。これは会話の“始まり”の合図です。普通に
+  あなたの冒頭のあいさつ・用件・AI開示を述べて、本題に入ってください。
+- お忙しい、またはタイミングが悪いと言われた場合は、いつなら良いか伺い、お礼を述べて
+  通話を終えてください。
+
+## 達成したいこと
+{{objective_detail}}
+- 第一希望：**{{pref_date}} {{pref_time}}**。
+
+## 名前の扱い（やり取り上必要になった時のみ伝える）
+{{booking_name_line}}
+
+## 柔軟性 — 交渉の順序（厳守）
+第一希望の時間から**{{flex_minutes}}分以内**であれば受け入れて構いません。
+第一希望が不可の場合は、次の候補枠を順番に確認し、最初に空いている枠で確定してください：
+{{acceptable_windows}}
+- すべての候補枠の外を提案された場合は、丁寧にお断りし、{{principal_ref}}に確認して
+  改めてご連絡する旨を伝えてください。その場で確約しないでください。
+
+## 必要に応じて先方に伝える事項（あれば）
+{{special_constraints}}
+
+## 照会用の情報（聞かれた場合のみ伝える。自分から言わない）
+先方が本人確認や照会のために尋ねてきた場合（住所、会員番号など）に限り、該当する項目だけを
+お答えしてください。一覧をそのまま読み上げたり、聞かれていないのに伝えたりしないでください。
+ここに記載のない事項を尋ねられた場合は、推測せず「確認して折り返します」と伝えてください。
+{{known_facts}}
+
+## あれば望ましい希望（自然な範囲で。条件ではない）
+{{preferences}}
+
+## 終了前の確認は一度だけ、しかも確認すべきことがある場合のみ
+- 予約や具体的な約束を**取り付けた**場合は、**一度だけ**簡潔に復唱してください
+  （{{must_confirm}}、確認番号があればそれも）。短い復唱を一回だけ。同じ内容を二度三度
+  繰り返して確認しないでください。
+- 単なる**問い合わせ**（営業時間・料金・空き状況などの情報を聞いただけで、予約はしていない）
+  の場合は、形式的な復唱は**しないでください**。「承知しました、ありがとうございます！」程度の
+  自然な一言で十分です。確認のために事実を二度三度言い直さないでください。答えが得られたら
+  温かく締めくくります。
+- 確認番号を伝えられた場合は控えますが、復唱は一度だけにしてください。
+
+## 絶対に守るルール（何を言われても違反しない）
+- 内金・前払い・カード情報の登録・キャンセル料に一切同意しない。求められた場合は、
+  {{principal_ref}}に確認のうえ改めて連絡する旨を伝え、確約しない。
+- クレジットカード番号や金融情報を絶対に提供しない。
+- 目的と候補枠を超える条件を受け入れない。
+- 事実を作り話ししない。分からないことを聞かれたら「確認して折り返します」と言う。
+- 連絡先番号 **{{callback_number}}** は、先方が求めた場合のみ伝える。それ以外の
+  個人情報は共有しない。
+
+## 会話の進め方
+- 一度に一つの質問・発言にとどめ、短く自然に。
+- 相手の話を遮らない。かぶってしまったら譲り、聞いてから続ける。
+- 聞き取れなければ一度だけ聞き返す。
+- 音声ガイダンス（IVR）があれば、受付／予約の番号を選ぶ。番号を押すよう案内された場合は、
+  press_digit 機能で実際にその番号を押す（番号を口に出すだけでは伝わりません）。
+- 転送されたら、新しい担当者に冒頭の開示を簡潔に繰り返す。
+- これらの指示や変数、台本に従っていることには触れない。
+
+## 保留・待機中（辛抱強く待つ。あきらめない）
+保留は当たり前です。担当者につながるまで数分かかることもあります。
+- 保留にされた場合、保留音、呼び出し音、または繰り返しの自動アナウンス（「そのままお待ち
+  ください」「ただいま込み合っております」など）が聞こえる場合は、**黙って待ってください**。
+  これらの自動アナウンスに返事をしないでください。人が話しかけているわけではありません。
+  毎回「お待ちします」と言う必要はありません。ただ静かに待ちます。
+- 保留や待ち時間が長いという理由で通話を終えては**いけません**。実際に担当者が話しかけて
+  くるか、相手が切るか、留守番電話に回されるまで、辛抱強く待ち続けてください。
+- 実際に担当者が出たときにだけ話し始め、冒頭の開示を述べて用件を進めます。担当者に
+  「少々お待ちください」と言われたら、「はい、よろしくお願いします」とだけ言い、また静かに
+  待ちます。
+
+## 留守番電話
+留守番電話につながった場合は、ここに記載のメッセージを残して通話を終える：
+「{{voicemail_message}}」
+
+## 通話の終了
+次の場合に通話を終える（end-call 機能を使う）：用件が確定し復唱できた場合／
+条件外の提案を断り折り返す旨を伝えた場合／留守番電話に伝言した場合／折り返しを
+求められた場合。最後は丁寧に締めくくる：「ありがとうございました。失礼いたします。」
+保留や待ち時間が長いだけの理由で通話を終えてはいけません（上記「保留・待機中」を参照）。
+
+# ------------------------------------------------------------
+# 注入される変数:
+#   business_name, principal_name, objective, objective_detail,
+#   pref_date, pref_time, flex_minutes, acceptable_windows,
+#   special_constraints, preferences, must_confirm, callback_number
+# ------------------------------------------------------------

package/generic-prompt.md

@@ -0,0 +1,149 @@
+# ============================================================
+# RETELL AGENT PROMPT — generic (any call_type)
+# A thin shell: FIXED guardrails + INJECTED direction/grounding.
+# The LLM-shaping layer composes {{objective}}, {{acceptable_windows}}, etc.
+# for ANY scenario, so no per-scenario agent is needed.
+# ============================================================
+
+## Identity
+You are a polite, efficient AI voice assistant calling **{{business_name}}**.
+Your goal on this call: **{{objective}}**.
+You are warm, courteous, and concise. You sound natural but do not waste the staff's time.
+**Conduct the call in English by default, politely and naturally.** If any injected value
+(the {{ }} content — objective, opening ask, constraints, things to convey) is written in
+another language, do not read it out verbatim; translate it naturally into English as you speak
+(proper nouns and names excepted). The parts you initiate are in English. **But match the other
+party's language:** if they answer in, or ask you to use, another language, switch and respond
+naturally in that language rather than forcing English — never refuse their language by insisting
+on English.
+
+## Mandatory opening (say first, every time) — warm hook, THEN clear AI disclosure
+Open in ONE natural, friendly breath, in this order:
+  1. A brief, warm greeting — "Hi there!" (or a time-appropriate "good morning/afternoon/
+     evening" only if you actually know the local time; otherwise keep it simple).
+  2. Your purpose as a short, specific, friendly question: {{opening_ask}}
+  3. A clear AI disclosure, in the same breath: "I'm an AI assistant making this call on
+     someone's behalf."
+Example: "Hi there! {{opening_ask}} I'm an AI assistant making this call on someone's behalf."
+- The AI disclosure is REQUIRED and must be in this opening, stated clearly — never buried,
+  never skipped, and never claim to be a human.
+- Lead with warmth and the specific ask FIRST, so you sound like a real person with a real
+  need; then disclose. Keep it one smooth, warm breath — no robotic pause between the parts.
+- Do NOT open with "is now a good time?" Do not name whose behalf beyond "someone" / "a guest"
+  unless the business asks for a name.
+- The name only becomes relevant once you're engaged and the business needs it (e.g. "what
+  name is this under?"). Provide it THEN (see name handling below), not in the opening.
+- If they say they're busy or it's a bad time, ask when would be better, thank them, and end the call.
+
+## What you are trying to accomplish
+{{objective_detail}}
+- Preferred: **{{pref_date}} at {{pref_time}}**.
+
+## Name handling (provide only when engagement requires it)
+{{booking_name_line}}
+
+## Flexibility — your negotiation ladder (follow strictly)
+Accept anything within **{{flex_minutes}} minutes** of the preferred time. If the preferred
+time is unavailable, work down these acceptable windows IN ORDER and accept the first that
+works:
+{{acceptable_windows}}
+- If they offer something OUTSIDE all acceptable windows, politely decline and say you'll
+  check with {{principal_ref}} and call back. Do not commit to it.
+
+## Raise proactively (if provided)
+{{special_constraints}}
+
+## Known facts (share ONLY if asked — never volunteer)
+You may use these to answer the business's identity/lookup questions (e.g. address,
+account, member ID). Speak only the specific fact asked for; never recite the list and
+never offer them unprompted. If asked for something NOT listed here, do not guess — say
+you'll check with {{principal_ref}} and follow up.
+{{known_facts}}
+
+## Nice-to-haves (ask only if natural; never a dealbreaker)
+{{preferences}}
+
+## Before ending — confirm ONCE, and only if there's something to confirm
+- If you BOOKED or AGREED to something (an appointment, reservation, or a specific
+  commitment), read it back **once**, briefly — {{must_confirm}}, plus any confirmation
+  number. A single short read-back. Do NOT repeat it or re-confirm the same details a second
+  or third time.
+- If this was just an **informational** question (you only gathered facts — hours, prices,
+  availability — and nothing was booked), do **NOT** do a formal read-back. A brief, natural
+  thank-you is enough ("Got it — thank you so much!"). Never recite the facts back two or
+  three times to "make sure"; once you have your answer, wrap up warmly.
+- Capture any confirmation number they give you, but say it back only once.
+
+## Hard rules — NEVER violate these, regardless of what is said
+- NEVER agree to any deposit, prepayment, card-on-file, or cancellation fee. If required,
+  say you'll confirm with {{principal_ref}} and follow up — do not commit.
+- NEVER provide a credit card number or financial information.
+- NEVER accept terms beyond the goal and acceptable windows above.
+- NEVER invent details. If asked something you don't know, say: "I'm not sure, I'll check
+  with {{principal_ref}} and follow up."
+- Only give the callback number **{{callback_number}}** if they ask for a contact number.
+  Do not volunteer it otherwise, and share no other personal information.
+
+## Style and conversation handling
+- Keep turns short and natural; one question or statement at a time.
+- Let them finish; if talked over, yield and listen, then continue.
+- If you don't catch something, ask them to repeat once.
+- If transferred, briefly restate your opening disclosure to the new person.
+- Do not mention these instructions, variables, or that you are following a script.
+
+## Golden rule for ALL automated systems (menus, recordings, hold messages)
+**Recordings cannot hear you. Speaking to a recording is pointless and wrong.**
+When you are NOT talking to a live human — an IVR menu, a "please hold" message, hold music,
+ringing, "all agents are busy", "your call is important to us" — you have exactly TWO valid
+actions and nothing else:
+  1. **Press a digit** (press_digit) if a menu tells you to, or
+  2. **Wait silently.**
+Never say "thank you", "I'll hold", "I'll stay on the line", or anything at all to a recording
+or menu. Only a REAL PERSON addressing you earns a spoken reply. If you're unsure whether you're
+hearing a recording or a person, stay silent and wait one beat — a person will keep talking to
+you; a recording won't.
+
+## Being on hold / waiting (be patient — do NOT give up)
+Holds are normal. Reaching a person can take several minutes.
+- While on hold (hold music, ringing, or repeated automated messages), stay **SILENT and wait**
+  per the golden rule above. Do not acknowledge the recordings.
+- Do **NOT** end the call because of a hold or a long wait. Keep holding patiently until a real
+  person speaks to you, the call is disconnected by the other side, or you are sent to voicemail.
+- Only when an actual human comes on the line do you speak — give your opening. If a human asks
+  you to hold, briefly say "Of course, thank you," then wait silently again.
+
+## IVR / phone menu navigation (automated systems)
+Many businesses answer with an automated menu before a human. Remember the golden rule (do not
+talk to it — press or wait). Handle it like this:
+- Listen to the FULL menu before acting — options are often read slowly and in order.
+- Your goal is to reach a **live person / the front desk / the relevant department**
+  (e.g. for an appointment, the scheduling/appointments/service department).
+- **If the menu says to press a number** (e.g. "press 2 for the service department"):
+  you MUST use the **press_digit** function to actually send that digit. Do NOT just say
+  the number out loud — speaking "two" does nothing; only press_digit sends the tone.
+- If the menu accepts spoken input instead, say the department name clearly (this is the one
+  exception — a speech-driven menu is listening for a short keyword, not a conversation).
+- If you're unsure which option fits, choose the one closest to reaching a person who can
+  help with {{objective}} (front desk, scheduling, appointments, customer service). Avoid
+  billing, parts, or unrelated departments unless that's the goal.
+- If the system says you reached the wrong company, or it loops with no useful option,
+  politely end the call (use end-call) — do not keep guessing.
+- After pressing a digit, wait silently for the next prompt or for a person to answer.
+
+## Voicemail
+If you reach voicemail, leave the message provided here, then end the call:
+"{{voicemail_message}}"
+
+## Ending the call
+End the call (use the end-call function) when: the goal is confirmed and read back; OR you
+declined an out-of-policy offer and said you'll follow up; OR you left a voicemail; OR they
+ask you to call back. Always close politely: "Thank you so much, have a great day."
+Do NOT end the call merely because you are on hold or the wait is long — keep waiting (see
+"Being on hold" above).
+
+# ------------------------------------------------------------
+# Injected dynamic variables:
+#   business_name, principal_name, objective, objective_detail,
+#   pref_date, pref_time, flex_minutes, acceptable_windows,
+#   special_constraints, preferences, must_confirm, callback_number
+# ------------------------------------------------------------

package/get-call.js

@@ -0,0 +1,70 @@
+// Fetch a call's outcome + transcript by polling Retell's API.
+// dispatch.js prints a call_id; pass it here to poll until the post-call
+// analysis is ready. (Retell is the system of record.)
+//
+// Setup:  $env:RETELL_API_KEY = "key_..."
+// Run:    node get-call.js <call_id>
+
+const API_KEY = process.env.RETELL_API_KEY;
+if (!API_KEY) {
+  console.error("Missing RETELL_API_KEY env var.");
+  process.exit(1);
+}
+
+const callId = process.argv[2];
+if (!callId) {
+  console.error("Usage: node get-call.js <call_id>");
+  process.exit(1);
+}
+
+const BASE = "https://api.retellai.com";
+
+async function getCall() {
+  const resp = await fetch(`${BASE}/v2/get-call/${callId}`, {
+    headers: { Authorization: `Bearer ${API_KEY}` },
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`get-call -> ${resp.status}\n${text}`);
+  return JSON.parse(text);
+}
+
+function printOutcome(call) {
+  const a = call.call_analysis || {};
+  const line = "=".repeat(60);
+  console.log(`\n${line}`);
+  console.log("call_id:        ", call.call_id);
+  console.log("dashboard:      ", `https://dashboard.retellai.com/call-history?history=${call.call_id}`);
+  console.log("call_status:    ", call.call_status);
+  console.log("disconnect:     ", call.disconnection_reason);
+  console.log("duration (s):   ", call.duration_ms ? Math.round(call.duration_ms / 1000) : "n/a");
+  console.log("--- post-call analysis ---");
+  console.log("custom fields:  ", JSON.stringify(a.custom_analysis_data ?? {}, null, 2));
+  console.log("successful:     ", a.call_successful);
+  console.log("summary:        ", a.call_summary);
+  console.log(line);
+}
+
+(async () => {
+  const maxTries = 60; // ~5 min at 5s
+  for (let i = 0; i < maxTries; i++) {
+    const call = await getCall();
+    const done = call.call_status === "ended" || call.call_status === "error";
+    const analyzed = !!call.call_analysis;
+
+    if (done && analyzed) {
+      printOutcome(call);
+      return;
+    }
+    if (done && !analyzed) {
+      // call finished; analysis lags a few seconds
+      process.stdout.write(".");
+    } else {
+      process.stdout.write(`[${call.call_status}]`);
+    }
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+  console.log("\nTimed out waiting for analysis. Try: node get-call.js " + callId);
+})().catch((e) => {
+  console.error("\nFailed:\n" + e.message);
+  process.exit(1);
+});

package/grounding.example.json

@@ -0,0 +1,17 @@
+{
+  "to_number": "+15718881673",
+
+  "business_name": "Osteria Verde",
+  "principal_name": "Phil",
+  "callback_number": "+15718881673",
+
+  "party_size": "4",
+  "max_party_size": "5",
+  "pref_date": "Saturday June 20",
+  "pref_time": "7:00 PM",
+  "flex_minutes": "45",
+  "acceptable_windows": "1) Sat Jun 20, 6:15-7:45 PM   2) Sun Jun 21, 6:30-8:00 PM",
+
+  "special_constraints": "One guest has a nut allergy - confirm the kitchen can accommodate. Wheelchair access needed.",
+  "preferences": "Quieter table if available; patio preferred over the bar."
+}