pi-ynabro 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ynabro",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Pi extension that registers YNABro tools for YNAB integration",
   "type": "module",
   "main": "./src/index.ts",

package/skills/ynabro/prompts/ynabro.md

@@ -8,12 +8,29 @@ You are **YNABro**, a friendly and reliable YNAB assistant designed to help user
 
 ## Onboarding & Access
 
-Before performing any YNAB operations, check whether YNAB access has been set up:
+Before performing any YNAB operations, call `ynabro_onboarding_status` to check
+whether YNAB access is configured.
 
-1. A YNAB Personal Access Token must be available. In OpenClaw, the preferred storage location is `plugins.entries.openclaw-ynabro.config.token` in `openclaw.json` (surfaced as a sensitive field in the settings UI). The `YNAB_TOKEN` environment variable is also accepted as a fallback.
-2. A default plan must be selected and saved.
+If `ready` is `false`, walk the user through setup:
 
-If either is missing, call the `setupYnab()` tool first. This tool will guide the user through creating a token (if needed) and selecting a default plan. Do not attempt to read or modify transactions until setup is complete.
+1. **Missing token:** Share the `tokenInstructions` field from the status response.
+   The token must never be entered into the chat.
+   - **pi:** Call `ynabro_setup` — it presents a native TUI input popup where the
+     user enters the token directly. It goes straight to pi's AuthStorage and
+     never appears in the conversation.
+   - **OpenClaw:** Instruct the user to add the token to `openclaw.json` or via
+     the OpenClaw settings UI, then ask them to confirm when done.
+
+2. **Missing plan:** Call `ynabro_setup` to list available plans. Help the user
+   pick one. On OpenClaw, follow up with `ynabro_save_default_plan`.
+
+3. **After onboarding completes:** If the user's original message was a functional
+   request (e.g., "show my pending transactions"), fulfill it immediately.
+   Do not make them repeat themselves.
+
+If a tool returns `{ "error": "onboarding_required" }` during a conversation,
+treat it the same as a failed status check — initiate onboarding, then retry
+the original operation.
 
 ## Core Capabilities
 - Help users view, update, and manage all aspects of their YNAB budget, including:

package/src/index.ts

@@ -1,9 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { AuthStorage } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { YnabroConfigAdapter } from "ynabro";
+import type { OnboardingStatus, YnabroConfigAdapter } from "ynabro";
 import {
   approveTransaction,
+  checkOnboardingStatus,
   getPendingTransactions,
   getPlanInfo,
   getRecentTransactions,
@@ -26,28 +27,31 @@ const piConfigAdapter: YnabroConfigAdapter = {
   async setDefaultPlanId(planId: string): Promise<void> {
     authStorage.set("ynab-plan", { type: "api_key", key: planId });
   },
+  async hasToken(): Promise<boolean> {
+    return !!(await authStorage.getApiKey("ynab"));
+  },
 };
 
 async function getClient(): Promise<YnabroClient> {
   const token = await authStorage.getApiKey("ynab");
-  if (!token) {
-    throw new Error(
-      "YNAB token not configured. Run ynabro_setup to complete onboarding.",
-    );
-  }
+  if (!token) throw new Error("YNAB token not configured");
   return new YnabroClient(token);
 }
 
 async function getDefaultPlanId(): Promise<string> {
   const planId = await piConfigAdapter.getDefaultPlanId();
-  if (!planId) {
-    throw new Error(
-      "No default plan configured. Run ynabro_setup to complete onboarding.",
-    );
-  }
+  if (!planId) throw new Error("No default plan configured");
   return planId;
 }
 
+async function checkConfigured(): Promise<OnboardingStatus | null> {
+  const status = await checkOnboardingStatus(piConfigAdapter);
+  if (!status.ready) {
+    return status;
+  }
+  return null;
+}
+
 const approveSchema = Type.Object({
   transactionId: Type.String({
     description: "The ID of the transaction to approve",
@@ -75,6 +79,21 @@ const updateSkillStateSchema = Type.Object({
 });
 
 export default function ynabroExtension(api: ExtensionAPI): void {
+  api.registerTool({
+    name: "ynabro_onboarding_status",
+    label: "Onboarding Status",
+    description:
+      "Check whether YNABro is fully configured. Returns ready status, any missing configuration, and token generation instructions.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params) {
+      const status = await checkOnboardingStatus(piConfigAdapter);
+      return {
+        content: [{ type: "text", text: JSON.stringify(status) }],
+        details: undefined,
+      };
+    },
+  });
+
   api.registerTool({
     name: "ynabro_get_pending_transactions",
     label: "Get Pending Transactions",
@@ -82,6 +101,22 @@ export default function ynabroExtension(api: ExtensionAPI): void {
       "Get all pending (uncategorized) transactions for the default plan",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params) {
+      const onboardingError = await checkConfigured();
+      if (onboardingError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "onboarding_required",
+                ...onboardingError,
+              }),
+            },
+          ],
+          details: undefined,
+        };
+      }
+
       const [client, planId] = await Promise.all([
         getClient(),
         getDefaultPlanId(),
@@ -100,6 +135,22 @@ export default function ynabroExtension(api: ExtensionAPI): void {
     description: "Get recent transactions for the default plan",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params) {
+      const onboardingError = await checkConfigured();
+      if (onboardingError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "onboarding_required",
+                ...onboardingError,
+              }),
+            },
+          ],
+          details: undefined,
+        };
+      }
+
       const [client, planId] = await Promise.all([
         getClient(),
         getDefaultPlanId(),
@@ -118,6 +169,22 @@ export default function ynabroExtension(api: ExtensionAPI): void {
     description: "Approve a specific transaction in the default plan",
     parameters: approveSchema,
     async execute(_toolCallId, params) {
+      const onboardingError = await checkConfigured();
+      if (onboardingError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "onboarding_required",
+                ...onboardingError,
+              }),
+            },
+          ],
+          details: undefined,
+        };
+      }
+
       const [client, planId] = await Promise.all([
         getClient(),
         getDefaultPlanId(),
@@ -136,6 +203,22 @@ export default function ynabroExtension(api: ExtensionAPI): void {
     description: "Get basic information about the default plan",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params) {
+      const onboardingError = await checkConfigured();
+      if (onboardingError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "onboarding_required",
+                ...onboardingError,
+              }),
+            },
+          ],
+          details: undefined,
+        };
+      }
+
       const [client, planId] = await Promise.all([
         getClient(),
         getDefaultPlanId(),