ray-finance 0.1.0 → 0.1.1

package/dist/ai/agent.d.ts

@@ -1,2 +1,10 @@
 import type Database from "libsql";
-export declare function handleMessage(db: Database.Database, userMessage: string): Promise<string>;
+/** Human-readable labels for tool calls shown in the spinner */
+export declare const TOOL_LABELS: Record<string, string>;
+export type ProgressCallback = (event: {
+    phase: "tool" | "responding";
+    toolName?: string;
+    toolCount: number;
+    elapsedMs: number;
+}) => void;
+export declare function handleMessage(db: Database.Database, userMessage: string, onProgress?: ProgressCallback): Promise<string>;

package/dist/ai/agent.js

@@ -11,7 +11,23 @@ const anthropic = new Anthropic(useManaged()
 function supportsThinking(model) {
     return /sonnet-4|opus-4/i.test(model);
 }
-export async function handleMessage(db, userMessage) {
+/** Human-readable labels for tool calls shown in the spinner */
+export const TOOL_LABELS = {
+    get_net_worth: "Checking net worth",
+    get_accounts: "Reviewing accounts",
+    get_transactions: "Looking at transactions",
+    get_spending_summary: "Analyzing spending",
+    get_budgets: "Reviewing budgets",
+    set_budget: "Setting budget",
+    get_goals: "Checking goals",
+    set_goal: "Setting goal",
+    get_score: "Calculating score",
+    get_recurring: "Finding recurring charges",
+    get_alerts: "Checking alerts",
+    save_memory: "Remembering that",
+    update_context: "Updating your profile",
+};
+export async function handleMessage(db, userMessage, onProgress) {
     // Save incoming message
     saveMessage(db, "user", userMessage);
     // Load conversation context, truncated to fit token budget
@@ -56,6 +72,8 @@ export async function handleMessage(db, userMessage) {
         // Initial API call
         let response = await anthropic.messages.create(apiParams);
         // Agentic tool loop
+        const startTime = Date.now();
+        let toolCount = 0;
         while (response.stop_reason === "tool_use") {
             // Filter out thinking blocks before adding to messages
             const assistantContent = response.content.filter((b) => b.type !== "thinking");
@@ -63,6 +81,13 @@ export async function handleMessage(db, userMessage) {
             const toolResults = [];
             for (const block of assistantContent) {
                 if (block.type === "tool_use") {
+                    toolCount++;
+                    onProgress?.({
+                        phase: "tool",
+                        toolName: block.name,
+                        toolCount,
+                        elapsedMs: Date.now() - startTime,
+                    });
                     const result = await executeTool(db, block.name, block.input);
                     logToolCall(db, block.name, block.input, result, response.usage?.output_tokens);
                     toolResults.push({
@@ -73,6 +98,11 @@ export async function handleMessage(db, userMessage) {
                 }
             }
             messages.push({ role: "user", content: toolResults });
+            onProgress?.({
+                phase: "responding",
+                toolCount,
+                elapsedMs: Date.now() - startTime,
+            });
             response = await anthropic.messages.create(apiParams);
         }
         // Extract text response (filter out thinking blocks), restore PII for display
@@ -83,11 +113,19 @@ export async function handleMessage(db, userMessage) {
         return responseText || "I looked into that but couldn't formulate a response. Could you try rephrasing?";
     }
     catch (error) {
-        // Log full error internally but don't expose details to user
+        if (error.status === 403) {
+            return "Your API key was rejected. This usually means your subscription is inactive. Run `ray billing` to check your payment status, or `ray setup` to reconfigure.";
+        }
+        if (error.status === 401) {
+            return "Invalid API key. Run `ray setup` to reconfigure your credentials.";
+        }
+        if (error.status === 429) {
+            return "Rate limited. Wait a moment and try again.";
+        }
         const safeMessage = error.status
             ? `API error (${error.status})`
-            : "internal error";
-        console.error("AI agent error:", safeMessage);
+            : error.message || "internal error";
+        console.error("AI error:", safeMessage);
         return "Sorry, I had trouble processing that. Could you try again?";
     }
 }

package/dist/ai/system-prompt.js

@@ -38,6 +38,7 @@ Today is ${dateStr}.
 - When the user shares something worth remembering (a preference, life event, financial goal context), use save_memory.
 - When circumstances change (new decisions, completed goals, changed balances, updated strategy), use update_context to persist the change.
 - For date-based queries, figure out the right date range from context (e.g., "this month" = first of current month to today).
+- If you notice transactions suggesting unlinked accounts (e.g., mortgage payments, car loans, investment transfers) that aren't in the linked accounts, mention it once and suggest \`ray link\`. If the user says they don't have that account, save it to context.
 
 ## Privacy
 - Never reveal account numbers, routing numbers, or Plaid access tokens.
@@ -49,18 +50,19 @@ ${name} just connected their financial accounts and needs help setting up their
 Instructions:
 1. Start by calling these tools to review their synced data: get_accounts, get_transactions (last 30 days), get_spending_summary, get_debts
 2. Present a concise summary of what you found — accounts, recent spending patterns, any debts
-3. Then ask about gaps ONE TOPIC AT A TIME (not all at once). Topics to cover:
+3. Check for missing account types: if you see mortgage payments but no mortgage account, car payments but no auto loan, investment contributions but no investment account, etc. — ask if they'd like to link those too (they can run \`ray link\`). If they say they don't have one, save that to context so you don't ask again.
+4. Then ask about gaps ONE TOPIC AT A TIME (not all at once). Topics to cover:
    - Family situation (partner, dependents)
    - Income details (salary, side income, frequency)
    - Financial goals (short-term and long-term)
    - Current challenges or concerns
    - Budget targets or spending limits they want
    - Any upcoming life changes (job change, move, baby, etc.)
-4. After each answer, call update_context with the "section" param to save that section of their context
-5. Also use save_memory for notable individual facts
-6. Keep it to 1-2 questions per turn — be conversational, not interrogative
-7. After gathering enough info, write a Strategy section summarizing priorities and next steps
-8. If the user says "skip" or changes topic, gracefully stop onboarding and help with whatever they need
+5. After each answer, call update_context with the "section" param to save that section of their context
+6. Also use save_memory for notable individual facts
+7. Keep it to 1-2 questions per turn — be conversational, not interrogative
+8. After gathering enough info, write a Strategy section summarizing priorities and next steps
+9. If the user says "skip" or changes topic, gracefully stop onboarding and help with whatever they need
 
 This onboarding block will automatically disappear once the context file is filled in.`;
     }

package/dist/cli/chat.js

@@ -1,22 +1,18 @@
 import chalk from "chalk";
-import { getDb } from "../db/connection.js";
-import { handleMessage } from "../ai/agent.js";
 import { config } from "../config.js";
-import { isContextEmpty } from "../ai/context.js";
-import { cliBriefing } from "../ai/insights.js";
-import { banner, formatResponse } from "./format.js";
+import { banner, formatResponse, formatDuration, formatError } from "./format.js";
 /** Raw-mode line reader that renders content below the cursor while waiting for input */
 function rawReadLine(prompt, belowLines) {
     return new Promise((resolve) => {
         let buf = "";
         const out = process.stdout;
-        // Render: prompt on current line, then content below, then restore cursor
+        // Render: prompt on current line, then content below, then move cursor back
         out.write(prompt);
         if (belowLines.length > 0) {
-            // Save cursor, render below, restore
-            out.write("\x1b[s");
             out.write("\n" + belowLines.join("\n"));
-            out.write("\x1b[u");
+            // Move cursor back up to the prompt line and to the end of prompt text
+            out.write(`\x1b[${belowLines.length}A`);
+            out.write("\r" + prompt);
         }
         process.stdin.setRawMode(true);
         process.stdin.resume();
@@ -73,8 +69,25 @@ function rawReadLine(prompt, belowLines) {
         process.stdin.on("data", onData);
     });
 }
+const THINKING_PHRASES = [
+    "Thinking...",
+    "Crunching numbers...",
+    "Reviewing your accounts...",
+    "Analyzing...",
+    "Looking into that...",
+    "Pulling up your data...",
+    "Checking the numbers...",
+    "On it...",
+];
+function getThinkingText() {
+    return THINKING_PHRASES[Math.floor(Math.random() * THINKING_PHRASES.length)];
+}
 export async function startChat() {
     const ora = (await import("ora")).default;
+    const { getDb } = await import("../db/connection.js");
+    const { handleMessage, TOOL_LABELS } = await import("../ai/agent.js");
+    const { isContextEmpty } = await import("../ai/context.js");
+    const { cliBriefing } = await import("../ai/insights.js");
     const db = getDb();
     // Show logo + briefing
     console.log("");
@@ -111,8 +124,8 @@ export async function startChat() {
     }
     // Auto-trigger onboarding for new users
     if (isContextEmpty()) {
-        console.log(chalk.cyan("Welcome! Let me review your accounts and help set up your financial profile.\n"));
-        const spinner = ora({ text: "Reviewing your accounts...", color: "cyan", discardStdin: false }).start();
+        console.log(chalk.yellowBright("Welcome! Let me review your accounts and help set up your financial profile.\n"));
+        const spinner = ora({ text: "Reviewing your accounts...", color: "yellow", discardStdin: false }).start();
         try {
             const response = await handleMessage(db, "I just connected my financial accounts. Help me set up my financial profile.");
             spinner.stop();
@@ -120,10 +133,28 @@ export async function startChat() {
         }
         catch (err) {
             spinner.stop();
-            console.error(chalk.red("Error during onboarding: " + err.message));
+            console.error(formatError(err, "Onboarding error"));
+        }
+    }
+    // Background re-sync for recently linked accounts (Plaid backfill can take hours)
+    let bgSyncTimer = null;
+    const oldestAccount = db.prepare(`SELECT MIN(created_at) as ts FROM institutions`).get();
+    if (oldestAccount?.ts) {
+        const ageMs = Date.now() - new Date(oldestAccount.ts + "Z").getTime();
+        if (ageMs < 6 * 60 * 60 * 1000) { // linked within last 6 hours
+            const { runDailySync } = await import("../daily-sync.js");
+            bgSyncTimer = setInterval(async () => {
+                try {
+                    await runDailySync(db);
+                }
+                catch { }
+            }, 15 * 60 * 1000); // every 15 minutes
+            bgSyncTimer.unref(); // don't prevent process exit
         }
     }
     const shutdown = () => {
+        if (bgSyncTimer)
+            clearInterval(bgSyncTimer);
         console.log(chalk.dim("\nGoodbye!"));
         process.exit(0);
     };
@@ -159,6 +190,7 @@ export async function startChat() {
         if (syncStr)
             parts.push(syncStr);
         parts.push(hints[hintIdx]);
+        parts.push("ctrl+c to exit");
         hintIdx = (hintIdx + 1) % hints.length;
         return parts.join("  ·  ");
     };
@@ -189,15 +221,24 @@ export async function startChat() {
             shutdown();
             break;
         }
-        const spinner = ora({ text: "Thinking...", color: "cyan", discardStdin: false }).start();
+        const spinner = ora({ text: getThinkingText(), color: "cyan", discardStdin: false }).start();
+        const onProgress = ({ phase, toolName, toolCount, elapsedMs }) => {
+            if (phase === "tool" && toolName) {
+                const label = TOOL_LABELS[toolName] || toolName;
+                spinner.text = `${label}... ${chalk.dim(`(${toolCount} ${toolCount === 1 ? "tool" : "tools"}, ${formatDuration(elapsedMs)})`)}`;
+            }
+            else if (phase === "responding" && toolCount > 0) {
+                spinner.text = `Composing response... ${chalk.dim(`(${toolCount} tools, ${formatDuration(elapsedMs)})`)}`;
+            }
+        };
         try {
-            const response = await handleMessage(db, trimmed);
+            const response = await handleMessage(db, trimmed, onProgress);
             spinner.stop();
             console.log(`\n${formatResponse(response)}\n`);
         }
         catch (err) {
             spinner.stop();
-            console.error(chalk.red("Error: " + err.message));
+            console.error(formatError(err));
         }
     }
 }

package/dist/cli/commands.js

@@ -5,17 +5,22 @@ import { getLatestScore, getAchievements, getMonthlySavings } from "../scoring/i
 import { generateAlerts } from "../alerts/index.js";
 import { runDailySync } from "../daily-sync.js";
 import { startLinkServer } from "../server.js";
-import { heading, progressBar, formatMoney, formatMoneyColored, dim } from "./format.js";
+import { heading, progressBar, formatMoney, formatMoneyColored, dim, formatDuration, formatError } from "./format.js";
 export async function runSync() {
     const ora = (await import("ora")).default;
     const spinner = ora("Syncing transactions...").start();
+    const startTime = Date.now();
     try {
         const db = getDb();
-        await runDailySync(db);
-        spinner.succeed("Sync complete.");
+        const result = await runDailySync(db);
+        const elapsed = formatDuration(Date.now() - startTime);
+        const parts = [elapsed];
+        if (result.transactionsAdded > 0)
+            parts.push(`${result.transactionsAdded} new transactions`);
+        spinner.succeed(`Sync complete. ${chalk.dim(`(${parts.join(", ")})`)}`);
     }
     catch (err) {
-        spinner.fail(`Sync failed: ${err.message}`);
+        spinner.fail(formatError(err, "Sync failed"));
     }
 }
 export async function runLink() {

package/dist/cli/format.d.ts

@@ -1,3 +1,18 @@
+export declare const colors: {
+    money: {
+        positive: (t: string) => string;
+        negative: (t: string) => string;
+    };
+    accent: (t: string) => string;
+    muted: (t: string) => string;
+    error: (t: string) => string;
+    success: (t: string) => string;
+    warning: (t: string) => string;
+    info: (t: string) => string;
+};
+export declare function formatDuration(ms: number): string;
+export declare function formatCount(n: number): string;
+export declare function formatError(error: any, context?: string): string;
 export declare function formatMoney(n: number): string;
 export declare function formatMoneyColored(n: number, invert?: boolean): string;
 export declare function progressBar(pct: number, width?: number): string;

package/dist/cli/format.js

@@ -1,4 +1,61 @@
 import chalk from "chalk";
+// ─── Color Palette ─── //
+export const colors = {
+    money: {
+        positive: (t) => chalk.green(t),
+        negative: (t) => chalk.red(t),
+    },
+    accent: (t) => chalk.cyan(t),
+    muted: (t) => chalk.dim(t),
+    error: (t) => chalk.red(t),
+    success: (t) => chalk.green(t),
+    warning: (t) => chalk.yellow(t),
+    info: (t) => chalk.blue(t),
+};
+// ─── Number & Duration Formatting ─── //
+export function formatDuration(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 1)
+        return "< 1s";
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    if (m < 60)
+        return rem > 0 ? `${m}m ${rem}s` : `${m}m`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+export function formatCount(n) {
+    return n.toLocaleString();
+}
+// ─── Error Display ─── //
+const ERROR_MAP = {
+    "401": { msg: "Invalid API key.", action: "Run `ray setup` to reconfigure your credentials." },
+    "403": { msg: "API key rejected.", action: "Run `ray billing` to check status, or `ray setup` to reconfigure." },
+    "429": { msg: "Rate limited.", action: "Wait a moment and try again." },
+    network: { msg: "Could not reach the server.", action: "Check your internet connection." },
+    plaid: { msg: "Bank connection issue.", action: "Run `ray link` to reconnect." },
+    decrypt: { msg: "Could not decrypt your data.", action: "Check your encryption key in `ray setup`." },
+};
+export function formatError(error, context) {
+    let key = "unknown";
+    if (error.status)
+        key = String(error.status);
+    else if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT")
+        key = "network";
+    else if (error.message?.includes("Plaid") || error.message?.includes("plaid"))
+        key = "plaid";
+    else if (error.message?.includes("decrypt"))
+        key = "decrypt";
+    const mapped = ERROR_MAP[key];
+    if (mapped) {
+        return `${chalk.red("✗")} ${mapped.msg} ${chalk.dim(mapped.action)}`;
+    }
+    const safeMsg = error.message || "Something went wrong.";
+    return `${chalk.red("✗")} ${context ? context + ": " : ""}${safeMsg}`;
+}
+// ─── Money Formatting ─── //
 export function formatMoney(n) {
     const abs = Math.abs(n);
     const formatted = "$" + abs.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });

package/dist/cli/setup.js

@@ -3,6 +3,9 @@ import { existsSync, mkdirSync } from "fs";
 import { dirname } from "path";
 import { config, saveConfig, isConfigured, RAY_PROXY_BASE } from "../config.js";
 import { heading, dim } from "./format.js";
+function stepHeader(current, total) {
+    return chalk.dim(`Step ${current}/${total}`);
+}
 export async function runSetup() {
     const inquirer = (await import("inquirer")).default;
     console.log(`\n${heading("Ray Finance Setup")}\n`);
@@ -27,12 +30,14 @@ export async function runSetup() {
         }]);
     let canLink = false;
     if (setupMode === "managed") {
+        console.log(stepHeader(1, 3));
         const { userName } = await inquirer.prompt([{
                 type: "input",
                 name: "userName",
                 message: "Your name:",
                 default: config.userName !== "User" ? config.userName : undefined,
             }]);
+        console.log(stepHeader(2, 3));
         const { hasKey } = await inquirer.prompt([{
                 type: "list",
                 name: "hasKey",
@@ -88,6 +93,7 @@ export async function runSetup() {
         canLink = true;
     }
     else {
+        console.log(stepHeader(1, 4));
         const answers = await inquirer.prompt([
             {
                 type: "input",
@@ -157,18 +163,47 @@ export async function runSetup() {
     const { createContextTemplate } = await import("../ai/context.js");
     createContextTemplate(config.userName);
     console.log(`\n${chalk.green("✓")} Config saved`);
-    // Link first account immediately — this is the critical path
+    console.log(`${chalk.green("✓")} Database initialized`);
+    console.log(`${chalk.green("✓")} Ready to go\n`);
+    // Ask to link first account
     if (canLink) {
-        console.log();
-        const { runLink } = await import("./commands.js");
-        await runLink();
-        // Auto-schedule daily sync at 6am after first successful link
-        if (!config.syncSchedule) {
-            saveConfig({ syncSchedule: "06:00" });
-            const { installSyncSchedule } = await import("./scheduler.js");
-            installSyncSchedule("06:00");
-            console.log(`${chalk.green("✓")} Daily sync scheduled at 6:00 AM`);
+        console.log(stepHeader(setupMode === "managed" ? 3 : 4, setupMode === "managed" ? 3 : 4));
+        const { wantLink } = await inquirer.prompt([{
+                type: "confirm",
+                name: "wantLink",
+                message: "Link your first bank account now?",
+                default: true,
+            }]);
+        if (wantLink) {
+            const { runLink } = await import("./commands.js");
+            await runLink();
+            // Sync immediately after linking
+            const ora = (await import("ora")).default;
+            const spinner = ora("Syncing your transactions...").start();
+            try {
+                const { getDb } = await import("../db/connection.js");
+                const { runDailySync } = await import("../daily-sync.js");
+                await runDailySync(getDb());
+                spinner.succeed("Transactions synced!");
+                console.log(chalk.dim("  Note: some banks take a few hours to deliver all transactions."));
+                console.log(chalk.dim("  Ray will re-sync in the background to pick up anything missing.\n"));
+            }
+            catch (err) {
+                spinner.fail(`Sync failed: ${err.message}`);
+            }
+            // Auto-schedule daily sync at 6am
+            if (!config.syncSchedule) {
+                saveConfig({ syncSchedule: "06:00" });
+                const { installSyncSchedule } = await import("./scheduler.js");
+                installSyncSchedule("06:00");
+                console.log(`${chalk.green("✓")} Daily sync scheduled at 6:00 AM`);
+            }
+            // Go straight into chat
+            console.log();
+            const { startChat } = await import("./chat.js");
+            await startChat();
+            return;
         }
     }
-    console.log(`\n${chalk.green("✓")} Setup complete! Run ${chalk.bold("ray")} to start chatting.\n`);
+    console.log(`Run ${chalk.bold("ray")} to start chatting.\n`);
 }

package/dist/daily-sync.d.ts

@@ -1,7 +1,11 @@
 import type BetterSqlite3 from "libsql";
 type Database = BetterSqlite3.Database;
+export interface SyncResult {
+    transactionsAdded: number;
+    institutionsSynced: number;
+}
 /** Run the daily sync for a single database */
-export declare function runDailySync(db: Database): Promise<void>;
+export declare function runDailySync(db: Database): Promise<SyncResult>;
 /** Run daily sync (cron / CLI entry point) */
 export declare function runDailySyncAll(): Promise<void>;
 export {};

package/dist/daily-sync.js

@@ -9,8 +9,10 @@ export async function runDailySync(db) {
         .all();
     if (institutions.length === 0) {
         console.log("No linked institutions.");
-        return;
+        return { transactionsAdded: 0, institutionsSynced: 0 };
     }
+    let totalAdded = 0;
+    let instSynced = 0;
     for (const inst of institutions) {
         if (inst.access_token === "manual") {
             console.log(`Skipping ${inst.name} (manual entry)`);
@@ -32,12 +34,14 @@ export async function runDailySync(db) {
         const products = JSON.parse(inst.products);
         console.log(`Syncing: ${inst.name} (${products.join(", ")})`);
         try {
+            instSynced++;
             // Always sync balances
             const accountCount = await syncBalances(db, accessToken);
             console.log(`  Accounts: ${accountCount}`);
             // Sync transactions if available
             if (products.includes("transactions")) {
                 const txResult = await syncTransactions(db, inst.item_id, accessToken, inst.cursor);
+                totalAdded += txResult.added;
                 console.log(`  Transactions: +${txResult.added} ~${txResult.modified} -${txResult.removed}`);
             }
             // Sync investments if available
@@ -100,6 +104,7 @@ export async function runDailySync(db) {
         console.log(`Auto-recategorized ${totalRecat} transaction(s).`);
     }
     console.log("Sync complete.");
+    return { transactionsAdded: totalAdded, institutionsSynced: instSynced };
 }
 /** Run daily sync (cron / CLI entry point) */
 export async function runDailySyncAll() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ray-finance",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local-first CLI that turns your bank data into a personal AI financial advisor",
   "type": "module",
   "license": "MIT",