openclaw-pine-voice 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pine AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# Pine AI Voice Call - OpenClaw Plugin
+
+Make phone calls via Pine AI's voice agent from OpenClaw. The AI agent calls the specified number, carries out the conversation based on your instructions, and returns a full transcript (and an optional LLM-generated summary if requested). The voice agent can only speak English.
+
+**Powered by [Pine AI](https://19pine.ai). Subject to [Pine AI Voice Terms of Service](https://19pine.ai/legal/voice-tos).**
+
+## How is this different from the built-in voice-call plugin?
+
+| | Built-in `voice_call` | Pine `pine_voice_call` |
+|---|---|---|
+| Who is the voice agent? | Your OpenClaw agent | Pine's purpose-trained agent |
+| Requires webhook URL? | Yes (ngrok/Tailscale) | No |
+| Requires Twilio/Telnyx account? | Yes | No (Pine handles telephony) |
+| Real-time conversation control? | Yes | No (delegated) |
+| Best for | Custom real-time voice bots | High-quality delegated calls |
+
+## Prerequisites
+
+- Pine AI Pro subscription ([19pine.ai](https://19pine.ai))
+
+## Install
+
+```bash
+openclaw plugins install openclaw-pine-voice
+```
+
+Restart the gateway after installation:
+
+```bash
+openclaw gateway restart
+```
+
+## Configure
+
+Configuration has two parts: enabling the tool for your agent, and authenticating with Pine AI.
+
+### Step 1: Enable the tool for your agent
+
+The plugin provides three tools (all registered as optional):
+
+| Tool | Description |
+|---|---|
+| `pine_voice_call_and_wait` | **Recommended.** Initiates a call and blocks until it completes, returning the full transcript in one tool call. Uses SSE to wait for the final result with automatic polling fallback. |
+| `pine_voice_call` | Initiates a call and returns immediately with a `call_id`. Use with `pine_voice_call_status` for manual polling. |
+| `pine_voice_call_status` | Checks the status of a call initiated by `pine_voice_call`. |
+
+Your agent won't see these tools until you explicitly allow them. Add them to your agent's tool allowlist in `openclaw.json`:
+
+**To enable for all agents globally**, add the tools to the top-level `tools.allow`:
+
+```json
+{
+  "tools": {
+    "allow": ["pine_voice_call_and_wait"]
+  }
+}
+```
+
+> **Tip:** `pine_voice_call_and_wait` is all most agents need. If you want the manual initiate+poll pattern as well, add `"pine_voice_call"` and `"pine_voice_call_status"` to the list.
+
+**To enable for a specific agent only**, add it under that agent's config in `agents.list`:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": ["pine_voice_call_and_wait"]
+        }
+      }
+    ]
+  }
+}
+```
+
+> **Note:** If your agent already has a `tools.allow` list with other tools, just append the tool names to the existing array. If you're using `tools.profile` (e.g., `"coding"` or `"messaging"`), adding tools to `tools.allow` will make them available alongside your profile's default tools — the profile won't be overridden.
+
+### Step 2: Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+Your agent now has access to the Pine Voice call tools.
+
+### Step 3: Authenticate with Pine AI
+
+You have two options for when to authenticate:
+
+**Option A: Authenticate now (recommended)**
+
+We recommend authenticating right after installation. The auth flow requires an email verification code, so it's best done while you're actively setting things up — not later when the agent tries to make a call (which could be at any time).
+
+```bash
+# 1. Request a verification code (sent to your Pine AI account email)
+openclaw pine-voice auth setup --email you@example.com
+
+# 2. Check your email for the code, then verify (use the request-token from setup output)
+openclaw pine-voice auth verify --email you@example.com --request-token <TOKEN> --code 1234
+```
+
+The command prints your access token. Add it to your plugin config in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "pine-voice": {
+        "enabled": true,
+        "config": {
+          "access_token": "PASTE_YOUR_TOKEN_HERE"
+        }
+      }
+    }
+  }
+}
+```
+
+Then restart the gateway again:
+
+```bash
+openclaw gateway restart
+```
+
+**Option B: Let the agent handle it on first use**
+
+If you skip authentication, the plugin still loads and the tool is visible to your agent. The first time the agent tries to make a call, it will receive an error explaining that authentication is needed. The agent will then guide you through the email verification flow — it will ask for your email, run the auth commands, and configure the token for you.
+
+This works, but keep in mind: the email verification code arrives in your inbox, so you need to be available to provide it. If the agent tries to make a call while you're away (e.g., in an automated workflow or overnight), it will be blocked until you complete verification.
+
+## Try it out
+
+After setup, test that everything works by making a quick call to your own phone:
+
+```
+"Call my phone at +1XXXXXXXXXX. Tell me that Pine Voice is set up and working.
+Just confirm the setup is complete and say goodbye."
+```
+
+Replace `+1XXXXXXXXXX` with your actual phone number. You'll receive a call from Pine's voice agent, hear it speak, and get a transcript back — this confirms your token, subscription, and the full end-to-end flow are all working.
+
+Then try real tasks:
+
+- "Call John at +14155551234 and schedule a meeting for Tuesday"
+- "Phone the restaurant at +14155559876 to make a reservation for tonight at 7pm for 4 people"
+- "Call Comcast at +18001234567 and negotiate my bill down to $60/mo. My account is 1234567890, current plan is $89.99/mo. I've been a customer for 8 years. Don't change the plan tier."
+
+### Supported countries
+
+The voice agent can only speak English. Calls can be placed to phone numbers in the following countries: US, Canada (+1), UK (+44), Australia (+61), New Zealand (+64), and Ireland (+353). Calls to numbers outside these country codes will be rejected.
+
+### Caller personality
+
+The plugin supports two caller personalities:
+
+- **Negotiator** (`caller: "negotiator"`): For complex negotiations like bill reductions, insurance claims, and formal business matters. **You must provide a thorough negotiation strategy** in the context and instructions — including target outcome, acceptable range, leverage points, fallback positions, and constraints. The negotiator agent thinks things through deliberately and confirms important details multiple times.
+- **Communicator** (`caller: "communicator"`): For general-purpose routine tasks like scheduling appointments, making reservations, and inquiries. A specific objective is sufficient — no elaborate strategy needed.
+
+If not specified, the caller defaults to "negotiator".
+
+### Important: Gather all required information first
+
+The voice agent **cannot ask a human for missing information mid-call**. There is no way for the AI to pause and request details during the conversation. Before making a call, make sure you have gathered all information the callee may need, including any authentication, verification, or payment details relevant to the task.
+
+The exact requirements vary depending on the type of call — anticipate what the callee will ask for and include it upfront. If calling customer service or any entity that verifies identity, **you must include sufficient verification information** — the call will fail without it.
+
+## What happens
+
+When using `pine_voice_call_and_wait` (recommended):
+
+1. The tool sends your instructions to Pine's voice agent
+2. An SSE connection waits for the final result (with automatic polling fallback)
+3. You receive the full transcript (and an optional summary if requested) as soon as the call completes
+
+> **Note:** No real-time intermediate updates are available during the call. You will not receive "call connected" events, partial transcripts, or live conversation updates. The only result is the final transcript delivered after the call ends.
+
+When using `pine_voice_call` + `pine_voice_call_status` (manual):
+
+1. The tool sends your instructions and returns a `call_id` immediately
+2. Your agent polls `pine_voice_call_status` every 30 seconds
+3. You receive the full transcript once the status reaches a terminal state
+
+> **Note:** While a call is in progress, your agent is waiting for the result. If you need to do other tasks simultaneously, use OpenClaw's sub-agents (`sessions_spawn`) to run the call in a background session.
+
+## Limits and pricing
+
+- Each call costs **50 base credits + 20 credits per minute** of duration
+- 5 concurrent calls per user
+- Pro subscription required
+- MCP voice calls use your existing Pine AI credit balance. All credit sources apply — daily login rewards (300 credits/day), subscription plan credits, and purchased add-ons. Credit policies are governed by the Pine AI app. See [Pine AI Pricing FAQ](https://www.19pine.ai/pricing-faqs) for details.
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| TOKEN_EXPIRED | Access token expired | Re-run `openclaw pine-voice auth setup` |
+| SUBSCRIPTION_REQUIRED | Not a Pro subscriber | Subscribe at 19pine.ai |
+| RATE_LIMITED | Too many calls | Wait and try again |
+| INSUFFICIENT_DETAIL | Objective too vague | Provide a more specific call objective |
+| DND_BLOCKED | Number on do-not-call list | Cannot call this number |
+
+## Development
+
+### Testing locally (before publishing)
+
+**Option A: Link local folder (recommended for development)**
+
+```bash
+openclaw plugins install -l /path/to/openclaw-pine-voice
+openclaw gateway restart
+```
+
+The `-l` flag creates a symlink instead of copying, so edits to your source files take effect after a gateway restart. No need to re-install.
+
+**Option B: Load path in config**
+
+Add the plugin path directly to `openclaw.json` — no install command needed:
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": ["/path/to/openclaw-pine-voice"]
+    }
+  }
+}
+```
+
+Restart the gateway to load the plugin.
+
+### Development workflow
+
+```bash
+# 1. Link your local plugin
+openclaw plugins install -l ./
+
+# 2. Add config to openclaw.json (token, gateway_url, tools.allow)
+
+# 3. Restart gateway
+openclaw gateway restart
+
+# 4. Test by chatting with your agent
+#    "Call +14155551234 and ask about store hours"
+
+# 5. Edit src/*.ts, restart gateway, test again
+
+# 6. Verify the plugin loads correctly
+openclaw plugins list
+```
+
+### Publishing to npm
+
+Once tested locally:
+
+```bash
+# 1. Login to npm
+npm login
+
+# 2. Publish the package
+npm publish
+```
+
+After publishing, users can install with:
+
+```bash
+openclaw plugins install openclaw-pine-voice
+```
+
+### Updating a published version
+
+```bash
+# Bump version in package.json, then:
+npm publish
+```
+
+Users update with:
+
+```bash
+openclaw plugins update openclaw-pine-voice
+openclaw gateway restart
+```
+
+## Terms of Service
+
+This plugin connects to Pine AI's voice calling service. Pine AI is the service provider. All calls are recorded and transcribed. By using this plugin, you agree to [Pine AI's Voice Terms of Service](https://19pine.ai/legal/voice-tos).
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth flow for Pine Voice plugin.
+ * Registers CLI commands for email-based authentication.
+ *
+ * Delegates to the pine-voice SDK for actual API calls.
+ */
+export declare function registerAuthCommands(api: any): void;

package/dist/auth.js

@@ -0,0 +1,57 @@
+/**
+ * Auth flow for Pine Voice plugin.
+ * Registers CLI commands for email-based authentication.
+ *
+ * Delegates to the pine-voice SDK for actual API calls.
+ */
+import { PineVoice } from "pine-voice";
+export function registerAuthCommands(api) {
+    api.registerCli?.(({ program }) => {
+        const pineVoice = program.command("pine-voice").description("Pine AI Voice Call plugin");
+        const auth = pineVoice.command("auth").description("Pine AI authentication");
+        auth
+            .command("setup")
+            .description("Set up Pine AI authentication")
+            .option("--email <email>", "Your Pine AI account email")
+            .action(async (opts) => {
+            if (!opts.email) {
+                console.log("Usage: openclaw pine-voice auth setup --email you@example.com");
+                return;
+            }
+            console.log(`Requesting verification code for ${opts.email}...`);
+            try {
+                const { requestToken } = await PineVoice.auth.requestCode(opts.email);
+                console.log("Verification code sent! Check your email.");
+                console.log(`Then run: openclaw pine-voice auth verify --email ${opts.email} --request-token ${requestToken} --code <code>`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`Error: ${message}`);
+            }
+        });
+        auth
+            .command("verify")
+            .description("Verify email code and get access token")
+            .option("--email <email>", "Your Pine AI account email")
+            .option("--request-token <token>", "Request token from auth setup step")
+            .option("--code <code>", "Verification code from email")
+            .action(async (opts) => {
+            if (!opts.code || !opts.email || !opts.requestToken) {
+                console.log("Usage: openclaw pine-voice auth verify --email you@example.com --request-token <token> --code 1234");
+                return;
+            }
+            try {
+                const { accessToken, userId } = await PineVoice.auth.verifyCode(opts.email, opts.requestToken || "", opts.code);
+                console.log("Authentication successful!");
+                console.log(`Add this to your pine-voice config:`);
+                console.log(`  access_token: "${accessToken}"`);
+                console.log(`  user_id: "${userId}"`);
+                console.log("\nOr set it in openclaw.json under plugins.entries.pine-voice.config");
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`Error: ${message}`);
+            }
+        });
+    }, { commands: ["pine-voice"] });
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pine AI Voice Call plugin for OpenClaw.
+ *
+ * Registers:
+ * - pine_voice_call tool (initiate a phone call, returns immediately)
+ * - pine_voice_call_status tool (check call progress / get results)
+ * - pine-voice CLI commands (auth setup/verify)
+ *
+ * Delegates all API calls to the pine-voice SDK. All safety, billing,
+ * and prompt logic lives on Pine's side.
+ *
+ * For non-blocking calls, the pine-voice skill instructs the AI to use
+ * sessions_spawn so the main agent stays responsive during long calls.
+ */
+export default function register(api: any): void;
+export declare const id = "pine-voice";
+export declare const name = "Pine AI Voice Call";

package/dist/index.js

@@ -0,0 +1,26 @@
+import { registerVoiceCallTools } from "./tool.js";
+import { registerAuthCommands } from "./auth.js";
+/**
+ * Pine AI Voice Call plugin for OpenClaw.
+ *
+ * Registers:
+ * - pine_voice_call tool (initiate a phone call, returns immediately)
+ * - pine_voice_call_status tool (check call progress / get results)
+ * - pine-voice CLI commands (auth setup/verify)
+ *
+ * Delegates all API calls to the pine-voice SDK. All safety, billing,
+ * and prompt logic lives on Pine's side.
+ *
+ * For non-blocking calls, the pine-voice skill instructs the AI to use
+ * sessions_spawn so the main agent stays responsive during long calls.
+ */
+export default function register(api) {
+    // Register voice call tools (initiate + status)
+    registerVoiceCallTools(api);
+    // Register CLI commands for authentication
+    registerAuthCommands(api);
+    api.log?.info?.("pine-voice: plugin loaded");
+}
+// Also export as named for module compatibility
+export const id = "pine-voice";
+export const name = "Pine AI Voice Call";

package/dist/tool.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Register voice call tools with OpenClaw:
+ *  - pine_voice_call: initiate a call (returns immediately)
+ *  - pine_voice_call_status: poll a call's status
+ *  - pine_voice_call_and_wait: initiate + block until complete (SSE + polling fallback)
+ *
+ * All tools are optional (user must add them to tools.allow).
+ * Delegates all API calls to the pine-voice SDK.
+ */
+export declare function registerVoiceCallTools(api: any): void;

package/dist/tool.js

@@ -0,0 +1,272 @@
+import { Type } from "@sinclair/typebox";
+import { PineVoice, AuthError } from "pine-voice";
+/** Auth error message returned when credentials are missing. */
+const AUTH_MISSING_MESSAGE = [
+    "Pine Voice is not authenticated yet. Both a user ID and access token are required before making calls.",
+    "",
+    "To set up authentication, run these commands in the terminal:",
+    "",
+    "  # Step 1: Request a verification code (sent to your Pine AI account email)",
+    "  openclaw pine-voice auth setup --email <USER_EMAIL>",
+    "",
+    "  # Step 2: Enter the code and request token from Step 1 to get your user ID and access token",
+    "  openclaw pine-voice auth verify --email <USER_EMAIL> --request-token <TOKEN> --code <CODE>",
+    "",
+    "  # Step 3: Add both values to your plugin config in openclaw.json:",
+    '  #   plugins.entries.pine-voice.config.user_id = "<USER_ID>"',
+    '  #   plugins.entries.pine-voice.config.access_token = "<TOKEN>"',
+    "",
+    "  # Step 4: Restart the gateway",
+    "  openclaw gateway restart",
+    "",
+    "Ask the user for their Pine AI account email to begin. If they don't have a Pine AI account, they can sign up at https://19pine.ai.",
+].join("\n");
+const AUTH_EXPIRED_MESSAGE = [
+    "Pine Voice authentication has expired or is invalid.",
+    "",
+    "To re-authenticate, run:",
+    "  openclaw pine-voice auth setup --email <USER_EMAIL>",
+    "  openclaw pine-voice auth verify --email <USER_EMAIL> --request-token <TOKEN> --code <CODE>",
+    "",
+    "Then update user_id and access_token in openclaw.json and restart the gateway.",
+    "Ask the user for their Pine AI account email to begin.",
+].join("\n");
+/** Read plugin config and create a PineVoice SDK client. Returns error response if not authenticated. */
+function getClientOrError(api) {
+    const config = api.config?.plugins?.entries?.["pine-voice"]?.config;
+    if (!config?.access_token || !config?.user_id) {
+        return { content: [{ type: "text", text: AUTH_MISSING_MESSAGE }], isError: true };
+    }
+    return new PineVoice({
+        accessToken: config.access_token,
+        userId: config.user_id,
+        gatewayUrl: config.gateway_url,
+    });
+}
+/** Convert a PineVoiceError into an OpenClaw tool error response. */
+function handleError(api, err) {
+    if (err instanceof AuthError) {
+        api.log?.error?.(`pine-voice: auth error: ${err.message}`);
+        return { content: [{ type: "text", text: AUTH_EXPIRED_MESSAGE }], isError: true };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    api.log?.error?.(`pine-voice: error: ${message}`);
+    return { content: [{ type: "text", text: `Pine Voice Call Error: ${message}` }], isError: true };
+}
+/**
+ * Register voice call tools with OpenClaw:
+ *  - pine_voice_call: initiate a call (returns immediately)
+ *  - pine_voice_call_status: poll a call's status
+ *  - pine_voice_call_and_wait: initiate + block until complete (SSE + polling fallback)
+ *
+ * All tools are optional (user must add them to tools.allow).
+ * Delegates all API calls to the pine-voice SDK.
+ */
+export function registerVoiceCallTools(api) {
+    // --- Tool 1: pine_voice_call (initiate) ---
+    api.registerTool({
+        name: "pine_voice_call",
+        description: "Make a phone call via Pine AI voice agent. The agent calls the specified number and handles the " +
+            "conversation (including IVR navigation, negotiation, and verification) based on your instructions. " +
+            "Important: the voice agent can only speak English, so calls can only be delivered to English-speaking " +
+            "countries and recipients who understand English. " +
+            "BEFORE calling this tool, you MUST gather from the user all information that may be needed during " +
+            "the call, including any authentication, verification, or payment details the callee may require. " +
+            "The voice agent has no way to contact a human for missing information mid-call — anticipate what " +
+            "the callee will ask for and include it upfront. " +
+            "For negotiations, include target outcome, acceptable range, constraints, and leverage points. " +
+            "Returns immediately with a call_id. Use pine_voice_call_status to check progress and get results. " +
+            "Powered by Pine AI.",
+        parameters: Type.Object({
+            to: Type.String({ description: "Phone number to call (E.164 format, e.g. +14155551234). Must be a number in an English-speaking country, as the voice agent can only speak English." }),
+            callee_name: Type.String({ description: "Name of the person or business being called" }),
+            callee_context: Type.String({ description: "Comprehensive context about the callee and all information needed for the call. Include: who they are, your relationship, and any authentication, verification, or payment details the callee may require. The voice agent CANNOT ask a human for missing information mid-call, so you must anticipate what will be needed and include everything upfront." }),
+            objective: Type.String({ description: "Specific goal the call should accomplish. For negotiations, include your target outcome, acceptable range, and constraints (e.g. 'Negotiate monthly bill down to $50/mo, do not accept above $65/mo, do not change plan tier')." }),
+            instructions: Type.Optional(Type.String({ description: "Detailed strategy and instructions for the voice agent. For negotiations, describe: what leverage points to use, what offers to accept/reject, fallback positions, and when to walk away. The more thorough the strategy, the better the outcome." })),
+            caller: Type.Optional(Type.String({ enum: ["negotiator", "communicator"], description: "Caller personality. 'negotiator' for complex negotiations — requires a thorough negotiation strategy in callee_context and instructions (target outcome, acceptable range, leverage points, fallback positions, walk-away conditions). 'communicator' for general-purpose routine tasks (scheduling, inquiries, reservations)." })),
+            voice: Type.Optional(Type.String({ enum: ["male", "female"], description: "Voice gender" })),
+            max_duration_minutes: Type.Optional(Type.Number({ default: 120, minimum: 1, maximum: 120, description: "Maximum call duration in minutes" })),
+            enable_summary: Type.Optional(Type.Boolean({ default: false, description: "Request an LLM-generated summary after the call. Default: false. Most AI agents can process the full transcript directly, so the summary is opt-in to save latency and cost." })),
+        }),
+        async execute(_toolCallId, params) {
+            const clientOrErr = getClientOrError(api);
+            if (!(clientOrErr instanceof PineVoice))
+                return clientOrErr;
+            try {
+                const { callId } = await clientOrErr.calls.create({
+                    to: params.to,
+                    name: params.callee_name,
+                    context: params.callee_context,
+                    objective: params.objective,
+                    instructions: params.instructions,
+                    caller: params.caller,
+                    voice: params.voice,
+                    maxDurationMinutes: params.max_duration_minutes,
+                    enableSummary: params.enable_summary,
+                });
+                api.log?.info?.(`pine-voice: call initiated, call_id=${callId}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Call initiated (call_id: ${callId}).\n\nUse pine_voice_call_status with call_id "${callId}" to check progress. Poll every 30 seconds until the call completes.`,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            catch (err) {
+                return handleError(api, err);
+            }
+        },
+    }, { optional: true });
+    // --- Tool 2: pine_voice_call_status (query) ---
+    api.registerTool({
+        name: "pine_voice_call_status",
+        description: "Check the status of a phone call initiated by pine_voice_call. " +
+            "Returns the current status while in progress and the full transcript when the call is complete " +
+            "(plus an LLM-generated summary if enable_summary was set to true). " +
+            "Poll this tool every 30 seconds after initiating a call until a transcript is present. " +
+            "Note: no real-time intermediate updates are available — you will not receive partial transcripts " +
+            "or 'call connected' events. Simply poll until the call reaches a terminal state. " +
+            "CRITICAL: Do NOT rely on the status field to judge whether the call succeeded. " +
+            "You MUST read the full transcript — especially what the OTHER party said. " +
+            "If the other side was silent, responded with automated/voicemail messages, or never gave a meaningful human response, the call FAILED regardless of the technical status. " +
+            "Powered by Pine AI.",
+        parameters: Type.Object({
+            call_id: Type.String({ description: "The call_id returned by pine_voice_call" }),
+        }),
+        async execute(_toolCallId, params) {
+            const clientOrErr = getClientOrError(api);
+            if (!(clientOrErr instanceof PineVoice))
+                return clientOrErr;
+            try {
+                const result = await clientOrErr.calls.get(params.call_id);
+                // Terminal states: return formatted result
+                if (result.status === "completed" || result.status === "failed" || result.status === "cancelled") {
+                    return formatResult(result);
+                }
+                // Non-terminal: return simple progress message.
+                // Note: Real-time intermediate updates (phase, partial transcript) are
+                // NOT currently available. The transcript is only delivered after the
+                // call completes.
+                const elapsed = result.durationSeconds ? formatDuration(result.durationSeconds) : "unknown";
+                const progressLines = [];
+                progressLines.push(`Call is still in progress (${elapsed} elapsed). No intermediate updates are available — the transcript will be delivered when the call completes.`);
+                progressLines.push("", "Poll again in 30 seconds to check status.");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: progressLines.join("\n"),
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            catch (err) {
+                return handleError(api, err);
+            }
+        },
+    }, { optional: true });
+    // --- Tool 3: pine_voice_call_and_wait (initiate + wait for result) ---
+    api.registerTool({
+        name: "pine_voice_call_and_wait",
+        description: "Make a phone call via Pine AI voice agent and wait for the result. This is the PREFERRED tool " +
+            "for making calls — it blocks until the call completes and returns the full transcript " +
+            "in a single tool call. No manual polling needed. Uses SSE under the hood to wait for " +
+            "the final result, with automatic fallback to polling if SSE is unavailable. " +
+            "No real-time intermediate updates are available — you simply wait for the final transcript. " +
+            "Important: the voice agent can only speak English, so calls can only be delivered to English-speaking " +
+            "countries and recipients who understand English. " +
+            "BEFORE calling this tool, you MUST gather from the user all information that may be needed during " +
+            "the call, including any authentication, verification, or payment details the callee may require. " +
+            "The voice agent has no way to contact a human for missing information mid-call — anticipate what " +
+            "the callee will ask for and include it upfront. " +
+            "For negotiations, include target outcome, acceptable range, constraints, and leverage points. " +
+            "Note: this tool blocks for the duration of the call (typically 1-30 minutes). " +
+            "Powered by Pine AI.",
+        parameters: Type.Object({
+            to: Type.String({ description: "Phone number to call (E.164 format, e.g. +14155551234). Must be a number in an English-speaking country, as the voice agent can only speak English." }),
+            callee_name: Type.String({ description: "Name of the person or business being called" }),
+            callee_context: Type.String({ description: "Comprehensive context about the callee and all information needed for the call. Include: who they are, your relationship, and any authentication, verification, or payment details the callee may require. The voice agent CANNOT ask a human for missing information mid-call, so you must anticipate what will be needed and include everything upfront." }),
+            objective: Type.String({ description: "Specific goal the call should accomplish. For negotiations, include your target outcome, acceptable range, and constraints (e.g. 'Negotiate monthly bill down to $50/mo, do not accept above $65/mo, do not change plan tier')." }),
+            instructions: Type.Optional(Type.String({ description: "Detailed strategy and instructions for the voice agent. For negotiations, describe: what leverage points to use, what offers to accept/reject, fallback positions, and when to walk away. The more thorough the strategy, the better the outcome." })),
+            caller: Type.Optional(Type.String({ enum: ["negotiator", "communicator"], description: "Caller personality. 'negotiator' for complex negotiations — requires a thorough negotiation strategy in callee_context and instructions (target outcome, acceptable range, leverage points, fallback positions, walk-away conditions). 'communicator' for general-purpose routine tasks (scheduling, inquiries, reservations)." })),
+            voice: Type.Optional(Type.String({ enum: ["male", "female"], description: "Voice gender" })),
+            max_duration_minutes: Type.Optional(Type.Number({ default: 120, minimum: 1, maximum: 120, description: "Maximum call duration in minutes" })),
+            enable_summary: Type.Optional(Type.Boolean({ default: false, description: "Request an LLM-generated summary after the call. Default: false. Most AI agents can process the full transcript directly, so the summary is opt-in to save latency and cost." })),
+        }),
+        async execute(_toolCallId, params) {
+            const clientOrErr = getClientOrError(api);
+            if (!(clientOrErr instanceof PineVoice))
+                return clientOrErr;
+            try {
+                api.log?.info?.(`pine-voice: initiating call and waiting for result...`);
+                const result = await clientOrErr.calls.createAndWait({
+                    to: params.to,
+                    name: params.callee_name,
+                    context: params.callee_context,
+                    objective: params.objective,
+                    instructions: params.instructions,
+                    caller: params.caller,
+                    voice: params.voice,
+                    maxDurationMinutes: params.max_duration_minutes,
+                    enableSummary: params.enable_summary,
+                });
+                api.log?.info?.(`pine-voice: call completed, status=${result.status}`);
+                return formatResult(result);
+            }
+            catch (err) {
+                return handleError(api, err);
+            }
+        },
+    }, { optional: true });
+}
+/**
+ * Format a CallResult into an OpenClaw tool response.
+ *
+ * NOTE: We intentionally do NOT include structuredContent here because
+ * these tools have no outputSchema. Per MCP spec 2025-03-26, returning
+ * structuredContent without a corresponding outputSchema is a protocol
+ * violation and causes schema validation errors in strict MCP clients
+ * (e.g., Claude). All relevant data is included in the text content.
+ */
+function formatResult(result) {
+    if (result.status === "failed") {
+        return {
+            content: [{ type: "text", text: `Call failed: ${result.summary || "Unknown error"}` }],
+            isError: true,
+        };
+    }
+    if (result.status === "cancelled") {
+        return {
+            content: [{ type: "text", text: "Call was cancelled." }],
+            isError: false,
+        };
+    }
+    const durationMin = Math.floor((result.durationSeconds || 0) / 60);
+    const durationSec = (result.durationSeconds || 0) % 60;
+    const lines = [
+        `**Call ${result.status}**`,
+        `Duration: ${durationMin}m ${durationSec}s | Credits charged: ${result.creditsCharged}`,
+    ];
+    if (result.summary) {
+        lines.push("", `**Summary:** ${result.summary}`);
+    }
+    if (result.transcript?.length > 0) {
+        lines.push("", "**Transcript:**");
+        for (const entry of result.transcript) {
+            lines.push(`- **${entry.speaker}:** ${entry.text}`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: false,
+    };
+}
+function formatDuration(seconds) {
+    const m = Math.floor(seconds / 60);
+    const s = seconds % 60;
+    return m > 0 ? `${m}m ${s}s` : `${s}s`;
+}

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+/** Plugin configuration from openclaw.plugin.json configSchema */
+export interface PineVoiceConfig {
+    gateway_url?: string;
+    access_token?: string;
+    user_id?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,40 @@
+{
+  "id": "pine-voice",
+  "name": "Pine AI Voice Call",
+  "version": "0.1.0",
+  "description": "Make phone calls via Pine AI voice agent. The AI agent calls the specified number and carries out the conversation based on your instructions. The voice agent can only speak English, so calls can only be delivered to English-speaking countries. Before calling, gather all information the callee may need for authentication and verification — the agent cannot ask a human for missing info mid-call. Returns the full transcript. Powered by Pine AI.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "gateway_url": {
+        "type": "string",
+        "description": "Pine Voice API Gateway URL",
+        "default": "https://agent3-api-gateway-staging.19pine.ai"
+      },
+      "access_token": {
+        "type": "string",
+        "description": "Pine access token (from email verification)"
+      },
+      "user_id": {
+        "type": "string",
+        "description": "Pine user ID (the \"id\" field from email verification)"
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "gateway_url": {
+      "label": "Gateway URL",
+      "placeholder": "https://agent3-api-gateway-staging.19pine.ai"
+    },
+    "access_token": {
+      "label": "Pine Access Token",
+      "sensitive": true
+    },
+    "user_id": {
+      "label": "Pine User ID",
+      "placeholder": "1234567890"
+    }
+  },
+  "skills": ["skills/pine-voice", "skills/pine-voice-auth"]
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "openclaw-pine-voice",
+  "version": "0.1.0",
+  "description": "Make phone calls via Pine AI voice agent from OpenClaw",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "voice",
+    "phone",
+    "pine"
+  ],
+  "author": "Pine AI",
+  "license": "MIT",
+  "homepage": "https://pineclaw.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.32.0",
+    "pine-voice": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/skills/pine-voice/SKILL.md

@@ -0,0 +1,131 @@
+# Pine AI Voice Call
+
+## When to use
+Use `pine_voice_call_and_wait` (preferred) or `pine_voice_call` when the user wants you to **make a phone call** on their behalf. The Pine AI voice agent will call the specified number, navigate IVR systems, handle verification, conduct negotiations, and carry out the conversation autonomously.
+
+**Important:** The voice agent can only speak English. Calls can be placed to the US, Canada (+1), UK (+44), Australia (+61), New Zealand (+64), and Ireland (+353). Do not use this tool for calls to numbers outside these countries.
+
+## Best for
+- Calling customer service to negotiate bills, request credits, or resolve issues
+- Scheduling meetings or appointments by phone
+- Making restaurant reservations
+- Calling businesses to inquire about services or availability
+- Following up with contacts on behalf of the user
+
+## How to make a call
+
+**IMPORTANT: Phone calls are long-running (5-120 minutes). ALWAYS use `sessions_spawn` to run the call in a background sub-agent so you remain available to the user.**
+
+### Step 1: Gather all required information
+
+Before initiating a call, you **must** ask the user for every piece of information the callee might need. The voice agent **cannot ask a human for missing information during the call**. There is no way for the AI agent to pause and request details mid-conversation.
+
+Anticipate what the callee will require based on the type of call. This may include authentication or verification details, payment information, negotiation targets and constraints, relevant background, or any other context specific to the task.
+
+If the user hasn't provided sufficient information for the callee to process the request (e.g., a customer service call with no verification details), **ask the user for this information before proceeding**. Do not invoke the tool hoping it will work without it.
+
+### Step 2: Spawn a background sub-agent
+
+Use `sessions_spawn` to run the call in the background.
+
+**Preferred approach — `pine_voice_call_and_wait` (single tool, blocks until done):**
+
+- **tool**: `sessions_spawn`
+- **task**: Write a clear task that includes ALL call parameters. Example:
+
+  > Make a phone call using the pine_voice_call_and_wait tool. Call details: Call the restaurant at +14155559876. Callee name: The Italian Place. Callee context: Italian restaurant on Main Street. Making a dinner reservation. Objective: Make a reservation for 4 people tonight at 7pm. Instructions: If 7pm is not available, try 7:30 or 8pm. Prefer a booth if possible. Name for the reservation: Jane Doe. When the call completes, report the full summary, transcript, and outcome.
+
+- **label**: Short description, e.g. `call-restaurant-reservation`
+- **runTimeoutSeconds**: `(max_duration_minutes + 5) * 60` — give extra buffer beyond the call's max duration
+
+**Alternative approach — `pine_voice_call` + `pine_voice_call_status` (manual polling):**
+
+If `pine_voice_call_and_wait` is not available, use `pine_voice_call` to initiate, then poll `pine_voice_call_status` every 30 seconds. Include polling instructions in the task description.
+
+### Step 3: Tell the user the call is active
+
+After spawning, tell the user that **the call is already active** — Pine's voice agent has dialed the number and is handling the conversation in the background. The call is NOT "connecting" or "being set up". Example:
+> "The call is now active — Pine's voice agent is on the line with [callee] handling the conversation in the background. This typically takes a few minutes. I'll let you know the results when it's done. Feel free to ask me anything else in the meantime."
+
+### Step 4: Evaluate the transcript and summarize the result
+
+When the sub-agent announces the result, you MUST read the full transcript carefully to determine the actual outcome. **Do NOT rely on the `status` field** — a status like `HungupByPeer` only means the other party hung up, not that the call succeeded.
+
+**How to evaluate the transcript:**
+
+Read what the OTHER party (not Pine's agent) actually said. The callee's responses are the only way to know if the objective was achieved.
+
+**Treat the call as a FAILURE if:**
+- Only Pine's agent speaks and the other side is silent or gives no meaningful response
+- The other party's responses are automated/recorded messages (e.g. voicemail greetings, "leave a message after the beep", "your call cannot be completed as dialed")
+- System messages report extended silence from both sides (e.g. "silence from both sides for 25 seconds")
+- The callee hung up before the objective could be discussed
+- The callee never acknowledged or responded to the request
+
+These patterns mean the call reached voicemail, an automated system, or the callee was unavailable. Report this honestly to the user.
+
+**Summarize for the user:**
+- Whether the objective was actually achieved (based on the transcript, not the status)
+- If it failed: why (voicemail, no answer, hung up, etc.) and suggest a retry or alternative
+- Key details from what the callee actually said
+- Any follow-up actions needed
+- Credits charged
+
+## Tools
+
+### pine_voice_call_and_wait (preferred — initiate + wait)
+Initiates a phone call and blocks until it completes, returning the full result in a single tool call. Uses SSE to wait for the final result with automatic fallback to polling. No manual polling needed.
+
+**Important:** No real-time intermediate updates are available. You will NOT receive "call connected" events, partial transcripts, or live conversation progress. The only result is the final complete transcript delivered after the call ends.
+
+Parameters:
+
+- `to` (required): Phone number in E.164 format (e.g., +14155551234). Must be in a supported country: US/CA (+1), UK (+44), AU (+61), NZ (+64), IE (+353).
+- `callee_name` (required): Name of the person or business being called
+- `callee_context` (required): Comprehensive context — include all authentication, verification, and payment info the agent may need during the call
+- `objective` (required): Specific goal with negotiation targets and constraints if applicable
+- `instructions` (optional): Detailed strategy, approach, and behavioral instructions
+- `caller` (optional): "negotiator" or "communicator", default "negotiator". Negotiator requires a thorough negotiation strategy in context/instructions (target outcome, acceptable range, leverage points, fallback positions). Communicator is for general-purpose routine tasks.
+- `voice` (optional): "male" or "female", default "female"
+- `max_duration_minutes` (optional): 1-120, default 120
+- `enable_summary` (optional): boolean, default false. Request an LLM-generated summary after the call. Most AI agents can process the full transcript directly, so the summary is opt-in.
+
+### pine_voice_call (initiate)
+Initiates a phone call and returns immediately with a `call_id`. At this point, the call is ALREADY ACTIVE — the voice agent has dialed and is on the line. Same parameters as `pine_voice_call_and_wait`. Use with `pine_voice_call_status` to poll for results.
+
+### pine_voice_call_status (poll)
+Checks call progress using the `call_id` from pine_voice_call. Poll every 30 seconds until a transcript is present in the response. When the status is `in_progress`, the voice agent is ACTIVELY on the call speaking with the callee — it is NOT connecting or waiting. Returns the full transcript and billing info when complete (plus summary if `enable_summary` was set to true).
+
+**CRITICAL:** When you receive the final result, do NOT assume the call succeeded just because the status says "completed" or "HungupByPeer". You MUST read the full transcript. If the other party never responded meaningfully (voicemail, silence, automated messages), the call failed.
+
+- `call_id` (required): The call_id returned by pine_voice_call
+
+**Note:** No real-time intermediate updates are available. The `phase` and `partial_transcript` fields are defined in the schema but are NOT currently populated. You will not receive "call connected" events or live transcript turns. The only way to get the transcript is to wait for the call to complete. Simply poll until the status is terminal and the full transcript is present.
+
+## Negotiation calls
+For calls involving negotiation (bill reduction, rate matching, fee waiver), provide a **thorough negotiation strategy**, not just a target:
+
+- **Target outcome**: "Reduce monthly bill to $50/mo"
+- **Acceptable range**: "Will accept up to $65/mo"
+- **Hard constraints**: "Do not change plan tier, do not remove any features"
+- **Leverage points**: "Mention 10-year customer loyalty", "Competitor offers $45/mo"
+- **Fallback**: "If no reduction, request one-time credit of $100"
+- **Walk-away point**: "If nothing offered, ask for retention department"
+
+## Examples
+
+**Test call to yourself:**
+"Call my phone at +1XXXXXXXXXX. Tell me that Pine Voice is set up and working. Confirm the setup is complete and say goodbye."
+
+**Restaurant reservation:**
+"Call the restaurant at +14155559876 and make a reservation for 4 people tonight at 7pm. If 7pm is not available, try 7:30 or 8pm. Name for the reservation: Jane Doe."
+
+## HTTP API reference
+
+The plugin uses these REST endpoints on the Pine Voice gateway (for transparency — the tools handle this automatically):
+
+- **POST /api/v2/voice/call** — Initiate a call. Returns `{ "call_id": "...", "status": "in_progress" }`.
+- **GET /api/v2/voice/call/{call_id}** — Poll call status. Returns full transcript and billing info when complete (plus summary if requested).
+- **GET /api/v2/voice/call/{call_id}/stream** — SSE stream that waits for the final call result. Used by `pine_voice_call_and_wait` under the hood. No intermediate events are delivered; only the final transcript after call completion.
+
+Auth: `Authorization: Bearer <token>` + `X-Pine-User-Id: <user_id>` headers.

package/skills/pine-voice-auth/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: pine-voice-auth
+description: Set up or refresh Pine Voice authentication. Obtains an access token via email verification and writes it to the plugin config.
+metadata:
+  {
+    "openclaw":
+      { "emoji": "🔑", "requires": { "bins": ["curl", "jq"] } },
+  }
+---
+
+# Pine Voice Auth Setup
+
+## When to use
+
+Use this skill when **any** of these are true:
+
+- The user asks to set up Pine Voice, configure Pine AI, or authenticate for voice calls
+- A `pine_voice_call` or `pine_voice_call_and_wait` invocation returns "Pine Voice is not authenticated yet"
+- A `pine_voice_call` or `pine_voice_call_and_wait` invocation fails with `TOKEN_EXPIRED`, `UNAUTHORIZED`, or a 401 response
+- The user says their Pine Voice token isn't working
+
+Do **not** use this skill for making phone calls — see the `pine-voice` skill for that.
+
+## Prerequisites
+
+- The user must have a **Pine AI account** with a Pro subscription (sign up at https://19pine.ai)
+- `curl` and `jq` must be available in the shell
+
+## Important: email verification requires user presence
+
+This auth flow sends a verification code to the user's email inbox. The user **must be available** to check their email and tell you the code. This cannot be automated.
+
+**Recommended timing:** Run this flow right after plugin installation or when the user explicitly asks to set up Pine Voice — not during an unattended or automated workflow.
+
+## Auth flow overview
+
+Pine Voice uses email-based verification. The flow has two API calls with a human step in between:
+
+1. **Request** — send the user's email to get a `request_token`
+2. **Wait** — user checks their email for a verification code
+3. **Verify** — send email + request_token + code to get a `user_id` and `access_token`
+4. **Store & restart** — write both values via `openclaw config set` and restart the gateway
+5. **Test** — make a test call to verify everything works
+
+## Step-by-step instructions
+
+### Step 1: Ask the user for their Pine AI email
+
+Ask: "What email address is your Pine AI account registered with?"
+
+Do not proceed until you have the email.
+
+### Step 2: Request a verification code
+
+Run this command, replacing `USER_EMAIL` with the email from step 1:
+
+```bash
+curl -s -X POST https://www.19pine.ai/api/v2/auth/email/request \
+  -H "Content-Type: application/json" \
+  -d '{"email": "USER_EMAIL"}' | jq .
+```
+
+**Expected response:**
+
+```json
+{"status": "success", "data": {"request_token": "abc123..."}}
+```
+
+Save the `request_token` value — you need it in step 4.
+
+**If the request fails:**
+- `400` or `422` — the email may not be registered. Ask the user to check their email or sign up at https://19pine.ai.
+- Network error — check connectivity and retry.
+
+### Step 3: Ask the user for the verification code
+
+Tell the user: "I've sent a verification code to your email. Please check your inbox (and spam folder) and tell me the code."
+
+Wait for the user to provide the code. Do not guess or skip this step.
+
+### Step 4: Verify the code and obtain the access token
+
+Run this command, replacing `USER_EMAIL`, `THE_REQUEST_TOKEN`, and `THE_CODE` with the actual values:
+
+```bash
+curl -s -X POST https://www.19pine.ai/api/v2/auth/email/verify \
+  -H "Content-Type: application/json" \
+  -d '{"email": "USER_EMAIL", "request_token": "THE_REQUEST_TOKEN", "code": "THE_CODE"}' | jq .
+```
+
+**Expected response:**
+
+```json
+{"id": "1234567890", "access_token": "eyJ...", ...}
+```
+
+Save **both** values:
+- **`id`** — the user's Pine user ID
+- **`access_token`** — the access token
+
+**If verification fails:**
+- `401` or `400` with "invalid code" — ask the user to double-check the code and try again.
+- `410` or "expired" — the request_token expired. Go back to step 2 to start over.
+
+### Step 5: Store the credentials and restart
+
+Use `openclaw config set` to write both values. Replace `THE_ACCESS_TOKEN` and `THE_USER_ID` with the actual values from step 4.
+
+**Important:** The user ID is all digits, so the CLI will parse it as a number unless you force it to be a JSON string with `--json` and explicit quotes.
+
+```bash
+openclaw config set plugins.entries.pine-voice.config.access_token "THE_ACCESS_TOKEN"
+openclaw config set plugins.entries.pine-voice.config.user_id '"THE_USER_ID"' --json
+openclaw gateway restart
+```
+
+You can verify the stored values with:
+
+```bash
+openclaw config get plugins.entries.pine-voice.config
+```
+
+### Step 6: Verify with a test call
+
+After authentication is complete, suggest the user make a test call to their own phone number to verify everything works end-to-end:
+
+"Would you like to test it? I can call your phone to confirm everything is working. Just tell me your phone number."
+
+Use the `pine_voice_call_and_wait` tool (or `pine_voice_call` if unavailable) with:
+- `to`: the user's phone number
+- `callee_name`: the user's name
+- `callee_context`: "This is a test call to verify Pine Voice setup."
+- `objective`: "Confirm that Pine Voice is set up and working correctly. Say hello, confirm the setup is complete, and say goodbye."
+
+This verifies the token, subscription, and full end-to-end flow.
+
+## Token refresh
+
+Access tokens expire periodically. When a call fails with `TOKEN_EXPIRED` or a 401 error:
+
+1. Inform the user their token has expired and needs to be refreshed
+2. Re-run this auth flow starting from step 1
+
+## Security notes
+
+- Never log or echo the access token in plaintext beyond what is needed to write the config file
+- The token is stored in a local config file with the same permissions as the user's home directory
+- Do not commit config files containing tokens to version control