@agenticmail/core 0.9.27 → 0.9.29

package/dist/index.cjs

@@ -1459,6 +1459,8 @@ __export(index_exports, {
   CloudflareClient: () => CloudflareClient,
   DEFAULT_AGENT_NAME: () => DEFAULT_AGENT_NAME,
   DEFAULT_AGENT_ROLE: () => DEFAULT_AGENT_ROLE,
+  DEFAULT_CALLBACK_POLICY: () => DEFAULT_CALLBACK_POLICY,
+  DEFAULT_EXTENSION_POLICY: () => DEFAULT_EXTENSION_POLICY,
   DEFAULT_REALTIME_AUDIO_FORMAT: () => DEFAULT_REALTIME_AUDIO_FORMAT,
   DEFAULT_REALTIME_MODEL: () => DEFAULT_REALTIME_MODEL,
   DEFAULT_REALTIME_VOICE: () => DEFAULT_REALTIME_VOICE,
@@ -1471,8 +1473,11 @@ __export(index_exports, {
   DomainPurchaser: () => DomainPurchaser,
   ELKS_REALTIME_AUDIO_FORMATS: () => ELKS_REALTIME_AUDIO_FORMATS,
   ELKS_REALTIME_WS_PATH: () => ELKS_REALTIME_WS_PATH,
+  END_CALL_TOOL: () => END_CALL_TOOL,
+  EXTEND_CALL_TIME_TOOL: () => EXTEND_CALL_TIME_TOOL,
   ElksRealtimeTransport: () => ElksRealtimeTransport,
   EmailSearchIndex: () => EmailSearchIndex,
+  GET_CALL_STATUS_TOOL: () => GET_CALL_STATUS_TOOL,
   GET_DATETIME_TOOL: () => GET_DATETIME_TOOL,
   GatewayManager: () => GatewayManager,
   InboxWatcher: () => InboxWatcher,
@@ -1487,6 +1492,8 @@ __export(index_exports, {
   OPERATOR_QUERY_SUBJECT_TAG: () => OPERATOR_QUERY_SUBJECT_TAG,
   OPERATOR_QUERY_TIMEOUT_MS: () => OPERATOR_QUERY_TIMEOUT_MS,
   OPERATOR_QUERY_TIMEOUT_SENTINEL: () => OPERATOR_QUERY_TIMEOUT_SENTINEL,
+  PHONE_CALLBACK_MAX_DELAY_SECONDS: () => PHONE_CALLBACK_MAX_DELAY_SECONDS,
+  PHONE_CALLBACK_MIN_DELAY_SECONDS: () => PHONE_CALLBACK_MIN_DELAY_SECONDS,
   PHONE_CALL_CONTROL_PROVIDERS: () => PHONE_CALL_CONTROL_PROVIDERS,
   PHONE_MAX_CONCURRENT_MISSIONS: () => PHONE_MAX_CONCURRENT_MISSIONS,
   PHONE_MIN_WEBHOOK_SECRET_LENGTH: () => PHONE_MIN_WEBHOOK_SECRET_LENGTH,
@@ -1495,8 +1502,12 @@ __export(index_exports, {
   PHONE_RATE_LIMIT_PER_MINUTE: () => PHONE_RATE_LIMIT_PER_MINUTE,
   PHONE_REGION_SCOPES: () => PHONE_REGION_SCOPES,
   PHONE_SERVER_MAX_ATTEMPTS: () => PHONE_SERVER_MAX_ATTEMPTS,
+  PHONE_SERVER_MAX_CALLBACK_CHAIN: () => PHONE_SERVER_MAX_CALLBACK_CHAIN,
   PHONE_SERVER_MAX_CALL_DURATION_SECONDS: () => PHONE_SERVER_MAX_CALL_DURATION_SECONDS,
   PHONE_SERVER_MAX_COST_PER_MISSION: () => PHONE_SERVER_MAX_COST_PER_MISSION,
+  PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL: () => PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL,
+  PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST: () => PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST,
+  PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS: () => PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS,
   PHONE_TASK_MAX_LENGTH: () => PHONE_TASK_MAX_LENGTH,
   PathTraversalError: () => PathTraversalError,
   PhoneManager: () => PhoneManager,
@@ -1512,6 +1523,7 @@ __export(index_exports, {
   RealtimeVoiceBridge: () => RealtimeVoiceBridge,
   RelayBridge: () => RelayBridge,
   RelayGateway: () => RelayGateway,
+  SCHEDULE_CALLBACK_TOOL: () => SCHEDULE_CALLBACK_TOOL,
   SEARCH_EMAIL_TOOL: () => SEARCH_EMAIL_TOOL,
   SEARCH_SKILLS_TOOL: () => SEARCH_SKILLS_TOOL,
   SPAM_THRESHOLD: () => SPAM_THRESHOLD,
@@ -1632,7 +1644,9 @@ __export(index_exports, {
   renderSkillAsPrompt: () => renderSkillAsPrompt,
   requireBinary: () => requireBinary,
   requireWhisperModel: () => requireWhisperModel,
+  resolveCallbackPolicy: () => resolveCallbackPolicy,
   resolveConfig: () => resolveConfig,
+  resolveExtensionPolicy: () => resolveExtensionPolicy,
   resolveTlsRejectUnauthorized: () => resolveTlsRejectUnauthorized,
   safeJoin: () => safeJoin,
   sanitizeEmail: () => sanitizeEmail,
@@ -7514,25 +7528,26 @@ var PHONE_MISSION_STATES = [
   "failed",
   "cancelled"
 ];
-var PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+var PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 7200;
 var PHONE_SERVER_MAX_COST_PER_MISSION = 5;
 var PHONE_SERVER_MAX_ATTEMPTS = 3;
 var PHONE_TASK_MAX_LENGTH = 2e3;
-var PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST = 300;
-var PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL = 4;
-var PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS = 600;
+var PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST = 900;
+var PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL = 8;
+var PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS = 3600;
 var DEFAULT_EXTENSION_POLICY = {
-  maxSecondsPerRequest: 120,
-  // 2 minutes
-  maxRequestsPerCall: 2,
-  maxTotalExtensionSeconds: 300
+  maxSecondsPerRequest: 300,
   // 5 minutes
+  maxRequestsPerCall: 4,
+  maxTotalExtensionSeconds: 1200
+  // 20 minutes
 };
 var PHONE_SERVER_MAX_CALLBACK_CHAIN = 3;
 var DEFAULT_CALLBACK_POLICY = {
   allowAutoCallback: true,
   maxCallbackChain: 2
 };
+var PHONE_CALLBACK_MIN_DELAY_SECONDS = 30;
 var PHONE_CALLBACK_MAX_DELAY_SECONDS = 7 * 24 * 60 * 60;
 var EU_DIAL_PREFIXES = [
   "+30",
@@ -10745,6 +10760,20 @@ var SCHEDULE_CALLBACK_TOOL = {
     required: ["delay_seconds", "summary_for_next_call"]
   }
 };
+var END_CALL_TOOL = {
+  type: "function",
+  name: "end_call",
+  description: `Hang up the call. You MUST call this AFTER you have said goodbye and the conversation is complete \u2014 saying "I'll hang up now" is not enough on its own, the call stays open until you actually call this tool. Use it when: the task is done and you have signed off, the caller has indicated the conversation is over, you have scheduled a callback and said goodbye, or the caller has stopped responding for an extended period. Once called the call drops immediately; you cannot un-hang-up.`,
+  parameters: {
+    type: "object",
+    properties: {
+      reason: {
+        type: "string",
+        description: 'One short line for the audit trail \u2014 e.g. "task complete", "caller said bye", "scheduled callback, signing off". Optional but recommended.'
+      }
+    }
+  }
+};
 var REALTIME_TOOL_DEFINITIONS = {
   ask_operator: ASK_OPERATOR_TOOL,
   web_search: WEB_SEARCH_TOOL,
@@ -10755,7 +10784,8 @@ var REALTIME_TOOL_DEFINITIONS = {
   load_skill: LOAD_SKILL_TOOL,
   get_call_status: GET_CALL_STATUS_TOOL,
   extend_call_time: EXTEND_CALL_TIME_TOOL,
-  schedule_callback: SCHEDULE_CALLBACK_TOOL
+  schedule_callback: SCHEDULE_CALLBACK_TOOL,
+  end_call: END_CALL_TOOL
 };
 function buildRealtimeToolGuidance(tools) {
   if (tools.length === 0) return "";
@@ -10802,6 +10832,24 @@ A skill's rendered playbook is now part of your instructions for the rest of the
       "When in doubt \u2014 out of time, out of extensions, the caller is uncertain \u2014 preferred order is: wrap up gracefully \u2192 schedule_callback \u2192 sign off. Never go silent or invent excuses; the right move is always a clean handoff to a future call."
     );
   }
+  if (names.has("end_call")) {
+    lines.push(
+      "# Hanging up \u2014 you must call end_call to actually drop the line",
+      `SAYING "I'll hang up now" or "goodbye" does NOT drop the call \u2014 the line stays open until you call the end_call tool. This is the single most important habit on a real phone call: after you have said your goodbye sentence, IMMEDIATELY call end_call({ reason: "..." }). Do not wait for the caller to hang up first; do not assume the system will close the line for you. Call end_call yourself.`,
+      "",
+      "When to call end_call:",
+      "- The task is complete and you have just said goodbye.",
+      '- The caller said "thanks, bye" or otherwise signalled they are done.',
+      `- You scheduled a callback and said "I'll call you back at <when>".`,
+      "- The caller has gone silent for an extended stretch and is clearly not coming back.",
+      "- The operator told you to hang up.",
+      "",
+      "Do NOT call end_call:",
+      "- Mid-conversation when there is still pending business.",
+      "- Because you ran into a tool error \u2014 handle it and keep the call going.",
+      "- During a hold while a tool is running \u2014 let the tool finish."
+    );
+  }
   return lines.join("\n");
 }
 function toolErrorText(err) {
@@ -11681,8 +11729,10 @@ var RealtimeVoiceBridge = class {
     }
     let granted = Math.min(asked, pol.maxSecondsPerRequest, remainingBudgetSeconds);
     const elapsedSeconds = Math.floor((this.nowFn() - this.callStartedAtMs) / 1e3);
-    const maxAllowedFromStart = 3600;
-    const hardCeilingRoom = Math.max(0, maxAllowedFromStart - (elapsedSeconds + this.getTimeRemainingSeconds()));
+    const hardCeilingRoom = Math.max(
+      0,
+      PHONE_SERVER_MAX_CALL_DURATION_SECONDS - (elapsedSeconds + this.getTimeRemainingSeconds())
+    );
     granted = Math.min(granted, hardCeilingRoom);
     if (granted <= 0) {
       return {
@@ -11921,6 +11971,31 @@ var RealtimeVoiceBridge = class {
     return "\u2026\n" + joined.slice(joined.length - MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH + 2);
   }
   // ─── Teardown ─────────────────────────────────────────
+  /**
+   * v0.9.82 — agent-initiated hangup. Called when the `end_call` tool
+   * fires. Logs a marker, then routes through {@link end} so the
+   * carrier sees the bye frame and `onEnd` fires exactly once (the
+   * same teardown path the human-hangup case takes). The "agent-
+   * requested" reason flows through to the mission transcript so a
+   * post-call audit can tell apart "agent hung up" from "human hung
+   * up" from "time budget exceeded".
+   *
+   * Returns the structured result the tool handler echoes back to the
+   * model — even though by the time the model receives it the line
+   * will already be closed, keeping a consistent return shape lets the
+   * executor JSON-stringify deterministically.
+   */
+  endByAgentRequest(reason) {
+    if (this.ended) {
+      return { ok: false, message: "Call has already ended." };
+    }
+    const trimmed = (reason ?? "").trim();
+    this.emitTranscript("system", `Agent requested hangup. Reason: ${trimmed || "unspecified"}`, {
+      endedByAgent: true
+    });
+    this.end("agent-requested");
+    return { ok: true, message: "Call ended." };
+  }
   /**
    * End the bridge. Idempotent — the first call wins, later calls are
    * no-ops. Sends the carrier's end-of-call frame (if it has one — 46elks
@@ -16045,6 +16120,8 @@ init_skills();
   CloudflareClient,
   DEFAULT_AGENT_NAME,
   DEFAULT_AGENT_ROLE,
+  DEFAULT_CALLBACK_POLICY,
+  DEFAULT_EXTENSION_POLICY,
   DEFAULT_REALTIME_AUDIO_FORMAT,
   DEFAULT_REALTIME_MODEL,
   DEFAULT_REALTIME_VOICE,
@@ -16057,8 +16134,11 @@ init_skills();
   DomainPurchaser,
   ELKS_REALTIME_AUDIO_FORMATS,
   ELKS_REALTIME_WS_PATH,
+  END_CALL_TOOL,
+  EXTEND_CALL_TIME_TOOL,
   ElksRealtimeTransport,
   EmailSearchIndex,
+  GET_CALL_STATUS_TOOL,
   GET_DATETIME_TOOL,
   GatewayManager,
   InboxWatcher,
@@ -16073,6 +16153,8 @@ init_skills();
   OPERATOR_QUERY_SUBJECT_TAG,
   OPERATOR_QUERY_TIMEOUT_MS,
   OPERATOR_QUERY_TIMEOUT_SENTINEL,
+  PHONE_CALLBACK_MAX_DELAY_SECONDS,
+  PHONE_CALLBACK_MIN_DELAY_SECONDS,
   PHONE_CALL_CONTROL_PROVIDERS,
   PHONE_MAX_CONCURRENT_MISSIONS,
   PHONE_MIN_WEBHOOK_SECRET_LENGTH,
@@ -16081,8 +16163,12 @@ init_skills();
   PHONE_RATE_LIMIT_PER_MINUTE,
   PHONE_REGION_SCOPES,
   PHONE_SERVER_MAX_ATTEMPTS,
+  PHONE_SERVER_MAX_CALLBACK_CHAIN,
   PHONE_SERVER_MAX_CALL_DURATION_SECONDS,
   PHONE_SERVER_MAX_COST_PER_MISSION,
+  PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL,
+  PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST,
+  PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS,
   PHONE_TASK_MAX_LENGTH,
   PathTraversalError,
   PhoneManager,
@@ -16098,6 +16184,7 @@ init_skills();
   RealtimeVoiceBridge,
   RelayBridge,
   RelayGateway,
+  SCHEDULE_CALLBACK_TOOL,
   SEARCH_EMAIL_TOOL,
   SEARCH_SKILLS_TOOL,
   SPAM_THRESHOLD,
@@ -16218,7 +16305,9 @@ init_skills();
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
+  resolveCallbackPolicy,
   resolveConfig,
+  resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
   safeJoin,
   sanitizeEmail,

package/dist/index.d.cts

@@ -2618,11 +2618,56 @@ type PhoneNumberRisk = 'invalid' | 'standard' | 'premium_or_special';
  * be MORE restrictive than the server, never less. A phone mission places
  * real, billed calls — these bounds are the financial blast-radius cap.
  */
-declare const PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+declare const PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 7200;
 declare const PHONE_SERVER_MAX_COST_PER_MISSION = 5;
 declare const PHONE_SERVER_MAX_ATTEMPTS = 3;
 /** Hard cap on the free-text `task` fed to the voice runtime. */
 declare const PHONE_TASK_MAX_LENGTH = 2000;
+/**
+ * Server-side ceilings for the extension policy. Like the duration /
+ * cost caps above, these are the financial blast-radius bound — a
+ * caller can ask for a stricter extension policy but never a looser
+ * one. The defaults err on the side of "give the agent a fighting
+ * chance to finish a real call" without letting it sit on the line
+ * forever. v0.9.82 bumped these substantially after field reports of
+ * agents running out of time on legitimately long calls (15-25 min
+ * hold queues, 30 min explanations from the rep):
+ *
+ *   - per-request cap raised 5 min → 15 min so a single "I need more
+ *     time on hold" request can carry the agent through a queue
+ *   - per-call cap raised 4 → 8 so chained extensions don't run dry
+ *     on a long bureaucracy call
+ *   - total cap raised 10 min → 1 hour so the absolute add can match
+ *     a long-tail call without artificial chunking
+ *
+ * The TOTAL also can't push the call past
+ * PHONE_SERVER_MAX_CALL_DURATION_SECONDS — that ceiling still wins.
+ */
+declare const PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST = 900;
+declare const PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL = 8;
+declare const PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS = 3600;
+/** Default per-call extension envelope when the caller doesn't set one.
+ *  Bumped in v0.9.82 — 5 min × 4 = 20 min of headroom is a much more
+ *  realistic out-of-the-box budget for the kinds of calls operators
+ *  actually use this for (bills, bookings, customer support). */
+declare const DEFAULT_EXTENSION_POLICY: PhoneExtensionPolicy;
+/**
+ * Server-side ceiling on how deep a callback chain can go. Each call
+ * counts; a brand-new mission is depth 0, its callback is depth 1, the
+ * callback's callback is depth 2. Prevents an agent + bot operator on
+ * the other end from getting stuck in an infinite re-dial loop.
+ */
+declare const PHONE_SERVER_MAX_CALLBACK_CHAIN = 3;
+/** Default callback envelope when the caller doesn't set one. */
+declare const DEFAULT_CALLBACK_POLICY: PhoneCallbackPolicy;
+/**
+ * Floor + ceiling on how far into the future a `schedule_callback` may
+ * defer. Lower bound prevents instant re-dial loops (give the human a
+ * breath); upper bound bounds the staging window so a scheduled
+ * callback can't sit in the DB forever.
+ */
+declare const PHONE_CALLBACK_MIN_DELAY_SECONDS = 30;
+declare const PHONE_CALLBACK_MAX_DELAY_SECONDS: number;
 interface PhoneConfirmPolicy {
     paymentDetails: 'never';
     contractCommitment: 'never';
@@ -2746,6 +2791,15 @@ type PhoneMissionStartValidationResult = {
     ok: false;
     issues: PhoneMissionValidationIssue[];
 };
+/**
+ * Resolve the effective extension policy: caller's value (if any),
+ * clamped DOWN to the server ceiling on each field. The server cap
+ * always wins — a caller asking for `maxSecondsPerRequest: 999_999`
+ * gets {@link PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST}.
+ */
+declare function resolveExtensionPolicy(input: PhoneExtensionPolicy | undefined): PhoneExtensionPolicy;
+/** Resolve the effective callback policy with server-ceiling clamping. */
+declare function resolveCallbackPolicy(input: PhoneCallbackPolicy | undefined): PhoneCallbackPolicy;
 declare function validatePhoneMissionPolicy(policy: unknown): PhoneMissionValidationResult;
 declare function validatePhoneTransportProfile(transport: unknown): PhoneTransportValidationResult;
 declare function inferPhoneRegion(phoneNumber: string): PhoneRegionScope | null;
@@ -2902,6 +2956,48 @@ declare const SEARCH_SKILLS_TOOL: RealtimeToolDefinition;
  * oldest (the bridge enforces this).
  */
 declare const LOAD_SKILL_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.81 — time-budget self-awareness. The voice model on a live call
+ * needs to know HOW LONG IT HAS, get reminded as that window closes,
+ * and have a graceful exit when it runs out. This tool returns a
+ * snapshot the model can read at any point. Cheap: pure function over
+ * bridge state, returns in microseconds.
+ */
+declare const GET_CALL_STATUS_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.81 — ask for more time on the current call. Auto-approved up to
+ * the per-call extension policy (per-request cap, per-call request cap,
+ * total seconds cap). On partial / refused grants the message field
+ * explains exactly what the agent has left so it can adapt rather than
+ * retry-loop.
+ */
+declare const EXTEND_CALL_TIME_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.81 — arrange an automatic callback when you cannot finish in
+ * this session (time, context, conversation needs a break, etc.). The
+ * bridge captures the agent's summary + a transcript digest now; the
+ * scheduler dials back at `delaySeconds` with full context loaded into
+ * the next call's task. Each call can schedule AT MOST ONE callback,
+ * and only within the mission's callbackPolicy.
+ */
+declare const SCHEDULE_CALLBACK_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.82 — the hang-up tool the agent must call when it's done.
+ *
+ * Before v0.9.82 the realtime voice model could SAY "Goodbye, I'll
+ * hang up now" but had no way to actually drop the call — the bridge
+ * only ended on a carrier-side bye (human hung up), OpenAI socket
+ * close, time-budget grace expiry, or programmatic teardown from the
+ * API layer. So the agent would say goodbye and then sit silently
+ * waiting for the human to hang up, racking up minutes.
+ *
+ * end_call wires the model to {@link RealtimeVoiceBridge.endByAgentRequest}
+ * which sends the carrier its end-of-call frame and closes both
+ * sockets. The model is instructed (in {@link buildRealtimeToolGuidance})
+ * to ALWAYS call this after it has said goodbye — verbal acknowledgement
+ * is not enough.
+ */
+declare const END_CALL_TOOL: RealtimeToolDefinition;
 /** Every tool defined in this module, keyed by name. */
 declare const REALTIME_TOOL_DEFINITIONS: Record<string, RealtimeToolDefinition>;
 /**
@@ -3692,6 +3788,24 @@ declare class RealtimeVoiceBridge {
      * Always honours {@link MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH}.
      */
     private composeTranscriptDigest;
+    /**
+     * v0.9.82 — agent-initiated hangup. Called when the `end_call` tool
+     * fires. Logs a marker, then routes through {@link end} so the
+     * carrier sees the bye frame and `onEnd` fires exactly once (the
+     * same teardown path the human-hangup case takes). The "agent-
+     * requested" reason flows through to the mission transcript so a
+     * post-call audit can tell apart "agent hung up" from "human hung
+     * up" from "time budget exceeded".
+     *
+     * Returns the structured result the tool handler echoes back to the
+     * model — even though by the time the model receives it the line
+     * will already be closed, keeping a consistent return shape lets the
+     * executor JSON-stringify deterministically.
+     */
+    endByAgentRequest(reason?: string): {
+        ok: boolean;
+        message: string;
+    };
     /**
      * End the bridge. Idempotent — the first call wins, later calls are
      * no-ops. Sends the carrier's end-of-call frame (if it has one — 46elks
@@ -3803,6 +3917,38 @@ interface PhoneWebhookResult {
     mission: PhoneCallMission;
     action: Record<string, unknown>;
 }
+/**
+ * Persisted shape of a `schedule_callback` request. Stored verbatim
+ * on `mission.metadata.scheduledCallback`; the scheduler reads it back
+ * when the wall-clock reaches `at`.
+ *
+ *   - `at`         — when to dial back, ISO timestamp
+ *   - `reason`     — short audit string
+ *   - `agentSummary` — what the next call needs to know (model-provided)
+ *   - `transcriptDigest` — bridge-built rolling transcript snapshot
+ *   - `chainDepth` — 0 for first scheduled callback, 1 if THIS mission
+ *                   was itself a callback, 2 if its parent was too, …
+ *                   Used to enforce `policy.callbackPolicy.maxCallbackChain`
+ *                   without re-walking the chain at dial time.
+ *   - `status`     — pending → dialing → fired (mission spawned) | failed
+ *   - `callbackMissionId` — id of the new mission once dialing happens
+ *   - `armedAt`    — when this record was written, audit only
+ *   - `firedAt`    — when the scheduler actually dialed
+ *   - `lastError`  — last dial-failure message (the scheduler retries
+ *                   inside the manager; this is the visibility hook)
+ */
+interface PhoneScheduledCallback {
+    at: string;
+    reason: string;
+    agentSummary: string;
+    transcriptDigest: string;
+    chainDepth: number;
+    status: 'pending' | 'dialing' | 'fired' | 'failed';
+    callbackMissionId?: string;
+    armedAt: string;
+    firedAt?: string;
+    lastError?: string;
+}
 declare function redactPhoneTransportConfig(config: PhoneTransportConfig): PhoneTransportConfig;
 declare class PhoneManager {
     private db;
@@ -5950,4 +6096,4 @@ declare function userSkillsDir(): string;
  */
 declare function renderSkillAsPrompt(skill: Skill): string;
 
-export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALL_CONTROL_PROVIDERS, 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, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };
+export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, 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_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.d.ts

@@ -2618,11 +2618,56 @@ type PhoneNumberRisk = 'invalid' | 'standard' | 'premium_or_special';
  * be MORE restrictive than the server, never less. A phone mission places
  * real, billed calls — these bounds are the financial blast-radius cap.
  */
-declare const PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+declare const PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 7200;
 declare const PHONE_SERVER_MAX_COST_PER_MISSION = 5;
 declare const PHONE_SERVER_MAX_ATTEMPTS = 3;
 /** Hard cap on the free-text `task` fed to the voice runtime. */
 declare const PHONE_TASK_MAX_LENGTH = 2000;
+/**
+ * Server-side ceilings for the extension policy. Like the duration /
+ * cost caps above, these are the financial blast-radius bound — a
+ * caller can ask for a stricter extension policy but never a looser
+ * one. The defaults err on the side of "give the agent a fighting
+ * chance to finish a real call" without letting it sit on the line
+ * forever. v0.9.82 bumped these substantially after field reports of
+ * agents running out of time on legitimately long calls (15-25 min
+ * hold queues, 30 min explanations from the rep):
+ *
+ *   - per-request cap raised 5 min → 15 min so a single "I need more
+ *     time on hold" request can carry the agent through a queue
+ *   - per-call cap raised 4 → 8 so chained extensions don't run dry
+ *     on a long bureaucracy call
+ *   - total cap raised 10 min → 1 hour so the absolute add can match
+ *     a long-tail call without artificial chunking
+ *
+ * The TOTAL also can't push the call past
+ * PHONE_SERVER_MAX_CALL_DURATION_SECONDS — that ceiling still wins.
+ */
+declare const PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST = 900;
+declare const PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL = 8;
+declare const PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS = 3600;
+/** Default per-call extension envelope when the caller doesn't set one.
+ *  Bumped in v0.9.82 — 5 min × 4 = 20 min of headroom is a much more
+ *  realistic out-of-the-box budget for the kinds of calls operators
+ *  actually use this for (bills, bookings, customer support). */
+declare const DEFAULT_EXTENSION_POLICY: PhoneExtensionPolicy;
+/**
+ * Server-side ceiling on how deep a callback chain can go. Each call
+ * counts; a brand-new mission is depth 0, its callback is depth 1, the
+ * callback's callback is depth 2. Prevents an agent + bot operator on
+ * the other end from getting stuck in an infinite re-dial loop.
+ */
+declare const PHONE_SERVER_MAX_CALLBACK_CHAIN = 3;
+/** Default callback envelope when the caller doesn't set one. */
+declare const DEFAULT_CALLBACK_POLICY: PhoneCallbackPolicy;
+/**
+ * Floor + ceiling on how far into the future a `schedule_callback` may
+ * defer. Lower bound prevents instant re-dial loops (give the human a
+ * breath); upper bound bounds the staging window so a scheduled
+ * callback can't sit in the DB forever.
+ */
+declare const PHONE_CALLBACK_MIN_DELAY_SECONDS = 30;
+declare const PHONE_CALLBACK_MAX_DELAY_SECONDS: number;
 interface PhoneConfirmPolicy {
     paymentDetails: 'never';
     contractCommitment: 'never';
@@ -2746,6 +2791,15 @@ type PhoneMissionStartValidationResult = {
     ok: false;
     issues: PhoneMissionValidationIssue[];
 };
+/**
+ * Resolve the effective extension policy: caller's value (if any),
+ * clamped DOWN to the server ceiling on each field. The server cap
+ * always wins — a caller asking for `maxSecondsPerRequest: 999_999`
+ * gets {@link PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST}.
+ */
+declare function resolveExtensionPolicy(input: PhoneExtensionPolicy | undefined): PhoneExtensionPolicy;
+/** Resolve the effective callback policy with server-ceiling clamping. */
+declare function resolveCallbackPolicy(input: PhoneCallbackPolicy | undefined): PhoneCallbackPolicy;
 declare function validatePhoneMissionPolicy(policy: unknown): PhoneMissionValidationResult;
 declare function validatePhoneTransportProfile(transport: unknown): PhoneTransportValidationResult;
 declare function inferPhoneRegion(phoneNumber: string): PhoneRegionScope | null;
@@ -2902,6 +2956,48 @@ declare const SEARCH_SKILLS_TOOL: RealtimeToolDefinition;
  * oldest (the bridge enforces this).
  */
 declare const LOAD_SKILL_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.81 — time-budget self-awareness. The voice model on a live call
+ * needs to know HOW LONG IT HAS, get reminded as that window closes,
+ * and have a graceful exit when it runs out. This tool returns a
+ * snapshot the model can read at any point. Cheap: pure function over
+ * bridge state, returns in microseconds.
+ */
+declare const GET_CALL_STATUS_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.81 — ask for more time on the current call. Auto-approved up to
+ * the per-call extension policy (per-request cap, per-call request cap,
+ * total seconds cap). On partial / refused grants the message field
+ * explains exactly what the agent has left so it can adapt rather than
+ * retry-loop.
+ */
+declare const EXTEND_CALL_TIME_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.81 — arrange an automatic callback when you cannot finish in
+ * this session (time, context, conversation needs a break, etc.). The
+ * bridge captures the agent's summary + a transcript digest now; the
+ * scheduler dials back at `delaySeconds` with full context loaded into
+ * the next call's task. Each call can schedule AT MOST ONE callback,
+ * and only within the mission's callbackPolicy.
+ */
+declare const SCHEDULE_CALLBACK_TOOL: RealtimeToolDefinition;
+/**
+ * v0.9.82 — the hang-up tool the agent must call when it's done.
+ *
+ * Before v0.9.82 the realtime voice model could SAY "Goodbye, I'll
+ * hang up now" but had no way to actually drop the call — the bridge
+ * only ended on a carrier-side bye (human hung up), OpenAI socket
+ * close, time-budget grace expiry, or programmatic teardown from the
+ * API layer. So the agent would say goodbye and then sit silently
+ * waiting for the human to hang up, racking up minutes.
+ *
+ * end_call wires the model to {@link RealtimeVoiceBridge.endByAgentRequest}
+ * which sends the carrier its end-of-call frame and closes both
+ * sockets. The model is instructed (in {@link buildRealtimeToolGuidance})
+ * to ALWAYS call this after it has said goodbye — verbal acknowledgement
+ * is not enough.
+ */
+declare const END_CALL_TOOL: RealtimeToolDefinition;
 /** Every tool defined in this module, keyed by name. */
 declare const REALTIME_TOOL_DEFINITIONS: Record<string, RealtimeToolDefinition>;
 /**
@@ -3692,6 +3788,24 @@ declare class RealtimeVoiceBridge {
      * Always honours {@link MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH}.
      */
     private composeTranscriptDigest;
+    /**
+     * v0.9.82 — agent-initiated hangup. Called when the `end_call` tool
+     * fires. Logs a marker, then routes through {@link end} so the
+     * carrier sees the bye frame and `onEnd` fires exactly once (the
+     * same teardown path the human-hangup case takes). The "agent-
+     * requested" reason flows through to the mission transcript so a
+     * post-call audit can tell apart "agent hung up" from "human hung
+     * up" from "time budget exceeded".
+     *
+     * Returns the structured result the tool handler echoes back to the
+     * model — even though by the time the model receives it the line
+     * will already be closed, keeping a consistent return shape lets the
+     * executor JSON-stringify deterministically.
+     */
+    endByAgentRequest(reason?: string): {
+        ok: boolean;
+        message: string;
+    };
     /**
      * End the bridge. Idempotent — the first call wins, later calls are
      * no-ops. Sends the carrier's end-of-call frame (if it has one — 46elks
@@ -3803,6 +3917,38 @@ interface PhoneWebhookResult {
     mission: PhoneCallMission;
     action: Record<string, unknown>;
 }
+/**
+ * Persisted shape of a `schedule_callback` request. Stored verbatim
+ * on `mission.metadata.scheduledCallback`; the scheduler reads it back
+ * when the wall-clock reaches `at`.
+ *
+ *   - `at`         — when to dial back, ISO timestamp
+ *   - `reason`     — short audit string
+ *   - `agentSummary` — what the next call needs to know (model-provided)
+ *   - `transcriptDigest` — bridge-built rolling transcript snapshot
+ *   - `chainDepth` — 0 for first scheduled callback, 1 if THIS mission
+ *                   was itself a callback, 2 if its parent was too, …
+ *                   Used to enforce `policy.callbackPolicy.maxCallbackChain`
+ *                   without re-walking the chain at dial time.
+ *   - `status`     — pending → dialing → fired (mission spawned) | failed
+ *   - `callbackMissionId` — id of the new mission once dialing happens
+ *   - `armedAt`    — when this record was written, audit only
+ *   - `firedAt`    — when the scheduler actually dialed
+ *   - `lastError`  — last dial-failure message (the scheduler retries
+ *                   inside the manager; this is the visibility hook)
+ */
+interface PhoneScheduledCallback {
+    at: string;
+    reason: string;
+    agentSummary: string;
+    transcriptDigest: string;
+    chainDepth: number;
+    status: 'pending' | 'dialing' | 'fired' | 'failed';
+    callbackMissionId?: string;
+    armedAt: string;
+    firedAt?: string;
+    lastError?: string;
+}
 declare function redactPhoneTransportConfig(config: PhoneTransportConfig): PhoneTransportConfig;
 declare class PhoneManager {
     private db;
@@ -5950,4 +6096,4 @@ declare function userSkillsDir(): string;
  */
 declare function renderSkillAsPrompt(skill: Skill): string;
 
-export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALL_CONTROL_PROVIDERS, 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, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };
+export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, 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_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.js

@@ -5865,25 +5865,26 @@ var PHONE_MISSION_STATES = [
   "failed",
   "cancelled"
 ];
-var PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+var PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 7200;
 var PHONE_SERVER_MAX_COST_PER_MISSION = 5;
 var PHONE_SERVER_MAX_ATTEMPTS = 3;
 var PHONE_TASK_MAX_LENGTH = 2e3;
-var PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST = 300;
-var PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL = 4;
-var PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS = 600;
+var PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST = 900;
+var PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL = 8;
+var PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS = 3600;
 var DEFAULT_EXTENSION_POLICY = {
-  maxSecondsPerRequest: 120,
-  // 2 minutes
-  maxRequestsPerCall: 2,
-  maxTotalExtensionSeconds: 300
+  maxSecondsPerRequest: 300,
   // 5 minutes
+  maxRequestsPerCall: 4,
+  maxTotalExtensionSeconds: 1200
+  // 20 minutes
 };
 var PHONE_SERVER_MAX_CALLBACK_CHAIN = 3;
 var DEFAULT_CALLBACK_POLICY = {
   allowAutoCallback: true,
   maxCallbackChain: 2
 };
+var PHONE_CALLBACK_MIN_DELAY_SECONDS = 30;
 var PHONE_CALLBACK_MAX_DELAY_SECONDS = 7 * 24 * 60 * 60;
 var EU_DIAL_PREFIXES = [
   "+30",
@@ -9096,6 +9097,20 @@ var SCHEDULE_CALLBACK_TOOL = {
     required: ["delay_seconds", "summary_for_next_call"]
   }
 };
+var END_CALL_TOOL = {
+  type: "function",
+  name: "end_call",
+  description: `Hang up the call. You MUST call this AFTER you have said goodbye and the conversation is complete \u2014 saying "I'll hang up now" is not enough on its own, the call stays open until you actually call this tool. Use it when: the task is done and you have signed off, the caller has indicated the conversation is over, you have scheduled a callback and said goodbye, or the caller has stopped responding for an extended period. Once called the call drops immediately; you cannot un-hang-up.`,
+  parameters: {
+    type: "object",
+    properties: {
+      reason: {
+        type: "string",
+        description: 'One short line for the audit trail \u2014 e.g. "task complete", "caller said bye", "scheduled callback, signing off". Optional but recommended.'
+      }
+    }
+  }
+};
 var REALTIME_TOOL_DEFINITIONS = {
   ask_operator: ASK_OPERATOR_TOOL,
   web_search: WEB_SEARCH_TOOL,
@@ -9106,7 +9121,8 @@ var REALTIME_TOOL_DEFINITIONS = {
   load_skill: LOAD_SKILL_TOOL,
   get_call_status: GET_CALL_STATUS_TOOL,
   extend_call_time: EXTEND_CALL_TIME_TOOL,
-  schedule_callback: SCHEDULE_CALLBACK_TOOL
+  schedule_callback: SCHEDULE_CALLBACK_TOOL,
+  end_call: END_CALL_TOOL
 };
 function buildRealtimeToolGuidance(tools) {
   if (tools.length === 0) return "";
@@ -9153,6 +9169,24 @@ A skill's rendered playbook is now part of your instructions for the rest of the
       "When in doubt \u2014 out of time, out of extensions, the caller is uncertain \u2014 preferred order is: wrap up gracefully \u2192 schedule_callback \u2192 sign off. Never go silent or invent excuses; the right move is always a clean handoff to a future call."
     );
   }
+  if (names.has("end_call")) {
+    lines.push(
+      "# Hanging up \u2014 you must call end_call to actually drop the line",
+      `SAYING "I'll hang up now" or "goodbye" does NOT drop the call \u2014 the line stays open until you call the end_call tool. This is the single most important habit on a real phone call: after you have said your goodbye sentence, IMMEDIATELY call end_call({ reason: "..." }). Do not wait for the caller to hang up first; do not assume the system will close the line for you. Call end_call yourself.`,
+      "",
+      "When to call end_call:",
+      "- The task is complete and you have just said goodbye.",
+      '- The caller said "thanks, bye" or otherwise signalled they are done.',
+      `- You scheduled a callback and said "I'll call you back at <when>".`,
+      "- The caller has gone silent for an extended stretch and is clearly not coming back.",
+      "- The operator told you to hang up.",
+      "",
+      "Do NOT call end_call:",
+      "- Mid-conversation when there is still pending business.",
+      "- Because you ran into a tool error \u2014 handle it and keep the call going.",
+      "- During a hold while a tool is running \u2014 let the tool finish."
+    );
+  }
   return lines.join("\n");
 }
 function toolErrorText(err) {
@@ -10032,8 +10066,10 @@ var RealtimeVoiceBridge = class {
     }
     let granted = Math.min(asked, pol.maxSecondsPerRequest, remainingBudgetSeconds);
     const elapsedSeconds = Math.floor((this.nowFn() - this.callStartedAtMs) / 1e3);
-    const maxAllowedFromStart = 3600;
-    const hardCeilingRoom = Math.max(0, maxAllowedFromStart - (elapsedSeconds + this.getTimeRemainingSeconds()));
+    const hardCeilingRoom = Math.max(
+      0,
+      PHONE_SERVER_MAX_CALL_DURATION_SECONDS - (elapsedSeconds + this.getTimeRemainingSeconds())
+    );
     granted = Math.min(granted, hardCeilingRoom);
     if (granted <= 0) {
       return {
@@ -10272,6 +10308,31 @@ var RealtimeVoiceBridge = class {
     return "\u2026\n" + joined.slice(joined.length - MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH + 2);
   }
   // ─── Teardown ─────────────────────────────────────────
+  /**
+   * v0.9.82 — agent-initiated hangup. Called when the `end_call` tool
+   * fires. Logs a marker, then routes through {@link end} so the
+   * carrier sees the bye frame and `onEnd` fires exactly once (the
+   * same teardown path the human-hangup case takes). The "agent-
+   * requested" reason flows through to the mission transcript so a
+   * post-call audit can tell apart "agent hung up" from "human hung
+   * up" from "time budget exceeded".
+   *
+   * Returns the structured result the tool handler echoes back to the
+   * model — even though by the time the model receives it the line
+   * will already be closed, keeping a consistent return shape lets the
+   * executor JSON-stringify deterministically.
+   */
+  endByAgentRequest(reason) {
+    if (this.ended) {
+      return { ok: false, message: "Call has already ended." };
+    }
+    const trimmed = (reason ?? "").trim();
+    this.emitTranscript("system", `Agent requested hangup. Reason: ${trimmed || "unspecified"}`, {
+      endedByAgent: true
+    });
+    this.end("agent-requested");
+    return { ok: true, message: "Call ended." };
+  }
   /**
    * End the bridge. Idempotent — the first call wins, later calls are
    * no-ops. Sends the carrier's end-of-call frame (if it has one — 46elks
@@ -14411,6 +14472,8 @@ export {
   CloudflareClient,
   DEFAULT_AGENT_NAME,
   DEFAULT_AGENT_ROLE,
+  DEFAULT_CALLBACK_POLICY,
+  DEFAULT_EXTENSION_POLICY,
   DEFAULT_REALTIME_AUDIO_FORMAT,
   DEFAULT_REALTIME_MODEL,
   DEFAULT_REALTIME_VOICE,
@@ -14423,8 +14486,11 @@ export {
   DomainPurchaser,
   ELKS_REALTIME_AUDIO_FORMATS,
   ELKS_REALTIME_WS_PATH,
+  END_CALL_TOOL,
+  EXTEND_CALL_TIME_TOOL,
   ElksRealtimeTransport,
   EmailSearchIndex,
+  GET_CALL_STATUS_TOOL,
   GET_DATETIME_TOOL,
   GatewayManager,
   InboxWatcher,
@@ -14439,6 +14505,8 @@ export {
   OPERATOR_QUERY_SUBJECT_TAG,
   OPERATOR_QUERY_TIMEOUT_MS,
   OPERATOR_QUERY_TIMEOUT_SENTINEL,
+  PHONE_CALLBACK_MAX_DELAY_SECONDS,
+  PHONE_CALLBACK_MIN_DELAY_SECONDS,
   PHONE_CALL_CONTROL_PROVIDERS,
   PHONE_MAX_CONCURRENT_MISSIONS,
   PHONE_MIN_WEBHOOK_SECRET_LENGTH,
@@ -14447,8 +14515,12 @@ export {
   PHONE_RATE_LIMIT_PER_MINUTE,
   PHONE_REGION_SCOPES,
   PHONE_SERVER_MAX_ATTEMPTS,
+  PHONE_SERVER_MAX_CALLBACK_CHAIN,
   PHONE_SERVER_MAX_CALL_DURATION_SECONDS,
   PHONE_SERVER_MAX_COST_PER_MISSION,
+  PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL,
+  PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST,
+  PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS,
   PHONE_TASK_MAX_LENGTH,
   PathTraversalError,
   PhoneManager,
@@ -14464,6 +14536,7 @@ export {
   RealtimeVoiceBridge,
   RelayBridge,
   RelayGateway,
+  SCHEDULE_CALLBACK_TOOL,
   SEARCH_EMAIL_TOOL,
   SEARCH_SKILLS_TOOL,
   SPAM_THRESHOLD,
@@ -14584,7 +14657,9 @@ export {
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
+  resolveCallbackPolicy,
   resolveConfig,
+  resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
   safeJoin,
   sanitizeEmail,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "description": "Core SDK for AgenticMail — email, SMS, and phone call-control for AI agents",
   "type": "module",
   "main": "dist/index.js",