callwright 1.0.0

package/dispatch-core.js

@@ -0,0 +1,371 @@
+// callwright — dispatch core (reusable, no CLI / no process.argv).
+//
+// The validate -> profile-match -> compose-vars -> resolve-agent -> dispatch
+// pipeline, callable in-process by BOTH the CLI (dispatch.js) and the MCP
+// server. Pure of stdin/stdout side effects except where noted (buildReadback
+// returns text; it does not print).
+
+const fs = require("fs");
+const Ajv = require("ajv/dist/2020");
+const addFormats = require("ajv-formats");
+const paths = require("./paths");
+const retry = require("./retry-core");
+
+const SCHEMA_PATH = "place_call.schema.json";
+const PROFILES_PATH = paths.PROFILES_PATH;
+const CONFIG_PATH = paths.CONFIG_PATH;
+const AGENTS_PATH = paths.AGENTS_PATH;
+const RETELL_BASE = "https://api.retellai.com";
+
+function loadJson(p, fb) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; }
+}
+function loadConfig() { return loadJson(CONFIG_PATH, {}); }
+
+// Per-language PHRASING. Code injects values; this data owns wording. Keyed by
+// BCP-47 primary subtag; unknown languages fall back to English so a call never
+// crashes for lack of a phrase block (it just speaks English helper text).
+// Volume-first: the image ships en/ja seeds; a volume copy (runtime-added
+// languages) is merged on top per language block. Not cached — the file is tiny
+// and add_language may write to it at runtime.
+const PHRASES_FILE = "lang-phrases.json";
+function loadPhrases() {
+  const image = loadJson(PHRASES_FILE, { en: {} });
+  if (paths.DATA_DIR !== ".") {
+    const vol = loadJson(paths.volumePath(PHRASES_FILE), null);
+    if (vol) return { ...image, ...vol };
+  }
+  return image;
+}
+function phrasesFor(lang) {
+  const all = loadPhrases();
+  const L = String(lang || "en").toLowerCase();
+  return all[L] || all[L.split("-")[0]] || all.en || {};
+}
+// Minimal {key} interpolation; missing keys render as "".
+function interp(tpl, vars = {}) {
+  return String(tpl || "").replace(/\{(\w+)\}/g, (_, k) => (vars[k] != null ? String(vars[k]) : ""));
+}
+
+// Backfill ONLY the always-safe basics from config (identity + callback). Facts
+// are NOT auto-merged (data minimization: caller furnishes a per-call subset).
+// A job may set principal.anonymous=true to opt out entirely (general inquiries).
+function applyConfigBackfill(job, config = loadConfig()) {
+  const anon = job.principal && job.principal.anonymous === true;
+  if (config.principal && !anon) {
+    const cp = config.principal;
+    job.principal = job.principal || {};
+    if (job.principal.name == null) job.principal.name = cp.name;
+    if (job.principal.callback_number == null && cp.callback_number != null)
+      job.principal.callback_number = cp.callback_number;
+  }
+  return job;
+}
+
+let _validate = null;
+function validateJob(job) {
+  if (!_validate) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    _validate = ajv.compile(loadJson(SCHEMA_PATH, {}));
+  }
+  const ok = _validate(job);
+  return {
+    ok,
+    errors: ok ? [] : _validate.errors.map((e) => `${e.instancePath || "(root)"} ${e.message}`),
+  };
+}
+
+// Match an open-ended call_type to a scenario profile (name or alias, fuzzy).
+function loadProfileFor(callType) {
+  const profiles = loadJson(PROFILES_PATH, null);
+  if (!profiles) return null;
+  const ct = (callType || "").toLowerCase();
+  for (const [name, p] of Object.entries(profiles)) {
+    const keys = [name, ...(p.aliases || [])].map((s) => s.toLowerCase());
+    if (keys.some((k) => ct === k || ct.includes(k) || k.includes(ct))) return { name, ...p };
+  }
+  return null;
+}
+
+// ---- formatting ----
+function prettyDate(iso) {
+  const d = new Date(iso + "T12:00:00");
+  if (isNaN(d)) return iso;
+  return d.toLocaleDateString("en-US", { weekday: "long", month: "long", day: "numeric" });
+}
+function pretty12h(t) {
+  const [h, m] = t.split(":").map(Number);
+  const ap = h >= 12 ? "PM" : "AM";
+  const h12 = ((h + 11) % 12) + 1;
+  return `${h12}:${String(m).padStart(2, "0")} ${ap}`;
+}
+function deriveWindows(req, flexMin) {
+  if (req.acceptable_windows && req.acceptable_windows.length) return req.acceptable_windows;
+  if (!req.preferred?.date || !req.preferred?.time) {
+    throw new Error("No acceptable_windows and no preferred date/time to derive from.");
+  }
+  const [h, m] = req.preferred.time.split(":").map(Number);
+  const base = h * 60 + m;
+  const fmt = (mins) => {
+    const hh = Math.floor((((mins % 1440) + 1440) % 1440) / 60);
+    const mm = ((mins % 60) + 60) % 60;
+    return `${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}`;
+  };
+  return [{ date: req.preferred.date, earliest: fmt(base - flexMin), latest: fmt(base + flexMin) }];
+}
+
+// Compose the rich job -> Retell dynamic variables + call metadata.
+// `lang` selects the per-language PHRASE block (lang-phrases.json) used for
+// composed helper strings. composeCall has no language conditionals — phrasing
+// is data; this function only injects values.
+function composeCall(job, { lang = "en" } = {}) {
+  const LANG = String(lang || "en").toLowerCase();
+  const P = phrasesFor(LANG);
+  const profile = loadProfileFor(job.call_type);
+
+  const flex = job.overrides?.time_flexibility_minutes ?? profile?.default_flex_minutes ?? 45;
+  const windows = deriveWindows(job.request, flex);
+  const windowsStr = windows
+    .map((w, i) => `${i + 1}) ${prettyDate(w.date)}, ${pretty12h(w.earliest)}-${pretty12h(w.latest)}`)
+    .join("   ");
+
+  const details = job.scenario_details || {};
+  const facts = (job.principal && job.principal.facts) || {};
+  const missingRecommended = [];
+  if (profile?.recommended_details) {
+    for (const [key, why] of Object.entries(profile.recommended_details)) {
+      const present =
+        (details[key] != null && details[key] !== "") ||
+        (facts[key] != null && facts[key] !== "") ||
+        (key === "party_size" && job.request.party_size);
+      if (!present) missingRecommended.push({ key, why });
+    }
+  }
+  const detailSentences = Object.entries(details).map(([k, v]) => {
+    const label = k.replace(/_/g, " ");
+    return `${label.charAt(0).toUpperCase() + label.slice(1)}: ${v}.`;
+  });
+
+  const principalName = (job.principal && job.principal.name) ? String(job.principal.name).trim() : "";
+  const hasName = principalName.length > 0;
+  const onBehalf = hasName ? interp(P.behalf_named, { name: principalName }) : "";
+  const principalRef = hasName ? principalName : P.principal_ref_anon;
+
+  const objective = job.request.summary;
+  // Trimmed/lowercased forms shared by the phrase templates (opening, voicemail).
+  const objectiveTrim = String(objective || "").trim().replace(/[.?!。、]+$/, "");
+  const objectiveLc = objectiveTrim.charAt(0).toLowerCase() + objectiveTrim.slice(1);
+  const serviceType = details.service_type ? ` (${details.service_type})` : "";
+  const objectiveDetail = job.request.party_size
+    ? `${job.request.summary}${serviceType} (party of ${job.request.party_size}).`
+    : `${job.request.summary}${serviceType}.`;
+
+  // The spoken purpose line. PREFER an explicit, call-language opening_ask that the
+  // host LLM authored (it writes fluent, natural sentences). Only fall back to a
+  // simple, language-neutral derivation when opening_ask is absent.
+  const openingAsk = job.request.opening_ask
+    || interp(P.opening_ask_fallback, { objective: objectiveTrim, objective_lc: objectiveLc });
+
+  const callbackNumber = (job.principal && job.principal.callback_number) || "";
+  const voicemailMessage = interp(
+    callbackNumber ? P.voicemail_callback : P.voicemail_no_callback,
+    { behalf: onBehalf, objective: objectiveTrim, objective_lc: objectiveLc, callback: callbackNumber }
+  );
+
+  const composeKnownFacts = (f) => {
+    const entries = Object.entries(f || {}).filter(([, v]) => v != null && v !== "");
+    if (!entries.length) return P.known_facts_none;
+    return entries
+      .map(([k, v]) => `- ${k.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())}: ${v}`)
+      .join("\n");
+  };
+  const knownFacts = composeKnownFacts(facts);
+
+  const bookingNameLine = hasName
+    ? interp(P.booking_name_line_named, { name: principalName })
+    : P.booking_name_line_anon;
+
+  // Default confirm list is built from per-language labels; party size is added
+  // only when present AND the language opts in (cf.party_size non-null).
+  const defaultConfirm = (() => {
+    const cf = P.confirm || { base: ["the date", "the time"], party_size: "the party size", join: ", " };
+    const parts = (cf.base || []).slice();
+    if (job.request.party_size && cf.party_size) parts.splice(2, 0, cf.party_size);
+    return parts.join(cf.join != null ? cf.join : ", ");
+  })();
+  const mustConfirm = (job.must_confirm && job.must_confirm.length)
+    ? job.must_confirm.join(", ")
+    : (profile?.must_confirm ? profile.must_confirm.join(", ") : defaultConfirm);
+
+  const baseConstraints = (job.constraints && job.constraints.length) ? job.constraints.slice() : [];
+  const allConstraints = [...baseConstraints, ...detailSentences];
+  const noneText = P.none_text;
+
+  // Retry policy (default: exactly 1 retry on no-answer/busy/failed). Round-tripped
+  // in the dynamic vars so the webhook can decide from the call_ended payload and
+  // the incrementing attempt counter makes the chain self-terminating.
+  const retryPolicy = retry.parseRetryPolicy(job.overrides && job.overrides.retry);
+  const retryVars = retry.policyToVars(retryPolicy, 0);
+
+  // Per-call SMS notify intent (opt-in). Round-tripped so the call_analyzed
+  // webhook can text the user. Default off (results pulled via get_call_outcome).
+  const notifySms = !!(job.notify && job.notify.sms);
+  const notifyVars = { notify_sms: notifySms ? "1" : "0", notify_to: (job.notify && job.notify.to) || "" };
+
+  const vars = {
+    business_name: job.target.business_name,
+    // Round-tripped metadata (not spoken; echoed back in the call_analyzed
+    // webhook payload so auto-learn knows the scenario + language).
+    call_type: job.call_type || "",
+    call_lang: LANG,
+    // Retry policy round-trip (read back from the call_ended webhook payload).
+    ...retryVars,
+    // SMS notify intent round-trip (read back from the call_analyzed webhook).
+    ...notifyVars,
+    principal_name: principalName,
+    principal_ref: principalRef,
+    booking_name_line: bookingNameLine,
+    objective,
+    objective_detail: objectiveDetail,
+    opening_ask: openingAsk,
+    voicemail_message: voicemailMessage,
+    known_facts: knownFacts,
+    must_confirm: mustConfirm,
+    party_size: String(job.request.party_size ?? ""),
+    max_party_size: String(job.request.max_party_size ?? job.request.party_size ?? ""),
+    pref_date: job.request.preferred?.date ? prettyDate(job.request.preferred.date) : "",
+    pref_time: job.request.preferred?.time ? pretty12h(job.request.preferred.time) : "",
+    flex_minutes: String(flex),
+    acceptable_windows: windowsStr,
+    callback_number: (job.principal && job.principal.callback_number) ?? "",
+    special_constraints: allConstraints.length ? allConstraints.join(" ") : noneText,
+    preferences: (job.preferences && job.preferences.length) ? job.preferences.join("; ") : noneText,
+  };
+
+  // Personal data types available to the agent (shared only if asked).
+  const piiKeys = [];
+  if (principalName) piiKeys.push("name");
+  if (job.principal && job.principal.callback_number) piiKeys.push("callback_number");
+  piiKeys.push(...Object.keys(facts).filter((k) => facts[k] != null && facts[k] !== ""));
+
+  return { profile, flex, windows, windowsStr, missingRecommended, detailSentences, vars, piiKeys, lang: LANG, phrases: P, retryPolicy };
+}
+
+// Resolve agent: language variant (config.agents.by_lang[lang]) -> agents.json
+// (call_type | default) -> config.agents.default -> env.
+function resolveAgentId(callType, { config = loadConfig(), lang } = {}) {
+  const L = String(lang || "en").toLowerCase().split("-")[0];
+  if (L && L !== "en" && config.agents?.by_lang?.[L]) return config.agents.by_lang[L];
+  const reg = loadJson(AGENTS_PATH, null);
+  if (reg) {
+    const id = reg[callType] || reg.default || config.agents?.default;
+    if (id) return id;
+  }
+  if (config.agents?.default) return config.agents.default;
+  const raw = process.env.RETELL_AGENT_ID || "";
+  if (raw.trim().startsWith("{")) {
+    const map = JSON.parse(raw);
+    if (map[callType]) return map[callType];
+  }
+  if (raw) return raw;
+  throw new Error(`No agent for call_type "${callType}" (no agents.json/config default/env).`);
+}
+
+// Build a human-readable read-back (returns lines; does not print).
+function buildReadback(job, composed, { testTo, agentId } = {}) {
+  const v = composed.vars;
+  const lines = [];
+  lines.push(`Call type:   ${job.call_type}${composed.profile ? `  (profile: ${composed.profile.name})` : "  (no profile — generic)"}`);
+  lines.push(`Calling:     ${job.target.business_name}  ${job.target.phone_number}`);
+  if (testTo) lines.push(`  (TEST: actual dial routed to ${testTo})`);
+  if (agentId) lines.push(`Agent:       ${agentId}`);
+  lines.push(`For:         ${job.request.summary}`);
+  // Representative Style-B opening (warm hook -> clear AI disclosure). The exact
+  // wording is generated by the agent at call time; this mirrors the prompt so
+  // the review gate matches what's actually spoken. Phrasing is per-language data.
+  const openingPreview = interp(
+    (composed.phrases && composed.phrases.opening_preview) || "{opening_ask}",
+    { opening_ask: v.opening_ask }
+  );
+  lines.push(`Opens with:  "${openingPreview}"`);
+  if (job.request.party_size) lines.push(`Party:       ${v.party_size} (max ${v.max_party_size})`);
+  lines.push(`Preferred:   ${v.pref_date} at ${v.pref_time}  (±${composed.flex} min)`);
+  lines.push(`Windows:     ${v.acceptable_windows}`);
+  lines.push(`Details:     ${composed.detailSentences.length ? composed.detailSentences.join(" ") : "(none)"}`);
+  lines.push(`Constraints: ${v.special_constraints}`);
+  lines.push(`Personal data sent (if asked):  ${composed.piiKeys.length ? composed.piiKeys.join(", ") : "(none)"}`);
+  lines.push(`Outcome:     pull on demand — ask for the result and it's fetched via get_call_outcome.`);
+  lines.push(`Retry:       ${retry.describePolicy(composed.retryPolicy)}`);
+  if (v.notify_sms === "1") lines.push(`Notify:      SMS to ${v.notify_to || "(your saved number)"} when done`);
+  if (composed.missingRecommended.length) {
+    lines.push("");
+    lines.push("⚠️  Profile recommends these details (missing — consider adding):");
+    for (const m of composed.missingRecommended) lines.push(`     - ${m.key}: ${m.why}`);
+  }
+  return lines;
+}
+
+// Place the outbound call via Retell. Returns the API response (has call_id).
+async function dispatchCall({ key, from, agentId, toNumber, businessNumber, vars }) {
+  if (!key) throw new Error("Missing Retell API key.");
+  if (!from) throw new Error("Missing from-number.");
+  if (!agentId) throw new Error("Missing agent id.");
+  const resp = await fetch(`${RETELL_BASE}/v2/create-phone-call`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      from_number: from,
+      to_number: toNumber || businessNumber,
+      override_agent_id: agentId,
+      retell_llm_dynamic_variables: vars,
+    }),
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`Retell create-phone-call ${resp.status}: ${text}`);
+  return JSON.parse(text);
+}
+
+// Re-dial a finished call for a retry. Reuses the original call's from/to/agent
+// and dynamic vars, bumping retry_attempt so the chain self-terminates. Returns
+// the new Retell call object.
+async function redialFromCall(call, { key = process.env.RETELL_API_KEY, attempt } = {}) {
+  const vars = retry.buildRetryVars(call.retell_llm_dynamic_variables || {}, attempt);
+  return dispatchCall({
+    key,
+    from: call.from_number,
+    agentId: call.agent_id || call.override_agent_id,
+    toNumber: call.to_number,
+    businessNumber: call.to_number,
+    vars,
+  });
+}
+
+// Convenience: full pipeline from a raw job object to a placed (or dry-run) call.
+// Returns { ok, errors?, readback, composed, call? }.
+async function placeCall(rawJob, { lang = "en", go = false, testTo = null, agentOverride = null, key = process.env.RETELL_API_KEY, from = null } = {}) {
+  const config = loadConfig();
+  const job = applyConfigBackfill({ ...rawJob }, config);
+  const valid = validateJob(job);
+  if (!valid.ok) return { ok: false, errors: valid.errors };
+  const composed = composeCall(job, { lang });
+  // Resolve the agent up-front so the read-back can show it (don't dial yet).
+  let agentId = agentOverride;
+  if (!agentId) { try { agentId = resolveAgentId(job.call_type, { config, lang }); } catch { agentId = null; } }
+  const readback = buildReadback(job, composed, { testTo, agentId });
+  if (!go) return { ok: true, dryRun: true, readback, composed, agentId };
+  if (!agentId) throw new Error(`No agent resolved for call_type "${job.call_type}" (lang ${lang}). Run setup/configure.`);
+  const fromNumber = from || process.env.RETELL_FROM_NUMBER || config.retell?.from_number;
+  const call = await dispatchCall({
+    key, from: fromNumber, agentId, toNumber: testTo,
+    businessNumber: job.target.phone_number, vars: composed.vars,
+  });
+  return { ok: true, dryRun: false, readback, composed, call };
+}
+
+module.exports = {
+  SCHEMA_PATH, PROFILES_PATH, CONFIG_PATH, AGENTS_PATH, RETELL_BASE,
+  loadConfig, applyConfigBackfill, validateJob, loadProfileFor,
+  prettyDate, pretty12h, deriveWindows, composeCall, resolveAgentId,
+  buildReadback, dispatchCall, redialFromCall, placeCall,
+};

package/dispatch.js

@@ -0,0 +1,55 @@
+// callwright — CLI dispatcher (thin wrapper over dispatch-core.js).
+//
+//   node dispatch.js <job.json>                         # dry-run: validate + read-back
+//   node dispatch.js <job.json> --go                    # actually place the call
+//   node dispatch.js <job.json> --to +1...              # route the dial to a test number
+//   node dispatch.js <job.json> --lang ja               # Japanese composed strings
+//   node dispatch.js <job.json> --agent agent_xxx       # force a specific agent
+//
+// Env: RETELL_API_KEY (required for --go). from-number + agent resolve from
+// config.json / agents.json (see `node init.js`).
+
+const fs = require("fs");
+const core = require("./dispatch-core");
+
+const jobFile = process.argv[2];
+const GO = process.argv.includes("--go");
+const toIdx = process.argv.indexOf("--to");
+const TEST_TO = toIdx > -1 ? process.argv[toIdx + 1] : null;
+const langIdx = process.argv.indexOf("--lang");
+const LANG = (langIdx > -1 ? process.argv[langIdx + 1] : (process.env.CALL_LANG || "en")).toLowerCase();
+const agentIdx = process.argv.indexOf("--agent");
+const AGENT_OVERRIDE = agentIdx > -1 ? process.argv[agentIdx + 1] : null;
+
+if (!jobFile) {
+  console.error("Usage: node dispatch.js <job.json> [--go] [--to +1...] [--lang ja] [--agent agent_xxx]");
+  process.exit(1);
+}
+
+const rawJob = JSON.parse(fs.readFileSync(jobFile, "utf8"));
+
+(async () => {
+  const result = await core.placeCall(rawJob, {
+    lang: LANG, go: GO, testTo: TEST_TO, agentOverride: AGENT_OVERRIDE,
+  });
+
+  if (!result.ok) {
+    console.error("❌ Job does NOT conform to place_call.schema.json:\n");
+    for (const e of result.errors) console.error(`  ${e}`);
+    process.exit(1);
+  }
+
+  console.log("✅ Job conforms to place_call.schema.json");
+  console.log("\n--- READ-BACK (confirm before dialing) ---");
+  console.log(result.readback.join("\n"));
+
+  if (result.dryRun) {
+    console.log("\n[dry run] Not dialing. Re-run with --go to place the call.");
+    return;
+  }
+
+  console.log("\n📞 Call dispatched.");
+  console.log("call_id:", result.call.call_id);
+  console.log("dashboard:", `https://dashboard.retellai.com/call-history?history=${result.call.call_id}`);
+  console.log("Read outcome with:  node get-call.js " + result.call.call_id);
+})().catch((e) => { console.error("\n" + (e.message || e)); process.exit(1); });

package/docs/add-language-spec.md

@@ -0,0 +1,207 @@
+# Spec: `add_language` — let an LLM add a call language at runtime
+
+## Goal
+
+Let the host LLM stand up a **new call language entirely in chat** — no code change, no
+redeploy. After it runs, `place_call` with `lang:"<new>"` conducts a fully native call.
+
+## Why it's blocked today
+
+Adding a language currently has 5 parts; **2 are hardcoded in source** (require a deploy):
+
+| Part | State today |
+|---|---|
+| Translated prompt (`generic-prompt.<lang>.md`) | file baked into the image |
+| Retell agent (language code + a voice that speaks it) | created via `ensureGenericAgent` / `setup-agent-from.js` |
+| Register in `config.agents.by_lang[<lang>]` | runtime-writable (volume) |
+| **MCP `lang` enum** = `["en","ja"]` | ❌ hardcoded — rejects a new code |
+| **`composeCall` `isJa` branches** (voicemail, booking line, "none" text, principal_ref, must_confirm default, read-back preview) | ❌ hardcoded — a 3rd language falls through to English |
+
+## The core principle (generalizes the `opening_ask` refactor)
+
+> **Code injects VALUES (language-agnostic). Per-language PROMPT FILES own all PHRASING.**
+
+Adding a language needs code changes today *only because language-specific phrasing leaked into
+code* (the `isJa` branches). We already proved the fix once: `opening_ask` used to be
+code-composed with a brittle regex; we made the **LLM author the spoken line** and the breakage
+vanished. The remaining `isJa` strings are the same debt. Eliminate them and the code becomes
+language-agnostic — then a new language is pure data (prompt + agent + registration).
+
+---
+
+## Prerequisite refactor (must land before the tool)
+
+### 1. Open the `lang` enum ✅ DONE (2026-06-27, Fly v19)
+`lang: z.enum(["en","ja"])` → a validated **free-form BCP-47 string** (validate *format*, not
+membership). Unknown-but-registered languages route via `config.agents.by_lang`.
+
+Implemented in `server.js`: `z.string().regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/)`. The
+`place_call` handler also computes `langSupported` (en OR a registered `by_lang` agent) and
+(a) surfaces a `language_warning` on dry-run for an unregistered language, and (b) **refuses to
+dial** (`confirm:true`) an unregistered language so a non-English call can't silently use the EN
+agent. Verified live: en→EN agent, ja→JA agent, fr→EN agent + warning (dry) / blocked (confirm),
+bad format rejected by schema. NOTE: this changed the tool schema → MCP clients must reconnect.
+
+### 2. Eliminate every `isJa` branch in `dispatch-core` ✅ DONE (2026-06-27)
+Phrasing moved out of code into a per-language **data file `lang-phrases.json`** (keyed by BCP-47
+primary subtag; unknown languages fall back to `en`). `composeCall` now injects VALUES and
+interpolates them into the language's phrase templates via a tiny `interp("{key}", vars)` helper —
+**no language conditionals remain**.
+
+> **Refinement vs the original plan:** these strings became a dedicated `lang-phrases.json` rather
+> than living inside the agent prompt `.md` files. Reason: the voicemail (`voicemail_option`
+> `static_text`) and the read-back preview are composed *outside* the agent prompt, so a data file
+> keyed by language is the correct realization of "phrasing is per-language data, not code." The
+> agent prompt `.md` still owns what the agent *speaks live*; `lang-phrases.json` owns code-composed
+> helper strings. **The `{{variable}}` contract was left identical**, so en/ja behavior and the
+> existing prompts were untouched — verified byte-identical across a 256-case old-vs-new matrix.
+
+| Code-composed string | New home (`lang-phrases.json` key) |
+|---|---|
+| `voicemail_message` | `voicemail_callback` / `voicemail_no_callback` (inject `{objective}`/`{callback}`/`{behalf}`) |
+| `booking_name_line` | `booking_name_line_named` / `booking_name_line_anon` (inject `{name}`) |
+| `principal_ref` (anon) | `principal_ref_anon` |
+| `known_facts` empty | `known_facts_none` |
+| `must_confirm` default | `confirm.{base,party_size,join}` (party size added only if the language opts in) |
+| `noneText` | `none_text` |
+| `opening_ask` fallback | `opening_ask_fallback` |
+| `openingPreview` (read-back) | `opening_preview` |
+
+After this, `composeCall` emits values; `lang-phrases.json` renders phrasing. A new language is
+now: add a `lang-phrases.<lang>` block + a `generic-prompt.<lang>.md` + an agent/voice.
+
+### 3. Make the base prompt language-parameterized ✅ DONE (2026-06-27)
+The English base prompt (`generic-prompt.md`) now carries the same language-handling rule the JA
+prompt already proved (Identity section): conduct the call in the prompt's language by default;
+translate any injected value written in another language rather than reading it verbatim (proper
+nouns excepted); **but mirror the callee** — switch to their language if they use it, never refuse
+it. Pushed live to the EN agent via `update-prompt.js`.
+
+> **Implementation choice:** the rule is **baked per-language** (each translated prompt states it
+> in its own language), not injected via a `{{call_language}}` variable. This matches the proven
+> JA precedent and keeps the `{{variable}}` contract stable. Because `add_language` translates
+> `generic-prompt.md` into the new language, every new language inherits the rule automatically —
+> `generic-prompt.md` is now the canonical translation template.
+
+### 4. Prompts become volume-resident for runtime-added languages ✅ DONE (2026-06-27)
+Both the prompt files **and `lang-phrases.json`** are now resolved **volume-first**:
+- `paths.resolveAsset(file)` returns a volume copy if one exists (`DATA_DIR/<file>`), else the
+  image-baked file. `setup-core.loadPromptText` uses it, so `generic-prompt.<lang>.md` for a
+  runtime-added language is read from the volume.
+- `dispatch-core.loadPhrases` loads the image seed (en/ja) and **merges any volume
+  `lang-phrases.json` on top, per language block** — so a runtime-added `fr` block persists on the
+  volume while en/ja keep flowing from the image. Not cached (the file is tiny and `add_language`
+  may write it at runtime).
+
+On prod the volume currently has none of these files, so everything falls back to the image exactly
+as before (verified: en/ja byte-identical). The volume-first path only activates once `add_language`
+writes `generic-prompt.<lang>.md` + an `fr`-style block to the volume. Guarded so local dev
+(`DATA_DIR="."`) skips the volume lookup entirely.
+
+
+---
+
+## The `add_language` MCP tool (enabled by the refactor)
+
+**Inputs**
+- `lang` (BCP-47, e.g. `fr`, `es`, `de`, `zh-CN`) — required
+- `display_name` (e.g. "French") — required
+- `prompt_text` — the full translated agent prompt. The host LLM produces this by translating
+  the base prompt (translation is the LLM's strength). Optional: if omitted, the tool returns the
+  base prompt for the LLM to translate and resubmit.
+- `voice_id` — a Retell voice that speaks the language. **Optional, with a default** (see below);
+  if provided it's validated against `list_voices(lang)`.
+- `stt_language` — the agent STT locale (default = `lang`); single-language (we learned
+  multilingual STT *hurts* — JA/EN garbling)
+
+**Steps**
+1. Validate `lang` format; refuse if already registered (offer `update_language`).
+2. Persist `prompt_text` to the volume as `generic-prompt.<lang>.md`.
+3. Create the Retell LLM + agent: language code, `voice_id`, `stt_mode:"accurate"`, the standard
+   system tools (`press_digit`, `end_call`), voicemail option `{{voicemail_message}}`, post-call
+   analysis fields, wait-for-greeting + hold settings — i.e. `ensureGenericAgent`'s baked
+   behavior, parameterized by language/voice.
+4. Register `config.agents.by_lang[lang] = agent_id`.
+5. Return `{ agent_id, lang, voice_id }`.
+
+**Companion tools**
+- `list_voices(lang)` — filter Retell's catalog so the LLM can *pick* a valid voice (it can't
+  invent one).
+- `update_language` / `remove_language`.
+
+---
+
+## Companion: verify_language ✅ DONE (2026-06-28)
+A dedicated quality-gate tool (closes the add_language loop). DRY-RUN returns a **review card**:
+the exact phrase-composed spoken opening (greeting + ask + AI disclosure), the voicemail message,
+name-handling line, and a native-review checklist — all routed through the language's own agent.
+With `to:<phone>` + `confirm:true` it places a live self-call (defaulting `to` to the configured
+`callback_number`) so the user judges accent/etiquette/disclosure by ear, then reads the transcript
+via `get_call_outcome`. Pure helpers `buildVerificationJob` + `verificationCard` in `lang-core.js`,
+covered by tests; live-verified on prod (dry-run review card for ja).
+
+## Guardrails (this is where the care goes)
+
+1. **Voice: default but overridable.** `voice_id` is optional. Resolution order:
+   1. explicit `voice_id` arg →
+   2. `config.defaults.voice_id` (the house voice) **if it appears in `list_voices(lang)`** →
+   3. `RETELL_VOICE_ID` env / `11labs-Brian` **if it speaks `lang`** →
+   4. else a sensible catalog pick for `lang`.
+
+   This mirrors today's live behavior — `voice_id || RETELL_VOICE_ID || "11labs-Brian"` in
+   `ensureGenericAgent`, where the multilingual `11labs-Brian` already drives **both** the EN and JA
+   agents. Defaulting to the house voice gives **voice consistency across languages for free**;
+   the user overrides anytime (pass `voice_id`, or later `update_language({lang, voice_id})`).
+   **Whatever is resolved — default or explicit — must validate against `list_voices(lang)`;**
+   reject a mismatch (the LLM can't invent a voice). The tool echoes the chosen voice + how to
+   change it. The verification call (guardrail 2) is the backstop that catches a mediocre default
+   by ear before production.
+2. **Disclosure + etiquette must survive translation (legal + quality).** The AI-disclosure line
+   is legally required in some jurisdictions; politeness conventions (e.g. Japanese keigo,
+   greeting norms) matter. **Do not let an unreviewed machine-translated disclosure go live
+   silently.** Require, before first production use:
+   - a **verification test call** (`place_call` with `--to` your own number) in the new language,
+     and/or
+   - a read-back of the composed opening + disclosure for human/native approval.
+3. **STT language.** Set the agent's STT to the single target locale + `accurate` (we learned
+   bilingual STT degrades quality).
+4. **Promotion to the repo.** A runtime-added language lives on the volume. To ship it in the OSS
+   repo for other adopters, promote the volume prompt back into the image as
+   `generic-prompt.<lang>.md` (same seed-vs-volume flow as profiles).
+
+---
+
+## What this does NOT change
+
+- The job schema, scenario profiles, grounding/PII model — all language-agnostic already.
+- Generic-agent behavior — unmatched/unknown still works; a language just adds native phrasing.
+- The provider boundary — `add_language` is implemented per provider (Retell today); the
+  ElevenLabs equivalent would use `language_detection` + its voice catalog.
+
+## Effort
+
+Bounded. The **refactor** (open enum + remove `isJa` + prompt-owns-phrasing) is the real work —
+and it's debt we'd want gone regardless. The **tool** is then thin: translate (LLM) → persist
+prompt → create agent → register. Voice selection and a verification call are the only
+human/catalog touchpoints.
+
+## Status
+
+**IMPLEMENTED & live (2026-06-27).** All 4 prerequisite refactor steps done, then the tooling
+shipped in `lang-core.js` + 5 MCP tools (`list_voices`, `list_languages`, `add_language`,
+`update_language`, `remove_language`). Covered by 20 `node:test` cases (`npm test`) and a full prod
+integration test (added a real French agent → native French dry-run with no warning → deleted the
+Retell agent + unregistered, all over the hosted MCP).
+
+Notes on what shipped vs this spec:
+- Phrasing lives in `lang-phrases.json` (data file), not inside the prompt `.md` (step-2 refinement).
+- `add_language` is a **two-phase handshake**: call with `lang`+`display_name` to get `base_prompt`
+  + `base_phrases` to translate, then resubmit with `prompt_text`+`phrases`.
+- `voice_id` is optional (defaults to the English house voice with a strong recommendation +
+  accent-matched suggestions to override); it's validated for EXISTENCE only — Retell voices expose
+  `accent`, not a language field, so the verification call is the real language-quality gate.
+- Per-language metadata persisted in `config.languages[primary]` ({agent_id, llm_id, voice_id,
+  language, display_name}); routing still uses `config.agents.by_lang[primary]`.
+- Idempotent: reuses an existing `generic_<primary>` agent; cleans up an orphan LLM if agent
+  creation fails; English is protected; writes are atomic + serialized; region variants collapse to
+  one agent per primary subtag.