@agenticmail/core 0.9.26 → 0.9.28

package/dist/index.d.cts

@@ -2600,6 +2600,161 @@ declare class TwilioRealtimeTransport implements RealtimeTransportAdapter {
 /** Construct the transport adapter for a provider. */
 declare function createRealtimeTransport(provider: RealtimeTransportProvider): RealtimeTransportAdapter;
 
+declare const PHONE_REGION_SCOPES: readonly ["AT", "DE", "EU", "WORLD"];
+type PhoneRegionScope = typeof PHONE_REGION_SCOPES[number];
+declare const TELEPHONY_TRANSPORT_CAPABILITIES: readonly ["sms", "call_control", "realtime_media", "recording_supported"];
+type TelephonyTransportCapability = typeof TELEPHONY_TRANSPORT_CAPABILITIES[number];
+declare const PHONE_MISSION_STATES: readonly ["draft", "approved", "dialing", "connected", "conversing", "needs_operator", "completed", "failed", "cancelled"];
+type PhoneMissionState = typeof PHONE_MISSION_STATES[number];
+type PhoneNumberRisk = 'invalid' | 'standard' | 'premium_or_special';
+/**
+ * Server-side hard ceilings for a phone mission policy.
+ *
+ * Hardening (#42-H1 / #43-H2) — `policy` is supplied by the calling agent,
+ * so a caller-set `maxCallDurationSeconds: 999999` or `maxCostPerMission:
+ * 1e9` is self-authorized and meaningless as a limit. These constants are
+ * the real ceiling: `validatePhoneMissionPolicy` clamps every caller value
+ * down to (at most) the server cap, so the effective policy can only ever
+ * 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 = 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;
+interface PhoneConfirmPolicy {
+    paymentDetails: 'never';
+    contractCommitment: 'never';
+    costOverLimit: 'needs_operator';
+    sensitivePersonalData: 'needs_operator';
+    unclearAlternative: 'needs_operator';
+}
+interface PhoneAlternativePolicy {
+    maxTimeShiftMinutes: number;
+}
+/**
+ * How aggressively the voice agent is allowed to ask for more time on a
+ * live call. Three independently-enforced caps:
+ *
+ *   - maxSecondsPerRequest: ceiling on a SINGLE `extend_call_time` call.
+ *     The agent can ask for less; it cannot ask for more.
+ *   - maxRequestsPerCall: how many times it may invoke the tool at all.
+ *     Once exhausted, further requests are denied even if there is
+ *     budget left in the total ceiling.
+ *   - maxTotalExtensionSeconds: TOTAL extra seconds across all granted
+ *     requests for this single call. A safety net under
+ *     `maxRequestsPerCall × maxSecondsPerRequest` in case the math
+ *     drifts. The call cannot run past
+ *     PHONE_SERVER_MAX_CALL_DURATION_SECONDS regardless of this.
+ *
+ * Auto-approved within these bounds — the agent does NOT need to bother
+ * the operator for routine "5 more minutes" requests. The whole point
+ * is to keep the agent agentic without making it ask permission every
+ * time it needs more line time to finish the job it was sent to do.
+ */
+interface PhoneExtensionPolicy {
+    maxSecondsPerRequest: number;
+    maxRequestsPerCall: number;
+    maxTotalExtensionSeconds: number;
+}
+/**
+ * Whether (and how) the agent may schedule an automatic callback when
+ * it can't finish the call in time, hits a context limit, gets cut off,
+ * or just wants to follow up later.
+ *
+ *   - allowAutoCallback: master switch. False disables `schedule_callback`
+ *     entirely (the tool is still callable but it returns a denial).
+ *   - maxCallbackChain: how many re-dials can chain off this mission.
+ *     0 means "no callbacks at all" (equivalent to allowAutoCallback=false
+ *     for this purpose); 1 means one callback is permitted but the
+ *     callback itself cannot schedule another; 2 means two hops are
+ *     allowed; etc. Bounded by PHONE_SERVER_MAX_CALLBACK_CHAIN.
+ */
+interface PhoneCallbackPolicy {
+    allowAutoCallback: boolean;
+    maxCallbackChain: number;
+}
+interface OpenClawPhoneMissionPolicy {
+    policyVersion: 1;
+    regionAllowlist: PhoneRegionScope[];
+    maxCallDurationSeconds: number;
+    maxCostPerMission: number;
+    maxAttempts: number;
+    transcriptEnabled: boolean;
+    recordingEnabled: boolean;
+    confirmPolicy: PhoneConfirmPolicy;
+    alternativePolicy: PhoneAlternativePolicy;
+    /**
+     * NEW in v0.9.81 — extension envelope. Optional for backward
+     * compatibility; falls back to {@link DEFAULT_EXTENSION_POLICY} when
+     * the caller omits it.
+     */
+    extensionPolicy?: PhoneExtensionPolicy;
+    /**
+     * NEW in v0.9.81 — callback envelope. Optional; falls back to
+     * {@link DEFAULT_CALLBACK_POLICY} when omitted.
+     */
+    callbackPolicy?: PhoneCallbackPolicy;
+}
+interface StartPhoneMissionInput {
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    voiceRuntimeRef?: string;
+}
+interface PhoneTransportProfile {
+    provider: string;
+    phoneNumber: string;
+    capabilities: TelephonyTransportCapability[];
+    supportedRegions: PhoneRegionScope[];
+}
+interface PhoneMissionValidationIssue {
+    code: string;
+    field: string;
+    message: string;
+}
+type PhoneMissionValidationResult = {
+    ok: true;
+    policy: OpenClawPhoneMissionPolicy;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+type PhoneTransportValidationResult = {
+    ok: true;
+    transport: PhoneTransportProfile;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+interface ValidatedPhoneMissionStart {
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    targetRegion: PhoneRegionScope;
+    transport: PhoneTransportProfile;
+    voiceRuntimeRef?: string;
+}
+type PhoneMissionStartValidationResult = {
+    ok: true;
+    mission: ValidatedPhoneMissionStart;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+declare function validatePhoneMissionPolicy(policy: unknown): PhoneMissionValidationResult;
+declare function validatePhoneTransportProfile(transport: unknown): PhoneTransportValidationResult;
+declare function inferPhoneRegion(phoneNumber: string): PhoneRegionScope | null;
+declare function isPhoneRegionAllowed(region: PhoneRegionScope, allowlist: readonly PhoneRegionScope[]): boolean;
+declare function classifyPhoneNumberRisk(phoneNumber: string): PhoneNumberRisk;
+declare function validatePhoneMissionStart(input: unknown, transport: unknown, options?: {
+    allowPremiumOrSpecialNumbers?: boolean;
+}): PhoneMissionStartValidationResult;
+
 /**
  * Realtime voice tools — the tool-using layer on top of the v0.9.52
  * audio bridge (see `realtime-bridge.ts`).
@@ -2931,64 +3086,6 @@ declare function extractEmailAddress(value: string | null | undefined): string;
  */
 declare function isOperatorReplySender(from: string | null | undefined, operatorEmail: string | null | undefined): boolean;
 
-/**
- * Realtime voice bridge — wires the OpenAI Realtime API to a phone
- * carrier's realtime-media WebSocket so a phone mission can actually
- * *converse*.
- *
- * # Shape of the integration
- *
- *   caller  ⇄  carrier  ⇄  (carrier media WebSocket)  ⇄  AgenticMail
- *                                                         │
- *                                          RealtimeVoiceBridge
- *                                                         │
- *                                      (OpenAI Realtime WebSocket)
- *                                                         │
- *                                                   gpt-realtime
- *
- * The carrier streams the live call audio to AgenticMail as JSON frames
- * (base64 audio); AgenticMail relays them to OpenAI as
- * `input_audio_buffer.append`; OpenAI streams synthesised speech back
- * as `response.output_audio.delta`; AgenticMail relays that to the
- * carrier. Server-side VAD on the OpenAI session handles turn-taking —
- * no manual commit / response.create.
- *
- * # Provider-pluggable transport
- *
- * The carrier side speaks a provider-specific wire protocol — 46elks
- * (`hello`/`audio`/`bye`, linear PCM) and Twilio Media Streams
- * (`connected`/`start`/`media`/`stop`, G.711 µ-law). Those differences
- * are isolated behind a {@link RealtimeTransportAdapter}: the bridge
- * itself — OpenAI session lifecycle, function calling, barge-in,
- * transcript, teardown — is identical across providers and lives here
- * once. The bridge defaults to the 46elks adapter, so existing callers
- * that pass no `transport` keep their exact prior behaviour.
- *
- * # Memory injection — the whole point
- *
- * Before the OpenAI session starts, the agent's persistent memory is
- * rendered (`AgentMemoryManager.generateMemoryContext()`) and folded
- * into the Realtime session `instructions`. The model is told to treat
- * that block as *its own* long-term knowledge — so on the call it acts
- * with full continuity, as if it had always known those things.
- *
- * # Why this file is transport-agnostic
- *
- * `RealtimeVoiceBridge` never touches a socket. It takes two abstract
- * {@link RealtimeBridgePort}s (one per side) and is driven by
- * `handle*Message` / `handle*Open` / `handle*Close` calls. The real
- * WebSocket plumbing lives in `@agenticmail/api` (which has the `ws`
- * dependency); tests drive the bridge with in-memory fake ports. This
- * keeps `@agenticmail/core` dependency-free and the bridge logic fully
- * unit-testable without a live OpenAI key or a carrier websocket number.
- *
- * The exact OpenAI Realtime wire shapes below are the GA `gpt-realtime`
- * protocol (session config nested under `audio.input` / `audio.output`,
- * `format` as an object, `response.output_audio.delta` for output). The
- * legacy beta output event name `response.audio.delta` is also handled
- * defensively — some `gpt-realtime` deployments still emit it.
- */
-
 /** OpenAI Realtime WebSocket base URL (model passed as `?model=`). */
 declare const OPENAI_REALTIME_URL = "wss://api.openai.com/v1/realtime";
 /** GA Realtime model. */
@@ -3033,6 +3130,25 @@ interface RealtimeInstructionOptions {
      * automatically by `buildRealtimeSessionConfig()` when tools are set.
      */
     toolGuidance?: string;
+    /**
+     * v0.9.81 — when set, the agent gets an explicit "you have N minutes"
+     * preamble so it can pace the conversation. Pulled into the
+     * instructions even when the bridge itself isn't enforcing a soft
+     * deadline (e.g. for downstream voice runtimes that consume the
+     * same instructions string).
+     */
+    callBudget?: {
+        /** Total budget for this call in seconds. */
+        seconds: number;
+        /**
+         * True when extend_call_time + schedule_callback are wired to the
+         * session. Toggles a separate "if you need more time" hint into
+         * the preamble. False ⇒ the agent should manage strictly within
+         * its budget.
+         */
+        extensionEnabled: boolean;
+        callbackEnabled: boolean;
+    };
 }
 /**
  * Compose the Realtime session `instructions` string. The agent's
@@ -3163,12 +3279,80 @@ interface RealtimeVoiceBridgeOptions {
      * is how many tool calls were still in flight at teardown — non-zero
      * means the call dropped mid-tool (e.g. an unanswered `ask_operator`),
      * which is the signal the API layer uses to arm callback-on-disconnect
-     * (plan §7).
+     * (plan §7). `endedByTimeBudget` is true when the bridge itself ended
+     * the call because the soft deadline elapsed and the grace period
+     * expired — the API layer uses this to log a different teardown
+     * reason and to skip "callback flagged" if the agent already used
+     * `schedule_callback` itself.
      */
     onEnd?: (summary: {
         reason: string;
         pendingToolCalls: number;
+        endedByTimeBudget?: boolean;
     }) => void;
+    /**
+     * NEW in v0.9.81 — initial soft time budget for the call, in seconds.
+     * When set, the bridge schedules a graceful-end timer with reminders
+     * (T-120s, T-30s) and a final 30s grace window after the budget
+     * elapses. The carrier-level hard cap (Twilio `TimeLimit` / 46elks
+     * `timeout`) still applies on top; this is the AGENT's view of how
+     * long it has, which it can grow via {@link extendCallTime}.
+     * Omitted ⇒ no bridge-level timer (legacy behaviour).
+     */
+    callBudgetSeconds?: number;
+    /**
+     * NEW in v0.9.81 — extension policy for {@link extendCallTime}. When
+     * the agent asks for more time, every request is auto-approved up to
+     * these caps. Omitted ⇒ extensions are denied.
+     */
+    extensionPolicy?: PhoneExtensionPolicy;
+    /**
+     * NEW in v0.9.81 — callback policy for {@link scheduleCallback}.
+     * Omitted ⇒ scheduled callbacks are denied.
+     */
+    callbackPolicy?: PhoneCallbackPolicy;
+    /**
+     * NEW in v0.9.81 — fires when the agent calls schedule_callback and the
+     * bridge has approved it against the policy. The API layer persists
+     * the request to mission metadata and the scheduler dials the
+     * callback when the requested `at` timestamp arrives. `priorContext`
+     * is the model-supplied summary plus a system-built transcript
+     * digest the bridge composed at request-time.
+     */
+    onCallbackScheduled?: (req: ScheduledCallbackRequest) => void;
+    /**
+     * NEW in v0.9.81 — injectable wall-clock + timer functions so unit
+     * tests can fast-forward the deadline without sleeping. Defaults to
+     * the real `Date.now` / `setTimeout` / `clearTimeout`.
+     */
+    now?: () => number;
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+}
+/**
+ * Captures everything the API layer needs to honour a `schedule_callback`
+ * tool call: when to dial, why, what the model wants to remember about
+ * the conversation so far, and a transcript digest the bridge composed
+ * at the moment of the request. The digest is the "context from the
+ * previous call" the operator asked for — without it, the next call's
+ * agent would start cold.
+ */
+interface ScheduledCallbackRequest {
+    /** Wall-clock ISO timestamp when the callback should fire. */
+    at: string;
+    /** Free-text reason from the agent (transcribed verbatim to logs). */
+    reason: string;
+    /**
+     * The agent's own summary of what the next-call agent should know.
+     * Trimmed to {@link MAX_CALLBACK_SUMMARY_LENGTH} chars.
+     */
+    agentSummary: string;
+    /**
+     * System-built digest of the assistant + system transcript so far,
+     * trimmed to {@link MAX_CALLBACK_TRANSCRIPT_DIGEST_LENGTH} chars.
+     * The next call sees this verbatim under "# What you said before".
+     */
+    transcriptDigest: string;
 }
 /**
  * Bridges a phone carrier's realtime-media connection to an OpenAI
@@ -3194,6 +3378,46 @@ declare class RealtimeVoiceBridge {
     private readonly maxToolCallMs;
     private readonly onTranscript?;
     private readonly onEnd?;
+    /** Injectable clock + timers (tests substitute fakes). */
+    private readonly nowFn;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    /** v0.9.81 — extension / callback state. */
+    private readonly extensionPolicy?;
+    private readonly callbackPolicy?;
+    private readonly onCallbackScheduled?;
+    /** Initial soft budget, in seconds. 0 = no bridge-side timer (legacy). */
+    private readonly initialBudgetSeconds;
+    /** Wall-clock ms when the call started, set on first carrier hello. */
+    private callStartedAtMs;
+    /** Wall-clock ms when the soft deadline fires. Bumped by extensions. */
+    private softDeadlineMs;
+    /** Soft-end timer (fires once, then schedules the grace timer). */
+    private softEndTimer;
+    /** Final hard-end timer that fires after the grace window. */
+    private graceEndTimer;
+    /** Reminder timers for the T-N marks. Cleared/re-armed on extensions. */
+    private 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. */
+    private firedReminderMarks;
+    /** Count of extensions granted this call. */
+    private extensionsUsed;
+    /** Total extra seconds granted across all extensions this call. */
+    private extensionSecondsUsed;
+    /** True once the agent's schedule_callback request was accepted. */
+    private callbackArmed;
+    /** Captured for the API layer when the soft deadline fires. */
+    private endedByTimeBudgetFlag;
+    /**
+     * 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.
+     */
+    private readonly recentUtterances;
     /** Carrier `hello`/`start` received — the call leg is live. */
     private helloSeen;
     /** OpenAI socket open + `session.update` sent. */
@@ -3343,6 +3567,149 @@ declare class RealtimeVoiceBridge {
      * > against current OpenAI docs before the live smoke test.
      */
     private answerToolCall;
+    /** True if the agent's `schedule_callback` request has been accepted. */
+    get isCallbackArmed(): boolean;
+    /**
+     * 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(): number;
+    /**
+     * 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(): {
+        extensionsUsed: number;
+        extensionsRemaining: number;
+        secondsUsedSoFar: number;
+        secondsAvailable: number;
+        maxSecondsPerRequest: number;
+    };
+    /**
+     * 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: number, reason?: string): {
+        granted: boolean;
+        secondsGranted: number;
+        secondsRemaining: number;
+        extensionsRemaining: number;
+        message: string;
+    };
+    /**
+     * 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: {
+        delaySeconds: number;
+        reason?: string;
+        summary: string;
+    }): {
+        accepted: boolean;
+        at?: string;
+        message: string;
+    };
+    /**
+     * 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(): {
+        secondsRemaining: number;
+        softDeadlineAt: string | null;
+        extension: ReturnType<RealtimeVoiceBridge['getExtensionStatus']>;
+        callbackAvailable: boolean;
+        callbackArmed: boolean;
+    };
+    /**
+     * Arm the soft-deadline timer + reminder timers. Called once at hello.
+     * No-op when the bridge has no budget configured.
+     */
+    private startCallBudget;
+    /**
+     * 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.
+     */
+    private rearmBudgetTimers;
+    /** Cancel all currently-armed budget timers. Idempotent. */
+    private clearBudgetTimers;
+    /**
+     * 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").
+     */
+    private injectReminder;
+    /**
+     * 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.
+     */
+    private onSoftDeadline;
+    /**
+     * 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.
+     */
+    private noteUtterance;
+    /**
+     * 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}.
+     */
+    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
@@ -3354,108 +3721,6 @@ declare class RealtimeVoiceBridge {
     private safeSend;
 }
 
-declare const PHONE_REGION_SCOPES: readonly ["AT", "DE", "EU", "WORLD"];
-type PhoneRegionScope = typeof PHONE_REGION_SCOPES[number];
-declare const TELEPHONY_TRANSPORT_CAPABILITIES: readonly ["sms", "call_control", "realtime_media", "recording_supported"];
-type TelephonyTransportCapability = typeof TELEPHONY_TRANSPORT_CAPABILITIES[number];
-declare const PHONE_MISSION_STATES: readonly ["draft", "approved", "dialing", "connected", "conversing", "needs_operator", "completed", "failed", "cancelled"];
-type PhoneMissionState = typeof PHONE_MISSION_STATES[number];
-type PhoneNumberRisk = 'invalid' | 'standard' | 'premium_or_special';
-/**
- * Server-side hard ceilings for a phone mission policy.
- *
- * Hardening (#42-H1 / #43-H2) — `policy` is supplied by the calling agent,
- * so a caller-set `maxCallDurationSeconds: 999999` or `maxCostPerMission:
- * 1e9` is self-authorized and meaningless as a limit. These constants are
- * the real ceiling: `validatePhoneMissionPolicy` clamps every caller value
- * down to (at most) the server cap, so the effective policy can only ever
- * 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_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;
-interface PhoneConfirmPolicy {
-    paymentDetails: 'never';
-    contractCommitment: 'never';
-    costOverLimit: 'needs_operator';
-    sensitivePersonalData: 'needs_operator';
-    unclearAlternative: 'needs_operator';
-}
-interface PhoneAlternativePolicy {
-    maxTimeShiftMinutes: number;
-}
-interface OpenClawPhoneMissionPolicy {
-    policyVersion: 1;
-    regionAllowlist: PhoneRegionScope[];
-    maxCallDurationSeconds: number;
-    maxCostPerMission: number;
-    maxAttempts: number;
-    transcriptEnabled: boolean;
-    recordingEnabled: boolean;
-    confirmPolicy: PhoneConfirmPolicy;
-    alternativePolicy: PhoneAlternativePolicy;
-}
-interface StartPhoneMissionInput {
-    to: string;
-    task: string;
-    policy: OpenClawPhoneMissionPolicy;
-    voiceRuntimeRef?: string;
-}
-interface PhoneTransportProfile {
-    provider: string;
-    phoneNumber: string;
-    capabilities: TelephonyTransportCapability[];
-    supportedRegions: PhoneRegionScope[];
-}
-interface PhoneMissionValidationIssue {
-    code: string;
-    field: string;
-    message: string;
-}
-type PhoneMissionValidationResult = {
-    ok: true;
-    policy: OpenClawPhoneMissionPolicy;
-    issues: [];
-} | {
-    ok: false;
-    issues: PhoneMissionValidationIssue[];
-};
-type PhoneTransportValidationResult = {
-    ok: true;
-    transport: PhoneTransportProfile;
-    issues: [];
-} | {
-    ok: false;
-    issues: PhoneMissionValidationIssue[];
-};
-interface ValidatedPhoneMissionStart {
-    to: string;
-    task: string;
-    policy: OpenClawPhoneMissionPolicy;
-    targetRegion: PhoneRegionScope;
-    transport: PhoneTransportProfile;
-    voiceRuntimeRef?: string;
-}
-type PhoneMissionStartValidationResult = {
-    ok: true;
-    mission: ValidatedPhoneMissionStart;
-    issues: [];
-} | {
-    ok: false;
-    issues: PhoneMissionValidationIssue[];
-};
-declare function validatePhoneMissionPolicy(policy: unknown): PhoneMissionValidationResult;
-declare function validatePhoneTransportProfile(transport: unknown): PhoneTransportValidationResult;
-declare function inferPhoneRegion(phoneNumber: string): PhoneRegionScope | null;
-declare function isPhoneRegionAllowed(region: PhoneRegionScope, allowlist: readonly PhoneRegionScope[]): boolean;
-declare function classifyPhoneNumberRisk(phoneNumber: string): PhoneNumberRisk;
-declare function validatePhoneMissionStart(input: unknown, transport: unknown, options?: {
-    allowPremiumOrSpecialNumbers?: boolean;
-}): PhoneMissionStartValidationResult;
-
 type PhoneTransportProvider = '46elks' | 'twilio';
 /** Providers that support starting outbound call-control missions. */
 declare const PHONE_CALL_CONTROL_PROVIDERS: readonly PhoneTransportProvider[];
@@ -3733,6 +3998,54 @@ declare class PhoneManager {
         mission: PhoneCallMission;
         callbackMission: PhoneCallMission;
     } | null>;
+    /**
+     * 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: string, payload: {
+        at: string;
+        reason: string;
+        agentSummary: string;
+        transcriptDigest: string;
+    }): PhoneCallMission | null;
+    /**
+     * 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: string, limit?: number): PhoneCallMission[];
+    /**
+     * 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.
+     */
+    triggerScheduledCallback(missionId: string, options?: StartPhoneCallOptions): Promise<{
+        mission: PhoneCallMission;
+        callbackMission: PhoneCallMission;
+    } | null>;
     private build46ElksCallRequest;
     /**
      * Build the Twilio outbound-call request — the mirror of