Refactor Pine AI authentication flow: update skill documentation, remove required fields in plugin config, and enhance error handling in auth tools. Introduce CLI commands for manual authentication fallback.

Author: bojieli

openclaw.plugin.json

@@ -21,7 +21,7 @@
         "default": "https://www.19pine.ai"
       }
     },
-    "required": ["access_token", "user_id"]
+    "required": []
   },
   "uiHints": {
     "access_token": {

skills/pine-ai-auth/SKILL.md

@@ -1,24 +1,92 @@
 ---
-name: Pine AI Auth
-description: Authenticate with Pine AI using email verification
-tools: [pine_auth_request, pine_auth_verify]
+name: pine-ai-auth
+description: Set up or refresh Pine AI authentication via the built-in auth tools.
+metadata:
+  { "openclaw": { "emoji": "🔑" } }
 ---
 
-# Pine AI Authentication
+# Pine AI Auth Setup
 
-To use Pine AI, the user needs to authenticate with their email address.
+## When to use
 
-## Steps
+Use this skill when **any** of these are true:
 
-1. Ask the user for their email address.
-2. Call `pine_auth_request` with their email.
-3. Tell the user to check their email for a 6-digit verification code.
-4. When they provide the code, call `pine_auth_verify` with email, code, and request_token.
-5. Save the returned `access_token` and `user_id` in the plugin configuration.
+- The user asks to set up Pine AI, configure Pine, or authenticate
+- A Pine AI tool invocation returns "not authenticated" or credentials are missing
+- A Pine AI operation fails with `TOKEN_EXPIRED`, `UNAUTHORIZED`, or a 401 response
+- The user says their Pine AI token isn't working
 
-## When to use
+Do **not** use this skill for creating sessions or starting tasks — see the `pine-ai` skill for that.
+
+## Prerequisites
+
+- The user must have a **Pine AI account** (sign up at https://19pine.ai)
+
+## 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 AI — not during an unattended or automated workflow.
+
+## 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: Send a verification code
+
+Call the `pine_auth_request` tool with the user's email:
+
+```
+pine_auth_request({ email: "user@example.com" })
+```
+
+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
+
+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 save credentials
+
+Call the `pine_auth_verify` tool with the email and code:
+
+```
+pine_auth_verify({ email: "user@example.com", code: "123456" })
+```
+
+The tool verifies the code, saves the credentials to `~/.openclaw/openclaw.json` automatically, and returns a success message.
+
+**If verification fails:**
+- Invalid code — ask the user to double-check the code and try again (call `pine_auth_verify` with the corrected code).
+- Expired token — go back to step 2 to send a new code.
+
+### Step 5: Restart the gateway
+
+Tell the user to restart the gateway for the new credentials to take effect:
+
+"Credentials saved! Please run this command to activate them:"
+
+```
+openclaw gateway restart
+```
+
+The gateway **must be restarted** after authentication for the new credentials to take effect.
+
+## Token refresh
+
+Access tokens expire periodically. When a Pine AI operation 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
 
-Use this when:
-- The user wants to use Pine AI but hasn't authenticated yet.
-- The user's token has expired.
-- The user explicitly asks to log in or authenticate.
+- 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

src/auth.ts

@@ -1,54 +1,245 @@
 /**
- * Auth tools for Pine AI — conversational email verification.
+ * Auth flow for Pine AI plugin.
+ *
+ * Provides two surfaces:
+ *  1. Tools (pine_auth_request / pine_auth_verify) — the primary,
+ *     conversational path where the AI agent drives the flow.
+ *  2. CLI commands (openclaw pine auth setup/verify) — a manual fallback.
+ *
+ * Delegates to the pine-ai SDK for actual API calls.
  */
 
 import { Type } from '@sinclair/typebox';
-import { PineAI } from 'pine-ai';
+import { PineAI, AuthError } from 'pine-ai';
+
+// ---------------------------------------------------------------------------
+// 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<string, string>(); // email → requestToken
+
+// ---------------------------------------------------------------------------
+// Tool registration (primary path)
+// ---------------------------------------------------------------------------
 
 export function registerAuthTools(api: any): void {
+  // --- Tool: pine_auth_request ---
   api.registerTool({
     name: 'pine_auth_request',
-    description: 'Request a Pine AI verification code. Sends an email with a 6-digit code.',
+    description:
+      'Start Pine AI 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_auth_verify.',
     parameters: Type.Object({
-      email: Type.String({ description: 'Email address to verify' }),
+      email: Type.String({ description: "The user's Pine AI account email address" }),
     }),
-    execute: async (args: { email: string }) => {
+    async execute(_toolCallId: string, params: { email: string }) {
       try {
         const client = new PineAI();
-        const result = await client.auth.requestCode(args.email);
+        const result = await client.auth.requestCode(params.email);
+        pendingAuth.set(params.email, result.request_token);
+
+        api.log?.info?.(`pine: auth code requested for ${params.email}`);
+
         return {
-          success: true,
-          request_token: result.request_token,
-          message: `Verification code sent to ${args.email}. Ask the user for the 6-digit code.`,
+          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_auth_verify with the email and code.',
+            },
+          ],
+          isError: false,
+        };
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        api.log?.error?.(`pine: auth request failed: ${message}`);
+
+        const hint =
+          err instanceof AuthError
+            ? ' The email may not be registered — the user can sign up at https://19pine.ai.'
+            : '';
+
+        return {
+          content: [{ type: 'text', text: `Pine AI auth request failed: ${message}.${hint}` }],
+          isError: true,
         };
-      } catch (err) {
-        return { error: `Failed to request code: ${(err as Error).message}` };
       }
     },
   });
 
+  // --- Tool: pine_auth_verify ---
   api.registerTool({
     name: 'pine_auth_verify',
-    description: 'Verify a Pine AI email code and get access credentials.',
+    description:
+      'Complete Pine AI 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_auth_request.',
     parameters: Type.Object({
-      email: Type.String({ description: 'Email address' }),
-      code: Type.String({ description: '6-digit verification code' }),
-      request_token: Type.String({ description: 'Token from pine_auth_request' }),
+      email: Type.String({ description: 'The same email used in pine_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_auth_request (usually not needed — resolved automatically)' }),
+      ),
     }),
-    execute: async (args: { email: string; code: string; request_token: string }) => {
+    async execute(_toolCallId: string, params: { email: string; code: string; request_token?: string }) {
+      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_auth_request first to send a new verification code.',
+            },
+          ],
+          isError: true,
+        };
+      }
+
       try {
         const client = new PineAI();
-        const result = await client.auth.verifyCode(args.email, args.code, args.request_token);
+        const result = await client.auth.verifyCode(params.email, params.code, requestToken);
+
+        // Write credentials to openclaw.json
+        const cfg = api.runtime.config.loadConfig();
+        const plugins = (cfg.plugins ?? {}) as Record<string, any>;
+        const entries = (plugins.entries ?? {}) as Record<string, any>;
+        const pluginEntry = (entries['openclaw-pine'] ?? {}) as Record<string, any>;
+
+        const updatedConfig = {
+          ...cfg,
+          plugins: {
+            ...plugins,
+            entries: {
+              ...entries,
+              'openclaw-pine': {
+                ...pluginEntry,
+                config: {
+                  ...(pluginEntry.config ?? {}),
+                  access_token: result.access_token,
+                  user_id: result.id,
+                },
+              },
+            },
+          },
+        };
+
+        await api.runtime.config.writeConfigFile(updatedConfig);
+        pendingAuth.delete(params.email);
+
+        api.log?.info?.(`pine: auth successful for ${params.email}, credentials saved`);
+
         return {
-          success: true,
-          user_id: result.id,
-          email: result.email,
-          access_token: result.access_token,
-          message: 'Authentication successful. Save access_token and user_id in plugin config.',
+          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: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        api.log?.error?.(`pine: auth verify failed: ${message}`);
+
+        const isExpired = message.toLowerCase().includes('expired');
+        const hint = isExpired
+          ? ' The request token has expired — call pine_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 AI auth verification failed: ${message}.${hint}` }],
+          isError: true,
         };
-      } catch (err) {
-        return { error: `Verification failed: ${(err as Error).message}` };
       }
     },
   });
 }
+
+// ---------------------------------------------------------------------------
+// CLI registration (manual fallback)
+// ---------------------------------------------------------------------------
+
+export function registerAuthCommands(api: any): void {
+  api.registerCli?.(
+    ({ program }: any) => {
+      const pine = program.command('pine').description('Pine AI plugin');
+      const auth = pine.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: any) => {
+          if (!opts.email) {
+            console.log('Usage: openclaw pine auth setup --email you@example.com');
+            return;
+          }
+
+          console.log(`Requesting verification code for ${opts.email}...`);
+
+          try {
+            const client = new PineAI();
+            const { request_token } = await client.auth.requestCode(opts.email);
+
+            console.log('Verification code sent! Check your email.');
+            console.log(`Then run: openclaw pine auth verify --email ${opts.email} --request-token ${request_token} --code <code>`);
+          } catch (err: unknown) {
+            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: any) => {
+          if (!opts.code || !opts.email || !opts.requestToken) {
+            console.log('Usage: openclaw pine auth verify --email you@example.com --request-token <token> --code 1234');
+            return;
+          }
+
+          try {
+            const client = new PineAI();
+            const result = await client.auth.verifyCode(
+              opts.email,
+              opts.code,
+              opts.requestToken || '',
+            );
+
+            console.log('Authentication successful!');
+            console.log('Add this to your plugin config in ~/.openclaw/openclaw.json:');
+            console.log('');
+            console.log('  "plugins": {');
+            console.log('    "entries": {');
+            console.log('      "openclaw-pine": {');
+            console.log('        "config": {');
+            console.log(`          "access_token": "${result.access_token}",`);
+            console.log(`          "user_id": "${result.id}"`);
+            console.log('        }');
+            console.log('      }');
+            console.log('    }');
+            console.log('  }');
+            console.log('');
+            console.log('Then restart the gateway:');
+            console.log('  openclaw gateway restart');
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Error: ${message}`);
+          }
+        });
+    },
+    { commands: ['pine'] },
+  );
+}