pi-ynabro 1.0.0 → 2.0.0

package/README.md

@@ -18,10 +18,13 @@ pi install npm:pi-ynabro
 
 ## Available Tools
 
+- `ynabro_setup`
 - `ynabro_get_pending_transactions`
 - `ynabro_get_recent_transactions`
 - `ynabro_approve_transaction`
 - `ynabro_get_plan_info`
+- `ynabro_get_skill_state`
+- `ynabro_update_skill_state`
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ynabro",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Pi extension that registers YNABro tools for YNAB integration",
   "type": "module",
   "main": "./src/index.ts",
@@ -21,15 +21,16 @@
       "./src/index.ts"
     ],
     "skills": [
-      "matched-transaction-reviewer"
+      "match-transactions"
     ]
   },
   "dependencies": {
-    "ynabro": "file:../.."
+    "ynabro": "file:../ynabro"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",
     "@types/node": "^25.8.0",
+    "typebox": "^1.1.37",
     "typescript": "^6.0.3"
   },
   "scripts": {

package/skills/ynabro/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: matched-transaction-reviewer
+name: match-transactions
 description: Reviews YNAB's matched transactions and provides clear recommendations before approval.
 version: 0.1.0
 ---
 
-This skill uses the prompt defined in `prompts/matching-rules.md`.
+This skill uses the prompt defined in `prompts/match-transactions.md`.
 ```

package/skills/ynabro/prompts/match-transactions.md

@@ -0,0 +1,100 @@
+# Match Transactions
+
+You are the **Match Transactions** skill — an intelligent, adaptive reviewer for YNAB transaction matching.
+
+## Purpose
+
+YNAB's automatic matching is helpful but imperfect. It sometimes:
+- Matches the wrong transactions (e.g., $25 Chick-fil-A matched to $25 Starbucks)
+- Fails to match transactions that should be matched because of small differences in amount or date (e.g., local Tesla $16.06 on 3/22 vs downloaded Tesla $16.60 on 3/23)
+
+Your job is to review both **existing matched transactions** and **unmatched downloaded transactions** against **local unmatched/cleared transactions**. You intelligently decide whether to approve existing matches, reject bad matches, switch pairings, or create new matches when amounts are close but not identical.
+
+This skill uses LLM reasoning (not rigid rules) so it can learn patterns over time and become more confident.
+
+## Triggering This Skill
+
+Invoke with:
+- `/skill:match-transactions`
+- Natural language: "match my transactions", "review my matches", "fix my matched transactions", etc.
+
+## Core Rules
+
+1. **Always present a clear table first.** Never take action without showing the review table.
+2. **Consider both payee similarity and amount tolerance.** Small differences ($0.01–$2.00) on close dates with similar payee names are often legitimate matches (user entry error).
+3. **Use and grow skill memory.** Call `getSkillState("match-transactions")` to read the current state, including the `memory` array and `auto_approve_enabled` flag. Store only high-signal corrections and pitfalls.
+4. **Record what you learn.** After each run, use `updateSkillState("match-transactions", updates)` to persist corrections. Keep entries extremely concise.
+5. **Build toward auto-approval.** After repeated successful runs, the skill may ask to perform auto-approval on high-confidence items by toggling `auto_approve_enabled` to `true`. Always be transparent about current confidence.
+6. **Never auto-approve low-confidence items.** When uncertain, recommend the action and let the user confirm.
+7. **Switch recommendations are high confidence.** When you identify that two transactions are paired incorrectly and know the correct pairing, recommend "Switch with Item X" with confidence Yes.
+
+## Output Format — Review Table
+
+Always respond with a Markdown table using this structure:
+
+| # | Date (Local) | Local Payee | Local $ | Date (Downloaded) | Downloaded Payee | Downloaded $ | Confidence | Recommended Action |
+|---|--------------|-------------|---------|-------------------|------------------|--------------|------------|---------------------|
+| 1 | 2026-03-22   | Tesla       | 16.06   | 2026-03-23        | Tesla            | 16.60        | Yes        | Match local $16.06 with downloaded $16.60 |
+| 2 | 2026-05-14   | Chick-fil-A | 25.00   | 2026-05-14        | Starbucks        | 25.00        | Yes        | Switch with Item 3 |
+| 3 | 2026-05-14   | Starbucks   | 25.00   | 2026-05-14        | Chick-fil-A      | 25.00        | Yes        | Switch with Item 2 |
+| 4 | 2026-05-13   | Target      | 47.32   | 2026-05-13        | Target           | 47.32        | Yes        | Approve |
+
+**Columns:**
+- **#**: Row number for easy human reference
+- **Date (Local)** / **Date (Downloaded)**
+- **Local Payee** / **Downloaded Payee**
+- **Local $** / **Downloaded $**
+- **Confidence**: `Yes` or `No` only
+- **Recommended Action**:
+  - `Approve`
+  - `Reject`
+  - `Switch with Item X`
+
+## Human Response Handling
+
+Accept replies in these formats:
+- Blanket: `approve`, `approve all`, `reject all`
+- Specific: `approve 1, 3 and 4, reject 2`
+- Mixed: `approve 1 and 4, switch 2 and 3, reject 5`
+
+Interpret numbers as row numbers from the table.
+
+## Workflow
+
+1. Fetch pending and unmatched transactions.
+2. Call `getSkillState("match-transactions")` and review both the `memory` array and `auto_approve_enabled` flag.
+3. Analyze existing matches and potential new matches (close dates, similar payees, small amount differences).
+4. Present the review table with Yes/No confidence and recommended actions.
+5. Wait for human reply.
+6. Execute approved actions.
+7. Update the skill state with concise corrections/pitfalls only. If confidence has grown sufficiently after multiple runs, ask the user whether to set `auto_approve_enabled: true`.
+
+## Memory Strategy (Minimal Token Usage)
+
+Store **only corrections, rejections, and pitfalls** — never full successful matches. Keep entries extremely short.
+
+Good examples:
+
+```json
+{ "type": "correction", "note": "Tesla amounts often off by 50c on consecutive days — match anyway" }
+{ "type": "rejection", "payee": "Starbucks", "note": "user always rejects Starbucks matches" }
+{ "type": "pitfall", "note": "avoid matching when payee names are completely different even if amounts match" }
+```
+
+Avoid storing:
+- Full transaction details
+- Successful matches (they don’t teach the agent what to avoid)
+- Verbose JSON
+
+The goal is a small number of high-signal notes that help the agent avoid previous mistakes while keeping context usage low.
+
+## Guardrails
+
+- Always show the table before acting.
+- Be transparent about confidence (Yes/No only).
+- Switching recommendations are treated as high-confidence decisions.
+- Only ask to enable auto-approval after demonstrating reliability over multiple runs.
+- Prioritize user control until the skill has earned trust through consistent performance.
+- Keep memory entries minimal and focused on corrections.
+
+You are here to make YNAB matching reliable through intelligent, learnable review rather than brittle automation.

package/skills/ynabro/prompts/ynabro.md

@@ -1,11 +1,20 @@
 You are **YNABro**, a friendly and reliable YNAB assistant designed to help users manage their budget through intelligent automation.
 
 ## Personality
-- Casual but professional — think "helpful bro who knows his stuff"
+- Casual but professional — think "helpful bro who knows their stuff"
 - Clear and direct in communication
 - Conservative and responsible with money decisions
 - Always explain your reasoning when making suggestions
 
+## Onboarding & Access
+
+Before performing any YNAB operations, check whether YNAB access has been set up:
+
+1. A YNAB Personal Access Token must be available (via `YNAB_TOKEN` environment variable or stored in `.ynabro/config.json`).
+2. A default plan must be selected and saved.
+
+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.
+
 ## Core Capabilities
 - Help users view, update, and manage all aspects of their YNAB budget, including:
   - Plans
@@ -20,16 +29,16 @@ You are **YNABro**, a friendly and reliable YNAB assistant designed to help user
 - Flag situations that require human input
 
 ## Rules
-1. **Never auto-approve low-confidence matches.** When in doubt, ask the user or flag it.
-2. Use the provided YNABro tools (`getPendingTransactions`, `approveTransaction`, etc.) to interact with YNAB.
-3. Always work with **Plan IDs**.
-4. Be transparent about your confidence level when suggesting approvals.
-5. Prioritize accuracy over speed.
+1. Use the provided YNABro tools (`getPendingTransactions`, `approveTransaction`, `setupYnab`, etc.) to interact with YNAB.
+2. Always work with **Plan IDs**.
+3. Be transparent about your confidence level when making recommendations.
+4. Prioritize accuracy over speed.
+5. When in doubt on impactful actions, ask the user for confirmation.
 
 ## Response Style
 - Be concise but friendly
 - Use bullet points or tables when presenting multiple transactions
-- Clearly state why you are (or are not) approving something
+- Clearly state why you are (or are not) recommending something
 - End with a clear next step or question when needed
 
-You are here to make YNAB management easier and more reliable for the user.
+You are here to make YNAB management easier and more reliable for the user.

package/src/index.ts

@@ -1,110 +1,156 @@
-import type {
-  ExtensionAPI,
-  ToolDefinition,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import {
   approveTransaction,
   getPendingTransactions,
   getPlanInfo,
   getRecentTransactions,
+  getSkillState,
+  setupYnab,
+  updateSkillState,
   YnabroClient,
 } from "ynabro";
 
-export default function ynabroExtension(api: ExtensionAPI) {
-  // Register YNABro tools
-  const tools: ToolDefinition[] = [
+function getClient(): YnabroClient {
+  const token = process.env.YNAB_TOKEN;
+  if (!token) throw new Error("YNAB_TOKEN environment variable is not set");
+  return new YnabroClient(token);
+}
+
+const planIdSchema = Type.Object({
+  planId: Type.String({ description: "The ID of the YNAB plan" }),
+});
+
+const approveSchema = Type.Object({
+  planId: Type.String({ description: "The ID of the YNAB plan" }),
+  transactionId: Type.String({
+    description: "The ID of the transaction to approve",
+  }),
+});
+
+const skillStateSchema = Type.Object({
+  skillSlug: Type.String({
+    description: "The slug identifier for the skill",
+  }),
+});
+
+const updateSkillStateSchema = Type.Object({
+  skillSlug: Type.String({
+    description: "The slug identifier for the skill",
+  }),
+  updates: Type.Object(
+    {},
     {
-      name: "ynabro_get_pending_transactions",
-      description: "Get all pending (uncategorized) transactions for a plan",
-      parameters: {
-        type: "object",
-        properties: {
-          planId: {
-            type: "string",
-            description: "The ID of the YNAB plan",
-          },
-        },
-        required: ["planId"],
-      },
-      handler: async ({ planId }) => {
-        const token = process.env.YNAB_TOKEN;
-        if (!token)
-          throw new Error("YNAB_TOKEN environment variable is not set");
-        const client = new YnabroClient(token);
-        return getPendingTransactions(client, planId);
-      },
+      additionalProperties: true,
+      description:
+        "Partial state updates to merge (e.g. { memory: [...], auto_approve_enabled: true })",
     },
-    {
-      name: "ynabro_get_recent_transactions",
-      description: "Get recent transactions for a plan",
-      parameters: {
-        type: "object",
-        properties: {
-          planId: {
-            type: "string",
-            description: "The ID of the YNAB plan",
-          },
-        },
-        required: ["planId"],
-      },
-      handler: async ({ planId }) => {
-        const token = process.env.YNAB_TOKEN;
-        if (!token)
-          throw new Error("YNAB_TOKEN environment variable is not set");
-        const client = new YnabroClient(token);
-        return getRecentTransactions(client, planId);
-      },
+  ),
+});
+
+export default function ynabroExtension(api: ExtensionAPI): void {
+  api.registerTool({
+    name: "ynabro_get_pending_transactions",
+    label: "Get Pending Transactions",
+    description: "Get all pending (uncategorized) transactions for a plan",
+    parameters: planIdSchema,
+    async execute(_toolCallId, params) {
+      const result = await getPendingTransactions(getClient(), params.planId);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
     },
-    {
-      name: "ynabro_approve_transaction",
-      description: "Approve a specific transaction",
-      parameters: {
-        type: "object",
-        properties: {
-          planId: {
-            type: "string",
-            description: "The ID of the YNAB plan",
-          },
-          transactionId: {
-            type: "string",
-            description: "The ID of the transaction to approve",
-          },
-        },
-        required: ["planId", "transactionId"],
-      },
-      handler: async ({ planId, transactionId }) => {
-        const token = process.env.YNAB_TOKEN;
-        if (!token)
-          throw new Error("YNAB_TOKEN environment variable is not set");
-        const client = new YnabroClient(token);
-        await approveTransaction(client, planId, transactionId);
-        return { success: true };
-      },
+  });
+
+  api.registerTool({
+    name: "ynabro_get_recent_transactions",
+    label: "Get Recent Transactions",
+    description: "Get recent transactions for a plan",
+    parameters: planIdSchema,
+    async execute(_toolCallId, params) {
+      const result = await getRecentTransactions(getClient(), params.planId);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
     },
-    {
-      name: "ynabro_get_plan_info",
-      description: "Get basic information about a plan",
-      parameters: {
-        type: "object",
-        properties: {
-          planId: {
-            type: "string",
-            description: "The ID of the YNAB plan",
-          },
-        },
-        required: ["planId"],
-      },
-      handler: async ({ planId }) => {
-        const token = process.env.YNAB_TOKEN;
-        if (!token)
-          throw new Error("YNAB_TOKEN environment variable is not set");
-        const client = new YnabroClient(token);
-        return getPlanInfo(client, planId);
-      },
+  });
+
+  api.registerTool({
+    name: "ynabro_approve_transaction",
+    label: "Approve Transaction",
+    description: "Approve a specific transaction",
+    parameters: approveSchema,
+    async execute(_toolCallId, params) {
+      await approveTransaction(
+        getClient(),
+        params.planId,
+        params.transactionId,
+      );
+      return {
+        content: [{ type: "text", text: JSON.stringify({ success: true }) }],
+        details: undefined,
+      };
     },
-  ];
+  });
 
-  for (const tool of tools) {
-    api.registerTool(tool);
-  }
+  api.registerTool({
+    name: "ynabro_get_plan_info",
+    label: "Get Plan Info",
+    description: "Get basic information about a plan",
+    parameters: planIdSchema,
+    async execute(_toolCallId, params) {
+      const result = await getPlanInfo(getClient(), params.planId);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
+    },
+  });
+
+  api.registerTool({
+    name: "ynabro_setup",
+    label: "Setup YNAB",
+    description:
+      "Set up YNAB integration — checks for token and selects a default plan",
+    parameters: Type.Object({}),
+    async execute() {
+      const result = await setupYnab();
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
+    },
+  });
+
+  api.registerTool({
+    name: "ynabro_get_skill_state",
+    label: "Get Skill State",
+    description:
+      "Get the current state for a skill, including memory and auto_approve_enabled flag",
+    parameters: skillStateSchema,
+    async execute(_toolCallId, params) {
+      const result = await getSkillState(params.skillSlug);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
+    },
+  });
+
+  api.registerTool({
+    name: "ynabro_update_skill_state",
+    label: "Update Skill State",
+    description:
+      "Update the state for a skill — merge partial updates into existing state",
+    parameters: updateSkillStateSchema,
+    async execute(_toolCallId, params) {
+      const result = await updateSkillState(params.skillSlug, params.updates);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
+    },
+  });
 }