agentic-qe 3.15.15 → 3.15.17

package/dist/shared/llm/spend-ledger.js

@@ -18,6 +18,7 @@
  * cross-process pattern.
  */
 import { createSafeRecord } from '../utils/safe-record.js';
+import { writeWhenUnlockedOn } from '../sqlite-write-queue.js';
 /** Bucket used for charges recorded without an agent context. */
 export const UNATTRIBUTED_AGENT = '(unattributed)';
 const CREATE_TABLE_SQL = `
@@ -49,6 +50,14 @@ export class SqliteSpendLedger {
      * drop ALL spend — bypassing the budget cap (the #557 class).
      */
     hasAgentColumn = false;
+    /**
+     * Charges queued but not yet in the table (#1283). record() queues its
+     * INSERT so a locked memory.db does not freeze the MCP server; until the row
+     * lands, the spend reads below count it from here, so the ADR-123 budget cap
+     * never under-counts. Each entry leaves this set in the same synchronous
+     * step that inserts its row, so a charge is never counted twice.
+     */
+    pending = new Set();
     constructor(db) {
         this.db = db;
         // Additive schema only — CREATE TABLE/INDEX IF NOT EXISTS never drops data.
@@ -70,45 +79,52 @@ export class SqliteSpendLedger {
         }
     }
     record(entry) {
-        try {
-            if (this.hasAgentColumn) {
-                this.db
-                    .prepare(`INSERT INTO llm_spend
-               (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id, agent_type)
-             VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id, @agent_type)`)
-                    .run({
-                    ts: Date.now(),
-                    provider: entry.provider,
-                    model: entry.model,
-                    cost_usd: entry.costUsd,
-                    cost_source: entry.costSource,
-                    prompt_tokens: entry.promptTokens,
-                    completion_tokens: entry.completionTokens,
-                    request_id: entry.requestId,
-                    agent_type: entry.agent ?? null,
-                });
-            }
-            else {
-                // Column absent (migration couldn't run) — still record spend so the
-                // budget cap holds; just without per-agent attribution.
-                this.db
-                    .prepare(`INSERT INTO llm_spend
-               (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id)
-             VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id)`)
-                    .run({
-                    ts: Date.now(),
-                    provider: entry.provider,
-                    model: entry.model,
-                    cost_usd: entry.costUsd,
-                    cost_source: entry.costSource,
-                    prompt_tokens: entry.promptTokens,
-                    completion_tokens: entry.completionTokens,
-                    request_id: entry.requestId,
-                });
-            }
-        }
-        catch {
+        const ts = Date.now();
+        const charge = { ts, costUsd: entry.costUsd, agent: entry.agent ?? UNATTRIBUTED_AGENT };
+        this.pending.add(charge);
+        writeWhenUnlockedOn(this.db, () => {
+            this.insert(entry, ts);
+            this.pending.delete(charge);
+        }).catch(() => {
             // A ledger write must never break a generation call.
+            this.pending.delete(charge);
+        });
+    }
+    insert(entry, ts) {
+        if (this.hasAgentColumn) {
+            this.db
+                .prepare(`INSERT INTO llm_spend
+             (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id, agent_type)
+           VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id, @agent_type)`)
+                .run({
+                ts,
+                provider: entry.provider,
+                model: entry.model,
+                cost_usd: entry.costUsd,
+                cost_source: entry.costSource,
+                prompt_tokens: entry.promptTokens,
+                completion_tokens: entry.completionTokens,
+                request_id: entry.requestId,
+                agent_type: entry.agent ?? null,
+            });
+        }
+        else {
+            // Column absent (migration couldn't run) — still record spend so the
+            // budget cap holds; just without per-agent attribution.
+            this.db
+                .prepare(`INSERT INTO llm_spend
+             (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id)
+           VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id)`)
+                .run({
+                ts,
+                provider: entry.provider,
+                model: entry.model,
+                cost_usd: entry.costUsd,
+                cost_source: entry.costSource,
+                prompt_tokens: entry.promptTokens,
+                completion_tokens: entry.completionTokens,
+                request_id: entry.requestId,
+            });
         }
     }
     spentSince(windowMs, nowMs = Date.now()) {
@@ -116,7 +132,12 @@ export class SqliteSpendLedger {
             const row = this.db
                 .prepare(`SELECT COALESCE(SUM(cost_usd), 0) AS total FROM llm_spend WHERE ts >= ?`)
                 .get(nowMs - windowMs);
-            return row?.total ?? 0;
+            let total = row?.total ?? 0;
+            for (const charge of this.pending) {
+                if (charge.ts >= nowMs - windowMs)
+                    total += charge.costUsd;
+            }
+            return total;
         }
         catch {
             return 0;
@@ -131,6 +152,10 @@ export class SqliteSpendLedger {
             const out = createSafeRecord();
             for (const r of rows)
                 out[r.agent] = r.total;
+            for (const charge of this.pending) {
+                if (charge.ts >= nowMs - windowMs)
+                    out[charge.agent] = (out[charge.agent] ?? 0) + charge.costUsd;
+            }
             return out;
         }
         catch {

package/dist/shared/pytest-junit-report.d.ts

@@ -0,0 +1,93 @@
+/**
+ * #1248: running pytest and reading its JUnit XML report.
+ *
+ * pytest is started as `<python> -m pytest <files> --junitxml=<file>`, with
+ * the report in a temporary directory owned by the run, so the result never
+ * depends on the console summary. The interpreter is `AQE_PYTHON` when set,
+ * otherwise `python` when it is on PATH, otherwise `python3`.
+ *
+ * The report is read with a small parser for the XML pytest writes (one or
+ * more `<testsuite>` elements holding `<testcase>` elements, each with an
+ * optional `<failure>`, `<error>` or `<skipped>` child). Counts come from the
+ * test cases themselves, so they always match the per-test list. An expected
+ * failure (xfail) is reported by pytest as skipped and counted as skipped.
+ *
+ * A run is only a result when pytest finished its tests: exit code 5 (no
+ * tests collected), 2 (interrupted, for example by a collection error),
+ * 3 (internal error) and 4 (usage error), or a missing report (pytest not
+ * installed for the interpreter), are runner errors, never a pass.
+ */
+import { TestRunnerExecutionError } from './test-runner-verdict.js';
+import { Result } from './types';
+/** True for a Python test file, which only pytest can run. */
+export declare function isPythonTestFile(file: string): boolean;
+/** The Python interpreter that runs pytest. */
+export declare function resolvePythonCommand(env?: NodeJS.ProcessEnv): string;
+/** Environment for a pytest process: no ANSI colour in its output or report. */
+export declare const PYTEST_ENV: Readonly<Record<string, string>>;
+/** Command and arguments that run `targets` (paths or node ids) with pytest. */
+export declare function pytestCommand(targets: readonly string[], reportPath: string, env?: NodeJS.ProcessEnv): {
+    command: string;
+    args: string[];
+};
+/** A per-run JUnit report location, read back after pytest exits. */
+export interface PytestJunitReport {
+    /** Absolute path pytest writes the report to. */
+    readonly path: string;
+    /** Arguments that point pytest at the report (already in pytestCommand). */
+    readonly args: readonly string[];
+    /** The report text; undefined when pytest wrote none. Malformed reports throw. */
+    read(stdout?: string): string | undefined;
+    /** Remove the temporary report directory. Safe to call more than once. */
+    cleanup(): void;
+}
+export declare function createPytestJunitReport(): PytestJunitReport;
+export type PytestCaseStatus = 'passed' | 'failed' | 'error' | 'skipped';
+/** One `<testcase>` of a pytest JUnit report. */
+export interface PytestJunitCase {
+    classname: string;
+    name: string;
+    status: PytestCaseStatus;
+    /** Duration in milliseconds, when reported. */
+    duration?: number;
+    /** The failure, error or skip message attribute. */
+    message?: string;
+    /** The failure or error body (traceback). */
+    details?: string;
+}
+/** The test cases of a pytest JUnit XML report, in report order. */
+export declare function parsePytestJunitXml(xml: string): PytestJunitCase[];
+/**
+ * The run file a test case belongs to, and its name inside that file
+ * (`TestClass::test_name[param]`, the node id without the file). The class
+ * name is the module's dotted path relative to pytest's rootdir followed by
+ * any classes, so the file is the one whose path ends with the longest
+ * leading part of it.
+ */
+export declare function locatePytestCase(testCase: Pick<PytestJunitCase, 'classname' | 'name'>, files: readonly string[]): {
+    file: string;
+    name: string;
+};
+/** One test of a finished pytest run. */
+export interface PytestTest {
+    name: string;
+    file: string;
+    status: 'passed' | 'failed' | 'skipped';
+    duration?: number;
+    /** Failure or error text for a failed test. */
+    failureMessage?: string;
+}
+export interface PytestRun {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    tests: PytestTest[];
+}
+/**
+ * The result of a finished pytest run, or the runner error that kept it from
+ * being one. `report` is the JUnit XML text, undefined when pytest wrote none.
+ * A test case that errored (in a fixture, say) counts as a failed test.
+ */
+export declare function pytestRunFromReport(report: string | undefined, files: readonly string[], exitCode: number | null, output: string, python?: string): Result<PytestRun, TestRunnerExecutionError>;
+//# sourceMappingURL=pytest-junit-report.d.ts.map

package/dist/shared/pytest-junit-report.js

@@ -0,0 +1,241 @@
+/**
+ * #1248: running pytest and reading its JUnit XML report.
+ *
+ * pytest is started as `<python> -m pytest <files> --junitxml=<file>`, with
+ * the report in a temporary directory owned by the run, so the result never
+ * depends on the console summary. The interpreter is `AQE_PYTHON` when set,
+ * otherwise `python` when it is on PATH, otherwise `python3`.
+ *
+ * The report is read with a small parser for the XML pytest writes (one or
+ * more `<testsuite>` elements holding `<testcase>` elements, each with an
+ * optional `<failure>`, `<error>` or `<skipped>` child). Counts come from the
+ * test cases themselves, so they always match the per-test list. An expected
+ * failure (xfail) is reported by pytest as skipped and counted as skipped.
+ *
+ * A run is only a result when pytest finished its tests: exit code 5 (no
+ * tests collected), 2 (interrupted, for example by a collection error),
+ * 3 (internal error) and 4 (usage error), or a missing report (pytest not
+ * installed for the interpreter), are runner errors, never a pass.
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import * as path from 'node:path';
+import { capDiagnostics, getTestRunnerExecutionError, TestRunnerExecutionError } from './test-runner-verdict.js';
+import { ok, err } from './types/index.js';
+/** True for a Python test file, which only pytest can run. */
+export function isPythonTestFile(file) {
+    return /\.py$/i.test(file);
+}
+function onPath(command, env) {
+    const names = process.platform === 'win32' ? [`${command}.exe`, `${command}.cmd`, command] : [command];
+    for (const dir of (env.PATH ?? env.Path ?? '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            try {
+                if (statSync(path.join(dir, name)).isFile())
+                    return true;
+            }
+            catch {
+                // Not in this directory.
+            }
+        }
+    }
+    return false;
+}
+/** The Python interpreter that runs pytest. */
+export function resolvePythonCommand(env = process.env) {
+    const configured = env.AQE_PYTHON?.trim();
+    if (configured)
+        return configured;
+    if (onPath('python', env))
+        return 'python';
+    return onPath('python3', env) ? 'python3' : 'python';
+}
+/** Environment for a pytest process: no ANSI colour in its output or report. */
+export const PYTEST_ENV = { PY_COLORS: '0' };
+/** Command and arguments that run `targets` (paths or node ids) with pytest. */
+export function pytestCommand(targets, reportPath, env = process.env) {
+    return {
+        command: resolvePythonCommand(env),
+        // No colour: runners are started with FORCE_COLOR set, which pytest reads
+        // as "force colour" (even in its report). PY_COLORS=0 (PYTEST_ENV) wins
+        // over FORCE_COLOR; --color=no covers the console output.
+        args: ['-m', 'pytest', ...targets, `--junitxml=${reportPath}`, '--color=no'],
+    };
+}
+export function createPytestJunitReport() {
+    const dir = mkdtempSync(path.join(tmpdir(), 'aqe-pytest-report-'));
+    const reportPath = path.join(dir, 'junit.xml');
+    let cleaned = false;
+    return {
+        path: reportPath,
+        args: [],
+        read: () => {
+            if (!existsSync(reportPath))
+                return undefined;
+            const text = readFileSync(reportPath, 'utf-8');
+            if (!/<testsuite\b/.test(text))
+                throw new TestRunnerExecutionError('The current pytest JUnit report is malformed.');
+            return text;
+        },
+        cleanup: () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best effort: a leftover temp dir is not worth failing a test run over.
+            }
+        },
+    };
+}
+function unescapeXml(text) {
+    return text.replace(/&(#x[0-9a-f]+|#\d+|lt|gt|amp|quot|apos);/gi, (_, entity) => {
+        const lower = entity.toLowerCase();
+        if (lower === 'lt')
+            return '<';
+        if (lower === 'gt')
+            return '>';
+        if (lower === 'amp')
+            return '&';
+        if (lower === 'quot')
+            return '"';
+        if (lower === 'apos')
+            return '\'';
+        const code = lower.startsWith('#x') ? parseInt(lower.slice(2), 16) : parseInt(lower.slice(1), 10);
+        return Number.isFinite(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : '';
+    });
+}
+function attributes(text) {
+    const attrs = {};
+    for (const match of text.matchAll(/([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+        attrs[match[1]] = unescapeXml(match[2] ?? match[3] ?? '');
+    }
+    return attrs;
+}
+/** The test cases of a pytest JUnit XML report, in report order. */
+export function parsePytestJunitXml(xml) {
+    if (!/<testsuite\b/.test(xml))
+        throw new Error('Not a JUnit XML report: no <testsuite> element.');
+    const cases = [];
+    const testcase = /<testcase\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+    for (const match of xml.matchAll(testcase)) {
+        const attrs = attributes(match[1]);
+        const body = match[2] ?? '';
+        // An error (setup/teardown) outranks a failure in the same test case.
+        const child = (tag) => body.match(new RegExp(`<${tag}\\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\\/>|>([\\s\\S]*?)<\\/${tag}>)`));
+        const error = child('error');
+        const failure = child('failure');
+        const skipped = child('skipped');
+        const outcome = error ?? failure ?? skipped;
+        const status = error ? 'error' : failure ? 'failed' : skipped ? 'skipped' : 'passed';
+        const seconds = Number.parseFloat(attrs.time ?? '');
+        const message = outcome ? attributes(outcome[1]).message : undefined;
+        const details = outcome?.[2] !== undefined ? unescapeXml(outcome[2]).trim() : undefined;
+        cases.push({
+            classname: attrs.classname ?? '',
+            name: attrs.name ?? '',
+            status,
+            ...(Number.isFinite(seconds) ? { duration: Math.round(seconds * 1000) } : {}),
+            ...(message ? { message } : {}),
+            ...(details ? { details } : {}),
+        });
+    }
+    return cases;
+}
+/** A collection error is reported as an error case with no class name. */
+function isCollectionError(testCase) {
+    return testCase.status === 'error' && (testCase.classname === '' || testCase.message === 'collection failure');
+}
+function pathSegments(file) {
+    return file.replace(/\.py$/i, '').split(/[\\/]+/).filter(Boolean);
+}
+/**
+ * The run file a test case belongs to, and its name inside that file
+ * (`TestClass::test_name[param]`, the node id without the file). The class
+ * name is the module's dotted path relative to pytest's rootdir followed by
+ * any classes, so the file is the one whose path ends with the longest
+ * leading part of it.
+ */
+export function locatePytestCase(testCase, files) {
+    const dotted = testCase.classname ? testCase.classname.split('.') : [];
+    let best;
+    for (const file of files) {
+        const segments = pathSegments(file);
+        for (let length = Math.min(dotted.length, segments.length); length > 0; length--) {
+            const tail = segments.slice(segments.length - length);
+            if (tail.every((segment, index) => segment === dotted[index])) {
+                if (!best || length > best.matched)
+                    best = { file, matched: length };
+                break;
+            }
+        }
+    }
+    if (!best) {
+        return {
+            file: files.length === 1 ? files[0] : files.join(', '),
+            name: testCase.classname ? `${testCase.classname}::${testCase.name}` : testCase.name,
+        };
+    }
+    return { file: best.file, name: [...dotted.slice(best.matched), testCase.name].join('::') };
+}
+const PYTEST_EXIT_REASONS = {
+    2: 'was interrupted (for example by a collection error)',
+    3: 'hit an internal error',
+    4: 'rejected its command line',
+    5: 'collected no tests',
+};
+/**
+ * The result of a finished pytest run, or the runner error that kept it from
+ * being one. `report` is the JUnit XML text, undefined when pytest wrote none.
+ * A test case that errored (in a fixture, say) counts as a failed test.
+ */
+export function pytestRunFromReport(report, files, exitCode, output, python = resolvePythonCommand()) {
+    const label = files.join(', ');
+    if (report === undefined) {
+        const notInstalled = /No module named pytest/.test(output);
+        return err(new TestRunnerExecutionError(`pytest wrote no JUnit report for ${label} (exit code ${exitCode ?? 'unknown'}).` +
+            (notInstalled
+                ? ` pytest is not installed for '${python}'; install it, or set AQE_PYTHON to an interpreter that has it.`
+                : ` Check that '${python} -m pytest' runs; set AQE_PYTHON to choose the interpreter.`) +
+            (output.trim() ? `\n${capDiagnostics(output.trim())}` : '')));
+    }
+    let cases;
+    try {
+        cases = parsePytestJunitXml(report);
+    }
+    catch (error) {
+        return err(new TestRunnerExecutionError(`Could not read the pytest JUnit report for ${label}: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    const collectionErrors = cases.filter(isCollectionError);
+    const exitReason = exitCode !== null ? PYTEST_EXIT_REASONS[exitCode] : undefined;
+    if (exitReason || collectionErrors.length > 0) {
+        const reasons = collectionErrors.map(c => `${c.name}: ${c.details ?? c.message ?? 'collection failure'}`);
+        return err(new TestRunnerExecutionError(`pytest ${exitReason ?? 'reported a collection error'} for ${label} (exit code ${exitCode ?? 'unknown'}).` +
+            `\n${capDiagnostics([...reasons, output.trim()].filter(Boolean).join('\n'))}`));
+    }
+    const tests = cases.map(testCase => {
+        const { file, name } = locatePytestCase(testCase, files);
+        const failed = testCase.status === 'failed' || testCase.status === 'error';
+        const failureMessage = failed
+            ? [testCase.message, testCase.details].filter(Boolean).join('\n') || 'Test failed'
+            : undefined;
+        return {
+            name, file,
+            status: failed ? 'failed' : testCase.status === 'skipped' ? 'skipped' : 'passed',
+            ...(testCase.duration !== undefined ? { duration: testCase.duration } : {}),
+            ...(failureMessage ? { failureMessage } : {}),
+        };
+    });
+    const passed = tests.filter(t => t.status === 'passed').length;
+    const failed = tests.filter(t => t.status === 'failed').length;
+    const skipped = tests.filter(t => t.status === 'skipped').length;
+    const executionError = getTestRunnerExecutionError('pytest', label, exitCode, { passed, failed, skipped }, output);
+    if (executionError)
+        return err(executionError);
+    return ok({ total: tests.length, passed, failed, skipped, tests });
+}
+//# sourceMappingURL=pytest-junit-report.js.map

package/dist/shared/sqlite-lock-wait.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How long one attempt of an asynchronously retried write may wait for a
+ * SQLite lock (#1263).
+ *
+ * better-sqlite3 waits for a locked database synchronously, inside the call,
+ * for up to the connection's busy_timeout (5 s by default). In a one-shot CLI
+ * command that is the patience we want. In the MCP server it freezes the event
+ * loop: while another process held memory.db's write lock, background writes
+ * blocked for 5 s each, back to back, and stopped all tool calls for 10-15 s.
+ *
+ * The MCP server sets this cap. Writes routed through
+ * UnifiedMemoryManager.writeWhenUnlocked then wait at most the cap per
+ * attempt and retry asynchronously until the connection's busy_timeout has
+ * passed. Connections keep their busy_timeout, so writes not routed that way
+ * keep their full (blocking) patience.
+ *
+ * Dependency-free so any module can read it.
+ */
+/** Longest one retried write attempt blocks the MCP server's event loop on a locked database. */
+export declare const INTERACTIVE_LOCK_WAIT_MS = 200;
+/** Set the per-attempt wait for asynchronously retried writes (null: no cap). */
+export declare function setLockWaitCap(ms: number | null): void;
+/** The current cap, or null when retried writes wait the full busy_timeout per attempt. */
+export declare function getLockWaitCap(): number | null;
+/** The per-attempt wait for a requested busy_timeout, honouring the process cap. */
+export declare function capBusyTimeout(requestedMs: number): number;
+//# sourceMappingURL=sqlite-lock-wait.d.ts.map

package/dist/shared/sqlite-lock-wait.js

@@ -0,0 +1,37 @@
+/**
+ * How long one attempt of an asynchronously retried write may wait for a
+ * SQLite lock (#1263).
+ *
+ * better-sqlite3 waits for a locked database synchronously, inside the call,
+ * for up to the connection's busy_timeout (5 s by default). In a one-shot CLI
+ * command that is the patience we want. In the MCP server it freezes the event
+ * loop: while another process held memory.db's write lock, background writes
+ * blocked for 5 s each, back to back, and stopped all tool calls for 10-15 s.
+ *
+ * The MCP server sets this cap. Writes routed through
+ * UnifiedMemoryManager.writeWhenUnlocked then wait at most the cap per
+ * attempt and retry asynchronously until the connection's busy_timeout has
+ * passed. Connections keep their busy_timeout, so writes not routed that way
+ * keep their full (blocking) patience.
+ *
+ * Dependency-free so any module can read it.
+ */
+/** Longest one retried write attempt blocks the MCP server's event loop on a locked database. */
+export const INTERACTIVE_LOCK_WAIT_MS = 200;
+let lockWaitCapMs = null;
+/** Set the per-attempt wait for asynchronously retried writes (null: no cap). */
+export function setLockWaitCap(ms) {
+    if (ms !== null && (!Number.isFinite(ms) || ms < 0)) {
+        throw new RangeError(`Lock wait cap must be a non-negative number of ms, got ${ms}`);
+    }
+    lockWaitCapMs = ms === null ? null : Math.floor(ms);
+}
+/** The current cap, or null when retried writes wait the full busy_timeout per attempt. */
+export function getLockWaitCap() {
+    return lockWaitCapMs;
+}
+/** The per-attempt wait for a requested busy_timeout, honouring the process cap. */
+export function capBusyTimeout(requestedMs) {
+    return lockWaitCapMs === null ? requestedMs : Math.min(requestedMs, lockWaitCapMs);
+}
+//# sourceMappingURL=sqlite-lock-wait.js.map

package/dist/shared/sqlite-write-queue.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which SQLite connections have a write queue (#1283).
+ *
+ * UnifiedMemoryManager registers its shared memory.db connection here while it
+ * is open, with its writeWhenUnlocked queue. Modules that hold only the raw
+ * connection route writes through `writeWhenUnlockedOn` without importing
+ * unified-memory's sqlite graph: on a registered connection the write is
+ * queued (FIFO, retried asynchronously under the MCP server's lock wait cap,
+ * full busy_timeout budget), so a locked memory.db does not freeze the event
+ * loop. A write on any other connection runs now, as it always did.
+ *
+ * Dependency-free so any module can import it.
+ */
+/** A connection's FIFO write queue: runs `fn` when the database is unlocked. */
+export type WriteQueue = <T>(fn: () => T) => Promise<T>;
+/** Route writes on `db` through `queue` until unregistered. */
+export declare function registerWriteQueue(db: object, queue: WriteQueue): void;
+/** Stop routing writes on `db` (the connection is closing). */
+export declare function unregisterWriteQueue(db: object): void;
+/** True when writes on `db` are queued. */
+export declare function hasWriteQueue(db: object | null | undefined): boolean;
+/**
+ * Run a write on `db`: queued when `db` has a write queue, otherwise at once.
+ * With the queue empty and the database unlocked a queued write also runs at
+ * once, so callers see the same result as a direct write.
+ */
+export declare function writeWhenUnlockedOn<T>(db: object | null | undefined, fn: () => T): Promise<T>;
+//# sourceMappingURL=sqlite-write-queue.d.ts.map

package/dist/shared/sqlite-write-queue.js

@@ -0,0 +1,38 @@
+/**
+ * Which SQLite connections have a write queue (#1283).
+ *
+ * UnifiedMemoryManager registers its shared memory.db connection here while it
+ * is open, with its writeWhenUnlocked queue. Modules that hold only the raw
+ * connection route writes through `writeWhenUnlockedOn` without importing
+ * unified-memory's sqlite graph: on a registered connection the write is
+ * queued (FIFO, retried asynchronously under the MCP server's lock wait cap,
+ * full busy_timeout budget), so a locked memory.db does not freeze the event
+ * loop. A write on any other connection runs now, as it always did.
+ *
+ * Dependency-free so any module can import it.
+ */
+const queues = new WeakMap();
+/** Route writes on `db` through `queue` until unregistered. */
+export function registerWriteQueue(db, queue) {
+    queues.set(db, queue);
+}
+/** Stop routing writes on `db` (the connection is closing). */
+export function unregisterWriteQueue(db) {
+    queues.delete(db);
+}
+/** True when writes on `db` are queued. */
+export function hasWriteQueue(db) {
+    return db != null && queues.has(db);
+}
+/**
+ * Run a write on `db`: queued when `db` has a write queue, otherwise at once.
+ * With the queue empty and the database unlocked a queued write also runs at
+ * once, so callers see the same result as a direct write.
+ */
+export function writeWhenUnlockedOn(db, fn) {
+    const queue = db != null ? queues.get(db) : undefined;
+    if (queue)
+        return queue(fn);
+    return new Promise((resolve) => resolve(fn()));
+}
+//# sourceMappingURL=sqlite-write-queue.js.map