plasalid 0.2.0

package/dist/ai/tools/ingest.js

@@ -0,0 +1,202 @@
+import { randomUUID } from "crypto";
+import { findAccountById } from "../../db/queries/account_balance.js";
+import { recordJournalEntry } from "../../db/queries/journal.js";
+import { sanitizeForPrompt } from "../sanitize.js";
+import { ALL_THAI_INSTITUTIONS, ACCOUNT_TYPE_DESCRIPTIONS, } from "../../accounts/taxonomy.js";
+const ACCOUNT_TYPES = Object.keys(ACCOUNT_TYPE_DESCRIPTIONS);
+const DEFS = [
+    {
+        name: "create_account",
+        description: "Create a new account in the chart of accounts when a statement reveals one that doesn't exist yet. Use a stable id like 'asset:kbank-savings-1234'.",
+        input_schema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Stable identifier, lowercase, colon-separated. e.g. 'asset:kbank-savings-1234'." },
+                name: { type: "string", description: "Human-readable name. e.g. 'KBank Savings ••1234'." },
+                type: { type: "string", enum: ACCOUNT_TYPES, description: "Account type." },
+                subtype: { type: "string", description: "e.g. 'bank', 'credit_card', 'salary', 'food'." },
+                bank_name: { type: "string", description: "Thai institution code from the taxonomy (e.g. KBANK, SCB, KTC)." },
+                account_number_masked: { type: "string", description: "Last 4 digits only, e.g. '••1234'." },
+                currency: { type: "string", description: "ISO 4217 code. Defaults to 'THB'.", default: "THB" },
+                due_day: { type: "number", description: "Credit-card due day of month (liabilities only)." },
+                statement_day: { type: "number", description: "Statement-cut day of month." },
+                metadata: { type: "object", description: "Free-form extra fields (e.g. {points_program: 'KTC Forever'})." },
+            },
+            required: ["id", "name", "type"],
+        },
+    },
+    {
+        name: "update_account_metadata",
+        description: "Update account metadata (due day, statement day, points balance, masked number, bank).",
+        input_schema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string" },
+                due_day: { type: "number" },
+                statement_day: { type: "number" },
+                points_balance: { type: "number" },
+                account_number_masked: { type: "string" },
+                bank_name: { type: "string" },
+                metadata: { type: "object", description: "Merged into existing metadata_json." },
+            },
+            required: ["account_id"],
+        },
+    },
+    {
+        name: "record_journal_entry",
+        description: "Post a balanced double-entry journal entry. The sum of debits MUST equal the sum of credits (within one currency). Convert Buddhist-Era dates by subtracting 543. Every line carries an ISO 4217 currency code (THB, USD, EUR, …); default to THB. Use the account's currency where set; only deviate when the source row is explicitly in another currency.",
+        input_schema: {
+            type: "object",
+            properties: {
+                date: { type: "string", description: "ISO Gregorian date (YYYY-MM-DD)." },
+                description: { type: "string", description: "Short human-readable description of the entry." },
+                source_page: { type: "number", description: "Page number in the source PDF, if known." },
+                lines: {
+                    type: "array",
+                    description: "Two or more journal lines that balance.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            account_id: { type: "string", description: "Existing account id from list_accounts or create_account." },
+                            debit: { type: "number", description: "Debit amount in this line's currency. Use 0 if this line is a credit." },
+                            credit: { type: "number", description: "Credit amount in this line's currency. Use 0 if this line is a debit." },
+                            currency: { type: "string", description: "ISO 4217 currency code for this line (e.g. THB, USD, EUR). Defaults to THB.", default: "THB" },
+                            memo: { type: "string", description: "Optional per-line memo." },
+                        },
+                        required: ["account_id"],
+                    },
+                },
+            },
+            required: ["date", "description", "lines"],
+        },
+    },
+    {
+        name: "ask_user",
+        description: "Ask the user a clarifying question when you cannot confidently proceed. The pipeline pauses and prompts the user interactively when running `plasalid scan` or `plasalid reconcile`.",
+        input_schema: {
+            type: "object",
+            properties: {
+                prompt: { type: "string", description: "The question to ask in plain language." },
+                options: {
+                    type: "array",
+                    description: "Optional list of candidate answers.",
+                    items: { type: "string" },
+                },
+            },
+            required: ["prompt"],
+        },
+    },
+];
+const LABELS = {
+    create_account: "Creating account",
+    update_account_metadata: "Updating account metadata",
+    record_journal_entry: "Posting journal entry",
+    ask_user: "Asking for clarification",
+};
+async function execute(db, name, input, ctx) {
+    switch (name) {
+        case "create_account": {
+            if (ctx?.dryRun)
+                return `Would create account ${input.id}.`;
+            if (!ACCOUNT_TYPES.includes(input.type)) {
+                return `Invalid type "${input.type}". Allowed: ${ACCOUNT_TYPES.join(", ")}.`;
+            }
+            const knownCodes = new Set(ALL_THAI_INSTITUTIONS.map(i => i.code));
+            const bank = input.bank_name ? String(input.bank_name).toUpperCase() : null;
+            if (bank && !knownCodes.has(bank)) {
+                // Allow unknown institutions; taxonomy is a hint, not a hard list.
+            }
+            try {
+                db.prepare(`INSERT INTO accounts (id, name, type, subtype, bank_name, account_number_masked, currency, due_day, statement_day, metadata_json)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.name, input.type, input.subtype || null, bank, input.account_number_masked || null, input.currency || "THB", input.due_day ?? null, input.statement_day ?? null, input.metadata ? JSON.stringify(input.metadata) : null);
+                return `Account created: ${input.id} (${input.name}, ${input.type}).`;
+            }
+            catch (err) {
+                if (String(err.message).includes("UNIQUE")) {
+                    return `Account "${input.id}" already exists. Use update_account_metadata to modify it.`;
+                }
+                throw err;
+            }
+        }
+        case "update_account_metadata": {
+            if (ctx?.dryRun)
+                return `Would update metadata for ${input.account_id}: ${JSON.stringify(input)}`;
+            const acct = findAccountById(db, input.account_id);
+            if (!acct)
+                return `Account "${input.account_id}" not found.`;
+            const updates = [];
+            const params = [];
+            if (input.due_day !== undefined) {
+                updates.push("due_day = ?");
+                params.push(input.due_day);
+            }
+            if (input.statement_day !== undefined) {
+                updates.push("statement_day = ?");
+                params.push(input.statement_day);
+            }
+            if (input.points_balance !== undefined) {
+                updates.push("points_balance = ?");
+                params.push(input.points_balance);
+            }
+            if (input.account_number_masked !== undefined) {
+                updates.push("account_number_masked = ?");
+                params.push(input.account_number_masked);
+            }
+            if (input.bank_name !== undefined) {
+                updates.push("bank_name = ?");
+                params.push(String(input.bank_name).toUpperCase());
+            }
+            if (input.metadata) {
+                const existing = acct.metadata_json ? JSON.parse(acct.metadata_json) : {};
+                const merged = { ...existing, ...input.metadata };
+                updates.push("metadata_json = ?");
+                params.push(JSON.stringify(merged));
+            }
+            if (updates.length === 0)
+                return "Nothing to update.";
+            params.push(input.account_id);
+            db.prepare(`UPDATE accounts SET ${updates.join(", ")} WHERE id = ?`).run(...params);
+            return `Updated ${input.account_id}.`;
+        }
+        case "record_journal_entry": {
+            if (!ctx)
+                return "record_journal_entry is only available inside an agent session.";
+            if (ctx.dryRun)
+                return `Would post journal entry "${input.description}" on ${input.date}.`;
+            try {
+                const entryId = recordJournalEntry(db, {
+                    date: input.date,
+                    description: input.description,
+                    source_file_id: ctx.fileId,
+                    source_page: input.source_page ?? null,
+                    lines: (input.lines || []).map((l) => ({
+                        account_id: l.account_id,
+                        debit: l.debit ?? 0,
+                        credit: l.credit ?? 0,
+                        currency: l.currency || "THB",
+                        memo: l.memo ?? null,
+                    })),
+                });
+                return `Posted journal entry ${entryId} (${input.date}).`;
+            }
+            catch (err) {
+                return `Could not post journal entry: ${err.message}`;
+            }
+        }
+        case "ask_user": {
+            if (!ctx)
+                return "ask_user is only available inside an agent session.";
+            const id = `pq:${randomUUID()}`;
+            db.prepare(`INSERT INTO pending_questions (id, file_id, prompt, options_json) VALUES (?, ?, ?, ?)`).run(id, ctx.fileId ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null);
+            if (ctx.interactive && ctx.promptUser) {
+                const answer = await ctx.promptUser(input.prompt, input.options);
+                db.prepare(`UPDATE pending_questions SET answer = ?, resolved_at = datetime('now') WHERE id = ?`).run(answer, id);
+                return `User answered: ${sanitizeForPrompt(answer)}`;
+            }
+            return `Question recorded for later (${id}). Awaiting user input — do not act on assumptions about this answer.`;
+        }
+        default:
+            return undefined;
+    }
+}
+export const ingestTools = { DEFS, LABELS, execute };

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

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

package/dist/ai/tools/read.js

@@ -0,0 +1,123 @@
+import { findAccountById, getAccountBalances, getNetWorth, getPeriodTotals, } from "../../db/queries/account_balance.js";
+import { listJournalLines } from "../../db/queries/journal.js";
+import { searchJournalLines } from "../../db/queries/search.js";
+import { formatCurrencyAmount } 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",
+        description: "Get balance for a single account by id.",
+        input_schema: {
+            type: "object",
+            properties: { account_id: { type: "string" } },
+            required: ["account_id"],
+        },
+    },
+    {
+        name: "get_net_worth",
+        description: "Compute current net worth: total assets minus total liabilities.",
+        input_schema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "list_journal_entries",
+        description: "List journal lines 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" },
+                limit: { type: "number", description: "Max results (default 50)" },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "search_transactions",
+        description: "Free-text search across journal entry descriptions, line memos, and account names.",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string" },
+                limit: { type: "number", default: 30 },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "get_period_totals",
+        description: "Get total income and total expense in a date range. Useful for monthly summaries.",
+        input_schema: {
+            type: "object",
+            properties: {
+                from: { type: "string", description: "Start date YYYY-MM-DD" },
+                to: { type: "string", description: "End date YYYY-MM-DD" },
+            },
+            required: ["from", "to"],
+        },
+    },
+];
+const LABELS = {
+    get_account_balance: "Looking up balance",
+    get_net_worth: "Computing net worth",
+    list_journal_entries: "Listing journal entries",
+    search_transactions: "Searching transactions",
+    get_period_totals: "Summing period totals",
+};
+async function execute(db, name, input, _ctx) {
+    switch (name) {
+        case "get_account_balance": {
+            const acct = findAccountById(db, input.account_id);
+            if (!acct)
+                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)}`;
+        }
+        case "get_net_worth": {
+            const nw = getNetWorth(db);
+            return `Net worth: ${formatTHB(nw.net_worth)} (assets ${formatTHB(nw.assets)} − liabilities ${formatTHB(nw.liabilities)})`;
+        }
+        case "list_journal_entries": {
+            const rows = listJournalLines(db, {
+                account_id: input.account_id,
+                from: input.from,
+                to: input.to,
+                q: input.q,
+                limit: input.limit,
+            });
+            if (rows.length === 0)
+                return "No matching journal lines.";
+            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 || "")}`;
+            })
+                .join("\n");
+        }
+        case "search_transactions": {
+            const rows = searchJournalLines(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}`;
+            })
+                .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)}`;
+        }
+        default:
+            return undefined;
+    }
+}
+export const readTools = { DEFS, LABELS, execute };

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

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

package/dist/ai/tools/reconcile.js

@@ -0,0 +1,227 @@
+import { deleteAccount, findSimilarAccounts, findUnusedAccounts, mergeAccounts, renameAccount, } from "../../db/queries/account_balance.js";
+import { deleteJournalEntry, findDuplicateEntries, updateJournalEntry, updateJournalLine, } from "../../db/queries/journal.js";
+import { formatCurrencyAmount } from "../../currency.js";
+import { sanitizeForPrompt } from "../sanitize.js";
+function formatTHB(amount) {
+    return formatCurrencyAmount(amount, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+const DEFS = [
+    {
+        name: "update_journal_entry",
+        description: "Header-only update: date, description, or source_page. To change amounts, delete the entry and record a new one.",
+        input_schema: {
+            type: "object",
+            properties: {
+                entry_id: { type: "string" },
+                date: { type: "string" },
+                description: { type: "string" },
+                source_page: { type: "number" },
+            },
+            required: ["entry_id"],
+        },
+    },
+    {
+        name: "update_journal_line",
+        description: "Safe single-line edit: re-categorize (account_id) or update memo. Refuses changes to debit/credit/currency — delete and re-record the entry for those.",
+        input_schema: {
+            type: "object",
+            properties: {
+                line_id: { type: "string" },
+                account_id: { type: "string" },
+                memo: { type: "string" },
+            },
+            required: ["line_id"],
+        },
+    },
+    {
+        name: "delete_journal_entry",
+        description: "Delete an entry and (via cascade) all its lines. The primitive for removing duplicates.",
+        input_schema: {
+            type: "object",
+            properties: { entry_id: { type: "string" } },
+            required: ["entry_id"],
+        },
+    },
+    {
+        name: "rename_account",
+        description: "Rename an account. Leaves lines and metadata untouched.",
+        input_schema: {
+            type: "object",
+            properties: { account_id: { type: "string" }, name: { type: "string" } },
+            required: ["account_id", "name"],
+        },
+    },
+    {
+        name: "merge_accounts",
+        description: "Move every journal line on `from_id` over to `to_id`, then delete the source account. Use to collapse duplicate accounts.",
+        input_schema: {
+            type: "object",
+            properties: { from_id: { type: "string" }, to_id: { type: "string" } },
+            required: ["from_id", "to_id"],
+        },
+    },
+    {
+        name: "delete_account",
+        description: "Delete an account that has no journal lines. Refuses if any line still references it — merge first.",
+        input_schema: {
+            type: "object",
+            properties: { account_id: { type: "string" } },
+            required: ["account_id"],
+        },
+    },
+    {
+        name: "find_duplicate_entries",
+        description: "Heuristic: groups journal entries by total amount and a configurable date tolerance. Returns groups with two or more candidate dupes.",
+        input_schema: {
+            type: "object",
+            properties: {
+                tolerance_days: { type: "number", default: 2 },
+                account_id: { type: "string" },
+                min_amount: { type: "number" },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "find_similar_accounts",
+        description: "Pairwise Levenshtein similarity on account names. Returns pairs above the threshold, sorted highest first.",
+        input_schema: {
+            type: "object",
+            properties: { threshold: { type: "number", default: 0.85 } },
+            required: [],
+        },
+    },
+    {
+        name: "find_unused_accounts",
+        description: "Accounts with zero linked journal lines.",
+        input_schema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "mark_reconcile_done",
+        description: "Call when reconciliation is complete. The summary is shown to the user.",
+        input_schema: {
+            type: "object",
+            properties: { summary: { type: "string" } },
+            required: ["summary"],
+        },
+    },
+];
+const LABELS = {
+    update_journal_entry: "Updating journal entry",
+    update_journal_line: "Updating journal line",
+    delete_journal_entry: "Deleting journal entry",
+    rename_account: "Renaming account",
+    merge_accounts: "Merging accounts",
+    delete_account: "Deleting account",
+    find_duplicate_entries: "Finding duplicate entries",
+    find_similar_accounts: "Finding similar accounts",
+    find_unused_accounts: "Finding unused accounts",
+    mark_reconcile_done: "Finalizing reconcile",
+};
+async function execute(db, name, input, ctx) {
+    switch (name) {
+        case "update_journal_entry": {
+            if (ctx?.dryRun)
+                return `Would update entry ${input.entry_id}: ${JSON.stringify(input)}`;
+            const changed = updateJournalEntry(db, input.entry_id, {
+                date: input.date,
+                description: input.description,
+                source_page: input.source_page,
+            });
+            return changed === 0
+                ? `Entry ${input.entry_id} not found or no fields to update.`
+                : `Updated entry ${input.entry_id}.`;
+        }
+        case "update_journal_line": {
+            if (ctx?.dryRun)
+                return `Would update line ${input.line_id}: ${JSON.stringify(input)}`;
+            const changed = updateJournalLine(db, input.line_id, {
+                account_id: input.account_id,
+                memo: input.memo,
+            });
+            return changed === 0
+                ? `Line ${input.line_id} not found or no fields to update.`
+                : `Updated line ${input.line_id}.`;
+        }
+        case "delete_journal_entry": {
+            if (ctx?.dryRun)
+                return `Would delete entry ${input.entry_id} (and its lines).`;
+            const changed = deleteJournalEntry(db, input.entry_id);
+            return changed === 0
+                ? `Entry ${input.entry_id} not found.`
+                : `Deleted entry ${input.entry_id} and its lines.`;
+        }
+        case "rename_account": {
+            if (ctx?.dryRun)
+                return `Would rename ${input.account_id} → "${input.name}".`;
+            const changed = renameAccount(db, input.account_id, input.name);
+            return changed === 0
+                ? `Account ${input.account_id} not found.`
+                : `Renamed ${input.account_id} → "${sanitizeForPrompt(input.name)}".`;
+        }
+        case "merge_accounts": {
+            if (ctx?.dryRun)
+                return `Would merge ${input.from_id} → ${input.to_id}.`;
+            try {
+                const moved = mergeAccounts(db, input.from_id, input.to_id);
+                return `Merged ${input.from_id} → ${input.to_id}; moved ${moved} line(s).`;
+            }
+            catch (err) {
+                return `Could not merge: ${err.message}`;
+            }
+        }
+        case "delete_account": {
+            if (ctx?.dryRun)
+                return `Would delete account ${input.account_id}.`;
+            try {
+                deleteAccount(db, input.account_id);
+                return `Deleted account ${input.account_id}.`;
+            }
+            catch (err) {
+                return `Could not delete: ${err.message}`;
+            }
+        }
+        case "find_duplicate_entries": {
+            const groups = findDuplicateEntries(db, {
+                toleranceDays: input.tolerance_days,
+                accountId: input.account_id,
+                minAmount: input.min_amount,
+            });
+            if (groups.length === 0)
+                return "No candidate duplicate groups found.";
+            return groups
+                .map((g, i) => {
+                const header = `Group ${i + 1} — ${formatTHB(g[0].amount)}`;
+                const lines = g.map((e, j) => {
+                    const accounts = e.account_names.length > 0
+                        ? e.account_names.map(n => sanitizeForPrompt(n)).join(", ")
+                        : "(no lines)";
+                    return `  ${j + 1}. ${e.date} "${sanitizeForPrompt(e.description)}" — ${accounts}    [${e.id}]`;
+                });
+                return `${header}\n${lines.join("\n")}`;
+            })
+                .join("\n\n");
+        }
+        case "find_similar_accounts": {
+            const pairs = findSimilarAccounts(db, input.threshold);
+            if (pairs.length === 0)
+                return "No similar account pairs above threshold.";
+            return pairs
+                .map(p => `${p.similarity}: ${p.a.id} (${sanitizeForPrompt(p.a.name)}) <-> ${p.b.id} (${sanitizeForPrompt(p.b.name)})`)
+                .join("\n");
+        }
+        case "find_unused_accounts": {
+            const rows = findUnusedAccounts(db);
+            if (rows.length === 0)
+                return "No unused accounts.";
+            return rows.map(a => `${a.id} | ${sanitizeForPrompt(a.name)} | ${a.type}`).join("\n");
+        }
+        case "mark_reconcile_done": {
+            ctx?.onComplete?.(input.summary || "");
+            return `Reconcile complete. Summary: ${sanitizeForPrompt(input.summary || "")}`;
+        }
+        default:
+            return undefined;
+    }
+}
+export const reconcileTools = { DEFS, LABELS, execute };

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

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

package/dist/ai/tools/scan.js

@@ -0,0 +1,24 @@
+import { sanitizeForPrompt } from "../sanitize.js";
+const DEFS = [
+    {
+        name: "mark_file_scanned",
+        description: "Call this once the file is fully processed and all journal entries are posted. Summary text is shown to the user.",
+        input_schema: {
+            type: "object",
+            properties: {
+                summary: { type: "string", description: "Short summary of what was recorded." },
+            },
+            required: ["summary"],
+        },
+    },
+];
+const LABELS = {
+    mark_file_scanned: "Finalizing file",
+};
+async function execute(_db, name, input, ctx) {
+    if (name !== "mark_file_scanned")
+        return undefined;
+    ctx?.onComplete?.(input.summary || "");
+    return `Marked file as scanned. Summary: ${sanitizeForPrompt(input.summary || "")}`;
+}
+export const scanTools = { DEFS, LABELS, execute };

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

@@ -0,0 +1,26 @@
+import type Database from "libsql";
+import type { ToolDefinition } from "../provider.js";
+export type ToolProfile = "scan" | "chat" | "reconcile";
+export interface AgentExecutionContext {
+    /** Set during scan so `record_journal_entry` can stamp `source_file_id`. */
+    fileId?: string;
+    /** When false, ask_user returns a marker and the caller halts after the run. */
+    interactive: boolean;
+    /** When true, mutating tools become no-ops that return a "would do X" preview. */
+    dryRun?: boolean;
+    /** Synchronously prompt the user (only invoked when interactive === true). */
+    promptUser?: (prompt: string, options?: string[]) => Promise<string>;
+    /** Called when the model declares the session is done (scan or reconcile). */
+    onComplete?: (summary: string) => void;
+}
+/**
+ * A tool module owns a slice of tool definitions, the spinner labels that go
+ * with them, and an executor that returns `undefined` when the tool name isn't
+ * one of its own. Composing modules at the dispatcher layer is just iteration.
+ */
+export interface ToolModule {
+    readonly DEFS: ToolDefinition[];
+    readonly LABELS: Record<string, string>;
+    execute(db: Database.Database, name: string, input: any, ctx: AgentExecutionContext | undefined): Promise<string | undefined>;
+}
+export type { ToolDefinition };

package/dist/ai/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/tools.d.ts

@@ -0,0 +1,18 @@
+import type Database from "libsql";
+import type { ToolDefinition } from "./provider.js";
+export type ToolProfile = "scan" | "chat";
+export declare function getToolDefinitions(profile: ToolProfile): ToolDefinition[];
+export interface ScanExecutionContext {
+    fileId: string;
+    scannerVersion: string;
+    /** When false, ask_user returns a marker and the pipeline halts after the run. */
+    interactive: boolean;
+    /** Synchronously prompt the user (only invoked when interactive === true). */
+    promptUser?: (prompt: string, options?: string[]) => Promise<string>;
+    /** Called when the model declares the file is done. */
+    onMarkScanned?: (summary: string) => void;
+}
+/** Human-readable labels shown in the spinner. */
+export declare const TOOL_LABELS: Record<string, string>;
+export declare function executeTool(db: Database.Database, toolName: string, toolInput: any, ctx?: ScanExecutionContext): Promise<string>;
+export declare function getTaxonomyHint(): string;