plasalid 0.7.0 → 0.7.2

package/dist/ai/tools/ingest.js

@@ -1,20 +1,70 @@
-import { createAccount, updateAccountMetadata, findAccountById, } from "../../db/queries/account-balance.js";
+import { createAccount, updateAccountMetadata, } from "../../db/queries/account-balance.js";
 import { validateTransaction, insertTransactionRows, recordTransaction, } from "../../db/queries/transactions.js";
-import { appendAction } from "../../db/queries/action-log.js";
-import { getUnknownTarget, recordUnknown, resolveUnknown, } from "../../db/queries/unknowns.js";
-import { runExclusive as runAccountExclusive } from "../../scanner/account-mutex.js";
-import { sanitizeForPrompt } from "../sanitize.js";
+import { recordQuestion } from "../../db/queries/questions.js";
+import { runExclusive as runAccountExclusive } from "./account-mutex.js";
 import { ACCOUNT_TYPE_DESCRIPTIONS } from "../../accounts/taxonomy.js";
 const ACCOUNT_TYPES = Object.keys(ACCOUNT_TYPE_DESCRIPTIONS);
-/**
- * Account + transaction write primitives
- *
- * Shared by scan, resolve, and record. Each tool branches once on
- * `ctx.correlationId`: when set (record path), the data write and the
- * action_log insert run inside a single transaction so the audit row is
- * atomic with the change. Without it (scan / resolve), the write goes through
- * the existing path unchanged.
- */
+const BATCH_MAX = 50;
+const TRANSACTION_ITEM_SCHEMA = {
+    type: "object",
+    properties: {
+        date: {
+            type: "string",
+            description: "ISO Gregorian date (YYYY-MM-DD).",
+        },
+        description: {
+            type: "string",
+            description: "Short human-readable description.",
+        },
+        source_page: {
+            type: "number",
+            description: "Page number in the source PDF, if known.",
+        },
+        raw_descriptor: {
+            type: "string",
+            description: "The exact statement line (the raw merchant descriptor) when posting from a PDF — preserved for alias matching and later review.",
+        },
+        merchant: {
+            type: "object",
+            description: "Counter-party block. Omit for transfers between own accounts and pure metadata movements.",
+            properties: {
+                canonical_name: {
+                    type: "string",
+                    description: "Normalized merchant name, Title Case.",
+                },
+                alias: {
+                    type: "string",
+                    description: "The raw descriptor exactly as it appears on the statement.",
+                },
+                default_account_id: {
+                    type: "string",
+                    description: "Optional learned cache; do not set on first sight.",
+                },
+            },
+            required: ["canonical_name"],
+        },
+        merchant_id: {
+            type: "string",
+            description: "Pre-resolved merchant id (from the scanner's alias pre-pass).",
+        },
+        postings: {
+            type: "array",
+            description: "Two or more postings that balance.",
+            items: {
+                type: "object",
+                properties: {
+                    account_id: { type: "string" },
+                    debit: { type: "number" },
+                    credit: { type: "number" },
+                    currency: { type: "string", default: "THB" },
+                    memo: { type: "string" },
+                },
+                required: ["account_id"],
+            },
+        },
+    },
+    required: ["date", "description", "postings"],
+};
 const ACCOUNT_DEFS = [
     {
         name: "create_account",
@@ -92,9 +142,26 @@ const ACCOUNT_DEFS = [
             required: ["account_id"],
         },
     },
+    {
+        name: "record_transactions",
+        description: `Post many balanced double-entry transactions in a single tool call. **Strongly preferred over record_transaction whenever you have more than one row to post** — the scan tool-step budget is finite (100 per file) and the singular form burns one step per row. Each item has the same shape as record_transaction. Validation runs per item: valid items are written directly to the DB and their ids returned; invalid items are reported back so you can fix and retry just those indices. Limit each call to ≤${BATCH_MAX} transactions; chunk larger statements across multiple calls.`,
+        input_schema: {
+            type: "object",
+            properties: {
+                transactions: {
+                    type: "array",
+                    description: `Up to ${BATCH_MAX} transactions; each has the same shape as record_transaction.`,
+                    items: TRANSACTION_ITEM_SCHEMA,
+                    minItems: 1,
+                    maxItems: BATCH_MAX,
+                },
+            },
+            required: ["transactions"],
+        },
+    },
     {
         name: "record_transaction",
-        description: "Post one balanced double-entry transaction — the right tool for any real-world event (purchase, payment, transfer, refund, salary, withdrawal). Use adjust_account_balance instead when the user is stating a current balance rather than describing a transaction. The sum of debits MUST equal the sum of credits (within one currency). Convert Buddhist-Era dates by subtracting 543. Each posting 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. When the transaction has an external counter-party, attach a `merchant` block — Plasalid dedups merchants and learns a default expense account per merchant so future statements skip re-categorization.",
+        description: "Post ONE balanced double-entry transaction. Prefer record_transactions (plural) when posting more than one row at a time — it burns one tool step instead of N. Use this singular form for one-off corrections (e.g. retrying a single failed item from a batch). The sum of debits MUST equal the sum of credits (within one currency). Convert Buddhist-Era dates by subtracting 543. Each posting 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. When the transaction has an external counter-party, attach a `merchant` block — Plasalid dedups merchants and learns a default expense account per merchant so future statements skip re-categorization.",
         input_schema: {
             type: "object",
             properties: {
@@ -177,32 +244,60 @@ const ACCOUNT_LABELS = {
     create_account: "Creating account",
     update_account_metadata: "Updating account metadata",
     record_transaction: "Posting transaction",
+    record_transactions: "Posting transactions",
 };
-/**
- * Run a write inside an audit-wrapping transaction. When the caller has a
- * correlation id, the write + action_log insert land atomically; otherwise
- * it's just the write. The write closure can return an AuditRecord (logged)
- * or null (no audit row this call — used when an update was a no-op).
- */
-function writeWithAudit(db, ctx, write) {
-    if (!ctx?.correlationId) {
-        write();
-        return;
-    }
-    const op = db.transaction(() => {
-        const audit = write();
-        if (!audit)
-            return;
-        appendAction(db, {
-            correlation_id: ctx.correlationId,
-            command: ctx.command ?? "record",
-            user_input: ctx.userInput ?? null,
-            action_type: audit.actionType,
-            target_id: audit.targetId,
-            payload: audit.payload,
+function buildTransactionInput(input, ctx) {
+    return {
+        date: input.date,
+        description: input.description,
+        source_file_id: ctx.fileId,
+        source_page: input.source_page ?? null,
+        raw_descriptor: input.raw_descriptor ?? null,
+        merchant: input.merchant ?? null,
+        merchant_id: input.merchant_id ?? null,
+        postings: (input.postings || []).map((p) => ({
+            account_id: p.account_id,
+            debit: p.debit ?? 0,
+            credit: p.credit ?? 0,
+            currency: p.currency || "THB",
+            memo: p.memo ?? null,
+        })),
+    };
+}
+async function persistOneTransaction(db, ctx, txInput) {
+    try {
+        const validated = validateTransaction(txInput);
+        const tx = db.transaction(() => {
+            insertTransactionRows(db, validated);
         });
-    });
-    op();
+        tx();
+        if (ctx.progress && ctx.chunkId) {
+            ctx.progress.emit({ chunkId: ctx.chunkId, kind: "tx" });
+        }
+        return { ok: true, id: validated.id };
+    }
+    catch (err) {
+        const message = err?.message ?? String(err);
+        if (ctx.scanId) {
+            try {
+                recordQuestion(db, {
+                    file_id: ctx.fileId ?? null,
+                    scan_id: ctx.scanId,
+                    transaction_id: null,
+                    account_id: null,
+                    kind: "scan_commit_failure",
+                    prompt: `Could not record "${txInput.description}" on ${txInput.date}: ${message}. Review the source statement and re-enter via the record flow.`,
+                });
+                if (ctx.progress && ctx.chunkId) {
+                    ctx.progress.emit({ chunkId: ctx.chunkId, kind: "question" });
+                }
+            }
+            catch {
+                // failure to record a failure shouldn't crash the scan
+            }
+        }
+        return { ok: false, error: message };
+    }
 }
 async function accountExecute(db, name, input, ctx) {
     switch (name) {
@@ -212,25 +307,18 @@ async function accountExecute(db, name, input, ctx) {
             }
             return await runAccountExclusive(() => {
                 try {
-                    writeWithAudit(db, ctx, () => {
-                        createAccount(db, {
-                            id: input.id,
-                            name: input.name,
-                            type: input.type,
-                            parent_id: input.parent_id ?? null,
-                            subtype: input.subtype ?? null,
-                            bank_name: input.bank_name ?? null,
-                            account_number_masked: input.account_number_masked ?? null,
-                            currency: input.currency,
-                            due_day: input.due_day ?? null,
-                            statement_day: input.statement_day ?? null,
-                            metadata: input.metadata ?? null,
-                        });
-                        return {
-                            actionType: "create_account",
-                            targetId: input.id,
-                            payload: { row: findAccountById(db, input.id) },
-                        };
+                    createAccount(db, {
+                        id: input.id,
+                        name: input.name,
+                        type: input.type,
+                        parent_id: input.parent_id ?? null,
+                        subtype: input.subtype ?? null,
+                        bank_name: input.bank_name ?? null,
+                        account_number_masked: input.account_number_masked ?? null,
+                        currency: input.currency,
+                        due_day: input.due_day ?? null,
+                        statement_day: input.statement_day ?? null,
+                        metadata: input.metadata ?? null,
                     });
                     return `Account created: ${input.id} (${input.name}, ${input.type}).`;
                 }
@@ -245,26 +333,15 @@ async function accountExecute(db, name, input, ctx) {
         case "update_account_metadata": {
             return await runAccountExclusive(() => {
                 try {
-                    let changed = false;
-                    writeWithAudit(db, ctx, () => {
-                        const result = updateAccountMetadata(db, input.account_id, {
-                            due_day: input.due_day,
-                            statement_day: input.statement_day,
-                            points_balance: input.points_balance,
-                            account_number_masked: input.account_number_masked,
-                            bank_name: input.bank_name,
-                            metadata: input.metadata,
-                        });
-                        changed = result.changed;
-                        if (!result.changed)
-                            return null;
-                        return {
-                            actionType: "update_account_metadata",
-                            targetId: input.account_id,
-                            payload: { before: result.before, after: result.after },
-                        };
+                    const result = updateAccountMetadata(db, input.account_id, {
+                        due_day: input.due_day,
+                        statement_day: input.statement_day,
+                        points_balance: input.points_balance,
+                        account_number_masked: input.account_number_masked,
+                        bank_name: input.bank_name,
+                        metadata: input.metadata,
                     });
-                    return changed ? `Updated ${input.account_id}.` : "Nothing to update.";
+                    return result.changed ? `Updated ${input.account_id}.` : "Nothing to update.";
                 }
                 catch (err) {
                     if (String(err.message).includes("not found")) {
@@ -274,55 +351,52 @@ async function accountExecute(db, name, input, ctx) {
                 }
             });
         }
+        case "record_transactions": {
+            if (!ctx)
+                return "record_transactions is only available inside an agent session.";
+            const items = Array.isArray(input?.transactions) ? input.transactions : [];
+            if (items.length === 0)
+                return "record_transactions requires at least one transaction.";
+            if (items.length > BATCH_MAX) {
+                return `record_transactions accepts at most ${BATCH_MAX} transactions per call; got ${items.length}. Split into smaller batches.`;
+            }
+            const posted = [];
+            const failed = [];
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const txInput = buildTransactionInput(item, ctx);
+                const outcome = await persistOneTransaction(db, ctx, txInput);
+                if (outcome.ok) {
+                    posted.push({ index: i, transactionId: outcome.id, date: item.date });
+                }
+                else {
+                    failed.push({ index: i, error: outcome.error });
+                }
+            }
+            const lines = [`Posted ${posted.length} of ${items.length}.`];
+            if (posted.length > 0) {
+                lines.push(...posted.map(p => `- index ${p.index}: ${p.transactionId} (${p.date})`));
+            }
+            if (failed.length > 0) {
+                lines.push("Failed:");
+                lines.push(...failed.map(f => `- index ${f.index}: ${f.error}`));
+                lines.push("Retry the failed indices with corrections.");
+            }
+            return lines.join("\n");
+        }
         case "record_transaction": {
             if (!ctx)
                 return "record_transaction is only available inside an agent session.";
-            const txInput = {
-                date: input.date,
-                description: input.description,
-                source_file_id: ctx.fileId,
-                source_page: input.source_page ?? null,
-                raw_descriptor: input.raw_descriptor ?? null,
-                merchant: input.merchant ?? null,
-                merchant_id: input.merchant_id ?? null,
-                postings: (input.postings || []).map((p) => ({
-                    account_id: p.account_id,
-                    debit: p.debit ?? 0,
-                    credit: p.credit ?? 0,
-                    currency: p.currency || "THB",
-                    memo: p.memo ?? null,
-                })),
-            };
+            const txInput = buildTransactionInput(input, ctx);
+            if (ctx.scanId) {
+                const outcome = await persistOneTransaction(db, ctx, txInput);
+                return outcome.ok
+                    ? `Posted transaction ${outcome.id} (${input.date}).`
+                    : `Could not post transaction: ${outcome.error}`;
+            }
             try {
-                if (ctx.buffer) {
-                    const transactionId = ctx.buffer.appendTransaction(txInput);
-                    return `Posted transaction ${transactionId} (${input.date}).`;
-                }
-                // No-audit path uses recordTransaction (validates + inserts in one go).
-                // Audit path validates ahead so the validated id can be returned without
-                // re-reading from disk after the transaction commits.
-                if (!ctx.correlationId) {
-                    const transactionId = recordTransaction(db, txInput);
-                    return `Posted transaction ${transactionId} (${input.date}).`;
-                }
-                const validated = validateTransaction(txInput);
-                writeWithAudit(db, ctx, () => {
-                    insertTransactionRows(db, validated);
-                    return {
-                        actionType: "record_transaction",
-                        targetId: validated.id,
-                        payload: {
-                            transaction: {
-                                date: validated.date,
-                                description: validated.description,
-                                source_page: validated.source_page ?? null,
-                                raw_descriptor: validated.raw_descriptor ?? null,
-                            },
-                            postings: validated.postings,
-                        },
-                    };
-                });
-                return `Posted transaction ${validated.id} (${input.date}).`;
+                const transactionId = recordTransaction(db, txInput);
+                return `Posted transaction ${transactionId} (${input.date}).`;
             }
             catch (err) {
                 return `Could not post transaction: ${err.message}`;
@@ -337,27 +411,20 @@ export const accountIngestTools = {
     LABELS: ACCOUNT_LABELS,
     execute: accountExecute,
 };
-/**
- * Scan-only unknowns
- *
- * `note_unknown` records a clarification mid-scan without ever prompting the
- * user — only scan needs this. Record uses `clarify` (transient prompt, no
- * unknowns-table residue); resolve uses `ask_user` (prompts and resolves).
- */
-const UNKNOWN_DEFS = [
+const QUESTION_DEFS = [
     {
-        name: "note_unknown",
-        description: "Record a clarification request without pausing the run. Use during scan when a row is ambiguous (post your best-guess transaction first, then call this with the transaction's id), when a row is unparseable (skip the transaction, call this with no transaction_id), or when you have a unknown about an account itself (pass account_id). Use kind='uncategorized_expense' when posting an expense to expense:uncategorized so resolve can group these. The resolver picks these up later with the full picture.",
+        name: "note_question",
+        description: "Record a clarification question without pausing the run. Use SPARINGLY during scan — best-guess expense categorization is preferred (small misses are cheap to fix; a flood of questions is not). Call note_question only when (a) the row is unparseable (skip the row, no transaction_id), (b) you have a doubt about an account itself (pass account_id), or (c) the amount/sign/date/counter-party is genuinely unclear (post your best-guess transaction first, then call this with the transaction_id). Use kind='uncategorized_expense' only for genuinely opaque expense descriptors that landed in expense:uncategorized. The resolver picks these up later with the full picture.",
         input_schema: {
             type: "object",
             properties: {
                 prompt: {
                     type: "string",
-                    description: "The question or unknown in a complete sentence, with date, ฿-formatted amount, and human account names. Never reference internal ids.",
+                    description: "The question in a complete sentence, with date, ฿-formatted amount, and human account names. Never reference internal ids.",
                 },
                 kind: {
                     type: "string",
-                    description: "Optional category for the unknown. Use 'uncategorized_expense' when the posting landed in expense:uncategorized; the resolver batches these into one cleanup pass.",
+                    description: "Optional category for the question. Use 'uncategorized_expense' when the posting landed in expense:uncategorized; the resolver batches these into one cleanup pass.",
                 },
                 options: {
                     type: "array",
@@ -366,64 +433,48 @@ const UNKNOWN_DEFS = [
                 },
                 transaction_id: {
                     type: "string",
-                    description: "Id of the transaction this unknown relates to (returned by record_transaction). Omit for file-level unknowns about an unparseable row.",
+                    description: "Id of the transaction this question relates to (returned by record_transaction). Omit for file-level questions about an unparseable row.",
                 },
                 account_id: {
                     type: "string",
-                    description: "Id of the account this unknown relates to. Set when the statement's bank name, currency, statement_day, due_day, or other metadata disagrees with the stored account, or when you suspect a new account you're about to create duplicates an existing one. Can be combined with transaction_id.",
+                    description: "Id of the account this question relates to. Set when the statement's bank name, currency, statement_day, due_day, or other metadata disagrees with the stored account, or when you suspect a new account you're about to create duplicates an existing one. Can be combined with transaction_id.",
                 },
             },
             required: ["prompt"],
         },
     },
 ];
-const UNKNOWN_LABELS = {
-    note_unknown: "Noting unknown",
+const QUESTION_LABELS = {
+    note_question: "Noting question",
 };
-async function unknownExecute(db, name, input, ctx) {
-    if (name !== "note_unknown")
+async function questionExecute(db, name, input, ctx) {
+    if (name !== "note_question")
         return undefined;
     if (!ctx)
-        return "note_unknown is only available inside an agent session.";
-    const target = {
+        return "note_question is only available inside an agent session.";
+    const id = recordQuestion(db, {
+        file_id: ctx.fileId ?? null,
+        scan_id: ctx.scanId ?? null,
         transaction_id: input.transaction_id ?? null,
         account_id: input.account_id ?? null,
-    };
-    if (ctx.buffer) {
-        ctx.buffer.appendUnknown({
-            ...target,
-            kind: input.kind ?? null,
-            prompt: input.prompt,
-            options: input.options,
-        });
-        return `Unknown noted (buffered). Continue with the next row.`;
-    }
-    const id = recordUnknown(db, {
-        file_id: ctx.fileId ?? null,
-        transaction_id: target.transaction_id,
-        account_id: target.account_id,
         kind: input.kind ?? null,
         prompt: input.prompt,
         options: input.options,
     });
-    return `Unknown noted (${id}). Continue with the next row.`;
+    if (ctx.progress && ctx.chunkId) {
+        ctx.progress.emit({ chunkId: ctx.chunkId, kind: "question" });
+    }
+    return `Question noted (${id}). Continue with the next row.`;
 }
-export const scanUnknownTools = {
-    DEFS: UNKNOWN_DEFS,
-    LABELS: UNKNOWN_LABELS,
-    execute: unknownExecute,
+export const scanQuestionTools = {
+    DEFS: QUESTION_DEFS,
+    LABELS: QUESTION_LABELS,
+    execute: questionExecute,
 };
-/**
- * Resolve-only tool definitions
- *
- * `ask_user` is the only interactive primitive. Scan never reaches it (the
- * scan profile doesn't include this module), so we don't need a "scan, please
- * don't use this" guard.
- */
 const RESOLVE_DEFS = [
     {
         name: "ask_user",
-        description: "Ask the user a clarifying question when you cannot confidently proceed. The pipeline pauses and prompts the user interactively. Available during `plasalid resolve`. Not exposed during `plasalid scan` — use `note_unknown` instead. Pass `transaction_id` / `account_id` to attach the question to the same target as a scan-noted unknown. Pass `unknown_id` to resolve an existing open unknown in place (recommended when re-posing a scan-noted unknown to the user). Pass `related_unknown_ids` to apply the user's single answer to a whole group of sibling unknowns at once.",
+        description: "Ask the user a clarifying question when you cannot confidently proceed. The pipeline pauses and prompts the user interactively. Available during `plasalid resolve`. Not exposed during `plasalid scan` — use `note_question` instead. Pass `question_id` to close an existing question in place. Pass `related_question_ids` to apply the user's single answer to a whole group of sibling questions at once.",
         input_schema: {
             type: "object",
             properties: {
@@ -436,122 +487,111 @@ const RESOLVE_DEFS = [
                     description: "Optional list of candidate answers.",
                     items: { type: "string" },
                 },
-                transaction_id: {
-                    type: "string",
-                    description: "Optional: transaction this question is about. Used to clear the transaction's has_unknown flag once all its unknowns close.",
-                },
-                account_id: {
-                    type: "string",
-                    description: "Optional: account this question is about. Used to clear the account's has_unknown flag once all its unknowns close.",
-                },
-                unknown_id: {
+                question_id: {
                     type: "string",
-                    description: "Optional: id of an existing open unknown. If supplied, the user's answer resolves that row in place instead of creating a new one.",
+                    description: "Id of the primary question this resolves. The user's answer closes (deletes) that row.",
                 },
-                related_unknown_ids: {
+                related_question_ids: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Optional: ids of additional open unknowns that share the same answer as `unknown_id`. The user is prompted once; every listed unknown (plus the primary) is marked resolved with the same answer. Use this for grouping duplicate questions — e.g., 12 Lazada rows that all categorize the same way — so the user isn't asked the same thing twelve times.",
+                    description: "Optional: ids of additional questions that share the same answer as `question_id`. The user is prompted once; every listed question (plus the primary) is closed with the same answer.",
                 },
                 facts: {
                     type: "object",
-                    description: "Optional structured highlights rendered as a single colored header line above the question. Provide whichever fields apply; the prompter colorizes each by category (amount=yellow, date=cyan, merchant=green, accounts=magenta). Keep the `prompt` text short — the facts header carries the context.",
+                    description: "Optional structured highlights rendered as a single colored header line above the question.",
                     properties: {
-                        amount: {
-                            type: "string",
-                            description: "฿-formatted amount, e.g. '฿1,200.00'.",
-                        },
-                        date: {
-                            type: "string",
-                            description: "ISO date or short range, e.g. '2026-04-15' or '2026-02-15 to 2026-05-15'.",
-                        },
-                        merchant: {
-                            type: "string",
-                            description: "Counterparty / merchant name, e.g. 'LAZADA TH', 'Spotify'.",
-                        },
+                        amount: { type: "string" },
+                        date: { type: "string" },
+                        merchant: { type: "string" },
                         accounts: {
                             type: "array",
                             items: { type: "string" },
-                            description: "Human account names involved. For merges, list the survivor first.",
                         },
                     },
                 },
             },
-            required: ["prompt"],
+            required: ["prompt", "question_id"],
         },
     },
     {
-        name: "close_unknown",
-        description: "Close an open unknown by writing its answer to the row WITHOUT prompting the user. Use after applying a mutation that a memory rule, heuristic, or small-amount auto-skip already implied. Pass `related_unknown_ids` to close a sibling group in one call. The actual mutation (update_posting / record_recurrence / merge_accounts / etc.) must be done BEFORE this call — close_unknown only records the answer for audit.",
+        name: "close_question",
+        description: "Close an question by writing its answer and deleting the row WITHOUT prompting the user. Use after applying a mutation that a memory rule or heuristic already implied. Pass `related_question_ids` to close a sibling group in one call.",
         input_schema: {
             type: "object",
             properties: {
-                unknown_id: { type: "string" },
+                question_id: { type: "string" },
                 answer: {
                     type: "string",
                     description: "The implied answer to record.",
                 },
-                related_unknown_ids: { type: "array", items: { type: "string" } },
+                related_question_ids: { type: "array", items: { type: "string" } },
             },
-            required: ["unknown_id", "answer"],
+            required: ["question_id", "answer"],
         },
     },
 ];
 const RESOLVE_LABELS = {
     ask_user: "Asking for clarification",
-    close_unknown: "Closing unknown",
+    close_question: "Closing question",
 };
-async function resolveExecute(db, name, input, ctx) {
-    if (name === "close_unknown")
-        return closeUnknown(db, input);
+async function resolveIngestExecute(db, name, input, ctx) {
+    if (name === "close_question")
+        return closeQuestionTool(db, input, ctx);
     if (name !== "ask_user")
         return undefined;
-    if (!ctx?.promptUser) {
-        return "ask_user requires an interactive resolve session.";
+    if (!ctx)
+        return "ask_user is only available inside an agent session.";
+    const primary = String(input.question_id ?? "");
+    if (!primary)
+        return "ask_user requires question_id.";
+    if (ctx.interactive && ctx.promptUser) {
+        const answer = await ctx.promptUser(input.prompt, input.options, input.facts);
+        const { closeQuestion } = await import("../../db/queries/questions.js");
+        const captured = closeQuestion(db, primary, answer);
+        if (!captured)
+            return `Question ${primary} not found.`;
+        ctx.onQuestionClosed?.(captured);
+        let propagated = 0;
+        const siblings = Array.isArray(input.related_question_ids) ? input.related_question_ids : [];
+        for (const sibId of siblings) {
+            if (sibId === primary)
+                continue;
+            const sibClosed = closeQuestion(db, String(sibId), answer);
+            if (sibClosed) {
+                ctx.onQuestionClosed?.(sibClosed);
+                propagated++;
+            }
+        }
+        const total = 1 + propagated;
+        return `User answered: ${answer}${total > 1 ? ` (applied to ${total} questions)` : ""}`;
     }
-    const id = input.unknown_id
-        ? String(input.unknown_id)
-        : recordUnknown(db, {
-            file_id: ctx.fileId ?? null,
-            transaction_id: input.transaction_id ?? null,
-            account_id: input.account_id ?? null,
-            prompt: input.prompt,
-            options: input.options,
-        });
-    if (!getUnknownTarget(db, id))
-        return `Unknown ${id} not found.`;
-    const answer = await ctx.promptUser(input.prompt, input.options, input.facts);
-    return applyAnswerToGroup(db, id, answer, input.related_unknown_ids);
+    return `Awaiting user input — cannot proceed in non-interactive mode.`;
 }
-function closeUnknown(db, input) {
-    const primary = String(input.unknown_id ?? "");
+async function closeQuestionTool(db, input, ctx) {
+    const { closeQuestion } = await import("../../db/queries/questions.js");
+    const primary = String(input.question_id ?? "");
     const answer = String(input.answer ?? "");
     if (!primary || !answer)
-        return "close_unknown requires unknown_id and answer.";
-    if (!getUnknownTarget(db, primary))
-        return `Unknown ${primary} not found.`;
-    return applyAnswerToGroup(db, primary, answer, input.related_unknown_ids);
-}
-function applyAnswerToGroup(db, primaryId, answer, rawSiblings) {
-    resolveUnknown(db, primaryId, answer);
-    const siblings = Array.isArray(rawSiblings) ? rawSiblings.map(String) : [];
-    const resolved = [primaryId];
-    const notFound = [];
+        return "close_question requires question_id and answer.";
+    const captured = closeQuestion(db, primary, answer);
+    if (!captured)
+        return `Question ${primary} not found.`;
+    ctx?.onQuestionClosed?.(captured);
+    let count = 1;
+    const siblings = Array.isArray(input.related_question_ids) ? input.related_question_ids : [];
     for (const sibId of siblings) {
-        if (sibId === primaryId)
+        if (sibId === primary)
             continue;
-        if (resolveUnknown(db, sibId, answer))
-            resolved.push(sibId);
-        else
-            notFound.push(sibId);
+        const sibClosed = closeQuestion(db, String(sibId), answer);
+        if (sibClosed) {
+            ctx?.onQuestionClosed?.(sibClosed);
+            count++;
+        }
     }
-    const preface = `Resolved ${resolved.length} unknown${resolved.length === 1 ? "" : "s"} with: ${sanitizeForPrompt(answer)}`;
-    if (notFound.length === 0)
-        return preface;
-    return `${preface}. NOT FOUND: ${notFound.join(", ")} — these ids did not exist; do not re-close them.`;
+    return `Closed ${count} question${count === 1 ? "" : "s"}.`;
 }
 export const resolveIngestTools = {
     DEFS: RESOLVE_DEFS,
     LABELS: RESOLVE_LABELS,
-    execute: resolveExecute,
+    execute: resolveIngestExecute,
 };