@openclaw/voice-call 2026.10.1-beta.2 → 2026.10.5-beta.1

package/README.md

@@ -102,12 +102,125 @@ Notes:
 - Twilio defaults to US1. For a non-US Region, set `twilio.region` to `ie1` or `au1` and use credentials created in that Region; see [Twilio's regional REST API guide](https://www.twilio.com/docs/global-infrastructure/using-the-twilio-rest-api-in-a-non-us-region).
 - `mock` is a local dev provider (no network calls).
 - Telnyx requires `telnyx.publicKey` (or `TELNYX_PUBLIC_KEY`) unless `skipSignatureVerification` is true.
-- Runtime accepts canonical config only. If older configs still use `provider: "log"`, `twilio.from`, or legacy `streaming.*` OpenAI keys, run `openclaw doctor --fix` to rewrite them.
+- Runtime accepts canonical config only. Doctor retains migrations for `provider: "log"`, `twilio.from`, legacy `streaming.*` OpenAI keys, and `realtime.agentContext.includeSystemPrompt` because supported releases can still preserve these settings. Run `openclaw doctor --fix` to normalize them; existing canonical values are preserved.
 - advanced webhook, streaming, and tunnel notes: `https://docs.openclaw.ai/plugins/voice-call`
 - `responseModel` is optional. When unset, voice responses use the runtime default model.
 - `sessionScope` defaults to `per-phone`, preserving caller memory across calls. Use `per-call` for reception, booking, IVR, and bridge flows where each carrier call should start fresh. Use `main` to share the configured agent's main session (`agent:<agentId>:main`, or `global` when core `session.scope` is `"global"`). Custom core `session.mainKey` values are ignored.
 - `realtime.consultThinkingLevel` is optional. When set, it overrides the thinking level used by the model behind realtime `openclaw_agent_consult` calls.
 - `realtime.consultFastMode` is optional. When set, it toggles fast mode for realtime `openclaw_agent_consult` calls.
+- `realtime.idleHangupMs` is optional. When set to a positive integer, an active realtime call ends after neither side has spoken for that many milliseconds; in-flight agent consults pause the timer. Unset keeps the current no-speech-idle-limit behavior.
+
+## Per-call briefs and errands
+
+`initiate_call` and `voicecall.initiate` accept an optional `brief`. The opening
+`message` remains the first verbatim line; the brief guides the conversation
+after it. The realtime voice and its consult agent receive the same brief.
+
+All brief fields are optional:
+
+| Field                | Value                                                                                                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task`               | Plain text describing what to achieve, up to 2000 characters.                                                                                                                      |
+| `context`            | Facts the voice may use, up to 4000 characters.                                                                                                                                    |
+| `language`           | Language name or BCP-47 tag, up to 100 characters.                                                                                                                                 |
+| `identity`           | Introduction text, or `{ introduction, disclose: "volunteer" \| "when-asked" }`; up to 500 characters. Defaults to introducing only when asked.                                    |
+| `disclosures`        | Up to 20 strings listing permitted personal details, each up to 500 characters. Defaults to none beyond the permitted identity.                                                    |
+| `approvals`          | What the voice may agree to, up to 2000 characters. Defaults to no spending or commitments beyond the task.                                                                        |
+| `voicemailMessage`   | Message to leave on a machine, up to 1000 characters. Defaults to the supplied introduction or a neutral message, followed by a promise to try again later; excludes task details. |
+| `successCriteria`    | What counts as done, up to 1000 characters.                                                                                                                                        |
+| `maxDurationSeconds` | Positive integer that shortens this call's duration limit; values above the configured cap are capped.                                                                             |
+
+Briefs have an overall limit of 8000 JSON characters. Unknown fields are rejected.
+For a plumber visit:
+
+```json
+{
+  "action": "initiate_call",
+  "to": "+15550005678",
+  "mode": "conversation",
+  "message": "Hello, can I arrange a plumber visit?",
+  "brief": {
+    "task": "Book a plumber to repair a leaking kitchen tap",
+    "context": "The owner is available Tuesday or Thursday, 9 AM to noon. Ask for the callout fee before agreeing.",
+    "language": "en",
+    "identity": {
+      "introduction": "I am calling on behalf of Alex",
+      "disclose": "volunteer"
+    },
+    "disclosures": ["The owner's first name is Alex"],
+    "approvals": "A visit on Tuesday or Thursday morning with a callout fee up to 20 EUR. No repair charges are approved.",
+    "successCriteria": "Confirm the day, arrival window, callout fee and booking reference",
+    "voicemailMessage": "Hello, I am calling to ask about a plumber visit for a leaking tap. The owner will follow up.",
+    "maxDurationSeconds": 180
+  }
+}
+```
+
+CLI callers can pass `--brief 'Ask whether a plumber is available Tuesday'`,
+`--brief '<JSON>'`, or `--brief-file ./plumber-brief.json`. The two brief flags
+are mutually exclusive. Use `--mode conversation` for a conversation.
+
+## Reports, live transcript, callbacks and voicemail
+
+These features are disabled by default. Configure them under
+`plugins.entries.voice-call.config`:
+
+```json5
+{
+  reports: {
+    enabled: true,
+    includeTranscript: true, // default true
+    // summaryModel: "<provider>/<model>",
+    // inboundSessionKey: "agent:reception:main",
+  },
+  live: { transcript: true, minIntervalMs: 5000 },
+  inboundPolicy: "allowlist",
+  callbacks: {
+    enabled: true,
+    windowMinutes: 60,
+    // greeting: "Hello, I can take a message for the owner.",
+    // brief: { task: "Take a message for the owner" },
+  },
+  voicemail: { detection: "twilio", onMachine: "leave-message" },
+}
+```
+
+- Reports go to the session that requested an outbound call. They include its
+  outcome, important facts, duration, end reason and, by default, transcript.
+  `reports.inboundSessionKey` selects the destination for ordinary inbound calls.
+  A Gateway restart marks an interrupted pending report or live-transcript delivery
+  as failed. OpenClaw does not resend it because the earlier process may already
+  have reached the channel.
+- Live transcript sends both sides' final lines to the requester in batches,
+  at most once per `live.minIntervalMs` (default 5000).
+  Each batch's position is saved before it is sent, so a call that survives a
+  restart continues with new lines only and never repeats an earlier batch.
+- With realtime voice enabled and `inboundPolicy: "allowlist"`, callbacks from a
+  number called within `callbacks.windowMinutes` (default 60) are also accepted.
+  They are linked to the original outbound call and take a message for the owner
+  without sharing details. The classic STT/TTS path never admits callbacks. Other
+  numbers follow the existing inbound policy. `callbacks.greeting` and
+  `callbacks.brief` can customize that conversation.
+- With Twilio machine detection, outbound conversation calls hold realtime input
+  and the opening until a human or unknown result, or 30 seconds after the bridge
+  is ready. A machine result blocks realtime speech even after that cap.
+- Twilio machine detection leaves the brief's voicemail message once, waits for
+  realtime voice playback to finish, and then hangs up. When realtime playback
+  is unavailable, it retires the realtime stream and uses carrier text-to-speech
+  followed by hang-up. With `onMachine: "hang-up"`, it ends the call immediately.
+  Notify calls wait for detection before playing the appropriate message.
+  The detected answer type is recorded. The mock provider can simulate this; Telnyx and Plivo behavior
+  is unchanged. `voicemail.detection` defaults to `"off"`.
+
+During a call, `steer_call` or `voicecall.steer` accepts `{ callId, message, mode }`.
+`mode: "guidance"` (the default) changes the voice's guidance and subsequent consults;
+`mode: "say"` makes the voice say the message verbatim now. Messages are limited
+to 500 characters. Only the requesting session or an operator may steer that call.
+
+```bash
+openclaw voicecall steer --call-id <id> --message "Ask for the callout fee" --mode guidance
+openclaw voicecall steer --call-id <id> --message "The owner can also do Thursday morning." --mode say
+```
 
 ## Stale call reaper
 
@@ -139,7 +252,8 @@ Tool name: `voice_call`
 
 Actions:
 
-- `initiate_call` (message, to?, mode?)
+- `initiate_call` (message, to?, mode?, brief?)
+- `steer_call` (callId, message, mode?: guidance | say)
 - `continue_call` (callId, message)
 - `speak_to_user` (callId, message)
 - `end_call` (callId)
@@ -147,7 +261,8 @@ Actions:
 
 ## Gateway RPC
 
-- `voicecall.initiate` (to?, message, mode?)
+- `voicecall.initiate` (to?, message, mode?, brief?)
+- `voicecall.steer` (callId, message, mode?: guidance | say)
 - `voicecall.continue` (callId, message)
 - `voicecall.speak` (callId, message)
 - `voicecall.end` (callId)

package/dist/.setup/{guarded-json-api-x55yqHvW.mjs → carrier-api-BYKw_fsQ.mjs}

@@ -1,5 +1,5 @@
 import { fetchWithSsrFGuard } from "../api.js";
-import { n as normalizeProxyIp, s as getHeader } from "./runtime-entry-CbSKxSKk.mjs";
+import { c as getHeader, r as normalizeProxyIp } from "./runtime-entry-STjFmi_B.mjs";
 import { n as reserveWebhookReplay, t as createWebhookReplayCache } from "./webhook-replay-B7RJNWNG.mjs";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { isLoopbackHost } from "openclaw/plugin-sdk/gateway-runtime";
@@ -181,19 +181,10 @@ function redactTwilioVerificationUrlForDiagnostics(url) {
 		return "<invalid verification URL>";
 	}
 }
-function stripPortFromUrl(url) {
-	try {
-		const parsed = new URL(url);
-		if (!parsed.port) return url;
-		parsed.port = "";
-		return parsed.toString();
-	} catch {
-		return url;
-	}
-}
 function setPortOnUrl(url, port) {
 	try {
 		const parsed = new URL(url);
+		if (!port && !parsed.port) return url;
 		parsed.port = port;
 		return parsed.toString();
 	} catch {
@@ -297,21 +288,24 @@ function verifyTwilioWebhook(ctx, authToken, options) {
 		remoteIP: options?.remoteIP
 	});
 	const params = new URLSearchParams(ctx.rawBody);
-	if (validateTwilioSignature(authToken, signature, verificationUrl, params)) {
+	const verifyUrl = (candidateUrl) => {
+		if (!validateTwilioSignature(authToken, signature, candidateUrl, params)) return;
 		const replayKey = createTwilioReplayKey({
-			verificationUrl,
+			verificationUrl: candidateUrl,
 			signature,
 			requestParams: params
 		});
 		return {
 			ok: true,
-			verificationUrl,
+			verificationUrl: candidateUrl,
 			...reserveWebhookReplay(twilioReplayCache, replayKey)
 		};
-	}
+	};
+	const verified = verifyUrl(verificationUrl);
+	if (verified) return verified;
 	const variants = /* @__PURE__ */ new Set();
 	variants.add(verificationUrl);
-	variants.add(stripPortFromUrl(verificationUrl));
+	variants.add(setPortOnUrl(verificationUrl, ""));
 	if (options?.publicUrl) try {
 		const publicPort = new URL(options.publicUrl).port;
 		if (publicPort) variants.add(setPortOnUrl(verificationUrl, publicPort));
@@ -320,17 +314,8 @@ function verifyTwilioWebhook(ctx, authToken, options) {
 	if (hostHeaderPort) variants.add(setPortOnUrl(verificationUrl, hostHeaderPort));
 	for (const candidateUrl of variants) {
 		if (candidateUrl === verificationUrl) continue;
-		if (!validateTwilioSignature(authToken, signature, candidateUrl, params)) continue;
-		const replayKey = createTwilioReplayKey({
-			verificationUrl: candidateUrl,
-			signature,
-			requestParams: params
-		});
-		return {
-			ok: true,
-			verificationUrl: candidateUrl,
-			...reserveWebhookReplay(twilioReplayCache, replayKey)
-		};
+		const result = verifyUrl(candidateUrl);
+		if (result) return result;
 	}
 	const isNgrokFreeTier = verificationUrl.includes(".ngrok-free.app") || verificationUrl.includes(".ngrok.io");
 	return {
@@ -346,15 +331,6 @@ function getBaseUrlNoQuery(url) {
 	const u = new URL(url);
 	return `${u.protocol}//${u.host}${u.pathname}`;
 }
-function createPlivoV2ReplayKey(url, nonce) {
-	return `plivo:v2:${sha256Hex(`${getBaseUrlNoQuery(url)}\n${nonce}`)}`;
-}
-function validatePlivoV2Signature(params) {
-	const baseUrl = getBaseUrlNoQuery(params.url);
-	const expected = normalizeSignatureBase64(crypto.createHmac("sha256", params.authToken).update(baseUrl + params.nonce).digest("base64"));
-	const provided = normalizeSignatureBase64(params.signature);
-	return safeEqualSecret(expected, provided);
-}
 function sortedPlivoParams(params, format) {
 	return [...params].toSorted(([leftKey, leftValue], [rightKey, rightValue]) => {
 		const left = leftKey === rightKey ? leftValue : leftKey;
@@ -373,10 +349,24 @@ function constructPlivoV3BaseUrl(params) {
 	if (params.method === "GET") return baseUrl;
 	return baseUrl + sortedPlivoParams(params.postParams, "body");
 }
-function validatePlivoV3Signature(params) {
-	const hmacBase = `${params.baseUrl}.${params.nonce}`;
+function verifyPlivoSignature(params) {
+	const hmacBase = `${params.baseUrl}${params.version === "v3" ? "." : ""}${params.nonce}`;
 	const expected = normalizeSignatureBase64(crypto.createHmac("sha256", params.authToken).update(hmacBase).digest("base64"));
-	return normalizeStringEntries(params.signatureHeader.split(",")).map((s) => normalizeSignatureBase64(s)).some((signature) => safeEqualSecret(expected, signature));
+	const ok = params.signatures.map(normalizeSignatureBase64).some((signature) => safeEqualSecret(expected, signature));
+	const result = {
+		ok,
+		version: params.version,
+		verificationUrl: params.verificationUrl
+	};
+	if (!ok) return {
+		...result,
+		reason: `Invalid Plivo ${params.version.toUpperCase()} signature`
+	};
+	const replayKey = `plivo:${params.version}:${sha256Hex(`${params.baseUrl}\n${params.nonce}`)}`;
+	return {
+		...result,
+		...reserveWebhookReplay(plivoReplayCache, replayKey)
+	};
 }
 /**
 * Verify Plivo webhooks using V3 signature if present; fall back to V2.
@@ -420,45 +410,23 @@ function verifyPlivoWebhook(ctx, authToken, options) {
 			url: verificationUrl,
 			postParams
 		});
-		if (!validatePlivoV3Signature({
+		return verifyPlivoSignature({
 			authToken,
-			signatureHeader: signatureV3,
-			nonce: nonceV3,
-			baseUrl
-		})) return {
-			ok: false,
 			version: "v3",
 			verificationUrl,
-			reason: "Invalid Plivo V3 signature"
-		};
-		const replayKey = `plivo:v3:${sha256Hex(`${baseUrl}\n${nonceV3}`)}`;
-		return {
-			ok: true,
-			version: "v3",
-			verificationUrl,
-			...reserveWebhookReplay(plivoReplayCache, replayKey)
-		};
-	}
-	if (signatureV2 && nonceV2) {
-		if (!validatePlivoV2Signature({
-			authToken,
-			signature: signatureV2,
-			nonce: nonceV2,
-			url: verificationUrl
-		})) return {
-			ok: false,
-			version: "v2",
-			verificationUrl,
-			reason: "Invalid Plivo V2 signature"
-		};
-		const replayKey = createPlivoV2ReplayKey(verificationUrl, nonceV2);
-		return {
-			ok: true,
-			version: "v2",
-			verificationUrl,
-			...reserveWebhookReplay(plivoReplayCache, replayKey)
-		};
+			signatures: normalizeStringEntries(signatureV3.split(",")),
+			nonce: nonceV3,
+			baseUrl
+		});
 	}
+	if (signatureV2 && nonceV2) return verifyPlivoSignature({
+		authToken,
+		version: "v2",
+		verificationUrl,
+		signatures: [signatureV2],
+		nonce: nonceV2,
+		baseUrl: getBaseUrlNoQuery(verificationUrl)
+	});
 	return {
 		ok: false,
 		reason: "Missing Plivo signature headers (V3 or V2)",
@@ -506,21 +474,57 @@ async function guardedJsonApiRequest(params) {
 		await release();
 	}
 }
-/** Failed carrier probes keep calls alive; an empty or missing response is terminal. */
-async function readProviderCallStatus(request, describe) {
-	try {
-		const data = await request();
-		return data ? describe(data) : {
-			status: "not-found",
-			isTerminal: true
-		};
-	} catch {
-		return {
-			status: "error",
-			isTerminal: false,
-			isUnknown: true
-		};
-	}
+//#endregion
+//#region extensions/voice-call/src/providers/shared/carrier-api.ts
+/** Keep call controls and recovery probes on the same carrier endpoint and credentials. */
+function createCarrierApi(name, baseUrl, authorization, options = {}) {
+	const provider = name.toLowerCase();
+	const headers = { Authorization: authorization };
+	const allowedHostnames = [new URL(baseUrl).hostname];
+	const request = (endpoint, body, params) => guardedJsonApiRequest({
+		method: params?.method ?? "POST",
+		allowNotFound: params?.allowNotFound,
+		body,
+		url: `${baseUrl}${endpoint}`,
+		headers: {
+			...headers,
+			"Content-Type": options.contentType ?? "application/json"
+		},
+		allowedHostnames,
+		auditContext: `voice-call.${provider}.api`,
+		errorPrefix: `${name} API error`,
+		createError: options.createError,
+		malformedJsonMessage: options.malformedJsonMessage
+	});
+	return {
+		request,
+		async getCallStatus(endpoint, describe) {
+			try {
+				const data = await guardedJsonApiRequest({
+					url: `${baseUrl}${endpoint}`,
+					method: "GET",
+					allowNotFound: true,
+					headers: options.statusContentType ? {
+						...headers,
+						"Content-Type": options.statusContentType
+					} : headers,
+					allowedHostnames,
+					auditContext: `${provider}-get-call-status`,
+					errorPrefix: `${name} get call status error`
+				});
+				return data ? describe(data) : {
+					status: "not-found",
+					isTerminal: true
+				};
+			} catch {
+				return {
+					status: "error",
+					isTerminal: false,
+					isUnknown: true
+				};
+			}
+		}
+	};
 }
 //#endregion
-export { verifyTelnyxWebhook as a, verifyPlivoWebhook as i, readProviderCallStatus as n, verifyTwilioWebhook as o, reconstructWebhookUrl as r, guardedJsonApiRequest as t };
+export { verifyTwilioWebhook as a, verifyTelnyxWebhook as i, reconstructWebhookUrl as n, verifyPlivoWebhook as r, createCarrierApi as t };

package/dist/.setup/{cli-Cn1leykM.mjs → cli-dyyK8Upw.mjs}

@@ -1,6 +1,6 @@
 import { sleep } from "../api.js";
-import { l as resolveVoiceCallStreamExposurePaths, u as validateProviderConfig } from "./config-CX9J-053.mjs";
-import { _ as MAX_CALL_RECORD_EVENTS, b as loadActiveCallsFromStore, c as resolveWebhookExposureStatus, d as setupTailscaleExposureRoutes, h as resolveVoiceCallAgentId, l as cleanupTailscaleExposureRoute, u as getTailscaleSelfInfo, v as findCallInStore, x as setVoiceCallStateRuntime, y as getCallHistoryFromStore } from "./runtime-entry-CbSKxSKk.mjs";
+import { g as CallBriefSchema, l as resolveVoiceCallStreamExposurePaths, u as validateProviderConfig } from "./config-CsrGuamE.mjs";
+import { S as resolveVoiceCallAgentId, _ as findCallInStore, b as setVoiceCallStateRuntime, d as getTailscaleSelfInfo, f as setupTailscaleExposureRoutes, g as MAX_CALL_RECORD_EVENTS, l as resolveWebhookExposureStatus, u as cleanupTailscaleExposureRoute, v as getCallHistoryFromStore, y as loadActiveCallsFromStore } from "./runtime-entry-STjFmi_B.mjs";
 import { r as resolveUserPath, t as resolveDefaultVoiceCallStoreDir } from "./store-path-Cfwff6j7.mjs";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { callGatewayFromCli, isGatewayClientRequestError, isGatewayTransportError, redactSensitiveUrlLikeString } from "openclaw/plugin-sdk/gateway-runtime";
@@ -8,6 +8,7 @@ import { isRecord, normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/
 import { MAX_TCP_PORT, MAX_TIMER_TIMEOUT_MS, addTimerTimeoutGraceMs, clampTimerTimeoutMs, parseStrictNonNegativeInteger } from "openclaw/plugin-sdk/number-runtime";
 import fs from "node:fs";
 import path from "node:path";
+import { readFile } from "node:fs/promises";
 import { createDeferred } from "openclaw/plugin-sdk/concurrency-runtime";
 import { once } from "node:events";
 import { format } from "node:util";
@@ -232,43 +233,23 @@ function resolveOperationTimeout(config) {
 function resolveContinueTimeout(config) {
 	return clampTimerTimeoutMs(config.transcriptTimeoutMs + VOICE_CALL_GATEWAY_OPERATION_TIMEOUT_MS + VOICE_CALL_GATEWAY_TRANSCRIPT_BUFFER_MS) ?? 1;
 }
-function resolveVoiceCallDeadlineMs(timeoutMs, nowMs = Date.now()) {
-	return nowMs + (clampTimerTimeoutMs(timeoutMs) ?? MAX_TIMER_TIMEOUT_MS);
-}
-function readGatewayPollTimeoutMs(payload, fallbackTimeoutMs) {
-	if (isRecord(payload) && typeof payload.pollTimeoutMs === "number") return clampTimerTimeoutMs(payload.pollTimeoutMs) ?? fallbackTimeoutMs;
-	return fallbackTimeoutMs;
-}
-function readCompletedContinueResult(payload) {
-	if (!isRecord(payload)) throw new Error("voicecall gateway response missing operation status");
-	if (payload.status === "pending") return { status: "pending" };
-	if (payload.status === "failed") return {
-		status: "failed",
-		error: typeof payload.error === "string" ? payload.error : "continue failed"
-	};
-	if (payload.status === "completed") return {
-		status: "completed",
-		result: payload.result
-	};
-	throw new Error("voicecall gateway response has unknown operation status");
-}
 async function pollContinueGateway(payload, fallbackTimeoutMs) {
 	if (!isRecord(payload) || typeof payload.operationId !== "string") return payload;
 	if (!payload.operationId) throw new Error("voicecall gateway response missing operationId");
-	const params = {
-		operationId: payload.operationId,
-		timeoutMs: readGatewayPollTimeoutMs(payload, fallbackTimeoutMs)
-	};
-	const deadlineMs = resolveVoiceCallDeadlineMs(params.timeoutMs);
+	const operationId = payload.operationId;
+	const timeoutMs = typeof payload.pollTimeoutMs === "number" ? clampTimerTimeoutMs(payload.pollTimeoutMs) ?? fallbackTimeoutMs : fallbackTimeoutMs;
+	const deadlineMs = performance.now() + (clampTimerTimeoutMs(timeoutMs) ?? MAX_TIMER_TIMEOUT_MS);
 	for (;;) {
-		const remainingMs = deadlineMs - Date.now();
+		const remainingMs = deadlineMs - performance.now();
 		if (remainingMs <= 0) break;
-		const gateway = await callVoiceCallGateway("voicecall.continue.result", { operationId: params.operationId }, { timeoutMs: Math.min(VOICE_CALL_GATEWAY_DEFAULT_TIMEOUT_MS, remainingMs) });
+		const gateway = await callVoiceCallGateway("voicecall.continue.result", { operationId }, { timeoutMs: Math.min(VOICE_CALL_GATEWAY_DEFAULT_TIMEOUT_MS, remainingMs) });
 		if (!gateway.ok) throw new Error(`gateway unavailable while waiting for voicecall continue result: ${formatErrorMessage(gateway.error)}`);
-		const result = readCompletedContinueResult(gateway.payload);
+		const result = gateway.payload;
+		if (!isRecord(result)) throw new Error("voicecall gateway response missing operation status");
 		if (result.status === "completed") return result.result;
-		if (result.status === "failed") throw new Error(result.error);
-		const sleepMs = Math.min(VOICE_CALL_GATEWAY_POLL_INTERVAL_MS, deadlineMs - Date.now());
+		if (result.status === "failed") throw new Error(typeof result.error === "string" ? result.error : "continue failed");
+		if (result.status !== "pending") throw new Error("voicecall gateway response has unknown operation status");
+		const sleepMs = Math.min(VOICE_CALL_GATEWAY_POLL_INTERVAL_MS, deadlineMs - performance.now());
 		if (sleepMs <= 0) break;
 		await sleep(sleepMs);
 	}
@@ -306,7 +287,8 @@ async function initiateVoiceCall(params) {
 	const gateway = await callVoiceCallGateway(params.method, {
 		...params.to ? { to: params.to } : {},
 		...params.message ? { message: params.message } : {},
-		...mode ? { mode } : {}
+		...mode ? { mode } : {},
+		...params.brief ? { brief: params.brief } : {}
 	}, { timeoutMs: resolveOperationTimeout(params.config) });
 	if (gateway.ok) return readGatewayCallId(gateway.payload, params.failureMessage);
 	const runtime = await ensureStandaloneRuntime(params);
@@ -314,6 +296,7 @@ async function initiateVoiceCall(params) {
 	if (!to) throw new Error("Missing --to and no toNumber configured");
 	const result = await runtime.manager.initiateCall(to, void 0, {
 		message: params.message,
+		brief: params.brief,
 		mode
 	});
 	if (!result.success) throw new Error(result.error || params.failureMessage || "initiate failed");
@@ -322,6 +305,14 @@ async function initiateVoiceCall(params) {
 }
 //#endregion
 //#region extensions/voice-call/src/cli.ts
+async function readCliBrief(options) {
+	if (options.brief && options.briefFile) throw new Error("Use either --brief or --brief-file");
+	const raw = options.briefFile ? await readFile(resolveUserPath(options.briefFile), "utf8") : options.brief;
+	if (raw === void 0) return;
+	if (raw.length > 16e3) throw new Error("Brief input is too large");
+	const value = options.briefFile || raw.trimStart().startsWith("{") || raw.trimStart().startsWith("[") ? JSON.parse(raw) : { task: raw };
+	return CallBriefSchema.parse(value);
+}
 function resolveMode(input) {
 	const raw = normalizeOptionalLowercaseString(input) ?? "";
 	if (raw === "serve" || raw === "off") return raw;
@@ -422,6 +413,11 @@ function registerVoiceCallCli(params) {
 		if (stateRuntime) setVoiceCallStateRuntime({ state: stateRuntime });
 	};
 	const root = program.command("voicecall").description("Voice call utilities").addHelpText("after", () => `\nDocs: https://docs.openclaw.ai/cli/voicecall\n`);
+	const managerAction = (command) => runWithStandaloneRuntime(createRuntime, (ensureRuntime) => runGatewayManagerCommand({
+		config,
+		ensureRuntime,
+		...command
+	}));
 	root.command("setup").description("Show Voice Call provider and webhook setup status").option("--json", "Print machine-readable JSON").action((options) => {
 		const status = buildSetupStatus(config, coreConfig);
 		if (options.json) {
@@ -441,28 +437,17 @@ function registerVoiceCallCli(params) {
 			process.exitCode = 1;
 			return;
 		}
-		if (!options.to) {
-			if (options.json) writeCliJson({
-				ok: true,
-				setup,
-				liveCall: false
-			});
-			else {
-				writeSetupStatus(setup);
-				writeCliLine("live-call: skipped (pass --to and --yes to place one)");
-			}
-			return;
-		}
-		if (!options.yes) {
+		if (!options.to || !options.yes) {
 			if (options.json) writeCliJson({
 				ok: true,
 				setup,
 				liveCall: false,
-				wouldCall: options.to
+				...options.to ? { wouldCall: options.to } : {}
 			});
 			else {
 				writeSetupStatus(setup);
-				writeCliLine("live-call: dry run for %s (add --yes to place it)", options.to);
+				if (options.to) writeCliLine("live-call: dry run for %s (add --yes to place it)", options.to);
+				else writeCliLine("live-call: skipped (pass --to and --yes to place one)");
 			}
 			return;
 		}
@@ -493,22 +478,21 @@ function registerVoiceCallCli(params) {
 			ensureRuntime,
 			config,
 			method,
+			brief: await readCliBrief(options),
 			to: options.to,
 			message: options.message,
 			mode: options.mode
 		}) });
 	});
-	root.command("call").description("Initiate an outbound voice call").requiredOption("-m, --message <text>", "Message to speak when call connects").option("-t, --to <phone>", "Phone number to call (E.164 format, uses config toNumber if not set)").option("--mode <mode>", "Call mode: notify (hangup after message) or conversation (stay open)", "conversation").action(callAction("voicecall.initiate"));
-	root.command("start").description("Alias for voicecall call").requiredOption("--to <phone>", "Phone number to call").option("--message <text>", "Message to speak when call connects").option("--mode <mode>", "Call mode: notify (hangup after message) or conversation (stay open)", "conversation").action(callAction("voicecall.start"));
-	root.command("continue").description("Speak a message and wait for a response").requiredOption("--call-id <id>", "Call ID").requiredOption("--message <text>", "Message to speak").action(async (options) => runWithStandaloneRuntime(createRuntime, async (ensureRuntime) => {
+	root.command("call").description("Initiate an outbound voice call").requiredOption("-m, --message <text>", "Message to speak when call connects").option("-t, --to <phone>", "Phone number to call (E.164 format, uses config toNumber if not set)").option("--mode <mode>", "Call mode: notify (hangup after message) or conversation (stay open)", "conversation").option("--brief <text-or-json>", "Per-call task or structured JSON brief").option("--brief-file <path>", "Read a structured JSON brief from a file").action(callAction("voicecall.initiate"));
+	root.command("start").description("Alias for voicecall call").requiredOption("--to <phone>", "Phone number to call").option("--message <text>", "Message to speak when call connects").option("--mode <mode>", "Call mode: notify (hangup after message) or conversation (stay open)", "conversation").option("--brief <text-or-json>", "Per-call task or structured JSON brief").option("--brief-file <path>", "Read a structured JSON brief from a file").action(callAction("voicecall.start"));
+	root.command("continue").description("Speak a message and wait for a response").requiredOption("--call-id <id>", "Call ID").requiredOption("--message <text>", "Message to speak").action((options) => {
 		const gatewayParams = {
 			callId: options.callId,
 			message: options.message
 		};
 		const continueTimeoutMs = resolveContinueTimeout(config);
-		await runGatewayManagerCommand({
-			config,
-			ensureRuntime,
+		return managerAction({
 			gatewayCall: async () => {
 				try {
 					return await callVoiceCallGateway("voicecall.continue.start", gatewayParams, { timeoutMs: resolveOperationTimeout(config) });
@@ -521,39 +505,37 @@ function registerVoiceCallCli(params) {
 			managerFallback: (manager) => manager.continueCall(options.callId, options.message),
 			failureLabel: "continue"
 		});
+	});
+	root.command("speak").description("Speak a message without waiting for response").requiredOption("--call-id <id>", "Call ID").requiredOption("--message <text>", "Message to speak").action((options) => managerAction({
+		gatewayCall: () => callVoiceCallGateway("voicecall.speak", {
+			callId: options.callId,
+			message: options.message
+		}),
+		managerFallback: (manager) => manager.speak(options.callId, options.message),
+		failureLabel: "speak"
 	}));
-	root.command("speak").description("Speak a message without waiting for response").requiredOption("--call-id <id>", "Call ID").requiredOption("--message <text>", "Message to speak").action(async (options) => runWithStandaloneRuntime(createRuntime, async (ensureRuntime) => {
-		await runGatewayManagerCommand({
-			config,
-			ensureRuntime,
-			gatewayCall: () => callVoiceCallGateway("voicecall.speak", {
-				callId: options.callId,
-				message: options.message
-			}),
-			managerFallback: (manager) => manager.speak(options.callId, options.message),
-			failureLabel: "speak"
-		});
-	}));
-	root.command("dtmf").description("Send DTMF digits to an active call").requiredOption("--call-id <id>", "Call ID").requiredOption("--digits <digits>", "DTMF digits").action(async (options) => runWithStandaloneRuntime(createRuntime, async (ensureRuntime) => {
-		await runGatewayManagerCommand({
-			config,
-			ensureRuntime,
-			gatewayCall: () => callVoiceCallGateway("voicecall.dtmf", {
-				callId: options.callId,
-				digits: options.digits
-			}),
-			managerFallback: (manager) => manager.sendDtmf(options.callId, options.digits),
-			failureLabel: "dtmf"
+	root.command("steer").description("Steer an active realtime call through its owning Gateway").requiredOption("--call-id <id>", "Call ID").requiredOption("--message <text>", "Owner instruction").option("--mode <mode>", "guidance or say", "guidance").action(async (options) => {
+		if (options.mode !== "say" && options.mode !== "guidance") throw new Error("mode must be say or guidance");
+		const gateway = await callVoiceCallGateway("voicecall.steer", {
+			callId: options.callId,
+			message: options.message,
+			mode: options.mode
 		});
+		if (!gateway.ok) throw new Error("Steering requires the running Gateway that owns the active call");
+		writeCliJson(gateway.payload);
+	});
+	root.command("dtmf").description("Send DTMF digits to an active call").requiredOption("--call-id <id>", "Call ID").requiredOption("--digits <digits>", "DTMF digits").action((options) => managerAction({
+		gatewayCall: () => callVoiceCallGateway("voicecall.dtmf", {
+			callId: options.callId,
+			digits: options.digits
+		}),
+		managerFallback: (manager) => manager.sendDtmf(options.callId, options.digits),
+		failureLabel: "dtmf"
 	}));
-	root.command("end").description("Hang up an active call").requiredOption("--call-id <id>", "Call ID").action(async (options) => runWithStandaloneRuntime(createRuntime, async (ensureRuntime) => {
-		await runGatewayManagerCommand({
-			config,
-			ensureRuntime,
-			gatewayCall: () => callVoiceCallGateway("voicecall.end", { callId: options.callId }),
-			managerFallback: (manager) => manager.endCall(options.callId),
-			failureLabel: "end"
-		});
+	root.command("end").description("Hang up an active call").requiredOption("--call-id <id>", "Call ID").action((options) => managerAction({
+		gatewayCall: () => callVoiceCallGateway("voicecall.end", { callId: options.callId }),
+		managerFallback: (manager) => manager.endCall(options.callId),
+		failureLabel: "end"
 	}));
 	root.command("status").description("Show call status").option("--call-id <id>", "Call ID").option("--json", "Print machine-readable JSON").action(async (options) => {
 		const gateway = await callVoiceCallGateway("voicecall.status", options.callId ? { callId: options.callId } : void 0);