openclaw-pine-voice 0.1.5 → 0.1.7

package/README.md

@@ -87,11 +87,25 @@ 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: Just ask the agent (recommended)**
 
-**Option A: Authenticate now (recommended)**
+The easiest way to authenticate is to simply tell your agent:
 
-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).
+> "Set up Pine Voice authentication"
+
+The agent will ask for your Pine AI email, send a verification code, ask you for the code, and save the credentials — all conversationally. It uses two built-in tools (`pine_voice_auth_request` and `pine_voice_auth_verify`) that handle the entire flow and write the credentials to `openclaw.json` automatically. After it's done, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+This also works on first use: if you skip authentication and later ask the agent to make a call, it will detect that credentials are missing and walk you through the same flow.
+
+> **Note:** The verification code arrives by email, so you need to be available to provide it. If the agent tries to make a call while you're away, it will be blocked until you complete verification.
+
+**Option B: Manual CLI setup**
+
+If you prefer to authenticate from the terminal:
 
 ```bash
 # 1. Request a verification code (sent to your Pine AI account email)
@@ -101,13 +115,13 @@ openclaw pine-voice auth setup --email you@example.com
 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`:
+The command prints your access token and user ID. Add them to your plugin config in `openclaw.json`:
 
 ```json
 {
   "plugins": {
     "entries": {
-      "pine-voice": {
+      "openclaw-pine-voice": {
         "config": {
           "access_token": "PASTE_YOUR_TOKEN_HERE",
           "user_id": "PASTE_YOUR_USER_ID_HERE"
@@ -118,18 +132,12 @@ The command prints your access token. Add it to your plugin config in `openclaw.
 }
 ```
 
-Then restart the gateway again:
+Then restart the gateway:
 
 ```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:
@@ -195,7 +203,7 @@ When using `pine_voice_call` + `pine_voice_call_status` (manual):
 
 | Error | Cause | Fix |
 |---|---|---|
-| TOKEN_EXPIRED | Access token expired | Re-run `openclaw pine-voice auth setup` |
+| TOKEN_EXPIRED | Access token expired | Ask your agent to re-authenticate, or 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 |

package/dist/auth.d.ts

@@ -1,7 +1,12 @@
 /**
  * Auth flow for Pine Voice plugin.
- * Registers CLI commands for email-based authentication.
+ *
+ * Provides two surfaces:
+ *  1. Tools (pine_voice_auth_request / pine_voice_auth_verify) — the primary,
+ *     conversational path where the AI agent drives the flow.
+ *  2. CLI commands (openclaw pine-voice auth setup/verify) — a manual fallback.
  *
  * Delegates to the pine-voice SDK for actual API calls.
  */
+export declare function registerAuthTools(api: any): void;
 export declare function registerAuthCommands(api: any): void;

package/dist/auth.js

@@ -1,10 +1,145 @@
 /**
  * Auth flow for Pine Voice plugin.
- * Registers CLI commands for email-based authentication.
+ *
+ * Provides two surfaces:
+ *  1. Tools (pine_voice_auth_request / pine_voice_auth_verify) — the primary,
+ *     conversational path where the AI agent drives the flow.
+ *  2. CLI commands (openclaw pine-voice auth setup/verify) — a manual fallback.
  *
  * Delegates to the pine-voice SDK for actual API calls.
  */
-import { PineVoice } from "pine-voice";
+import { Type } from "@sinclair/typebox";
+import { PineVoice, AuthError } from "pine-voice";
+// ---------------------------------------------------------------------------
+// Module-level state: stores requestToken between the request and verify steps
+// so the AI agent never needs to pass it explicitly.
+// ---------------------------------------------------------------------------
+const pendingAuth = new Map(); // email → requestToken
+// ---------------------------------------------------------------------------
+// Tool registration (primary path)
+// ---------------------------------------------------------------------------
+export function registerAuthTools(api) {
+    // --- Tool: pine_voice_auth_request ---
+    api.registerTool({
+        name: "pine_voice_auth_request",
+        description: "Start Pine Voice authentication. Sends a verification code to the user's " +
+            "Pine AI account email. After calling this, ask the user to check their email " +
+            "(including spam) and provide the code, then call pine_voice_auth_verify.",
+        parameters: Type.Object({
+            email: Type.String({ description: "The user's Pine AI account email address" }),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const { requestToken } = await PineVoice.auth.requestCode(params.email);
+                pendingAuth.set(params.email, requestToken);
+                api.log?.info?.(`pine-voice: auth code requested for ${params.email}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Verification code sent to ${params.email}. ` +
+                                "Ask the user to check their email (including spam folder) and provide the code. " +
+                                "Then call pine_voice_auth_verify with the email and code.",
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                api.log?.error?.(`pine-voice: auth request failed: ${message}`);
+                const hint = err instanceof AuthError && err.status >= 400 && err.status < 500
+                    ? " The email may not be registered — the user can sign up at https://19pine.ai."
+                    : "";
+                return {
+                    content: [{ type: "text", text: `Pine Voice auth request failed: ${message}.${hint}` }],
+                    isError: true,
+                };
+            }
+        },
+    });
+    // --- Tool: pine_voice_auth_verify ---
+    api.registerTool({
+        name: "pine_voice_auth_verify",
+        description: "Complete Pine Voice authentication. Verifies the code the user received by email, " +
+            "saves the credentials to openclaw.json, and tells the user to restart the gateway. " +
+            "Must be called after pine_voice_auth_request.",
+        parameters: Type.Object({
+            email: Type.String({ description: "The same email used in pine_voice_auth_request" }),
+            code: Type.String({ description: "The verification code from the user's email" }),
+            request_token: Type.Optional(Type.String({ description: "Request token from pine_voice_auth_request (usually not needed — resolved automatically)" })),
+        }),
+        async execute(_toolCallId, params) {
+            const requestToken = params.request_token || pendingAuth.get(params.email);
+            if (!requestToken) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No pending auth request found for this email. " +
+                                "Call pine_voice_auth_request first to send a new verification code.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            try {
+                const { accessToken, userId } = await PineVoice.auth.verifyCode(params.email, requestToken, params.code);
+                // Write credentials to openclaw.json
+                const cfg = api.runtime.config.loadConfig();
+                const plugins = (cfg.plugins ?? {});
+                const entries = (plugins.entries ?? {});
+                const pluginEntry = (entries["openclaw-pine-voice"] ?? {});
+                const updatedConfig = {
+                    ...cfg,
+                    plugins: {
+                        ...plugins,
+                        entries: {
+                            ...entries,
+                            "openclaw-pine-voice": {
+                                ...pluginEntry,
+                                config: {
+                                    ...(pluginEntry.config ?? {}),
+                                    access_token: accessToken,
+                                    user_id: userId,
+                                },
+                            },
+                        },
+                    },
+                };
+                await api.runtime.config.writeConfigFile(updatedConfig);
+                pendingAuth.delete(params.email);
+                api.log?.info?.(`pine-voice: auth successful for ${params.email}, credentials saved`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Authentication successful! Credentials have been saved to openclaw.json. " +
+                                "Tell the user to restart the gateway for the changes to take effect:\n\n" +
+                                "  openclaw gateway restart",
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                api.log?.error?.(`pine-voice: auth verify failed: ${message}`);
+                const isExpired = message.toLowerCase().includes("expired");
+                const hint = isExpired
+                    ? " The request token has expired — call pine_voice_auth_request again to send a new code."
+                    : " Ask the user to double-check the code and try again.";
+                return {
+                    content: [{ type: "text", text: `Pine Voice auth verification failed: ${message}.${hint}` }],
+                    isError: true,
+                };
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// CLI registration (manual fallback)
+// ---------------------------------------------------------------------------
 export function registerAuthCommands(api) {
     api.registerCli?.(({ program }) => {
         const pineVoice = program.command("pine-voice").description("Pine AI Voice Call plugin");
@@ -43,11 +178,11 @@ export function registerAuthCommands(api) {
             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 in ~/.openclaw/openclaw.json:`);
+                console.log(`Add this to your plugin config in ~/.openclaw/openclaw.json:`);
                 console.log("");
                 console.log(`  "plugins": {`);
                 console.log(`    "entries": {`);
-                console.log(`      "pine-voice": {`);
+                console.log(`      "openclaw-pine-voice": {`);
                 console.log(`        "config": {`);
                 console.log(`          "access_token": "${accessToken}",`);
                 console.log(`          "user_id": "${userId}"`);

package/dist/index.d.ts

@@ -4,7 +4,10 @@
  * 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)
+ * - pine_voice_call_and_wait tool (initiate + wait for result)
+ * - pine_voice_auth_request tool (start email-based auth)
+ * - pine_voice_auth_verify tool (complete auth and save credentials)
+ * - pine-voice CLI commands (auth setup/verify — manual fallback)
  *
  * Delegates all API calls to the pine-voice SDK. All safety, billing,
  * and prompt logic lives on Pine's side.

package/dist/index.js

@@ -1,12 +1,15 @@
 import { registerVoiceCallTools } from "./tool.js";
-import { registerAuthCommands } from "./auth.js";
+import { registerAuthTools, 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)
+ * - pine_voice_call_and_wait tool (initiate + wait for result)
+ * - pine_voice_auth_request tool (start email-based auth)
+ * - pine_voice_auth_verify tool (complete auth and save credentials)
+ * - pine-voice CLI commands (auth setup/verify — manual fallback)
  *
  * Delegates all API calls to the pine-voice SDK. All safety, billing,
  * and prompt logic lives on Pine's side.
@@ -15,9 +18,11 @@ import { registerAuthCommands } from "./auth.js";
  * sessions_spawn so the main agent stays responsive during long calls.
  */
 export default function register(api) {
-    // Register voice call tools (initiate + status)
+    // Register voice call tools (initiate + status + wait)
     registerVoiceCallTools(api);
-    // Register CLI commands for authentication
+    // Register auth tools (conversational flow — primary)
+    registerAuthTools(api);
+    // Register CLI commands for authentication (manual fallback)
     registerAuthCommands(api);
     api.log?.info?.("pine-voice: plugin loaded");
 }

package/dist/tool.js

@@ -2,38 +2,17 @@ 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.",
+    "Pine Voice is not authenticated. To set up, use the pine_voice_auth_request tool",
+    "with the user's Pine AI email address. If they don't have an 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.",
+    "Pine Voice authentication has expired. Use pine_voice_auth_request with the",
+    "user's email to re-authenticate.",
 ].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;
+    const config = api.config?.plugins?.entries?.["openclaw-pine-voice"]?.config;
     if (!config?.access_token || !config?.user_id) {
         return { content: [{ type: "text", text: AUTH_MISSING_MESSAGE }], isError: true };
     }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
-  "id": "pine-voice",
+  "id": "openclaw-pine-voice",
   "name": "Pine AI Voice Call",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-pine-voice",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Make phone calls via Pine AI voice agent from OpenClaw",
   "type": "module",
   "main": "dist/index.js",

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

@@ -1,11 +1,8 @@
 ---
 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.
+description: Set up or refresh Pine Voice authentication via the built-in auth tools.
 metadata:
-  {
-    "openclaw":
-      { "emoji": "🔑", "requires": { "bins": ["curl", "jq"] } },
-  }
+  { "openclaw": { "emoji": "🔑" } }
 ---
 
 # Pine Voice Auth Setup
@@ -15,7 +12,7 @@ metadata:
 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 returns "Pine Voice is not authenticated"
 - 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
 
@@ -24,7 +21,6 @@ Do **not** use this skill for making phone calls — see the `pine-voice` skill
 ## 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
 
@@ -32,16 +28,6 @@ This auth flow sends a verification code to the user's email inbox. The user **m
 
 **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
@@ -50,27 +36,15 @@ 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
+### Step 2: Send a verification code
 
-Run this command, replacing `USER_EMAIL` with the email from step 1:
+Call the `pine_voice_auth_request` tool with the user's email:
 
-```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..."}}
+pine_voice_auth_request({ email: "user@example.com" })
 ```
 
-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.
+This sends a verification code to their email. If the request fails with a 400/422, the email may not be registered — ask the user to check their email or sign up at https://19pine.ai.
 
 ### Step 3: Ask the user for the verification code
 
@@ -78,53 +52,35 @@ Tell the user: "I've sent a verification code to your email. Please check your i
 
 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
+### Step 4: Verify the code and save credentials
 
-Run this command, replacing `USER_EMAIL`, `THE_REQUEST_TOKEN`, and `THE_CODE` with the actual values:
+Call the `pine_voice_auth_verify` tool with the email and code:
 
-```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...", ...}
+pine_voice_auth_verify({ email: "user@example.com", code: "123456" })
 ```
 
-Save **both** values:
-- **`id`** — the user's Pine user ID
-- **`access_token`** — the access token
+The tool verifies the code, saves the credentials to `~/.openclaw/openclaw.json` automatically, and returns a success message.
 
 **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.
+- Invalid code — ask the user to double-check the code and try again (call `pine_voice_auth_verify` with the corrected code).
+- Expired token — go back to step 2 to send a new code.
 
-### Step 5: Store the credentials and restart
+### Step 5: Restart the gateway
 
-Use `openclaw config set` to write both values to the OpenClaw config file (`~/.openclaw/openclaw.json`). Replace `THE_ACCESS_TOKEN` and `THE_USER_ID` with the actual values from step 4.
+Tell the user to restart the gateway for the new credentials to take effect:
 
-**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.
+"Credentials saved! Please run this command to activate them:"
 
-```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
+openclaw gateway restart
 ```
 
-**Note:** The config file is located at `~/.openclaw/openclaw.json`. The `plugins.entries.pine-voice.config` section should contain both `access_token` and `user_id`. The gateway **must be restarted** after updating the config for the new credentials to take effect.
+The gateway **must be restarted** after authentication for the new credentials to take effect.
 
 ### 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:
+After the gateway has restarted, 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."
 
@@ -145,6 +101,6 @@ Access tokens expire periodically. When a call fails with `TOKEN_EXPIRED` or a 4
 
 ## Security notes
 
-- Never log or echo the access token in plaintext beyond what is needed to write the config file
+- Never log or echo the access token in plaintext beyond what is needed
 - 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