plasalid 0.4.1 → 0.5.1

package/dist/ai/tools/merchants.js

@@ -0,0 +1,117 @@
+import { upsertMerchant, findMerchantByAlias, findMerchantById, setMerchantDefaultAccount, } from "../../db/queries/merchants.js";
+import { appendAction } from "../../db/queries/action_log.js";
+import { sanitizeForPrompt } from "../sanitize.js";
+/**
+ * Merchant tools
+ *
+ * Used by record-mode for utterances about merchants ("set Starbucks default
+ * to Dining") and by the scanner pipeline for pre-resolution lookups. The
+ * scan path normally resolves merchants inline via `record_transaction`'s
+ * embedded `merchant` block; these standalone tools exist for the cases where
+ * the LLM needs to query or update merchants without posting a transaction.
+ */
+const DEFS = [
+    {
+        name: "find_or_create_merchant",
+        description: "Upsert a merchant by canonical_name. Optionally register a raw-descriptor alias and a learned default expense account. Returns the merchant row. Use this in record mode for utterances like 'add Spotify as a subscription merchant' or 'mark Starbucks as Dining'.",
+        input_schema: {
+            type: "object",
+            properties: {
+                canonical_name: { type: "string", description: "Title-cased merchant name, e.g. 'Starbucks', 'Amazon'." },
+                alias: { type: "string", description: "Optional raw descriptor (as seen on a statement). Plasalid normalizes and dedups it." },
+                default_account_id: { type: "string", description: "Optional learned cache: the merchant's default expense account." },
+            },
+            required: ["canonical_name"],
+        },
+    },
+    {
+        name: "find_merchant_by_descriptor",
+        description: "Look up an existing merchant by its raw descriptor (alias match after normalization). Returns null if no alias matches.",
+        input_schema: {
+            type: "object",
+            properties: {
+                descriptor: { type: "string", description: "The raw statement line or merchant string to look up." },
+            },
+            required: ["descriptor"],
+        },
+    },
+    {
+        name: "set_merchant_default_account",
+        description: "Update a merchant's learned default expense account. Use after the user (or you) recategorizes a posting so future statements skip the LLM categorizer.",
+        input_schema: {
+            type: "object",
+            properties: {
+                merchant_id: { type: "string" },
+                account_id: { type: "string" },
+            },
+            required: ["merchant_id", "account_id"],
+        },
+    },
+];
+const LABELS = {
+    find_or_create_merchant: "Resolving merchant",
+    find_merchant_by_descriptor: "Looking up merchant",
+    set_merchant_default_account: "Updating merchant default",
+};
+async function execute(db, name, input, ctx) {
+    switch (name) {
+        case "find_or_create_merchant": {
+            if (ctx?.dryRun)
+                return `Would upsert merchant "${input.canonical_name}".`;
+            const existing = db
+                .prepare(`SELECT id FROM merchants WHERE canonical_name = ?`)
+                .get(input.canonical_name);
+            const merchant = upsertMerchant(db, {
+                canonical_name: input.canonical_name,
+                alias: input.alias,
+                default_account_id: input.default_account_id,
+            });
+            if (ctx?.correlationId && !existing) {
+                appendAction(db, {
+                    correlation_id: ctx.correlationId,
+                    command: ctx.command ?? "record",
+                    user_input: ctx.userInput ?? null,
+                    action_type: "create_merchant",
+                    target_id: merchant.id,
+                    payload: { canonical_name: merchant.canonical_name, default_account_id: merchant.default_account_id },
+                });
+            }
+            const defaultStr = merchant.default_account_id ? ` (default → ${merchant.default_account_id})` : "";
+            return `Merchant ${merchant.id}: ${sanitizeForPrompt(merchant.canonical_name)}${defaultStr}.`;
+        }
+        case "find_merchant_by_descriptor": {
+            const hit = findMerchantByAlias(db, String(input.descriptor ?? ""));
+            if (!hit)
+                return `No merchant matched descriptor "${sanitizeForPrompt(String(input.descriptor ?? ""))}".`;
+            const defaultStr = hit.default_account_id ? ` (default → ${hit.default_account_id})` : "";
+            return `Merchant ${hit.merchant.id}: ${sanitizeForPrompt(hit.merchant.canonical_name)}${defaultStr}.`;
+        }
+        case "set_merchant_default_account": {
+            if (ctx?.dryRun)
+                return `Would set ${input.merchant_id}'s default to ${input.account_id}.`;
+            const m = findMerchantById(db, input.merchant_id);
+            if (!m)
+                return `Merchant ${input.merchant_id} not found.`;
+            try {
+                const result = setMerchantDefaultAccount(db, input.merchant_id, input.account_id);
+                if (ctx?.correlationId) {
+                    appendAction(db, {
+                        correlation_id: ctx.correlationId,
+                        command: ctx.command ?? "record",
+                        user_input: ctx.userInput ?? null,
+                        action_type: "update_merchant_default",
+                        target_id: input.merchant_id,
+                        payload: { before: result.before, after: result.after },
+                    });
+                }
+                return `Merchant ${input.merchant_id}: default ${result.before ?? "(none)"} → ${result.after}.`;
+            }
+            catch (err) {
+                return `Could not set merchant default: ${err.message}`;
+            }
+        }
+        default:
+            return undefined;
+    }
+}
+export const merchantTools = { DEFS, LABELS, execute };

package/dist/ai/tools/read.js

@@ -1,12 +1,9 @@
 import { findAccountById, getAccountBalances, getNetWorth, getPeriodTotals, } from "../../db/queries/account_balance.js";
-import { listJournalLines } from "../../db/queries/journal.js";
+import { listPostings } from "../../db/queries/transactions.js";
 import { listOpenConcerns } from "../../db/queries/concerns.js";
-import { searchJournalLines } from "../../db/queries/search.js";
-import { formatCurrencyAmount } from "../../currency.js";
+import { searchPostings } from "../../db/queries/search.js";
+import { formatAmount } from "../../currency.js";
 import { sanitizeForPrompt, sanitizeForPromptCell } from "../sanitize.js";
-function formatTHB(amount) {
-    return formatCurrencyAmount(amount, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-}
 const DEFS = [
     {
         name: "get_account_balance",
@@ -23,15 +20,15 @@ const DEFS = [
         input_schema: { type: "object", properties: {}, required: [] },
     },
     {
-        name: "list_journal_entries",
-        description: "List journal lines filtered by account and/or date range.",
+        name: "list_postings",
+        description: "List transaction postings filtered by account and/or date range.",
         input_schema: {
             type: "object",
             properties: {
                 account_id: { type: "string" },
                 from: { type: "string", description: "Start date YYYY-MM-DD" },
                 to: { type: "string", description: "End date YYYY-MM-DD" },
-                q: { type: "string", description: "Free-text contains-match on description or memo" },
+                q: { type: "string", description: "Free-text contains-match on description, memo, or merchant" },
                 limit: { type: "number", description: "Max results (default 50)" },
             },
             required: [],
@@ -39,7 +36,7 @@ const DEFS = [
     },
     {
         name: "search_transactions",
-        description: "Free-text search across journal entry descriptions, line memos, and account names.",
+        description: "Free-text search across transaction descriptions, posting memos, account names, and merchant names.",
         input_schema: {
             type: "object",
             properties: {
@@ -63,11 +60,12 @@ const DEFS = [
     },
     {
         name: "list_open_concerns",
-        description: "List clarification requests recorded by the scanner that have not been resolved yet. Each row carries the prompt, optional candidate answers, and the file/entry/account it was attached to. The reviewer uses this to drive the step-by-step clarification loop.",
+        description: "List clarification requests recorded by the scanner that have not been resolved yet. Each row carries the prompt, optional candidate answers, and the file/transaction/account it was attached to. The reviewer uses this to drive the step-by-step clarification loop.",
         input_schema: {
             type: "object",
             properties: {
                 limit: { type: "number", default: 50 },
+                kind: { type: "string", description: "Optional filter by concern kind (e.g. 'uncategorized_expense')." },
             },
             required: [],
         },
@@ -76,7 +74,7 @@ const DEFS = [
 const LABELS = {
     get_account_balance: "Looking up balance",
     get_net_worth: "Computing net worth",
-    list_journal_entries: "Listing journal entries",
+    list_postings: "Listing postings",
     search_transactions: "Searching transactions",
     get_period_totals: "Summing period totals",
     list_open_concerns: "Listing open concerns",
@@ -89,14 +87,14 @@ async function execute(db, name, input, _ctx) {
                 return `Account "${input.account_id}" not found.`;
             const balances = getAccountBalances(db);
             const bal = balances.find(b => b.id === acct.id)?.balance ?? 0;
-            return `${sanitizeForPrompt(acct.name)} (${acct.type}): ${formatTHB(bal)}`;
+            return `${sanitizeForPrompt(acct.name)} (${acct.type}): ${formatAmount(bal)}`;
         }
         case "get_net_worth": {
             const nw = getNetWorth(db);
-            return `Net worth: ${formatTHB(nw.net_worth)} (assets ${formatTHB(nw.assets)} − liabilities ${formatTHB(nw.liabilities)})`;
+            return `Net worth: ${formatAmount(nw.net_worth)} (assets ${formatAmount(nw.assets)} − liabilities ${formatAmount(nw.liabilities)})`;
         }
-        case "list_journal_entries": {
-            const rows = listJournalLines(db, {
+        case "list_postings": {
+            const rows = listPostings(db, {
                 account_id: input.account_id,
                 from: input.from,
                 to: input.to,
@@ -104,41 +102,45 @@ async function execute(db, name, input, _ctx) {
                 limit: input.limit,
             });
             if (rows.length === 0)
-                return "No matching journal lines.";
+                return "No matching postings.";
             return rows
                 .map(r => {
-                const dr = r.debit > 0 ? `DR ${formatTHB(r.debit)}` : "";
-                const cr = r.credit > 0 ? `CR ${formatTHB(r.credit)}` : "";
-                return `${r.entry_date} | ${sanitizeForPromptCell(r.entry_description)} | ${sanitizeForPromptCell(r.account_name || "")} | ${dr}${cr} | ${sanitizeForPromptCell(r.memo || "")}`;
+                const dr = r.debit > 0 ? `DR ${formatAmount(r.debit)}` : "";
+                const cr = r.credit > 0 ? `CR ${formatAmount(r.credit)}` : "";
+                const merchant = r.merchant_name ? ` (${sanitizeForPromptCell(r.merchant_name)})` : "";
+                return `${r.transaction_date} | ${sanitizeForPromptCell(r.transaction_description || "")}${merchant} | ${sanitizeForPromptCell(r.account_name || "")} | ${dr}${cr} | ${sanitizeForPromptCell(r.memo || "")}`;
             })
                 .join("\n");
         }
         case "search_transactions": {
-            const rows = searchJournalLines(db, input.query, input.limit);
+            const rows = searchPostings(db, input.query, input.limit);
             if (rows.length === 0)
                 return `No matches for "${sanitizeForPrompt(input.query)}".`;
             return rows
                 .map(r => {
-                const dr = r.debit > 0 ? `DR ${formatTHB(r.debit)}` : "";
-                const cr = r.credit > 0 ? `CR ${formatTHB(r.credit)}` : "";
-                return `${r.entry_date} | ${sanitizeForPromptCell(r.entry_description)} | ${sanitizeForPromptCell(r.account_name || "")} | ${dr}${cr}`;
+                const dr = r.debit > 0 ? `DR ${formatAmount(r.debit)}` : "";
+                const cr = r.credit > 0 ? `CR ${formatAmount(r.credit)}` : "";
+                const merchant = r.merchant_name ? ` (${sanitizeForPromptCell(r.merchant_name)})` : "";
+                return `${r.transaction_date} | ${sanitizeForPromptCell(r.transaction_description || "")}${merchant} | ${sanitizeForPromptCell(r.account_name || "")} | ${dr}${cr}`;
             })
                 .join("\n");
         }
         case "get_period_totals": {
             const totals = getPeriodTotals(db, input.from, input.to);
-            return `Income ${formatTHB(totals.income)} · Expenses ${formatTHB(totals.expenses)} · Net ${formatTHB(totals.income - totals.expenses)}`;
+            return `Income ${formatAmount(totals.income)} · Expenses ${formatAmount(totals.expenses)} · Net ${formatAmount(totals.income - totals.expenses)}`;
         }
         case "list_open_concerns": {
             const rows = listOpenConcerns(db, input.limit ?? 50);
-            if (rows.length === 0)
+            const filtered = input.kind ? rows.filter(r => r.kind === input.kind) : rows;
+            if (filtered.length === 0)
                 return "No open concerns. The picture is clear.";
-            return rows
+            return filtered
                 .map(r => {
                 const targets = [
-                    r.entry_id ? `entry=${r.entry_id}` : null,
+                    r.transaction_id ? `transaction=${r.transaction_id}` : null,
                     r.account_id ? `account=${r.account_id}` : null,
-                    !r.entry_id && !r.account_id && r.file_id ? `file=${r.file_id}` : null,
+                    !r.transaction_id && !r.account_id && r.file_id ? `file=${r.file_id}` : null,
+                    r.kind ? `kind=${r.kind}` : null,
                 ].filter(Boolean).join(" ");
                 const options = r.options_json
                     ? ` [options: ${JSON.parse(r.options_json).map(o => sanitizeForPrompt(o)).join(" | ")}]`

package/dist/ai/tools/record.d.ts

@@ -0,0 +1,2 @@
+import type { ToolModule } from "./types.js";
+export declare const recordTools: ToolModule;

package/dist/ai/tools/record.js

@@ -0,0 +1,188 @@
+import { findAccountById, findAccountsByFuzzyName, getAccountBalances, ensureStructuralAccount, } from "../../db/queries/account_balance.js";
+import { validateTransaction, insertTransactionRows, } from "../../db/queries/transactions.js";
+import { appendAction } from "../../db/queries/action_log.js";
+import { formatAmount } from "../../currency.js";
+import { sanitizeForPrompt } from "../sanitize.js";
+const EQUITY_ADJUST_ID = "equity:adjustments";
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Record-only tool definitions
+ *
+ * `find_similar_accounts` and `clarify` are reads / prompts; only
+ * `adjust_account_balance` mutates the DB. It writes its own action_log row
+ * with `action_type='adjust_balance'` rather than going through the shared
+ * `record_transaction` path.
+ */
+const DEFS = [
+    {
+        name: "find_similar_accounts",
+        description: "Find existing accounts whose name fuzzy-matches a candidate. Always call this before create_account when the user names an account (e.g. 'my ttb saving', 'SET portfolio') so you don't create a duplicate. Returns the top matches with similarity scores; if the highest score is >= 0.7 and it isn't an exact id hit, call clarify to confirm with the user before creating a new one.",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Free-text name to match against the chart of accounts." },
+                threshold: { type: "number", description: "Minimum similarity (0-1). Default 0.5.", default: 0.5 },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "adjust_account_balance",
+        description: "Move an account's current balance to `target_balance` by posting a balancing transaction against the equity:adjustments account. Use this when the user states a balance ('my SET portfolio is now 1.8MB', '500k networth in my Diem Investment') rather than a transaction. Reads the account's current balance, computes the delta, posts a 2-posting transaction with the right debit/credit sides for the account type, and creates equity:adjustments on demand if it doesn't exist. Currency follows the account.",
+        input_schema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string" },
+                target_balance: { type: "number", description: "The new desired balance in the account's currency, in natural sign (positive)." },
+                reason: { type: "string", description: "Short description, e.g. 'Set DIEM portfolio to current market value (user-asserted).'." },
+                date: { type: "string", description: "ISO YYYY-MM-DD. Defaults to today." },
+            },
+            required: ["account_id", "target_balance", "reason"],
+        },
+    },
+    {
+        name: "clarify",
+        description: "Ask the user a clarifying question and return their answer as a string. Use when the utterance is ambiguous (multiple matching accounts, missing amount, unclear date, can't tell expense vs transfer, plan confirmation before a multi-step action). Unlike review's ask_user, this does NOT write to the concerns table — record-time questions are transient.",
+        input_schema: {
+            type: "object",
+            properties: {
+                prompt: { type: "string", description: "The question to ask in plain language." },
+                options: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional list of candidate answers.",
+                },
+                facts: {
+                    type: "object",
+                    description: "Optional structured highlights rendered as a single colored header line above the question. amount=yellow, date=cyan, merchant=green, accounts=magenta.",
+                    properties: {
+                        amount: { type: "string" },
+                        date: { type: "string" },
+                        merchant: { type: "string" },
+                        accounts: { type: "array", items: { type: "string" } },
+                    },
+                },
+            },
+            required: ["prompt"],
+        },
+    },
+];
+const LABELS = {
+    find_similar_accounts: "Searching similar accounts",
+    adjust_account_balance: "Adjusting balance",
+    clarify: "Asking for clarification",
+};
+async function execute(db, name, input, ctx) {
+    switch (name) {
+        case "find_similar_accounts": {
+            const matches = findAccountsByFuzzyName(db, String(input.query ?? ""), input.threshold);
+            if (matches.length === 0)
+                return `No accounts matched "${sanitizeForPrompt(input.query ?? "")}".`;
+            return matches
+                .slice(0, 8)
+                .map(m => `${m.account.id} | ${sanitizeForPrompt(m.account.name)} | ${m.account.type}${m.account.subtype ? `/${m.account.subtype}` : ""} | similarity ${m.similarity}`)
+                .join("\n");
+        }
+        case "adjust_account_balance":
+            return adjustAccountBalance(db, input, ctx);
+        case "clarify": {
+            if (!ctx)
+                return "clarify is only available inside an agent session.";
+            if (!ctx.interactive || !ctx.promptUser) {
+                return `Awaiting user input — cannot proceed in non-interactive mode. Question was: ${sanitizeForPrompt(input.prompt)}`;
+            }
+            const answer = await ctx.promptUser(input.prompt, input.options, input.facts);
+            return `User answered: ${sanitizeForPrompt(answer)}`;
+        }
+        default:
+            return undefined;
+    }
+}
+async function adjustAccountBalance(db, input, ctx) {
+    if (!ctx)
+        return "adjust_account_balance is only available inside an agent session.";
+    if (ctx.dryRun)
+        return `Would adjust ${input.account_id} balance to ${input.target_balance}.`;
+    const account = findAccountById(db, input.account_id);
+    if (!account)
+        return `Account "${input.account_id}" not found.`;
+    const target = Number(input.target_balance);
+    if (!Number.isFinite(target))
+        return `target_balance must be a number, got ${JSON.stringify(input.target_balance)}.`;
+    const balances = getAccountBalances(db);
+    const current = balances.find(b => b.id === account.id)?.balance ?? 0;
+    const delta = round2(target - current);
+    if (delta === 0) {
+        return `${sanitizeForPrompt(account.name)} is already at ${formatAmount(target)}; no transaction posted.`;
+    }
+    const amount = Math.abs(delta);
+    const debitNormal = account.type === "asset" || account.type === "expense";
+    const debitAccountId = (debitNormal && delta > 0) || (!debitNormal && delta < 0)
+        ? account.id
+        : EQUITY_ADJUST_ID;
+    const creditAccountId = debitAccountId === account.id ? EQUITY_ADJUST_ID : account.id;
+    const date = input.date && /^\d{4}-\d{2}-\d{2}$/.test(input.date) ? input.date : todayIso();
+    const reason = String(input.reason || "Balance adjustment").trim();
+    const currency = account.currency || "THB";
+    const txInput = {
+        date,
+        description: reason,
+        postings: [
+            { account_id: debitAccountId, debit: amount, currency },
+            { account_id: creditAccountId, credit: amount, currency },
+        ],
+    };
+    let validated;
+    try {
+        validated = validateTransaction(txInput);
+    }
+    catch (err) {
+        return `Could not build adjustment transaction: ${err.message}`;
+    }
+    try {
+        const tx = db.transaction(() => {
+            const equityExisted = !!findAccountById(db, EQUITY_ADJUST_ID);
+            if (!equityExisted) {
+                ensureStructuralAccount(db, "equity:adjustments");
+                if (ctx.correlationId) {
+                    appendAction(db, {
+                        correlation_id: ctx.correlationId,
+                        command: ctx.command ?? "record",
+                        user_input: ctx.userInput ?? null,
+                        action_type: "create_account",
+                        target_id: EQUITY_ADJUST_ID,
+                        payload: { row: findAccountById(db, EQUITY_ADJUST_ID) },
+                    });
+                }
+            }
+            insertTransactionRows(db, validated);
+            if (ctx.correlationId) {
+                appendAction(db, {
+                    correlation_id: ctx.correlationId,
+                    command: ctx.command ?? "record",
+                    user_input: ctx.userInput ?? null,
+                    action_type: "adjust_balance",
+                    target_id: validated.id,
+                    payload: {
+                        account_id: account.id,
+                        before_balance: current,
+                        after_balance: target,
+                        transaction: { date: validated.date, description: validated.description },
+                        postings: validated.postings,
+                    },
+                });
+            }
+        });
+        tx();
+    }
+    catch (err) {
+        return `Could not post adjustment transaction: ${err.message}`;
+    }
+    return `Adjusted ${sanitizeForPrompt(account.name)}: ${formatAmount(current)} → ${formatAmount(target)} (Δ ${delta > 0 ? "+" : ""}${formatAmount(delta)}). Transaction ${validated.id}.`;
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+export const recordTools = { DEFS, LABELS, execute };