@agenticmail/core 0.9.25 → 0.9.27

package/dist/index.cjs

@@ -7518,6 +7518,22 @@ 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 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 DEFAULT_EXTENSION_POLICY = {
+  maxSecondsPerRequest: 120,
+  // 2 minutes
+  maxRequestsPerCall: 2,
+  maxTotalExtensionSeconds: 300
+  // 5 minutes
+};
+var PHONE_SERVER_MAX_CALLBACK_CHAIN = 3;
+var DEFAULT_CALLBACK_POLICY = {
+  allowAutoCallback: true,
+  maxCallbackChain: 2
+};
+var PHONE_CALLBACK_MAX_DELAY_SECONDS = 7 * 24 * 60 * 60;
 var EU_DIAL_PREFIXES = [
   "+30",
   "+31",
@@ -7632,6 +7648,76 @@ function validateAlternativePolicy(value) {
   }
   return [];
 }
+function validateExtensionPolicy(value) {
+  if (value === void 0) return [];
+  if (!isRecord(value)) {
+    return [issue("invalid-extension-policy", "policy.extensionPolicy", "extensionPolicy must be an object")];
+  }
+  const issues = [];
+  const perReq = readPositiveInteger(value.maxSecondsPerRequest);
+  if (perReq === null) {
+    issues.push(issue(
+      "invalid-extension-per-request",
+      "policy.extensionPolicy.maxSecondsPerRequest",
+      "maxSecondsPerRequest must be a positive integer"
+    ));
+  }
+  const requests = readPositiveInteger(value.maxRequestsPerCall);
+  if (requests === null) {
+    issues.push(issue(
+      "invalid-extension-requests",
+      "policy.extensionPolicy.maxRequestsPerCall",
+      "maxRequestsPerCall must be a positive integer"
+    ));
+  }
+  const total = readPositiveInteger(value.maxTotalExtensionSeconds);
+  if (total === null) {
+    issues.push(issue(
+      "invalid-extension-total",
+      "policy.extensionPolicy.maxTotalExtensionSeconds",
+      "maxTotalExtensionSeconds must be a positive integer"
+    ));
+  }
+  return issues;
+}
+function validateCallbackPolicy(value) {
+  if (value === void 0) return [];
+  if (!isRecord(value)) {
+    return [issue("invalid-callback-policy", "policy.callbackPolicy", "callbackPolicy must be an object")];
+  }
+  const issues = [];
+  if (readBoolean(value.allowAutoCallback) === null) {
+    issues.push(issue(
+      "invalid-callback-allow",
+      "policy.callbackPolicy.allowAutoCallback",
+      "allowAutoCallback must be boolean"
+    ));
+  }
+  const chain = readNonNegativeNumber(value.maxCallbackChain);
+  if (chain === null || !Number.isInteger(chain)) {
+    issues.push(issue(
+      "invalid-callback-chain",
+      "policy.callbackPolicy.maxCallbackChain",
+      "maxCallbackChain must be a non-negative integer"
+    ));
+  }
+  return issues;
+}
+function resolveExtensionPolicy(input) {
+  const src = input ?? DEFAULT_EXTENSION_POLICY;
+  return {
+    maxSecondsPerRequest: Math.min(src.maxSecondsPerRequest, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST),
+    maxRequestsPerCall: Math.min(src.maxRequestsPerCall, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL),
+    maxTotalExtensionSeconds: Math.min(src.maxTotalExtensionSeconds, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS)
+  };
+}
+function resolveCallbackPolicy(input) {
+  const src = input ?? DEFAULT_CALLBACK_POLICY;
+  return {
+    allowAutoCallback: src.allowAutoCallback,
+    maxCallbackChain: Math.min(src.maxCallbackChain, PHONE_SERVER_MAX_CALLBACK_CHAIN)
+  };
+}
 function validatePhoneMissionPolicy(policy) {
   const issues = [];
   if (!isRecord(policy)) {
@@ -7666,6 +7752,8 @@ function validatePhoneMissionPolicy(policy) {
   }
   issues.push(...validateConfirmPolicy(policy.confirmPolicy));
   issues.push(...validateAlternativePolicy(policy.alternativePolicy));
+  issues.push(...validateExtensionPolicy(policy.extensionPolicy));
+  issues.push(...validateCallbackPolicy(policy.callbackPolicy));
   if (issues.length > 0) return { ok: false, issues };
   return {
     ok: true,
@@ -7680,7 +7768,14 @@ function validatePhoneMissionPolicy(policy) {
       confirmPolicy: policy.confirmPolicy,
       alternativePolicy: {
         maxTimeShiftMinutes: policy.alternativePolicy.maxTimeShiftMinutes
-      }
+      },
+      // The extension + callback policies are optional in the caller's
+      // input but we ALWAYS materialise them in the resolved policy so
+      // every downstream consumer (the bridge, the scheduler, the
+      // manager) can read a concrete value without juggling undefined.
+      // Caller-omitted → DEFAULT_*. Caller-set → clamped to server caps.
+      extensionPolicy: resolveExtensionPolicy(policy.extensionPolicy),
+      callbackPolicy: resolveCallbackPolicy(policy.callbackPolicy)
     },
     issues: []
   };
@@ -7915,6 +8010,13 @@ function readOperatorQueries(mission) {
   if (!Array.isArray(value)) return [];
   return value.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item) && typeof item.id === "string" && typeof item.question === "string");
 }
+function readChainDepth(mission) {
+  const raw = mission.metadata.callbackChainDepth;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+  const sc = mission.metadata.scheduledCallback;
+  if (sc && Number.isFinite(sc.chainDepth)) return Math.floor(sc.chainDepth);
+  return 0;
+}
 function escapeLike(value) {
   return value.replace(/[\\%_]/g, "\\$&");
 }
@@ -7933,6 +8035,26 @@ function buildCallbackTask(originalTask, query) {
   return `${continuity}
 ${originalTask.slice(0, room)}`.slice(0, PHONE_TASK_MAX_LENGTH);
 }
+function buildScheduledCallbackTask(originalTask, payload) {
+  const continuity = [
+    "# Call continuity \u2014 auto-callback",
+    'You were on a call with this person earlier and scheduled this follow-up before signing off. Open by acknowledging it naturally \u2014 e.g. "Hi, this is <your name> calling back as I said I would." Then continue the conversation from where you left off.',
+    "",
+    `## Why you arranged this callback
+${payload.reason}`,
+    "",
+    `## Notes you left for yourself (your own summary at the end of the prior call)
+${payload.agentSummary}`,
+    "",
+    `## What was actually said on the prior call (verbatim digest)
+${payload.transcriptDigest}`,
+    "",
+    "# Original task"
+  ].join("\n");
+  const room = Math.max(0, PHONE_TASK_MAX_LENGTH - continuity.length - 1);
+  return `${continuity}
+${originalTask.slice(0, room)}`.slice(0, PHONE_TASK_MAX_LENGTH);
+}
 function parseJson(value, fallback) {
   if (!value) return fallback;
   try {
@@ -8605,6 +8727,134 @@ var PhoneManager = class {
       throw err;
     }
   }
+  // ─── Scheduled callbacks (v0.9.81 — schedule_callback tool) ──────────
+  /**
+   * Persist a `schedule_callback` request to the mission. Called from
+   * the realtime bridge's `onCallbackScheduled` hook. The scheduler
+   * picks this up later when `payload.at <= now`. ChainDepth is
+   * computed from the parent's metadata so {@link triggerScheduledCallback}
+   * can enforce policy.callbackPolicy.maxCallbackChain without
+   * walking back through the mission history.
+   *
+   * Returns the updated mission, or null if the mission isn't known.
+   * Idempotent on the `mission.metadata.scheduledCallback.at` key: if
+   * a scheduled callback already exists on the mission this writes a
+   * SECOND copy on `scheduledCallbacks` as an audit trail but does
+   * NOT overwrite the active record (the bridge only allows one per
+   * call anyway; the audit log is a belt-and-braces guard against
+   * the unusual case where a server restart re-runs the bridge logic).
+   */
+  armScheduledCallback(missionId, payload) {
+    const mission = this.getMission(missionId);
+    if (!mission) return null;
+    const parentDepth = readChainDepth(mission);
+    const record = {
+      at: payload.at,
+      reason: payload.reason,
+      agentSummary: payload.agentSummary,
+      transcriptDigest: payload.transcriptDigest,
+      chainDepth: parentDepth + 1,
+      status: "pending",
+      armedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return this.updateMissionStatus(mission.id, mission.status, {
+      scheduledCallback: record
+    }, [{
+      at: record.armedAt,
+      source: "system",
+      text: `Scheduled callback armed for ${record.at} (chain depth ${record.chainDepth}). Reason: ${record.reason}`,
+      metadata: { scheduledAt: record.at, chainDepth: record.chainDepth }
+    }]);
+  }
+  /**
+   * All missions with a `scheduledCallback.status === 'pending'` whose
+   * `at` is <= now. The scheduler's per-tick worklist. Pass an upper
+   * bound on count so a backlog doesn't dial every overdue callback in
+   * one frame.
+   */
+  findDueScheduledCallbacks(nowIso, limit = 16) {
+    const rows = this.db.prepare(
+      "SELECT * FROM phone_missions WHERE metadata_json LIKE '%scheduledCallback%' AND metadata_json LIKE '%pending%' LIMIT ?"
+    ).all(limit * 4);
+    return rows.map(rowToMission).filter((mission) => {
+      const sc = mission.metadata.scheduledCallback;
+      return sc && sc.status === "pending" && sc.at <= nowIso;
+    }).slice(0, limit);
+  }
+  /**
+   * Dial a due scheduled callback. Mirrors {@link triggerCallback} for
+   * the operator-query path:
+   *
+   *   1. Reject if the mission's policy.callbackPolicy disallows it OR
+   *      `chainDepth > maxCallbackChain` (no infinite chains).
+   *   2. Transition status pending → dialing BEFORE dialing so a
+   *      concurrent tick can't double-dial.
+   *   3. Build the continuation task with prior-call context and dial.
+   *   4. On success: write `status: 'fired'` + the new mission id.
+   *   5. On failure: write `status: 'pending'` + `lastError` so the
+   *      next tick can retry, then rethrow.
+   *
+   * Returns `null` if the mission isn't known or has no due callback.
+   */
+  async triggerScheduledCallback(missionId, options = {}) {
+    const mission = this.getMission(missionId);
+    if (!mission) return null;
+    const sc = mission.metadata.scheduledCallback;
+    if (!sc) return null;
+    if (sc.status !== "pending") return null;
+    const callbackPol = mission.policy.callbackPolicy;
+    if (!callbackPol || !callbackPol.allowAutoCallback || sc.chainDepth > callbackPol.maxCallbackChain) {
+      const updated = this.updateMissionStatus(mission.id, mission.status, {
+        scheduledCallback: { ...sc, status: "failed", lastError: "policy denies callback (chain or disabled)" }
+      }, [{
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        source: "system",
+        text: `Scheduled callback denied by policy (chainDepth=${sc.chainDepth}, max=${callbackPol?.maxCallbackChain ?? 0}).`
+      }]);
+      return updated ? { mission: updated, callbackMission: updated } : null;
+    }
+    this.updateMissionStatus(mission.id, mission.status, {
+      scheduledCallback: { ...sc, status: "dialing" }
+    }, [{
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "system",
+      text: `Dialing scheduled callback (chain depth ${sc.chainDepth}).`
+    }]);
+    try {
+      const result = await this.startMission(mission.agentId, {
+        to: mission.to,
+        task: buildScheduledCallbackTask(mission.task, {
+          reason: sc.reason,
+          agentSummary: sc.agentSummary,
+          transcriptDigest: sc.transcriptDigest
+        }),
+        policy: mission.policy
+      }, options);
+      const callbackMission = this.updateMissionStatus(result.mission.id, result.mission.status, {
+        callbackChainDepth: sc.chainDepth,
+        callbackParentMissionId: mission.id
+      }, []) ?? result.mission;
+      const linked = this.updateMissionStatus(mission.id, mission.status, {
+        scheduledCallback: {
+          ...sc,
+          status: "fired",
+          firedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          callbackMissionId: result.mission.id
+        }
+      }, []);
+      return { mission: linked, callbackMission };
+    } catch (err) {
+      const message = err?.message ?? String(err);
+      this.updateMissionStatus(mission.id, mission.status, {
+        scheduledCallback: { ...sc, status: "pending", lastError: message }
+      }, [{
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        source: "system",
+        text: `Scheduled callback dial failed (${message}); will retry on next scheduler tick.`
+      }]);
+      throw err;
+    }
+  }
   build46ElksCallRequest(config, mission) {
     const timeout = Math.min(Math.max(mission.policy.maxCallDurationSeconds, 1), PHONE_SERVER_MAX_CALL_DURATION_SECONDS);
     return {
@@ -8745,7 +8995,8 @@ function buildPhoneTransportConfig(input) {
     }
   }
   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 defaultRegions = isTwilio ? ["WORLD"] : ["EU"];
+  const supportedRegions = Array.isArray(input.supportedRegions) ? input.supportedRegions.filter((item) => typeof item === "string" && ["AT", "DE", "EU", "WORLD"].includes(item)) : defaultRegions;
   const config = {
     provider,
     phoneNumber,
@@ -8755,7 +9006,7 @@ function buildPhoneTransportConfig(input) {
     webhookSecret,
     apiUrl: apiUrl || void 0,
     capabilities: Array.from(/* @__PURE__ */ new Set(["call_control", ...capabilities])),
-    supportedRegions: supportedRegions.length ? Array.from(new Set(supportedRegions)) : ["EU"],
+    supportedRegions: supportedRegions.length ? Array.from(new Set(supportedRegions)) : defaultRegions,
     configuredAt: input.configuredAt ?? (/* @__PURE__ */ new Date()).toISOString()
   };
   const validation = validatePhoneTransportProfile(config);
@@ -10443,6 +10694,57 @@ var LOAD_SKILL_TOOL = {
     additionalProperties: false
   }
 };
+var GET_CALL_STATUS_TOOL = {
+  type: "function",
+  name: "get_call_status",
+  description: "Check how much time you have left on this call and whether you can request more time or schedule a callback. Use this whenever you are unsure if there is room to keep going. Returns: secondsRemaining, soft deadline timestamp, extensions used/remaining/availableSeconds, callbackAvailable.",
+  parameters: {
+    type: "object",
+    properties: {}
+  }
+};
+var EXTEND_CALL_TIME_TOOL = {
+  type: "function",
+  name: "extend_call_time",
+  description: "Request more time on this call. Auto-approved within your call's extension policy \u2014 you do not need to ask the operator. Use this BEFORE your time runs out. If the grant is partial or refused the response tells you exactly what you have left; do not retry-loop.",
+  parameters: {
+    type: "object",
+    properties: {
+      seconds: {
+        type: "number",
+        description: "How many MORE seconds you need. Positive integer. The server caps each grant."
+      },
+      reason: {
+        type: "string",
+        description: "One short line on why \u2014 kept on the mission transcript for review."
+      }
+    },
+    required: ["seconds"]
+  }
+};
+var SCHEDULE_CALLBACK_TOOL = {
+  type: "function",
+  name: "schedule_callback",
+  description: 'Arrange an auto-callback to this same number at a later time. Use this when you cannot finish in the time available, or when the caller needs a break, or when context dictates a follow-up ("call me after 5pm", "try again tomorrow"). The next call picks up with your summary + the transcript so far automatically \u2014 say goodbye and the system handles re-dialing. Only ONE callback can be scheduled per call; choose carefully.',
+  parameters: {
+    type: "object",
+    properties: {
+      delay_seconds: {
+        type: "number",
+        description: 'How many seconds from now to call back. Minimum 30, maximum 604800 (7 days). Use larger delays generously \u2014 "tomorrow morning" is ~57600s.'
+      },
+      reason: {
+        type: "string",
+        description: 'One short line for the audit trail \u2014 e.g. "ran out of time before confirming the booking" or "caller asked me to ring back after 5pm".'
+      },
+      summary_for_next_call: {
+        type: "string",
+        description: "What the next call agent MUST know to pick up where you left off \u2014 facts you collected, the caller's name, what was agreed, what is still open. Be concrete; this is all the next agent has from your call."
+      }
+    },
+    required: ["delay_seconds", "summary_for_next_call"]
+  }
+};
 var REALTIME_TOOL_DEFINITIONS = {
   ask_operator: ASK_OPERATOR_TOOL,
   web_search: WEB_SEARCH_TOOL,
@@ -10450,7 +10752,10 @@ var REALTIME_TOOL_DEFINITIONS = {
   get_datetime: GET_DATETIME_TOOL,
   search_email: SEARCH_EMAIL_TOOL,
   search_skills: SEARCH_SKILLS_TOOL,
-  load_skill: LOAD_SKILL_TOOL
+  load_skill: LOAD_SKILL_TOOL,
+  get_call_status: GET_CALL_STATUS_TOOL,
+  extend_call_time: EXTEND_CALL_TIME_TOOL,
+  schedule_callback: SCHEDULE_CALLBACK_TOOL
 };
 function buildRealtimeToolGuidance(tools) {
   if (tools.length === 0) return "";
@@ -10479,6 +10784,24 @@ function buildRealtimeToolGuidance(tools) {
 A skill's rendered playbook is now part of your instructions for the rest of the call. You can load a second skill if a new situation comes up \u2014 but the model keeps a max of two loaded; a third load drops the oldest. Pick skills deliberately.`
     );
   }
+  if (names.has("get_call_status") || names.has("extend_call_time") || names.has("schedule_callback")) {
+    lines.push(
+      "# Managing your time on this call",
+      "You have a fixed time budget. The system will quietly remind you when you have about 2 minutes left and again at about 30 seconds left \u2014 pace your conversation so you can wrap up cleanly.",
+      "",
+      "If you need more time to finish the job:",
+      `- Call extend_call_time({ seconds: 120, reason: "..." }) BEFORE you run out. Requests are auto-approved within the call's extension policy \u2014 you do not need to ask the operator. The response tells you exactly how much you got and how much extension budget remains.`,
+      "",
+      "If you cannot finish in time, the caller wants you to call back later, OR you sense the conversation has hit a natural pause that needs a follow-up:",
+      `- Call schedule_callback({ delay_seconds: <when>, reason: "...", summary_for_next_call: "..." }) BEFORE you sign off. The summary you pass becomes the next call's starting context \u2014 be concrete: caller's name, what was agreed, what's still open, any commitments you made.`,
+      `- Then politely close: "Thanks for your time \u2014 I'll call you back at <when>." The system dials back automatically with your summary + the conversation so far loaded for the next agent.`,
+      "- You can ONLY schedule one callback per call. Choose deliberately.",
+      "",
+      "You can check the current status (time left, extensions used, callback availability) at any moment with get_call_status \u2014 but do not fixate; keep the call moving.",
+      "",
+      "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."
+    );
+  }
   return lines.join("\n");
 }
 function toolErrorText(err) {
@@ -10684,6 +11007,26 @@ ${task}`);
       '# What you already know\nThe following is your own long-term memory \u2014 knowledge, preferences, and lessons you have accumulated over time. Treat it as your own experience and act on it naturally. Do not read it aloud or mention that it is "memory"; simply know it.\n\n' + memory
     );
   }
+  const budget = opts.callBudget;
+  if (budget && budget.seconds > 0) {
+    const mins = Math.round(budget.seconds / 60);
+    const human = mins >= 1 ? `about ${mins} minute(s)` : `${budget.seconds} seconds`;
+    const tips = [];
+    if (budget.extensionEnabled) {
+      tips.push(
+        "If you need more time, call extend_call_time({ seconds, reason }) BEFORE you run out. Auto-approved within the call's extension policy."
+      );
+    }
+    if (budget.callbackEnabled) {
+      tips.push(
+        "If you cannot finish in time, the caller wants you to ring back later, or the conversation naturally pauses for a follow-up, call schedule_callback({ delay_seconds, reason, summary_for_next_call }) BEFORE signing off. The next call automatically picks up with your summary and the transcript so far."
+      );
+    }
+    sections.push(
+      `# Your time on this call
+You have ${human} for this call. The system will quietly remind you at the 2-minute and 30-second marks \u2014 pace the conversation so you can wrap up cleanly.` + (tips.length > 0 ? "\n\n" + tips.join("\n") : "")
+    );
+  }
   const toolGuidance = opts.toolGuidance?.trim();
   if (toolGuidance) {
     sections.push(toolGuidance);
@@ -10723,6 +11066,10 @@ function buildRealtimeSessionConfig(opts) {
 function buildOpenAIRealtimeUrl(model = DEFAULT_REALTIME_MODEL) {
   return `${OPENAI_REALTIME_URL}?model=${encodeURIComponent(model || DEFAULT_REALTIME_MODEL)}`;
 }
+var MAX_CALLBACK_SUMMARY_LENGTH = 1500;
+var MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH = 2500;
+var CALL_BUDGET_REMINDER_MARKS_SECONDS = [120, 30];
+var CALL_BUDGET_GRACE_SECONDS = 30;
 var RealtimeVoiceBridge = class {
   carrier;
   openai;
@@ -10733,6 +11080,46 @@ var RealtimeVoiceBridge = class {
   maxToolCallMs;
   onTranscript;
   onEnd;
+  /** Injectable clock + timers (tests substitute fakes). */
+  nowFn;
+  setTimeoutFn;
+  clearTimeoutFn;
+  /** v0.9.81 — extension / callback state. */
+  extensionPolicy;
+  callbackPolicy;
+  onCallbackScheduled;
+  /** Initial soft budget, in seconds. 0 = no bridge-side timer (legacy). */
+  initialBudgetSeconds;
+  /** Wall-clock ms when the call started, set on first carrier hello. */
+  callStartedAtMs = null;
+  /** Wall-clock ms when the soft deadline fires. Bumped by extensions. */
+  softDeadlineMs = null;
+  /** Soft-end timer (fires once, then schedules the grace timer). */
+  softEndTimer = null;
+  /** Final hard-end timer that fires after the grace window. */
+  graceEndTimer = null;
+  /** Reminder timers for the T-N marks. Cleared/re-armed on extensions. */
+  reminderTimers = [];
+  /** Marks (in seconds-remaining) we've already fired this call. Dedup
+   *  prevents re-injecting the same reminder after an extension if the
+   *  new deadline still has us past the same mark. */
+  firedReminderMarks = /* @__PURE__ */ new Set();
+  /** Count of extensions granted this call. */
+  extensionsUsed = 0;
+  /** Total extra seconds granted across all extensions this call. */
+  extensionSecondsUsed = 0;
+  /** True once the agent's schedule_callback request was accepted. */
+  callbackArmed = false;
+  /** Captured for the API layer when the soft deadline fires. */
+  endedByTimeBudgetFlag = false;
+  /**
+   * Sliding window of recent assistant + system utterances, used to
+   * build the transcript digest carried into a scheduled callback.
+   * Capped at {@link MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH} chars so
+   * the digest itself can always be produced cheaply even on a long
+   * call.
+   */
+  recentUtterances = [];
   /** Carrier `hello`/`start` received — the call leg is live. */
   helloSeen = false;
   /** OpenAI socket open + `session.update` sent. */
@@ -10790,6 +11177,13 @@ var RealtimeVoiceBridge = class {
     this.maxToolCallMs = opts.maxToolCallMs ?? REALTIME_TOOL_CALL_TIMEOUT_MS;
     this.onTranscript = opts.onTranscript;
     this.onEnd = opts.onEnd;
+    this.nowFn = opts.now ?? Date.now;
+    this.setTimeoutFn = opts.setTimeoutFn ?? setTimeout;
+    this.clearTimeoutFn = opts.clearTimeoutFn ?? clearTimeout;
+    this.initialBudgetSeconds = opts.callBudgetSeconds && opts.callBudgetSeconds > 0 ? Math.floor(opts.callBudgetSeconds) : 0;
+    this.extensionPolicy = opts.extensionPolicy;
+    this.callbackPolicy = opts.callbackPolicy;
+    this.onCallbackScheduled = opts.onCallbackScheduled;
   }
   /** True once the bridge has ended. */
   get isEnded() {
@@ -10951,6 +11345,7 @@ var RealtimeVoiceBridge = class {
         from: event.from,
         to: event.to
       });
+      this.startCallBudget();
       return;
     }
     if (event.kind === "audio") {
@@ -11029,14 +11424,20 @@ var RealtimeVoiceBridge = class {
       case "response.output_audio_transcript.done":
       case "response.audio_transcript.done": {
         const text = this.assistantTranscript.trim();
-        if (text) this.emitTranscript("agent", text);
+        if (text) {
+          this.emitTranscript("agent", text);
+          this.noteUtterance(`Agent: ${text}`);
+        }
         this.assistantTranscript = "";
         return;
       }
       // Caller speech transcription, when input transcription is on.
       case "conversation.item.input_audio_transcription.completed": {
         const text = typeof event.transcript === "string" ? event.transcript.trim() : "";
-        if (text) this.emitTranscript("provider", text, { speaker: "caller" });
+        if (text) {
+          this.emitTranscript("provider", text, { speaker: "caller" });
+          this.noteUtterance(`Caller: ${text}`);
+        }
         return;
       }
       // A new output item was added to the response. When it is a
@@ -11156,6 +11557,369 @@ var RealtimeVoiceBridge = class {
     });
     this.safeSend(this.openai, { type: "response.create" });
   }
+  // ─── Call-budget timers / extensions / callback (v0.9.81) ─────────
+  /** True if the agent's `schedule_callback` request has been accepted. */
+  get isCallbackArmed() {
+    return this.callbackArmed;
+  }
+  /**
+   * Seconds remaining on the current soft deadline, floored at 0. Returns
+   * the initial budget if hello hasn't fired yet, and `Infinity` if no
+   * call budget was configured (legacy mode). Used by `get_call_status`.
+   */
+  getTimeRemainingSeconds() {
+    if (this.initialBudgetSeconds <= 0) return Number.POSITIVE_INFINITY;
+    if (this.callStartedAtMs == null || this.softDeadlineMs == null) {
+      return this.initialBudgetSeconds;
+    }
+    return Math.max(0, Math.ceil((this.softDeadlineMs - this.nowFn()) / 1e3));
+  }
+  /**
+   * Public extension state snapshot for `get_call_status`. Each value is
+   * "what the agent has left" so the model can decide whether to call
+   * `extend_call_time` at all — exposing both the per-request cap AND
+   * the remaining budget makes greedy / unbounded extension attempts
+   * impossible.
+   */
+  getExtensionStatus() {
+    const pol = this.extensionPolicy;
+    if (!pol) {
+      return {
+        extensionsUsed: 0,
+        extensionsRemaining: 0,
+        secondsUsedSoFar: 0,
+        secondsAvailable: 0,
+        maxSecondsPerRequest: 0
+      };
+    }
+    return {
+      extensionsUsed: this.extensionsUsed,
+      extensionsRemaining: Math.max(0, pol.maxRequestsPerCall - this.extensionsUsed),
+      secondsUsedSoFar: this.extensionSecondsUsed,
+      secondsAvailable: Math.max(0, pol.maxTotalExtensionSeconds - this.extensionSecondsUsed),
+      maxSecondsPerRequest: pol.maxSecondsPerRequest
+    };
+  }
+  /**
+   * Grant (or refuse) more time on the call. Auto-approved within all
+   * three policy caps; the granted amount is the min of:
+   *
+   *   - the agent's requested seconds (positive integer, clamped > 0)
+   *   - policy.maxSecondsPerRequest
+   *   - policy.maxTotalExtensionSeconds − seconds already granted
+   *
+   * AND we won't push the new deadline past the hard ceiling
+   * (PHONE_SERVER_MAX_CALL_DURATION_SECONDS from call start). The
+   * returned shape always includes a model-readable `reason` so a
+   * partial grant ("you asked for 5 min, you got 2 min") doesn't
+   * confuse the agent.
+   *
+   * Failure modes (granted: 0):
+   *   - no extension policy on this call
+   *   - max requests already used
+   *   - max total seconds already used
+   *   - call already ended
+   *   - non-positive `seconds`
+   */
+  extendCallTime(requestedSeconds, reason) {
+    if (this.ended) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: 0,
+        extensionsRemaining: 0,
+        message: "The call has already ended; no more extensions can be granted."
+      };
+    }
+    const pol = this.extensionPolicy;
+    if (!pol) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: this.getTimeRemainingSeconds(),
+        extensionsRemaining: 0,
+        message: "Extensions are not enabled for this call."
+      };
+    }
+    if (this.initialBudgetSeconds <= 0 || this.softDeadlineMs == null || this.callStartedAtMs == null) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: Number.POSITIVE_INFINITY,
+        extensionsRemaining: pol.maxRequestsPerCall - this.extensionsUsed,
+        message: "This call has no soft time budget, so extensions are a no-op."
+      };
+    }
+    if (this.extensionsUsed >= pol.maxRequestsPerCall) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: this.getTimeRemainingSeconds(),
+        extensionsRemaining: 0,
+        message: `Out of extensions \u2014 already used ${pol.maxRequestsPerCall}/${pol.maxRequestsPerCall} this call. Wrap up or schedule a callback.`
+      };
+    }
+    const remainingBudgetSeconds = Math.max(0, pol.maxTotalExtensionSeconds - this.extensionSecondsUsed);
+    if (remainingBudgetSeconds <= 0) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: this.getTimeRemainingSeconds(),
+        extensionsRemaining: Math.max(0, pol.maxRequestsPerCall - this.extensionsUsed),
+        message: `Out of extension time \u2014 already granted ${this.extensionSecondsUsed}s of the ${pol.maxTotalExtensionSeconds}s cap.`
+      };
+    }
+    const asked = Math.floor(requestedSeconds);
+    if (!Number.isFinite(asked) || asked <= 0) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: this.getTimeRemainingSeconds(),
+        extensionsRemaining: Math.max(0, pol.maxRequestsPerCall - this.extensionsUsed),
+        message: "extend_call_time requires a positive integer number of seconds."
+      };
+    }
+    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()));
+    granted = Math.min(granted, hardCeilingRoom);
+    if (granted <= 0) {
+      return {
+        granted: false,
+        secondsGranted: 0,
+        secondsRemaining: this.getTimeRemainingSeconds(),
+        extensionsRemaining: Math.max(0, pol.maxRequestsPerCall - this.extensionsUsed),
+        message: "No extension granted \u2014 the call is already at the hard duration ceiling."
+      };
+    }
+    this.extensionsUsed += 1;
+    this.extensionSecondsUsed += granted;
+    this.softDeadlineMs = this.softDeadlineMs + granted * 1e3;
+    this.rearmBudgetTimers();
+    this.emitTranscript("system", `Granted ${granted}s extension (#${this.extensionsUsed}). Reason: ${truncate2(asString5(reason) || "unspecified", 120)}`, {
+      extensionsUsed: this.extensionsUsed,
+      extensionSecondsUsed: this.extensionSecondsUsed,
+      softDeadlineMs: this.softDeadlineMs
+    });
+    return {
+      granted: true,
+      secondsGranted: granted,
+      secondsRemaining: this.getTimeRemainingSeconds(),
+      extensionsRemaining: Math.max(0, pol.maxRequestsPerCall - this.extensionsUsed),
+      message: `Granted ${granted} more seconds (${this.getTimeRemainingSeconds()}s now remaining). ${Math.max(0, pol.maxRequestsPerCall - this.extensionsUsed)} extension(s) left after this one.`
+    };
+  }
+  /**
+   * Capture the agent's `schedule_callback` request. The bridge VALIDATES
+   * (policy allows it, delay is in the legal window, summary present),
+   * builds a transcript digest from {@link recentUtterances}, then fires
+   * {@link onCallbackScheduled} so the API layer can persist + arm the
+   * scheduler. The bridge does NOT itself dial — that's the scheduler's
+   * job, fired at the requested wall-clock time.
+   *
+   * Returning `{ accepted: true }` arms `isCallbackArmed`, which the
+   * end-of-call path uses to skip the legacy operator-query callback
+   * flag (the agent has already declared its own follow-up plan).
+   */
+  scheduleCallback(req) {
+    if (this.ended) {
+      return { accepted: false, message: "Cannot schedule a callback \u2014 the call has already ended." };
+    }
+    if (this.callbackArmed) {
+      return { accepted: false, message: "A callback has already been scheduled for this call. Stick with that plan." };
+    }
+    const pol = this.callbackPolicy;
+    if (!pol || !pol.allowAutoCallback || pol.maxCallbackChain <= 0) {
+      return {
+        accepted: false,
+        message: "Auto-callbacks are disabled by policy on this call. Tell the caller you will follow up another way."
+      };
+    }
+    const delay = Math.floor(req.delaySeconds);
+    const minDelay = 30;
+    const maxDelay = 7 * 24 * 60 * 60;
+    if (!Number.isFinite(delay) || delay < minDelay) {
+      return {
+        accepted: false,
+        message: `Callbacks must be scheduled at least ${minDelay}s in the future.`
+      };
+    }
+    if (delay > maxDelay) {
+      return {
+        accepted: false,
+        message: `Callbacks must be scheduled within ${Math.floor(maxDelay / 86400)} days.`
+      };
+    }
+    const summary = asString5(req.summary);
+    if (!summary) {
+      return {
+        accepted: false,
+        message: "schedule_callback requires a non-empty `summary` for the next call to pick up from."
+      };
+    }
+    const at = new Date(this.nowFn() + delay * 1e3).toISOString();
+    const digest = this.composeTranscriptDigest();
+    const payload = {
+      at,
+      reason: truncate2(asString5(req.reason) || "no reason given", 240),
+      agentSummary: truncate2(summary, MAX_CALLBACK_SUMMARY_LENGTH),
+      transcriptDigest: digest
+    };
+    try {
+      this.onCallbackScheduled?.(payload);
+    } catch (err) {
+      return { accepted: false, message: `Could not arm callback: ${errorText(err)}` };
+    }
+    this.callbackArmed = true;
+    this.emitTranscript("system", `Callback scheduled for ${at}. Reason: ${payload.reason}`, {
+      scheduledAt: at,
+      summaryLength: payload.agentSummary.length,
+      digestLength: digest.length
+    });
+    return {
+      accepted: true,
+      at,
+      message: `Callback scheduled for ${at}. The next call will pick up with your summary + the transcript so far.`
+    };
+  }
+  /**
+   * Public time-budget snapshot for `get_call_status`. Bundles
+   * everything the agent needs to decide whether to keep going, ask
+   * for more time, or schedule a callback.
+   */
+  getCallStatus() {
+    return {
+      secondsRemaining: this.getTimeRemainingSeconds(),
+      softDeadlineAt: this.softDeadlineMs ? new Date(this.softDeadlineMs).toISOString() : null,
+      extension: this.getExtensionStatus(),
+      callbackAvailable: !!this.callbackPolicy?.allowAutoCallback && (this.callbackPolicy?.maxCallbackChain ?? 0) > 0 && !this.callbackArmed,
+      callbackArmed: this.callbackArmed
+    };
+  }
+  /**
+   * Arm the soft-deadline timer + reminder timers. Called once at hello.
+   * No-op when the bridge has no budget configured.
+   */
+  startCallBudget() {
+    if (this.initialBudgetSeconds <= 0) return;
+    const nowMs = this.nowFn();
+    this.callStartedAtMs = nowMs;
+    this.softDeadlineMs = nowMs + this.initialBudgetSeconds * 1e3;
+    this.emitTranscript("system", `Call budget armed: ${this.initialBudgetSeconds}s, soft deadline ${new Date(this.softDeadlineMs).toISOString()}.`, {
+      budgetSeconds: this.initialBudgetSeconds
+    });
+    this.rearmBudgetTimers();
+  }
+  /**
+   * Cancel all existing budget timers and re-arm them against
+   * {@link softDeadlineMs}. Called at startCallBudget time AND after
+   * every successful {@link extendCallTime} grant — the timers always
+   * reflect the CURRENT deadline.
+   */
+  rearmBudgetTimers() {
+    this.clearBudgetTimers();
+    if (this.softDeadlineMs == null) return;
+    const nowMs = this.nowFn();
+    const msToDeadline = this.softDeadlineMs - nowMs;
+    for (const mark of CALL_BUDGET_REMINDER_MARKS_SECONDS) {
+      const msUntilMark = msToDeadline - mark * 1e3;
+      if (msUntilMark <= 0) continue;
+      if (this.firedReminderMarks.has(mark)) continue;
+      const t = this.setTimeoutFn(() => {
+        this.firedReminderMarks.add(mark);
+        this.injectReminder(mark);
+      }, msUntilMark);
+      this.reminderTimers.push(t);
+    }
+    const msUntilSoftEnd = Math.max(0, msToDeadline);
+    this.softEndTimer = this.setTimeoutFn(() => {
+      this.softEndTimer = null;
+      this.onSoftDeadline();
+    }, msUntilSoftEnd);
+  }
+  /** Cancel all currently-armed budget timers. Idempotent. */
+  clearBudgetTimers() {
+    if (this.softEndTimer) {
+      this.clearTimeoutFn(this.softEndTimer);
+      this.softEndTimer = null;
+    }
+    if (this.graceEndTimer) {
+      this.clearTimeoutFn(this.graceEndTimer);
+      this.graceEndTimer = null;
+    }
+    for (const t of this.reminderTimers) {
+      this.clearTimeoutFn(t);
+    }
+    this.reminderTimers = [];
+  }
+  /**
+   * Inject a "you have ~N seconds left" system message into the live
+   * OpenAI session. The model receives it as a `conversation.item.create`
+   * with role:`system`, followed by `response.create` so it can decide
+   * whether to acknowledge it out loud (often it just naturally
+   * accelerates wrap-up; we don't force a verbal "I have 30 seconds").
+   */
+  injectReminder(secondsRemaining) {
+    if (this.ended || !this.openaiReady) return;
+    const text = secondsRemaining >= 60 ? `[system] About ${Math.round(secondsRemaining / 60)} minute(s) left on this call. Start wrapping up \u2014 if you need more time, call extend_call_time; if you can't finish, call schedule_callback before signing off.` : `[system] About ${secondsRemaining}s left on this call. Wrap up now: thank the caller, give a clear next step, and sign off.`;
+    this.safeSend(this.openai, {
+      type: "conversation.item.create",
+      item: { type: "message", role: "system", content: [{ type: "input_text", text }] }
+    });
+    this.safeSend(this.openai, { type: "response.create" });
+    this.emitTranscript("system", `Time reminder injected at T-${secondsRemaining}s.`);
+  }
+  /**
+   * Fires once the soft deadline elapses. Injects a "your time is up"
+   * system message + schedules the grace-window hard end. If the agent
+   * uses the grace window to call `schedule_callback` or `extend_call_time`
+   * the latter can push the deadline forward again — that's fine, the
+   * grace timer is cancelled by {@link extendCallTime} via rearmBudgetTimers.
+   */
+  onSoftDeadline() {
+    if (this.ended) return;
+    if (this.openaiReady) {
+      const text = `[system] Your time on this call is up. You have ~${CALL_BUDGET_GRACE_SECONDS} seconds to wrap up. If you need to continue with this person, call schedule_callback NOW with the time and a summary. Then thank them, give a clear next step, and sign off. The line will close at the end of the grace window.`;
+      this.safeSend(this.openai, {
+        type: "conversation.item.create",
+        item: { type: "message", role: "system", content: [{ type: "input_text", text }] }
+      });
+      this.safeSend(this.openai, { type: "response.create" });
+    }
+    this.emitTranscript("system", `Soft deadline reached; ${CALL_BUDGET_GRACE_SECONDS}s grace window started.`);
+    this.endedByTimeBudgetFlag = true;
+    this.graceEndTimer = this.setTimeoutFn(() => {
+      this.graceEndTimer = null;
+      if (this.ended) return;
+      this.emitTranscript("system", "Grace window elapsed \u2014 bridge ending call.");
+      this.end("time-budget-exceeded");
+    }, CALL_BUDGET_GRACE_SECONDS * 1e3);
+  }
+  /**
+   * Add an utterance to the rolling buffer used for the callback
+   * transcript digest. Bounded by char count, not entry count, so a
+   * burst of short turns doesn't get pruned prematurely.
+   */
+  noteUtterance(line) {
+    if (!line) return;
+    this.recentUtterances.push(line);
+    let total = this.recentUtterances.reduce((n, s) => n + s.length, 0);
+    while (total > MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH * 2 && this.recentUtterances.length > 1) {
+      const dropped = this.recentUtterances.shift();
+      total -= dropped.length;
+    }
+  }
+  /**
+   * Compose a transcript digest from the rolling buffer. Used as the
+   * "context from the previous call" payload in {@link scheduleCallback}.
+   * Always honours {@link MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH}.
+   */
+  composeTranscriptDigest() {
+    const joined = this.recentUtterances.join("\n");
+    if (joined.length <= MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH) return joined;
+    return "\u2026\n" + joined.slice(joined.length - MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH + 2);
+  }
   // ─── Teardown ─────────────────────────────────────────
   /**
    * End the bridge. Idempotent — the first call wins, later calls are
@@ -11165,6 +11929,7 @@ var RealtimeVoiceBridge = class {
   end(reason) {
     if (this.ended) return;
     this.ended = true;
+    this.clearBudgetTimers();
     if (this.droppedFrames > 0) {
       this.onTranscript?.({
         source: "system",
@@ -11193,7 +11958,11 @@ var RealtimeVoiceBridge = class {
       this.openai.close();
     } catch {
     }
-    this.onEnd?.({ reason, pendingToolCalls });
+    if (this.endedByTimeBudgetFlag) {
+      this.onEnd?.({ reason, pendingToolCalls, endedByTimeBudget: true });
+    } else {
+      this.onEnd?.({ reason, pendingToolCalls });
+    }
   }
   // ─── Internals ────────────────────────────────────────
   noteDroppedFrame() {