callwright 1.0.0

package/learn-core.js

@@ -0,0 +1,257 @@
+// callwright — learning core (enrich existing scenario profiles AND stage
+// candidates for NEW profiles). Deterministic heuristics only; the JUDGMENT
+// calls the spec reserves for an LLM (canonicalize merge-vs-create,
+// propose-and-confirm) happen in the MCP layer / host LLM, not here.
+//
+// The one invariant (docs/profile-learning-spec.md): a profile stores SCHEMA
+// (field keys), never VALUES. Every guard here serves that invariant.
+
+// ---- agent-uncertainty signals (the agent deferring instead of answering) ----
+const DEFER_PATTERNS = [
+  /i'?m not sure/i, /i'?ll check with/i, /i will check with/i, /follow up/i,
+  /i don'?t (have|know)/i, /let me check with/i,
+];
+
+// Map a business question to a GENERALIZED profile field (heuristic; LLM refines).
+const QUESTION_TO_FIELD = [
+  { rx: /(type|kind|style) of (haircut|cut|service)|what (type|kind|service)/i, key: "service_type", why: "Type of service requested" },
+  { rx: /stylist|barber|who (will|would)|preferred (stylist|barber)/i, key: "stylist", why: "Preferred stylist/barber name" },
+  { rx: /how long|length of (your |the )?hair|hair length/i, key: "hair_length", why: "Current/target hair length" },
+  { rx: /new patient|been here before|existing patient|first (time|visit)/i, key: "new_or_existing", why: "New or existing patient" },
+  { rx: /insurance|provider|carrier/i, key: "insurance", why: "Insurance provider" },
+  { rx: /occasion|celebrat|birthday|anniversary/i, key: "occasion", why: "Special occasion, if any" },
+  { rx: /allerg|dietary|gluten|vegan|vegetarian/i, key: "dietary_notes", why: "Dietary restrictions/allergies" },
+  { rx: /destination|where (to|are you going)|drop.?off|going to/i, key: "destination", why: "Drop-off destination" },
+  { rx: /pick.?up (time|when)|what time.*pick|when.*pick.?up/i, key: "pickup_time", why: "Requested pickup time" },
+  { rx: /how many (people|passengers|in your party)|party size|number of (people|guests)/i, key: "party_size", why: "Number of people" },
+  { rx: /how (much )?luggage|how many (bags|suitcases)|baggage/i, key: "luggage", why: "Amount of luggage" },
+  { rx: /address|location|where (is it|do you live)|street|zip/i, key: "service_address", why: "Service/site address used to look up the appointment" },
+  { rx: /phone number|number on (the |your )?account|contact number|callback/i, key: "account_phone", why: "Phone number on the account for lookup" },
+];
+
+const WEEKDAYS = new Set(["monday","tuesday","wednesday","thursday","friday","saturday","sunday","mon","tue","wed","thu","fri","sat","sun"]);
+const MONTHS = new Set(["january","february","march","april","may","june","july","august","september","october","november","december","jan","feb","mar","apr","jun","jul","aug","sep","sept","oct","nov","dec"]);
+const CONNECTORS = new Set(["to","for","with","at","in","on","near","by","from","of"]);
+// Generic scenario tail-words that must NOT be stripped even after a connector.
+const KEEP_TAIL = new Set(["inquiry","reservation","booking","confirmation","appointment","service","request","call"]);
+
+// #1: reduce an instance-shaped call_type to its general scenario form.
+function generalizeCallType(callType) {
+  const raw = String(callType || "").toLowerCase().trim();
+  let tokens = raw.split(/[\s_\-]+/).filter(Boolean);
+  const stripped = [];
+  // Cut at the first connector preposition (e.g. "..._to_haneda") UNLESS what
+  // follows is a generic scenario word (e.g. "type_of_service").
+  const ci = tokens.findIndex((t, i) => i > 0 && CONNECTORS.has(t));
+  if (ci > 0) {
+    const tail = tokens.slice(ci + 1);
+    if (!tail.some((t) => KEEP_TAIL.has(t))) {
+      stripped.push(...tokens.slice(ci));
+      tokens = tokens.slice(0, ci);
+    }
+  }
+  // Drop pure numbers, dates, weekdays, months (instance values).
+  tokens = tokens.filter((t) => {
+    if (/^\d+$/.test(t) || /^\d{4}-\d{2}-\d{2}$/.test(t) || WEEKDAYS.has(t) || MONTHS.has(t)) { stripped.push(t); return false; }
+    return true;
+  });
+  const general = tokens.join("_");
+  return { general: general || raw, stripped, changed: stripped.length > 0 };
+}
+
+// #3: a "field" whose key/description bakes in a specific value is a value in
+// disguise — reject it from the profile (it belongs in the per-call job).
+function looksInstanceValued(key, description = "") {
+  const k = String(key || "");
+  const d = String(description || "");
+  if (/\d/.test(k)) return true;                                   // digits in a field key
+  if (/\d{4}-\d{2}-\d{2}/.test(d)) return true;                    // a date
+  if (/["'].+["']/.test(d)) return true;                          // a quoted literal
+  const segs = k.toLowerCase().split(/[_\-]+/).filter(Boolean);
+  // A generalized field is a short generic noun; >3 segments usually = value-baked.
+  if (segs.length > 3) return true;
+  // Trailing proper-noun-ish segment after a known generic head (destination_haneda).
+  const GENERIC_HEADS = new Set(["destination","party","date","time","name","stylist","location","address","city","airport"]);
+  if (segs.length >= 2 && GENERIC_HEADS.has(segs[0]) && !["size","type","range","window","preference","notes","time"].includes(segs[segs.length - 1])) {
+    return true;
+  }
+  return false;
+}
+
+function mapQuestionToField(question) {
+  return QUESTION_TO_FIELD.find((m) => m.rx.test(String(question || ""))) || null;
+}
+
+function parseTurns(transcript) {
+  const turns = [];
+  for (const line of String(transcript || "").split("\n")) {
+    const m = line.match(/^(Agent|User):\s?(.*)$/);
+    if (m) turns.push({ who: m[1], text: m[2] });
+    else if (turns.length) turns[turns.length - 1].text += " " + line.trim();
+  }
+  return turns;
+}
+
+// Detect moments the agent could not answer (deferred) + structured unanswered.
+function detectGaps(call) {
+  const turns = parseTurns(call && call.transcript);
+  const gaps = [];
+  for (let i = 0; i < turns.length; i++) {
+    const t = turns[i];
+    if (t.who !== "Agent" || !DEFER_PATTERNS.some((rx) => rx.test(t.text))) continue;
+    let q = null;
+    for (let j = i - 1; j >= 0; j--) { if (turns[j].who === "User") { q = turns[j].text; break; } }
+    if (q) gaps.push({ question: q.trim(), agent: t.text.trim() });
+  }
+  const ua = call && call.call_analysis && call.call_analysis.custom_analysis_data
+    && call.call_analysis.custom_analysis_data.unanswered_questions;
+  if (ua && String(ua).trim()) gaps.push({ question: String(ua).trim(), agent: "(post-call analysis)" });
+  return gaps;
+}
+
+// #2 (first pass): existing fuzzy name/alias match.
+function matchProfile(profiles, callType) {
+  const ct = String(callType || "").toLowerCase();
+  for (const [name, p] of Object.entries(profiles || {})) {
+    const keys = [name, ...((p && p.aliases) || [])].map((s) => s.toLowerCase());
+    if (keys.some((k) => ct === k || ct.includes(k) || k.includes(ct))) return name;
+  }
+  return null;
+}
+
+// Enrich an existing profile from gaps. value-rejection guard (#3) applied.
+// minCount (#4/#5): only PROMOTE a field to recommended_details once it has been
+// seen >= minCount times (across this profile's learned history + this call).
+// minCount=1 = promote on first sight (explicit/manual use); minCount>=2 =
+// noise-guard for autonomous/webhook use. Idempotent: a call_id already in the
+// learned log is skipped so a webhook redelivery can't double-count.
+function enrichProfile(profile, gaps, callId, { minCount = 1 } = {}) {
+  profile.recommended_details = profile.recommended_details || {};
+  profile.learned = profile.learned || [];
+  if (callId && profile.learned.some((e) => e.call_id === callId)) {
+    return { added: [], skipped: true };
+  }
+  // Prior occurrence counts from history.
+  const counts = {};
+  for (const e of profile.learned) if (e.mapped_field) counts[e.mapped_field] = (counts[e.mapped_field] || 0) + 1;
+  const added = [];
+  for (const g of gaps || []) {
+    const map = mapQuestionToField(g.question);
+    const key = map && map.key;
+    if (!key) {
+      profile.learned.push({ call_id: callId, question: g.question, mapped_field: null, at: new Date().toISOString() });
+      continue;
+    }
+    if (looksInstanceValued(key, map.why)) {
+      profile.learned.push({ call_id: callId, question: g.question, mapped_field: null, rejected: "instance_valued", at: new Date().toISOString() });
+      continue;
+    }
+    profile.learned.push({ call_id: callId, question: g.question, mapped_field: key, at: new Date().toISOString() });
+    counts[key] = (counts[key] || 0) + 1;
+    if (!profile.recommended_details[key] && counts[key] >= minCount) {
+      profile.recommended_details[key] = map.why;
+      added.push(key);
+    }
+  }
+  return { added };
+}
+
+// #4: stage an unmatched (generalized) call_type; promote at N occurrences.
+function stageCandidate(store, generalType, { callId, variant, gaps } = {}, N = 2) {
+  const now = new Date().toISOString();
+  const c = store[generalType] || { count: 0, examples: [], variants: [], questions: {}, first_seen: now, last_seen: now, proposed: false };
+  const isNewCall = callId && !c.examples.includes(callId);
+  if (isNewCall) { c.count += 1; c.examples.push(callId); }
+  if (variant && !c.variants.includes(variant)) c.variants.push(variant);
+  for (const g of gaps || []) {
+    const map = mapQuestionToField(g.question);
+    const fkey = map && map.key ? map.key : ("q:" + slug(g.question));
+    const why = map && map.why ? map.why : g.question;
+    const q = c.questions[fkey] || { count: 0, why, mapped: !!(map && map.key), examples: [] };
+    // only count once per call for a given field
+    if (isNewCall) q.count += 1;
+    if (q.examples.length < 3 && !q.examples.includes(g.question)) q.examples.push(g.question);
+    c.questions[fkey] = q;
+  }
+  c.last_seen = now;
+  store[generalType] = c;
+  return { candidate: c, ready: c.count >= N && !c.proposed };
+}
+
+function slug(s) {
+  return String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 40);
+}
+
+// Build a propose-and-confirm proposal from a ready candidate.
+function buildProposal(generalType, candidate, N = 2) {
+  const recommended = {};
+  const weak = {};
+  for (const [fkey, q] of Object.entries((candidate && candidate.questions) || {})) {
+    if (fkey.startsWith("q:") || !q.mapped) { weak[fkey] = q.why; continue; }     // unmapped -> weak suggestion
+    if (q.count >= N && !looksInstanceValued(fkey, q.why)) recommended[fkey] = q.why;
+    else weak[fkey] = q.why;
+  }
+  const aliases = ((candidate && candidate.variants) || []).filter((v) => v && v !== generalType);
+  return {
+    name: generalType,
+    aliases,
+    recommended_details: recommended,
+    weak_candidates: weak,
+    seen: (candidate && candidate.count) || 0,
+    examples: (candidate && candidate.examples) || [],
+  };
+}
+
+// #1 + collision: validate a proposed NEW profile before creation.
+function validateNewProfile(name, profiles = {}, recommended_details = {}) {
+  const errors = [];
+  const n = String(name || "").toLowerCase().trim();
+  if (!/^[a-z][a-z0-9_]{1,40}$/.test(n)) errors.push(`Invalid profile name "${name}" (use snake_case, no spaces/values).`);
+  const gen = generalizeCallType(n);
+  if (gen.changed) errors.push(`"${name}" looks instance-shaped (embeds ${gen.stripped.join(", ")}). Use the general form "${gen.general}" and route the specific part into the per-call job.`);
+  // collision: name or alias already exists
+  let collision = null;
+  for (const [pname, p] of Object.entries(profiles || {})) {
+    const keys = [pname, ...((p && p.aliases) || [])].map((s) => s.toLowerCase());
+    if (keys.includes(n)) { collision = pname; break; }
+  }
+  for (const [k, why] of Object.entries(recommended_details || {})) {
+    if (looksInstanceValued(k, why)) errors.push(`recommended_details key "${k}" looks value-baked; use a generalized field name.`);
+  }
+  return { ok: errors.length === 0 && !collision, errors, collision };
+}
+
+// Shared orchestrator used by BOTH the MCP learn_from_call tool and the webhook
+// auto-learn path. Mutates the passed profiles/candidates; the caller persists.
+// callType comes from the arg or the call's round-tripped dynamic variable.
+function applyLearning(call, { profiles, candidates, callType, minCount = 1, N = 2 } = {}) {
+  const ct = String(
+    callType || (call && call.retell_llm_dynamic_variables && call.retell_llm_dynamic_variables.call_type) || ""
+  ).toLowerCase();
+  const callId = call && call.call_id;
+  const gaps = detectGaps(call);
+  if (!ct) return { mode: "skip", reason: "no_call_type", gaps: gaps.map((g) => g.question) };
+  if (!gaps.length) return { mode: "skip", reason: "no_gaps", call_type: ct };
+
+  const profKey = matchProfile(profiles || {}, ct);
+  if (profKey) {
+    const r = enrichProfile(profiles[profKey], gaps, callId, { minCount });
+    return { mode: "enriched", profile: profKey, added: r.added || [], skipped: r.skipped || false, gaps: gaps.map((g) => g.question) };
+  }
+  const { general, changed, stripped } = generalizeCallType(ct);
+  const { candidate, ready } = stageCandidate(candidates || {}, general, { callId, variant: ct, gaps }, N);
+  const out = {
+    mode: "staged", scenario: general,
+    generalized_from: changed ? { original: ct, stripped } : undefined,
+    seen: candidate.count, ready_to_propose: ready, gaps: gaps.map((g) => g.question),
+  };
+  if (ready) out.proposal = buildProposal(general, candidate, N);
+  return out;
+}
+
+module.exports = {
+  DEFER_PATTERNS, QUESTION_TO_FIELD,
+  generalizeCallType, looksInstanceValued, mapQuestionToField,
+  parseTurns, detectGaps, matchProfile, enrichProfile,
+  stageCandidate, buildProposal, validateNewProfile, slug, applyLearning,
+};

package/learn.js

@@ -0,0 +1,65 @@
+// Learning loop CLI — enrich a scenario profile (or stage a candidate for a NEW
+// profile) from a completed call. Thin wrapper over learn-core.js.
+//
+//   node learn.js <call_id> <call_type>
+//
+// Env: RETELL_API_KEY
+
+const fs = require("fs");
+const { PROFILES_PATH, CANDIDATES_PATH } = require("./paths");
+const L = require("./learn-core");
+
+const API_KEY = process.env.RETELL_API_KEY;
+if (!API_KEY) { console.error("Missing RETELL_API_KEY."); process.exit(1); }
+
+const callId = process.argv[2];
+const callType = (process.argv[3] || "").toLowerCase();
+if (!callId || !callType) {
+  console.error("Usage: node learn.js <call_id> <call_type>");
+  process.exit(1);
+}
+
+function loadJson(p, fb) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; } }
+
+async function getCall() {
+  const r = await fetch(`https://api.retellai.com/v2/get-call/${callId}`, {
+    headers: { Authorization: `Bearer ${API_KEY}` },
+  });
+  if (!r.ok) throw new Error(`get-call -> ${r.status}\n${await r.text()}`);
+  return r.json();
+}
+
+(async () => {
+  const call = await getCall();
+  const gaps = L.detectGaps(call);
+
+  if (!gaps.length) {
+    console.log("No unanswered-question gaps detected in this call. Nothing to learn.");
+    return;
+  }
+  console.log(`Detected ${gaps.length} gap(s) where the agent could not answer:`);
+  gaps.forEach((g, i) => console.log(`  ${i + 1}. Business asked: "${g.question}"`));
+
+  const profiles = loadJson(PROFILES_PATH, {});
+  const profKey = L.matchProfile(profiles, callType);
+
+  if (profKey) {
+    const r = L.enrichProfile(profiles[profKey], gaps, callId);
+    fs.writeFileSync(PROFILES_PATH, JSON.stringify(profiles, null, 2) + "\n");
+    console.log(`\nProfile "${profKey}" enriched (${r.added.length} new field(s): ${r.added.join(", ") || "none"}).`);
+    return;
+  }
+
+  // No profile -> stage a candidate for possible NEW-profile creation (N>=2).
+  const { general } = L.generalizeCallType(callType);
+  const candidates = loadJson(CANDIDATES_PATH, {});
+  const { candidate, ready } = L.stageCandidate(candidates, general, { callId, variant: callType, gaps }, 2);
+  fs.writeFileSync(CANDIDATES_PATH, JSON.stringify(candidates, null, 2) + "\n");
+  console.log(`\nNo profile matches "${callType}". Staged candidate "${general}" (seen ${candidate.count}x).`);
+  if (ready) {
+    const proposal = L.buildProposal(general, candidate, 2);
+    console.log("READY for proposal:", JSON.stringify(proposal, null, 2));
+  } else {
+    console.log("Not yet promoted (needs to be seen >= 2 times).");
+  }
+})().catch((e) => { console.error("\nFailed:\n" + e.message); process.exit(1); });

package/notify-core.js

@@ -0,0 +1,113 @@
+// callwright — notification core. Per-call, opt-in SMS ("notify me when it's
+// done") via Retell's outbound SMS (create-sms-chat). The DEFAULT remains
+// pull-on-demand (get_call_outcome); SMS only fires when a call explicitly
+// requested it (notify_sms round-tripped in the dynamic vars).
+//
+// Retell SMS requires a CHAT-mode agent; we provision a tiny "summary notifier"
+// chat agent once and cache its id in config.notify.sms. The from_number must be
+// a Retell number with SMS capability (KYC-gated).
+
+const setup = require("./setup-core");
+
+const SMS_AGENT_PROMPT =
+  "You are an SMS notifier for a personal assistant. Your ONLY job is to send a single " +
+  "text message containing exactly the notification provided in the variable {{summary}}. " +
+  "Send {{summary}} verbatim — no greeting, no sign-off, no extra words, and never ask a " +
+  "question. After sending that one message you are done; if the recipient replies, do not " +
+  "continue the conversation beyond a brief 'Thanks, noted.'";
+
+const STATUS_EMOJI = { booked: "✅", failed: "❌", voicemail: "📭", callback_needed: "↩️", escalated: "⚠️", completed: "✅" };
+
+// Build a concise one-line SMS summary of a finished call. Pure.
+function buildCallSms(call) {
+  const v = (call && call.retell_llm_dynamic_variables) || {};
+  const a = (call && call.call_analysis) || {};
+  const c = a.custom_analysis_data || {};
+  const business = v.business_name || (call && call.to_number) || "the business";
+  const objective = v.objective || v.objective_detail || "";
+  const status = c.status || (a.call_successful === false ? "failed" : (a.call_successful ? "completed" : "completed"));
+  const emoji = STATUS_EMOJI[status] || "📞";
+
+  const phrase = {
+    booked: "booked", completed: "done", voicemail: "left a voicemail",
+    callback_needed: "callback needed", escalated: "escalated", failed: "not completed",
+  }[status] || status;
+
+  const details = [];
+  const when = `${c.booked_date || ""} ${c.booked_time || ""}`.trim();
+  if (when) details.push(when);
+  if (c.confirmation_ref) details.push(`conf ${c.confirmation_ref}`);
+
+  let msg = `${emoji} ${business}${objective ? ` (${objective})` : ""}: ${phrase}`;
+  if (details.length) msg += ` — ${details.join(", ")}`;
+  msg += ".";
+  return msg.slice(0, 320);
+}
+
+// Read the per-call notify intent off the round-tripped dynamic vars. Pure.
+function shouldNotify(call) {
+  const v = (call && call.retell_llm_dynamic_variables) || {};
+  if (String(v.notify_sms || "") !== "1") return { notify: false };
+  return { notify: true, to: v.notify_to || "" };
+}
+
+const defaultApi = (key) => (m, p, b) => setup.apiCall(key, m, p, b);
+
+// Provision (or reuse) the SMS summary chat agent. Mutates `smsCfg` with the ids
+// and returns whether it created a new one.
+async function ensureSmsAgent(api, smsCfg = {}) {
+  if (smsCfg.chat_agent_id) return { chat_agent_id: smsCfg.chat_agent_id, chat_llm_id: smsCfg.chat_llm_id, created: false };
+  const llm = await api("POST", "/create-retell-llm", { general_prompt: SMS_AGENT_PROMPT });
+  const agent = await api("POST", "/create-chat-agent", {
+    response_engine: { type: "retell-llm", llm_id: llm.llm_id },
+    agent_name: "callwright_sms_notifier",
+  });
+  smsCfg.chat_agent_id = agent.agent_id;
+  smsCfg.chat_llm_id = llm.llm_id;
+  return { chat_agent_id: agent.agent_id, chat_llm_id: llm.llm_id, created: true };
+}
+
+// Orchestrate a per-call SMS notification. Mutates `config` if it provisions the
+// agent (caller persists when configChanged). Retell calls are injectable.
+async function notifyCall(call, { config, api, key, to: forceTo, force = false } = {}) {
+  api = api || defaultApi(key);
+  const want = force ? { notify: true, to: forceTo } : shouldNotify(call);
+  if (!want.notify) return { sent: false, reason: "not_requested" };
+
+  const smsCfg = (config.notify && config.notify.sms) || {};
+  const to = want.to || forceTo || smsCfg.to || (config.principal && config.principal.callback_number) || "";
+  if (!to) return { sent: false, reason: "no_number" };
+  if (!force && call && call.to_number && call.to_number === to) return { sent: false, reason: "self_call" };
+
+  const fromNumber = smsCfg.from_number || (config.retell && config.retell.from_number);
+  if (!fromNumber) return { sent: false, reason: "no_from_number" };
+
+  let configChanged = false;
+  try {
+    config.notify = config.notify || {};
+    config.notify.sms = config.notify.sms || {};
+    const ens = await ensureSmsAgent(api, config.notify.sms);
+    if (ens.created) configChanged = true;
+
+    const summary = buildCallSms(call);
+    const resp = await api("POST", "/create-sms-chat", {
+      from_number: fromNumber,
+      to_number: to,
+      override_agent_id: config.notify.sms.chat_agent_id,
+      retell_llm_dynamic_variables: { summary },
+      metadata: { parent_call_id: call && call.call_id, kind: "call_notification" },
+    });
+    return { sent: true, to, from: fromNumber, chat_id: resp.chat_id || resp.chat_session_id || null, summary, configChanged };
+  } catch (e) {
+    const msg = e.message || String(e);
+    if (/a2p/i.test(msg)) {
+      return { sent: false, reason: "needs_a2p_registration", error: msg, configChanged,
+        hint: `The from-number ${fromNumber} is not registered for A2P 10DLC SMS. Complete A2P brand+campaign registration for this number in the Retell dashboard (or use configure_notifications from_number with an already SMS-registered number). This is a US carrier requirement, separate from voice; no code change is needed once registered.` };
+    }
+    return { sent: false, reason: "send_failed", error: msg, configChanged };
+  }
+}
+
+module.exports = {
+  SMS_AGENT_PROMPT, buildCallSms, shouldNotify, ensureSmsAgent, notifyCall,
+};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "callwright",
+  "version": "1.0.0",
+  "description": "A voice agent that places phone calls (reservations, appointments, inquiries) on your behalf, shaped by LLM direction + grounding. Runs fire-and-forget on Retell; an MCP server lets an LLM shape the grounding before each call.",
+  "main": "server.js",
+  "bin": {
+    "callwright": "server.js",
+    "callwright-init": "init.js"
+  },
+  "files": [
+    "server.js",
+    "init.js",
+    "dispatch-core.js",
+    "dispatch.js",
+    "get-call.js",
+    "lang-core.js",
+    "learn-core.js",
+    "learn.js",
+    "notify-core.js",
+    "paths.js",
+    "retry-core.js",
+    "setup-agent-from.js",
+    "setup-core.js",
+    "update-prompt.js",
+    "generic-prompt.md",
+    "generic-prompt.ja.md",
+    "place_call.schema.json",
+    "scenario-profiles.json",
+    "lang-phrases.json",
+    "config.example.json",
+    "grounding.example.json",
+    ".env.example",
+    "Dockerfile",
+    "fly.toml",
+    ".dockerignore",
+    "providers/",
+    "webhook/",
+    "examples/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "init": "node init.js",
+    "status": "node init.js status",
+    "test": "node --test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "retell",
+    "voice-agent",
+    "phone-calls"
+  ],
+  "author": "topness-msft",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topness-msft/callwright.git"
+  },
+  "homepage": "https://github.com/topness-msft/callwright#readme",
+  "bugs": {
+    "url": "https://github.com/topness-msft/callwright/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "express": "^4.21.0",
+    "retell-sdk": "^4.66.0"
+  }
+}

package/paths.js

@@ -0,0 +1,37 @@
+// Centralized paths for the MUTABLE state files, so they can live on a
+// persistent volume when hosted. Static assets (prompts, schema) stay in the
+// app dir and are loaded relative to cwd as before.
+//
+// Set CALLWRIGHT_DATA_DIR (e.g. /data on a Fly volume) to relocate state.
+// VIRTUPHIL_DATA_DIR is accepted as a legacy fallback. Defaults to "." so
+// local/dev behavior is unchanged.
+
+const path = require("path");
+const fs = require("fs");
+
+const DATA_DIR =
+  process.env.CALLWRIGHT_DATA_DIR || process.env.VIRTUPHIL_DATA_DIR || ".";
+
+// Path to a file on the persistent volume (where runtime-added assets live).
+function volumePath(file) { return path.join(DATA_DIR, file); }
+
+// Volume-first asset resolution: prefer a volume copy (e.g. a runtime-added
+// language's prompt) and fall back to the image-baked file. Used for assets
+// that may be added at runtime but ship with seeds (prompts, lang-phrases).
+function resolveAsset(file) {
+  if (DATA_DIR !== ".") {
+    try { const v = volumePath(file); if (fs.existsSync(v)) return v; } catch { /* ignore */ }
+  }
+  return file;
+}
+
+module.exports = {
+  DATA_DIR,
+  CONFIG_PATH: path.join(DATA_DIR, "config.json"),
+  AGENTS_PATH: path.join(DATA_DIR, "agents.json"),
+  PROFILES_PATH: path.join(DATA_DIR, "scenario-profiles.json"),
+  CANDIDATES_PATH: path.join(DATA_DIR, "scenario-candidates.json"),
+  RETRIES_PATH: path.join(DATA_DIR, "retries.json"),
+  volumePath,
+  resolveAsset,
+};