@agenticmail/core 0.9.13 → 0.9.14

package/dist/index.js

@@ -6225,8 +6225,969 @@ var RELAY_PRESETS = {
   }
 };
 
+// src/phone/realtime.ts
+var ELKS_REALTIME_AUDIO_FORMATS = ["ulaw", "pcm_16000", "pcm_24000", "wav"];
+function asRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asString2(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function isAudioFormat(value) {
+  return typeof value === "string" && ELKS_REALTIME_AUDIO_FORMATS.includes(value);
+}
+function assertAudioFormat(format) {
+  if (!isAudioFormat(format)) {
+    throw new Error(`Unsupported 46elks realtime audio format: ${String(format)}`);
+  }
+  return format;
+}
+function looksLikeBase64(value) {
+  return value.length > 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(value) && value.length % 4 === 0;
+}
+function decodeJsonMessage(input) {
+  if (typeof input === "string") {
+    try {
+      return asRecord(JSON.parse(input));
+    } catch {
+      throw new Error("Invalid 46elks realtime message: expected JSON object string");
+    }
+  }
+  return asRecord(input);
+}
+function parseElksRealtimeMessage(input) {
+  const msg = decodeJsonMessage(input);
+  const type = asString2(msg.t);
+  if (type === "hello") {
+    const callid = asString2(msg.callid);
+    const from = asString2(msg.from);
+    const to = asString2(msg.to);
+    if (!callid || !from || !to) {
+      throw new Error("Invalid 46elks realtime hello: callid, from, and to are required");
+    }
+    return { ...msg, t: "hello", callid, from, to };
+  }
+  if (type === "audio") {
+    const data = asString2(msg.data);
+    if (!looksLikeBase64(data)) {
+      throw new Error("Invalid 46elks realtime audio: data must be non-empty base64");
+    }
+    return { t: "audio", data };
+  }
+  if (type === "bye") {
+    const reason = asString2(msg.reason) || void 0;
+    const message = asString2(msg.message) || void 0;
+    return { ...msg, t: "bye", reason, message };
+  }
+  throw new Error(`Unsupported 46elks realtime message type: ${type || "(missing)"}`);
+}
+function buildElksListeningMessage(format = "pcm_24000") {
+  return { t: "listening", format: assertAudioFormat(format) };
+}
+function buildElksSendingMessage(format = "pcm_24000") {
+  return { t: "sending", format: assertAudioFormat(format) };
+}
+function buildElksAudioMessage(data) {
+  const encoded = typeof data === "string" ? data : Buffer.from(data).toString("base64");
+  if (!looksLikeBase64(encoded)) {
+    throw new Error("46elks realtime audio data must be base64 or bytes");
+  }
+  return { t: "audio", data: encoded };
+}
+function buildElksInterruptMessage() {
+  return { t: "interrupt" };
+}
+function buildElksByeMessage() {
+  return { t: "bye" };
+}
+function buildElksHandshakeMessages(options = {}) {
+  return [
+    buildElksListeningMessage(options.listenFormat ?? "pcm_24000"),
+    buildElksSendingMessage(options.sendFormat ?? "pcm_24000")
+  ];
+}
+
+// src/phone/manager.ts
+import { createHash as createHash2, createHmac, randomUUID, timingSafeEqual } from "crypto";
+
+// src/phone/mission.ts
+var PHONE_REGION_SCOPES = ["AT", "DE", "EU", "WORLD"];
+var TELEPHONY_TRANSPORT_CAPABILITIES = [
+  "sms",
+  "call_control",
+  "realtime_media",
+  "recording_supported"
+];
+var PHONE_MISSION_STATES = [
+  "draft",
+  "approved",
+  "dialing",
+  "connected",
+  "conversing",
+  "needs_operator",
+  "completed",
+  "failed",
+  "cancelled"
+];
+var PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+var PHONE_SERVER_MAX_COST_PER_MISSION = 5;
+var PHONE_SERVER_MAX_ATTEMPTS = 3;
+var PHONE_TASK_MAX_LENGTH = 2e3;
+var EU_DIAL_PREFIXES = [
+  "+30",
+  "+31",
+  "+32",
+  "+33",
+  "+34",
+  "+351",
+  "+352",
+  "+353",
+  "+354",
+  "+356",
+  "+357",
+  "+358",
+  "+359",
+  "+36",
+  "+370",
+  "+371",
+  "+372",
+  "+385",
+  "+386",
+  "+39",
+  "+40",
+  "+420",
+  "+421",
+  "+43",
+  "+45",
+  "+46",
+  "+48",
+  "+49"
+];
+var PREMIUM_OR_SPECIAL_PREFIXES = [
+  "+1900",
+  "+1976",
+  "+43810",
+  "+43820",
+  "+43821",
+  "+43828",
+  "+43900",
+  "+43901",
+  "+43930",
+  "+43931",
+  "+49190",
+  "+49900"
+];
+function issue(code, field, message) {
+  return { code, field, message };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isPhoneRegionScope(value) {
+  return typeof value === "string" && PHONE_REGION_SCOPES.includes(value);
+}
+function isTelephonyTransportCapability(value) {
+  return typeof value === "string" && TELEPHONY_TRANSPORT_CAPABILITIES.includes(value);
+}
+function readPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+function readNonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function readBoolean(value) {
+  return typeof value === "boolean" ? value : null;
+}
+function readRegionList(value) {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const regions = value.filter(isPhoneRegionScope);
+  if (regions.length !== value.length) return null;
+  return Array.from(new Set(regions));
+}
+function readCapabilityList(value) {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const capabilities = value.filter(isTelephonyTransportCapability);
+  if (capabilities.length !== value.length) return null;
+  return Array.from(new Set(capabilities));
+}
+function validateConfirmPolicy(value) {
+  const issues = [];
+  if (!isRecord(value)) {
+    return [issue("confirm-policy-required", "policy.confirmPolicy", "confirmPolicy is required")];
+  }
+  const required = {
+    paymentDetails: "never",
+    contractCommitment: "never",
+    costOverLimit: "needs_operator",
+    sensitivePersonalData: "needs_operator",
+    unclearAlternative: "needs_operator"
+  };
+  for (const [field, expected] of Object.entries(required)) {
+    if (value[field] !== expected) {
+      issues.push(issue(
+        "unsafe-confirm-policy",
+        `policy.confirmPolicy.${field}`,
+        `${field} must be ${expected}`
+      ));
+    }
+  }
+  return issues;
+}
+function validateAlternativePolicy(value) {
+  if (!isRecord(value)) {
+    return [issue("alternative-policy-required", "policy.alternativePolicy", "alternativePolicy is required")];
+  }
+  const maxTimeShiftMinutes = readNonNegativeNumber(value.maxTimeShiftMinutes);
+  if (maxTimeShiftMinutes === null || !Number.isInteger(maxTimeShiftMinutes)) {
+    return [issue(
+      "invalid-alternative-policy",
+      "policy.alternativePolicy.maxTimeShiftMinutes",
+      "maxTimeShiftMinutes must be a non-negative integer"
+    )];
+  }
+  return [];
+}
+function validatePhoneMissionPolicy(policy) {
+  const issues = [];
+  if (!isRecord(policy)) {
+    return { ok: false, issues: [issue("policy-required", "policy", "policy is required")] };
+  }
+  if (policy.policyVersion !== 1) {
+    issues.push(issue("unsupported-policy-version", "policy.policyVersion", "policyVersion must be 1"));
+  }
+  const regionAllowlist = readRegionList(policy.regionAllowlist);
+  if (!regionAllowlist) {
+    issues.push(issue("invalid-region-allowlist", "policy.regionAllowlist", "regionAllowlist must contain at least one supported region"));
+  }
+  const maxCallDurationSeconds = readPositiveInteger(policy.maxCallDurationSeconds);
+  if (maxCallDurationSeconds === null) {
+    issues.push(issue("invalid-max-duration", "policy.maxCallDurationSeconds", "maxCallDurationSeconds must be a positive integer"));
+  }
+  const maxCostPerMission = readNonNegativeNumber(policy.maxCostPerMission);
+  if (maxCostPerMission === null) {
+    issues.push(issue("invalid-max-cost", "policy.maxCostPerMission", "maxCostPerMission must be a non-negative number"));
+  }
+  const maxAttempts = readPositiveInteger(policy.maxAttempts);
+  if (maxAttempts === null) {
+    issues.push(issue("invalid-max-attempts", "policy.maxAttempts", "maxAttempts must be a positive integer"));
+  }
+  const transcriptEnabled = readBoolean(policy.transcriptEnabled);
+  if (transcriptEnabled === null) {
+    issues.push(issue("invalid-transcript-enabled", "policy.transcriptEnabled", "transcriptEnabled must be boolean"));
+  }
+  const recordingEnabled = readBoolean(policy.recordingEnabled);
+  if (recordingEnabled === null) {
+    issues.push(issue("invalid-recording-enabled", "policy.recordingEnabled", "recordingEnabled must be boolean"));
+  }
+  issues.push(...validateConfirmPolicy(policy.confirmPolicy));
+  issues.push(...validateAlternativePolicy(policy.alternativePolicy));
+  if (issues.length > 0) return { ok: false, issues };
+  return {
+    ok: true,
+    policy: {
+      policyVersion: 1,
+      regionAllowlist,
+      maxCallDurationSeconds: Math.min(maxCallDurationSeconds, PHONE_SERVER_MAX_CALL_DURATION_SECONDS),
+      maxCostPerMission: Math.min(maxCostPerMission, PHONE_SERVER_MAX_COST_PER_MISSION),
+      maxAttempts: Math.min(maxAttempts, PHONE_SERVER_MAX_ATTEMPTS),
+      transcriptEnabled,
+      recordingEnabled,
+      confirmPolicy: policy.confirmPolicy,
+      alternativePolicy: {
+        maxTimeShiftMinutes: policy.alternativePolicy.maxTimeShiftMinutes
+      }
+    },
+    issues: []
+  };
+}
+function validatePhoneTransportProfile(transport) {
+  const issues = [];
+  if (!isRecord(transport)) {
+    return { ok: false, issues: [issue("transport-required", "transport", "transport profile is required")] };
+  }
+  const provider = typeof transport.provider === "string" ? transport.provider.trim() : "";
+  if (!provider) {
+    issues.push(issue("invalid-provider", "transport.provider", "provider is required"));
+  }
+  const phoneNumber = typeof transport.phoneNumber === "string" ? normalizePhoneNumber(transport.phoneNumber) : null;
+  if (!phoneNumber) {
+    issues.push(issue("invalid-transport-number", "transport.phoneNumber", "transport phoneNumber must be valid E.164"));
+  }
+  const capabilities = readCapabilityList(transport.capabilities);
+  if (!capabilities) {
+    issues.push(issue("invalid-capabilities", "transport.capabilities", "capabilities must contain supported transport capabilities"));
+  } else if (!capabilities.includes("call_control")) {
+    issues.push(issue("missing-call-control", "transport.capabilities", "transport must support call_control to start phone missions"));
+  }
+  const supportedRegions = readRegionList(transport.supportedRegions);
+  if (!supportedRegions) {
+    issues.push(issue("invalid-supported-regions", "transport.supportedRegions", "supportedRegions must contain at least one supported region"));
+  }
+  if (issues.length > 0) return { ok: false, issues };
+  return {
+    ok: true,
+    transport: {
+      provider,
+      phoneNumber,
+      capabilities,
+      supportedRegions
+    },
+    issues: []
+  };
+}
+function inferPhoneRegion(phoneNumber) {
+  const normalized = normalizePhoneNumber(phoneNumber);
+  if (!normalized) return null;
+  if (normalized.startsWith("+43")) return "AT";
+  if (normalized.startsWith("+49")) return "DE";
+  if (EU_DIAL_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return "EU";
+  return "WORLD";
+}
+function isPhoneRegionAllowed(region, allowlist) {
+  if (allowlist.includes("WORLD")) return true;
+  if (allowlist.includes(region)) return true;
+  if ((region === "AT" || region === "DE" || region === "EU") && allowlist.includes("EU")) return true;
+  return false;
+}
+function classifyPhoneNumberRisk(phoneNumber) {
+  const normalized = normalizePhoneNumber(phoneNumber);
+  if (!normalized) return "invalid";
+  if (PREMIUM_OR_SPECIAL_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+    return "premium_or_special";
+  }
+  return "standard";
+}
+function validatePhoneMissionStart(input, transport, options = {}) {
+  const issues = [];
+  if (!isRecord(input)) {
+    return { ok: false, issues: [issue("start-input-required", "input", "start input is required")] };
+  }
+  const to = typeof input.to === "string" ? normalizePhoneNumber(input.to) : null;
+  if (!to) {
+    issues.push(issue("invalid-target-number", "input.to", "target number must be valid E.164"));
+  }
+  const rawTask = typeof input.task === "string" ? input.task : "";
+  const task = rawTask.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "").trim();
+  if (!task) {
+    issues.push(issue("task-required", "input.task", "task is required"));
+  } else if (task.length > PHONE_TASK_MAX_LENGTH) {
+    issues.push(issue("task-too-long", "input.task", `task must be ${PHONE_TASK_MAX_LENGTH} characters or fewer`));
+  }
+  const policyResult = validatePhoneMissionPolicy(input.policy);
+  if (!policyResult.ok) issues.push(...policyResult.issues);
+  const transportResult = validatePhoneTransportProfile(transport);
+  if (!transportResult.ok) issues.push(...transportResult.issues);
+  const risk = typeof input.to === "string" ? classifyPhoneNumberRisk(input.to) : "invalid";
+  if (risk === "premium_or_special" && !options.allowPremiumOrSpecialNumbers) {
+    issues.push(issue("premium-number-blocked", "input.to", "premium or special-rate numbers require an explicit allowlist"));
+  }
+  const targetRegion = to ? inferPhoneRegion(to) : null;
+  if (!targetRegion) {
+    issues.push(issue("unknown-target-region", "input.to", "target region could not be inferred"));
+  }
+  if (policyResult.ok && targetRegion && !isPhoneRegionAllowed(targetRegion, policyResult.policy.regionAllowlist)) {
+    issues.push(issue("region-not-allowed", "input.to", "target number is outside the mission policy regionAllowlist"));
+  }
+  if (transportResult.ok && targetRegion && !isPhoneRegionAllowed(targetRegion, transportResult.transport.supportedRegions)) {
+    issues.push(issue("transport-region-unsupported", "transport.supportedRegions", "target number is outside the transport supportedRegions"));
+  }
+  const capabilities = transportResult.ok ? transportResult.transport.capabilities : [];
+  if (policyResult.ok && policyResult.policy.recordingEnabled && !capabilities.includes("recording_supported")) {
+    issues.push(issue("recording-unsupported", "policy.recordingEnabled", "recordingEnabled requires transport recording_supported capability"));
+  }
+  if (issues.length > 0 || !policyResult.ok || !transportResult.ok || !to || !targetRegion) {
+    return { ok: false, issues };
+  }
+  return {
+    ok: true,
+    mission: {
+      to,
+      task,
+      policy: policyResult.policy,
+      targetRegion,
+      transport: transportResult.transport,
+      voiceRuntimeRef: typeof input.voiceRuntimeRef === "string" && input.voiceRuntimeRef.trim() ? input.voiceRuntimeRef.trim() : void 0
+    },
+    issues: []
+  };
+}
+
+// src/phone/manager.ts
+var PHONE_RATE_LIMIT_PER_MINUTE = 5;
+var PHONE_RATE_LIMIT_PER_HOUR = 30;
+var PHONE_MAX_CONCURRENT_MISSIONS = 3;
+var PHONE_MIN_WEBHOOK_SECRET_LENGTH = 24;
+var TERMINAL_MISSION_STATES = ["completed", "failed", "cancelled"];
+var PhoneWebhookAuthError = class extends Error {
+  isPhoneWebhookAuthError = true;
+  constructor() {
+    super("Invalid phone webhook request");
+    this.name = "PhoneWebhookAuthError";
+  }
+};
+var PhoneRateLimitError = class extends Error {
+  isPhoneRateLimitError = true;
+  constructor(message) {
+    super(message);
+    this.name = "PhoneRateLimitError";
+  }
+};
+var PHONE_SECRET_FIELDS = ["password", "webhookSecret"];
+var MAX_PHONE_WEBHOOK_EVENT_KEYS = 50;
+function asString3(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function asRecord2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function defaultApiUrl2(config) {
+  const url = (config.apiUrl || "https://api.46elks.com/a1").replace(/\/+$/, "");
+  if (!/^https:\/\//i.test(url)) {
+    throw new Error("46elks apiUrl must use https:// \u2014 refusing to send credentials over a non-TLS connection");
+  }
+  return url;
+}
+function basicAuth2(username, password) {
+  return Buffer.from(`${username}:${password}`, "utf8").toString("base64");
+}
+function secretMatches(provided, expected) {
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function apiBaseUrl(webhookBaseUrl) {
+  const root = webhookBaseUrl.replace(/\/+$/, "");
+  return root.endsWith("/api/agenticmail") ? root : `${root}/api/agenticmail`;
+}
+function webhookToken(webhookSecret, missionId) {
+  return createHmac("sha256", webhookSecret).update(missionId).digest("hex");
+}
+function buildWebhookUrl(config, path2, missionId) {
+  const url = new URL(`${apiBaseUrl(config.webhookBaseUrl)}${path2}`);
+  url.searchParams.set("missionId", missionId);
+  url.searchParams.set("token", webhookToken(config.webhookSecret, missionId));
+  return url.toString();
+}
+function redactWebhookUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.searchParams.has("token")) url.searchParams.set("token", "***");
+    if (url.searchParams.has("secret")) url.searchParams.set("secret", "***");
+    return url.toString();
+  } catch {
+    return "[redacted-url]";
+  }
+}
+function redactProviderRequest(request) {
+  return {
+    url: request.url,
+    body: {
+      ...request.body,
+      voice_start: redactWebhookUrl(request.body.voice_start),
+      whenhangup: redactWebhookUrl(request.body.whenhangup)
+    }
+  };
+}
+function stableFlatJson(value) {
+  return JSON.stringify(Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))));
+}
+function phoneWebhookEventKey(kind, payload) {
+  const callId = asString3(payload.callid) || asString3(payload.id) || asString3(payload.call_id);
+  const result = asString3(payload.result) || asString3(payload.status) || asString3(payload.why);
+  const fingerprint = createHash2("sha256").update(stableFlatJson(payload)).digest("hex").slice(0, 16);
+  return [kind, callId || fingerprint, result].filter(Boolean).join(":");
+}
+function processedWebhookEventKeys(mission) {
+  const value = mission.metadata.phoneWebhookEvents;
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function hasProcessedWebhookEvent(mission, eventKey) {
+  return processedWebhookEventKeys(mission).includes(eventKey);
+}
+function appendProcessedWebhookEvent(mission, eventKey) {
+  return [...processedWebhookEventKeys(mission), eventKey].slice(-MAX_PHONE_WEBHOOK_EVENT_KEYS);
+}
+function parseJson(value, fallback) {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+function rowToMission(row) {
+  return {
+    id: row.id,
+    agentId: row.agent_id,
+    status: row.status,
+    from: row.from_phone,
+    to: row.to_phone,
+    task: row.task,
+    policy: parseJson(row.policy_json, {}),
+    transport: parseJson(row.transport_json, {}),
+    provider: row.provider,
+    providerCallId: row.provider_call_id ?? void 0,
+    transcript: parseJson(row.transcript_json, []),
+    metadata: parseJson(row.metadata_json, {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function redactPhoneTransportConfig(config) {
+  return {
+    ...config,
+    password: config.password ? "***" : "",
+    webhookSecret: config.webhookSecret ? "***" : ""
+  };
+}
+var PhoneManager = class {
+  constructor(db2, encryptionKey) {
+    this.db = db2;
+    this.encryptionKey = encryptionKey;
+    this.ensureTables();
+  }
+  initialized = false;
+  /** Per-agent outbound-call timestamps (ms) for the in-memory rate limiter. */
+  callTimestamps = /* @__PURE__ */ new Map();
+  /**
+   * Abuse / cost gate for /calls/start (#43-H1). Each non-dry-run call is
+   * a real billed outbound call, so before dialing we enforce:
+   *   - a hard cap on concurrently-active (non-terminal) missions, and
+   *   - a per-agent token-bucket rate limit (per-minute + per-hour).
+   * Throws {@link PhoneRateLimitError} (-> HTTP 429) when a limit is hit.
+   * Call only on the real path — dry runs place no call and are exempt.
+   */
+  enforceCallLimits(agentId, nowMs) {
+    const activeRow = this.db.prepare(
+      `SELECT COUNT(*) AS cnt FROM phone_missions
+       WHERE agent_id = ? AND status NOT IN ('completed', 'failed', 'cancelled')`
+    ).get(agentId);
+    if ((activeRow?.cnt ?? 0) >= PHONE_MAX_CONCURRENT_MISSIONS) {
+      throw new PhoneRateLimitError(
+        `Too many active phone missions (max ${PHONE_MAX_CONCURRENT_MISSIONS}). Wait for an active call to end before starting another.`
+      );
+    }
+    const recent = (this.callTimestamps.get(agentId) ?? []).filter((ts) => nowMs - ts < 36e5);
+    const lastMinute = recent.filter((ts) => nowMs - ts < 6e4).length;
+    if (lastMinute >= PHONE_RATE_LIMIT_PER_MINUTE) {
+      throw new PhoneRateLimitError(
+        `Phone call rate limit reached (max ${PHONE_RATE_LIMIT_PER_MINUTE}/minute). Try again shortly.`
+      );
+    }
+    if (recent.length >= PHONE_RATE_LIMIT_PER_HOUR) {
+      throw new PhoneRateLimitError(
+        `Phone call rate limit reached (max ${PHONE_RATE_LIMIT_PER_HOUR}/hour). Try again later.`
+      );
+    }
+    recent.push(nowMs);
+    this.callTimestamps.set(agentId, recent);
+  }
+  encryptConfig(config) {
+    if (!this.encryptionKey) return config;
+    const out = { ...config };
+    for (const field of PHONE_SECRET_FIELDS) {
+      const value = out[field];
+      if (typeof value === "string" && value && !isEncryptedSecret(value)) {
+        out[field] = encryptSecret(value, this.encryptionKey);
+      }
+    }
+    return out;
+  }
+  decryptConfig(config) {
+    if (!this.encryptionKey) return config;
+    const out = { ...config };
+    for (const field of PHONE_SECRET_FIELDS) {
+      const value = out[field];
+      if (typeof value === "string" && isEncryptedSecret(value)) {
+        try {
+          out[field] = decryptSecret(value, this.encryptionKey);
+        } catch {
+        }
+      }
+    }
+    return out;
+  }
+  ensureTables() {
+    if (this.initialized) return;
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS phone_missions (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        status TEXT NOT NULL,
+        from_phone TEXT NOT NULL,
+        to_phone TEXT NOT NULL,
+        task TEXT NOT NULL,
+        policy_json TEXT NOT NULL,
+        transport_json TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        provider_call_id TEXT,
+        transcript_json TEXT NOT NULL DEFAULT '[]',
+        metadata_json TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+    try {
+      this.db.exec("CREATE INDEX IF NOT EXISTS idx_phone_missions_agent ON phone_missions(agent_id)");
+    } catch {
+    }
+    try {
+      this.db.exec("CREATE INDEX IF NOT EXISTS idx_phone_missions_status ON phone_missions(status)");
+    } catch {
+    }
+    this.initialized = true;
+  }
+  getPhoneTransportConfig(agentId) {
+    const row = this.db.prepare("SELECT metadata FROM agents WHERE id = ?").get(agentId);
+    if (!row) return null;
+    const meta = parseJson(row.metadata, {});
+    const config = meta.phoneTransport;
+    if (!config || typeof config !== "object") return null;
+    return this.decryptConfig(config);
+  }
+  savePhoneTransportConfig(agentId, config) {
+    const row = this.db.prepare("SELECT metadata FROM agents WHERE id = ?").get(agentId);
+    if (!row) throw new Error(`Agent ${agentId} not found`);
+    const transportCheck = validatePhoneTransportProfile(config);
+    if (!transportCheck.ok) {
+      throw new Error(`Invalid phone transport config: ${transportCheck.issues.map((item) => `${item.field}: ${item.message}`).join("; ")}`);
+    }
+    const meta = parseJson(row.metadata, {});
+    meta.phoneTransport = this.encryptConfig({
+      ...config,
+      phoneNumber: transportCheck.transport.phoneNumber,
+      capabilities: transportCheck.transport.capabilities,
+      supportedRegions: transportCheck.transport.supportedRegions
+    });
+    this.db.prepare("UPDATE agents SET metadata = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(meta), agentId);
+    return config;
+  }
+  getMission(missionId, agentId) {
+    const row = agentId ? this.db.prepare("SELECT * FROM phone_missions WHERE id = ? AND agent_id = ?").get(missionId, agentId) : this.db.prepare("SELECT * FROM phone_missions WHERE id = ?").get(missionId);
+    return row ? rowToMission(row) : null;
+  }
+  listMissions(agentId, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+    const offset = Math.max(opts.offset ?? 0, 0);
+    const params = [agentId];
+    let sql = "SELECT * FROM phone_missions WHERE agent_id = ?";
+    if (opts.status && PHONE_MISSION_STATES.includes(opts.status)) {
+      sql += " AND status = ?";
+      params.push(opts.status);
+    }
+    sql += " ORDER BY created_at DESC LIMIT ? OFFSET ?";
+    params.push(limit, offset);
+    return this.db.prepare(sql).all(...params).map(rowToMission);
+  }
+  async startMission(agentId, input, options = {}) {
+    const config = this.getPhoneTransportConfig(agentId);
+    if (!config) {
+      throw new Error("Phone transport is not configured. Use phone_transport_setup first.");
+    }
+    if (config.provider !== "46elks") {
+      throw new Error(`Phone provider ${config.provider} does not support call_control yet`);
+    }
+    const validation = validatePhoneMissionStart(input, config);
+    if (!validation.ok) {
+      throw new Error(`Invalid phone mission: ${validation.issues.map((item) => `${item.code} (${item.field})`).join(", ")}`);
+    }
+    const now = options.now ?? /* @__PURE__ */ new Date();
+    if (!options.dryRun) {
+      this.enforceCallLimits(agentId, now.getTime());
+    }
+    const missionId = `call_${randomUUID()}`;
+    const transcript = [{
+      at: now.toISOString(),
+      source: "system",
+      text: "Phone mission created; outbound carrier call requested."
+    }];
+    const metadata = {
+      voiceRuntimeRef: validation.mission.voiceRuntimeRef,
+      targetRegion: validation.mission.targetRegion,
+      dryRun: !!options.dryRun,
+      // Attempt counter (#43-H2) — wired for breach detection; there is
+      // no automatic retry loop today, so a fresh mission is attempt 1.
+      attempts: 1
+    };
+    const mission = {
+      id: missionId,
+      agentId,
+      status: "dialing",
+      from: config.phoneNumber,
+      to: validation.mission.to,
+      task: validation.mission.task,
+      policy: validation.mission.policy,
+      transport: validation.mission.transport,
+      provider: config.provider,
+      transcript,
+      metadata,
+      createdAt: now.toISOString(),
+      updatedAt: now.toISOString()
+    };
+    this.insertMission(mission);
+    const providerRequest = this.build46ElksCallRequest(config, mission);
+    if (options.dryRun) {
+      const updated2 = this.updateProviderCall(missionId, "dryrun-call", {
+        dryRun: true,
+        providerRequest: redactProviderRequest(providerRequest)
+      });
+      return { mission: updated2, providerRequest };
+    }
+    const fetchFn = options.fetchFn ?? fetch;
+    let response;
+    try {
+      response = await fetchFn(providerRequest.url, {
+        method: "POST",
+        headers: {
+          "Authorization": `Basic ${basicAuth2(config.username, config.password)}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams(providerRequest.body),
+        signal: AbortSignal.timeout(15e3)
+      });
+    } catch (err) {
+      const message = err?.message ?? String(err);
+      this.updateMissionStatus(missionId, "failed", {
+        providerError: message
+      }, [{
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        source: "provider",
+        text: "46elks call start failed \u2014 the provider request threw before any response.",
+        metadata: { error: message }
+      }]);
+      throw err;
+    }
+    const text = await response.text();
+    let raw = text;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+    }
+    if (!response.ok) {
+      const failed = this.updateMissionStatus(missionId, "failed", {
+        providerStatus: response.status,
+        providerResponse: raw
+      }, [{
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        source: "provider",
+        text: `46elks call start failed with HTTP ${response.status}.`,
+        metadata: { providerResponse: raw }
+      }]);
+      throw new Error(`46elks call start failed (${response.status}) for mission ${failed.id}`);
+    }
+    const providerCallId = asRecord2(raw).id ? String(asRecord2(raw).id) : void 0;
+    const updated = this.updateProviderCall(missionId, providerCallId, { providerResponse: raw });
+    return { mission: updated, providerRequest, providerResponse: raw };
+  }
+  /**
+   * Verify a webhook request and return the mission, or throw a uniform
+   * {@link PhoneWebhookAuthError} for ANY failure (unknown mission, no
+   * token, wrong token). Uniform on purpose — no 404-vs-403 oracle.
+   */
+  authenticateWebhook(missionId, providedToken) {
+    const mission = missionId ? this.getMission(missionId) : null;
+    const config = mission ? this.getPhoneTransportConfig(mission.agentId) : null;
+    if (!mission || !config || !providedToken || !secretMatches(providedToken, webhookToken(config.webhookSecret, mission.id))) {
+      throw new PhoneWebhookAuthError();
+    }
+    return mission;
+  }
+  handleVoiceStartWebhook(missionId, providedToken, payload = {}) {
+    const mission = this.authenticateWebhook(missionId, providedToken);
+    if (TERMINAL_MISSION_STATES.includes(mission.status)) {
+      return { mission, action: this.buildVoiceStartAction() };
+    }
+    const eventKey = phoneWebhookEventKey("voice_start", payload);
+    if (hasProcessedWebhookEvent(mission, eventKey)) {
+      return {
+        mission,
+        action: this.buildVoiceStartAction()
+      };
+    }
+    const updated = this.updateMissionStatus(mission.id, "connected", {
+      lastVoiceStartPayload: payload,
+      phoneWebhookEvents: appendProcessedWebhookEvent(mission, eventKey)
+    }, [{
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "provider",
+      text: "46elks voice_start webhook received. Realtime voice runtime is not connected in this slice.",
+      metadata: { payload }
+    }]);
+    return {
+      mission: updated,
+      action: this.buildVoiceStartAction()
+    };
+  }
+  handleHangupWebhook(missionId, providedToken, payload = {}) {
+    const mission = this.authenticateWebhook(missionId, providedToken);
+    const eventKey = phoneWebhookEventKey("hangup", payload);
+    if (hasProcessedWebhookEvent(mission, eventKey)) {
+      return mission;
+    }
+    const costPatch = this.buildCostMetadataPatch(mission, payload);
+    const nextStatus = TERMINAL_MISSION_STATES.includes(mission.status) ? mission.status : "failed";
+    const transcript = [{
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "provider",
+      text: nextStatus === "failed" ? "46elks hangup webhook received before a conversation runtime completed the mission." : "46elks hangup webhook received.",
+      metadata: { payload }
+    }];
+    if (costPatch.costExceeded) {
+      transcript.push({
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        source: "system",
+        text: `Mission cost ${costPatch.totalCost} exceeded the policy cap of ${mission.policy.maxCostPerMission}.`
+      });
+    }
+    return this.updateMissionStatus(mission.id, nextStatus, {
+      lastHangupPayload: payload,
+      hangupReason: nextStatus === "failed" ? "call-ended-before-conversation-runtime" : void 0,
+      phoneWebhookEvents: appendProcessedWebhookEvent(mission, eventKey),
+      ...costPatch
+    }, transcript);
+  }
+  /**
+   * Read the call cost off a 46elks hangup payload, add it to the
+   * mission's running total, and flag a policy-cap breach (#43-H2).
+   * Cost is only knowable post-call from the provider — the preventive
+   * cost controls are the duration ceiling, rate limit, and concurrency
+   * cap; this is the after-the-fact accounting + alerting.
+   */
+  buildCostMetadataPatch(mission, payload) {
+    const rawCost = payload.cost;
+    const callCost = typeof rawCost === "number" && Number.isFinite(rawCost) && rawCost >= 0 ? rawCost : Number.parseFloat(asString3(rawCost)) || 0;
+    const priorCost = typeof mission.metadata.totalCost === "number" ? mission.metadata.totalCost : 0;
+    const totalCost = Math.round((priorCost + callCost) * 1e6) / 1e6;
+    const cap = mission.policy?.maxCostPerMission;
+    const costExceeded = typeof cap === "number" && totalCost > cap;
+    return { totalCost, costExceeded };
+  }
+  buildVoiceStartAction() {
+    return {
+      play: "AgenticMail has received this call mission. The live voice runtime is not connected yet; the operator will follow up."
+    };
+  }
+  cancelMission(agentId, missionId) {
+    const mission = this.getMission(missionId, agentId);
+    if (!mission) throw new Error("Phone mission not found");
+    return this.updateMissionStatus(mission.id, "cancelled", {}, [{
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "operator",
+      text: "Phone mission cancelled."
+    }]);
+  }
+  build46ElksCallRequest(config, mission) {
+    const timeout = Math.min(Math.max(mission.policy.maxCallDurationSeconds, 1), PHONE_SERVER_MAX_CALL_DURATION_SECONDS);
+    return {
+      url: `${defaultApiUrl2(config)}/calls`,
+      body: {
+        from: config.phoneNumber,
+        to: mission.to,
+        voice_start: buildWebhookUrl(config, "/calls/webhook/46elks/voice-start", mission.id),
+        whenhangup: buildWebhookUrl(config, "/calls/webhook/46elks/hangup", mission.id),
+        timeout: String(timeout)
+      }
+    };
+  }
+  insertMission(mission) {
+    this.db.prepare(`
+      INSERT INTO phone_missions (
+        id, agent_id, status, from_phone, to_phone, task,
+        policy_json, transport_json, provider, provider_call_id,
+        transcript_json, metadata_json, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      mission.id,
+      mission.agentId,
+      mission.status,
+      mission.from,
+      mission.to,
+      mission.task,
+      JSON.stringify(mission.policy),
+      JSON.stringify(mission.transport),
+      mission.provider,
+      mission.providerCallId ?? null,
+      JSON.stringify(mission.transcript),
+      JSON.stringify(mission.metadata),
+      mission.createdAt,
+      mission.updatedAt
+    );
+  }
+  updateProviderCall(missionId, providerCallId, metadata) {
+    const mission = this.getMission(missionId);
+    if (!mission) throw new Error("Phone mission not found");
+    const nextMetadata = { ...mission.metadata, ...metadata };
+    this.db.prepare(`
+      UPDATE phone_missions
+      SET provider_call_id = ?, metadata_json = ?, updated_at = ?
+      WHERE id = ?
+    `).run(providerCallId ?? null, JSON.stringify(nextMetadata), (/* @__PURE__ */ new Date()).toISOString(), missionId);
+    return this.getMission(missionId);
+  }
+  updateMissionStatus(missionId, status, metadata, transcriptEntries = []) {
+    const mission = this.getMission(missionId);
+    if (!mission) throw new Error("Phone mission not found");
+    const nextTranscript = [...mission.transcript, ...transcriptEntries];
+    const nextMetadata = Object.fromEntries(
+      Object.entries({ ...mission.metadata, ...metadata }).filter(([, value]) => value !== void 0)
+    );
+    this.db.prepare(`
+      UPDATE phone_missions
+      SET status = ?, transcript_json = ?, metadata_json = ?, updated_at = ?
+      WHERE id = ?
+    `).run(status, JSON.stringify(nextTranscript), JSON.stringify(nextMetadata), (/* @__PURE__ */ new Date()).toISOString(), missionId);
+    return this.getMission(missionId);
+  }
+};
+function buildPhoneTransportConfig(input) {
+  const provider = asString3(input.provider) || "46elks";
+  if (provider !== "46elks") throw new Error('provider must be "46elks"');
+  const phoneNumber = normalizePhoneNumber(asString3(input.phoneNumber));
+  if (!phoneNumber) throw new Error("phoneNumber must be a valid E.164 phone number");
+  const username = asString3(input.username);
+  const password = asString3(input.password);
+  const webhookBaseUrl = asString3(input.webhookBaseUrl);
+  const webhookSecret = asString3(input.webhookSecret);
+  if (!username || !password) throw new Error('username and password are required for provider "46elks"');
+  if (!webhookBaseUrl) throw new Error("webhookBaseUrl is required");
+  if (!webhookSecret) throw new Error("webhookSecret is required");
+  if (webhookSecret.length < PHONE_MIN_WEBHOOK_SECRET_LENGTH) {
+    throw new Error(`webhookSecret must be at least ${PHONE_MIN_WEBHOOK_SECRET_LENGTH} characters`);
+  }
+  const parsedWebhookBaseUrl = new URL(webhookBaseUrl);
+  if (parsedWebhookBaseUrl.protocol !== "https:" && parsedWebhookBaseUrl.hostname !== "127.0.0.1" && parsedWebhookBaseUrl.hostname !== "localhost") {
+    throw new Error("webhookBaseUrl must use https:// unless it points at localhost");
+  }
+  const apiUrl = asString3(input.apiUrl);
+  if (apiUrl) {
+    const parsedApiUrl = new URL(apiUrl);
+    if (parsedApiUrl.protocol !== "https:") {
+      throw new Error("apiUrl must use https:// \u2014 credentials are sent on every request");
+    }
+  }
+  const capabilities = Array.isArray(input.capabilities) ? input.capabilities.filter((item) => typeof item === "string" && ["sms", "call_control", "realtime_media", "recording_supported"].includes(item)) : ["call_control"];
+  const supportedRegions = Array.isArray(input.supportedRegions) ? input.supportedRegions.filter((item) => typeof item === "string" && ["AT", "DE", "EU", "WORLD"].includes(item)) : ["EU"];
+  const config = {
+    provider,
+    phoneNumber,
+    username,
+    password,
+    webhookBaseUrl,
+    webhookSecret,
+    apiUrl: apiUrl || void 0,
+    capabilities: Array.from(/* @__PURE__ */ new Set(["call_control", ...capabilities])),
+    supportedRegions: supportedRegions.length ? Array.from(new Set(supportedRegions)) : ["EU"],
+    configuredAt: input.configuredAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const validation = validatePhoneTransportProfile(config);
+  if (!validation.ok) {
+    throw new Error(`Invalid phone transport config: ${validation.issues.map((item) => `${item.field}: ${item.message}`).join("; ")}`);
+  }
+  return config;
+}
+
 // src/telemetry.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3 } from "fs";
 import { join as join5 } from "path";
 import { homedir as homedir4 } from "os";
@@ -6257,12 +7218,12 @@ function getInstallId() {
         return installId;
       }
     }
-    installId = randomUUID();
+    installId = randomUUID2();
     if (!existsSync3(dir2)) mkdirSync3(dir2, { recursive: true });
     writeFileSync3(idFile, installId, "utf8");
     return installId;
   } catch {
-    installId = randomUUID();
+    installId = randomUUID2();
     return installId;
   }
 }
@@ -8039,7 +9000,7 @@ secret = "${password}"
 };
 
 // src/threading/thread-id.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 function stripReplyPrefixes(subject) {
   let s = subject.length > 1e3 ? subject.slice(0, 1e3) : subject;
   for (; ; ) {
@@ -8068,7 +9029,7 @@ function normalizeAddress(addr) {
 }
 function threadIdFor(input) {
   const subject = normalizeSubject(input.subject);
-  return createHash2("sha256").update(subject).digest("base64url").slice(0, 16);
+  return createHash3("sha256").update(subject).digest("base64url").slice(0, 16);
 }
 
 // src/threading/thread-cache.ts
@@ -8344,12 +9305,26 @@ export {
   DependencyInstaller,
   DomainManager,
   DomainPurchaser,
+  ELKS_REALTIME_AUDIO_FORMATS,
   EmailSearchIndex,
   GatewayManager,
   InboxWatcher,
   MailReceiver,
   MailSender,
+  PHONE_MAX_CONCURRENT_MISSIONS,
+  PHONE_MIN_WEBHOOK_SECRET_LENGTH,
+  PHONE_MISSION_STATES,
+  PHONE_RATE_LIMIT_PER_HOUR,
+  PHONE_RATE_LIMIT_PER_MINUTE,
+  PHONE_REGION_SCOPES,
+  PHONE_SERVER_MAX_ATTEMPTS,
+  PHONE_SERVER_MAX_CALL_DURATION_SECONDS,
+  PHONE_SERVER_MAX_COST_PER_MISSION,
+  PHONE_TASK_MAX_LENGTH,
   PathTraversalError,
+  PhoneManager,
+  PhoneRateLimitError,
+  PhoneWebhookAuthError,
   REDACTED,
   RELAY_PRESETS,
   RelayBridge,
@@ -8360,6 +9335,7 @@ export {
   SmsManager,
   SmsPoller,
   StalwartAdmin,
+  TELEPHONY_TRANSPORT_CAPABILITIES,
   ThreadCache,
   TunnelManager,
   UnsafeApiUrlError,
@@ -8368,8 +9344,16 @@ export {
   bridgeWakeErrorMessage,
   bridgeWakeLastSeenAgeMs,
   buildApiUrl,
+  buildElksAudioMessage,
+  buildElksByeMessage,
+  buildElksHandshakeMessages,
+  buildElksInterruptMessage,
+  buildElksListeningMessage,
+  buildElksSendingMessage,
   buildInboundSecurityAdvisory,
+  buildPhoneTransportConfig,
   classifyEmailRoute,
+  classifyPhoneNumberRisk,
   classifyResumeError,
   closeDatabase,
   composeBridgeWakePrompt,
@@ -8384,8 +9368,10 @@ export {
   getOperatorEmail,
   getSmsProvider,
   hostSessionStoragePath,
+  inferPhoneRegion,
   isInternalEmail,
   isLoopbackMailHost,
+  isPhoneRegionAllowed,
   isSessionFresh,
   isValidPhoneNumber,
   loadHostSession,
@@ -8394,11 +9380,13 @@ export {
   normalizePhoneNumber,
   normalizeSubject,
   operatorPrefsStoragePath,
+  parseElksRealtimeMessage,
   parseEmail,
   parseGoogleVoiceSms,
   planBridgeWake,
   recordToolCall,
   redactObject,
+  redactPhoneTransportConfig,
   redactSecret,
   redactSmsConfig,
   resolveConfig,
@@ -8415,5 +9403,8 @@ export {
   startRelayBridge,
   threadIdFor,
   tryJoin,
-  validateApiUrl
+  validateApiUrl,
+  validatePhoneMissionPolicy,
+  validatePhoneMissionStart,
+  validatePhoneTransportProfile
 };