bernard-agent 0.8.1 → 0.9.0

package/dist/reference-resolver.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAG_SOURCE_KEY = void 0;
+exports.deriveKeyFromReference = deriveKeyFromReference;
+exports.stripToolResolvableTokens = stripToolResolvableTokens;
+exports.shouldSkipResolver = shouldSkipResolver;
+exports.buildRecentTurnsBlock = buildRecentTurnsBlock;
+exports.validateAgainstMemory = validateAgainstMemory;
+exports.resolveReferences = resolveReferences;
+exports.renderResolvedBlock = renderResolvedBlock;
+const ai_1 = require("ai");
+const index_js_1 = require("./providers/index.js");
+const logger_js_1 = require("./logger.js");
+const memory_js_1 = require("./memory.js");
+/** Sentinel sourceKey used for resolutions drawn from the RAG knowledge base. */
+exports.RAG_SOURCE_KEY = 'rag';
+/**
+ * Derive a memory key from a natural-language reference phrase.
+ * Strips a leading possessive/demonstrative and replaces internal spaces with dashes.
+ *
+ * Examples: "my brother" → "brother", "the car" → "car", "my brother Tom" → "brother-tom".
+ */
+function deriveKeyFromReference(reference) {
+    const stripped = reference
+        .toLowerCase()
+        .trim()
+        .replace(/^(my|our|the|her|his|their|that|this)\s+/, '');
+    return (0, memory_js_1.sanitizeKey)(stripped.replace(/\s+/g, '-'));
+}
+const RESOLVER_MAX_TOKENS = 512;
+const RESOLVER_SYSTEM_PROMPT = `You resolve references in a user's request against their stored personal memory and knowledge base.
+You DO NOT retrieve facts unprompted. You only resolve phrases the user already wrote.
+
+Given the user's input, a list of available memory entries, and (optionally) relevant facts from the knowledge base, identify every phrase that refers to a specific person, thing, routine, or plan.
+
+For each phrase:
+- If exactly ONE memory entry unambiguously matches the reference, include it in \`entries\` with its memory key as \`sourceKey\`.
+- If no memory entry matches but a fact in "## Relevant known facts" unambiguously identifies the person or thing, include it in \`entries\` with \`sourceKey: "rag"\`. Draw \`resolvedTo\` from the fact text.
+- Prefer a memory entry over a RAG fact when both match the same phrase.
+- If MULTIPLE memory entries plausibly match, stop and return status \`ambiguous\` for the FIRST ambiguous reference with 2-4 candidates. Do not guess.
+- If the phrase clearly names a specific person, organization, or concrete thing (e.g. "my brother", "my dentist", "the car", "aaron") AND neither memory nor known facts match AND the reference was NOT already introduced in "## Recent conversation" AND resolving it is necessary to complete the request, stop and return status \`unknown\` for the FIRST such reference. The caller will prompt the user.
+- If the reference was already introduced or clarified in "## Recent conversation" (e.g. the user or assistant named the person/thing earlier in this session), return \`noop\` for that phrase. The downstream agent has full history access and can resolve it without our help.
+- Generic words ("the file", "this code", "the bug", "the PR", "my response", "my email") that don't point at a stored entity are NOT references — omit and prefer \`noop\`.
+- Tool-resolvable identifiers (URLs like \`https://github.com/...\`, PR/issue numbers like \`#3802\` or \`PR 3802\`, file paths like \`/home/user/foo.md\`, commit hashes, package names, API endpoints) are NOT references — the downstream agent will fetch them with \`shell\`, \`gh\`, \`web_read\`, or similar tools. Omit them and prefer \`noop\`. Example: for "review PR https://github.com/foo/bar/pull/123", return \`{"status":"noop"}\`.
+
+Output strict JSON matching one of these shapes and nothing else:
+  {"status":"noop"}
+  {"status":"resolved","entries":[{"phrase":"...","resolvedTo":"...","sourceKey":"..."}]}
+  {"status":"ambiguous","reference":"...","candidates":[{"label":"...","sourceKey":"...","preview":"..."}]}
+  {"status":"unknown","reference":"..."}
+
+Rules:
+- Be conservative. Prefer \`noop\` over guessing.
+- Only one \`unknown\` or \`ambiguous\` per turn — pick the most important reference.
+- For memory-sourced entries, use only keys from the provided memory list. For knowledge-base-sourced entries, use the literal string \`"rag"\`.
+- \`resolvedTo\` is a short human-readable expansion drawn from the source content (not a raw dump).
+- \`preview\` in candidates is a short one-line summary (~60 chars) distinguishing candidates.`;
+const POSSESSIVE_PRESCAN = /\b(my|our|her|his|their)\s+\w+/i;
+// Require 2+ words after "the/this/that" to avoid generic "the bug" / "this code" false-positives.
+const DEMONSTRATIVE_PRESCAN = /\b(the|this|that)\s+\w+\s+\w+/i;
+const URL_RE = /https?:\/\/\S+/gi;
+const GH_REF_RE = /\b(?:PR|issue|pull|issues)[\s#]*\d+\b|#\d+\b/gi;
+const FILE_PATH_RE = /(?<!\S)(?:~|\.{1,2})?\/[\w./\-]+/g;
+const COMMIT_HASH_RE = /\b[a-f0-9]{7,40}\b/gi;
+/**
+ * Remove tokens that the main agent can resolve with tools (URLs, PR/issue refs,
+ * file paths, commit hashes) before the reference resolver sees the input.
+ * Mirrors {@link ./image.ts:stripImagePaths} in shape and intent.
+ */
+function stripToolResolvableTokens(text) {
+    return text
+        .replace(URL_RE, ' ')
+        .replace(GH_REF_RE, ' ')
+        .replace(FILE_PATH_RE, ' ')
+        .replace(COMMIT_HASH_RE, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function shouldSkipResolver(userInput) {
+    // Run the resolver when the prompt contains a strong reference signal (possessive, or a
+    // multi-word demonstrative phrase). Even when memory is empty the resolver may return
+    // `unknown` and prompt the user to fill in the missing entity.
+    return !(POSSESSIVE_PRESCAN.test(userInput) || DEMONSTRATIVE_PRESCAN.test(userInput));
+}
+function buildHintsBlock(hints) {
+    if (!hints || hints.size === 0)
+        return '';
+    const lines = ['## Persisted hints (honor these first, do not re-ask)'];
+    for (const [phrase, sourceKey] of hints.entries()) {
+        lines.push(`- "${phrase}" → ${sourceKey}`);
+    }
+    return lines.join('\n');
+}
+const MAX_MEMORY_ENTRIES_IN_PROMPT = 40;
+const MAX_MEMORY_PREVIEW_CHARS = 140;
+const MAX_RAG_FACTS_IN_PROMPT = 12;
+const MAX_RAG_FACT_CHARS = 240;
+const RECENT_TURNS_IN_PROMPT = 4;
+const MAX_TURN_PREVIEW_CHARS = 300;
+function extractMessageText(msg) {
+    if (typeof msg.content === 'string')
+        return msg.content;
+    if (!Array.isArray(msg.content))
+        return '';
+    const parts = [];
+    for (const part of msg.content) {
+        if (part.type === 'text' && typeof part.text === 'string') {
+            parts.push(part.text);
+        }
+    }
+    return parts.join(' ');
+}
+function buildRecentTurnsBlock(history) {
+    if (history.length === 0)
+        return '';
+    const turns = [];
+    for (let i = history.length - 1; i >= 0 && turns.length < RECENT_TURNS_IN_PROMPT; i--) {
+        const msg = history[i];
+        if (msg.role !== 'user' && msg.role !== 'assistant')
+            continue;
+        const text = extractMessageText(msg).trim().replace(/\s+/g, ' ');
+        if (text.length === 0)
+            continue;
+        const preview = text.length > MAX_TURN_PREVIEW_CHARS ? text.slice(0, MAX_TURN_PREVIEW_CHARS) + '…' : text;
+        turns.unshift({ role: msg.role, text: preview });
+    }
+    if (turns.length === 0)
+        return '';
+    const lines = ['## Recent conversation'];
+    for (const t of turns) {
+        lines.push(`- ${t.role}: ${t.text}`);
+    }
+    return lines.join('\n');
+}
+function buildRagBlock(facts) {
+    if (facts.length === 0)
+        return '';
+    const lines = ['## Relevant known facts'];
+    const selected = facts.slice(0, MAX_RAG_FACTS_IN_PROMPT);
+    for (const f of selected) {
+        const trimmed = f.fact.trim().replace(/\s+/g, ' ');
+        const preview = trimmed.length > MAX_RAG_FACT_CHARS ? trimmed.slice(0, MAX_RAG_FACT_CHARS) + '…' : trimmed;
+        lines.push(`- ${preview}`);
+    }
+    return lines.join('\n');
+}
+function buildMemoryBlock(contents) {
+    const lines = ['## Available memory entries'];
+    const entries = Array.from(contents.entries());
+    const selected = entries.slice(0, MAX_MEMORY_ENTRIES_IN_PROMPT);
+    for (const [key, content] of selected) {
+        const trimmed = content.trim().replace(/\s+/g, ' ');
+        const preview = trimmed.length > MAX_MEMORY_PREVIEW_CHARS
+            ? trimmed.slice(0, MAX_MEMORY_PREVIEW_CHARS) + '…'
+            : trimmed;
+        lines.push(`- ${key}: ${preview}`);
+    }
+    const omitted = entries.length - selected.length;
+    if (omitted > 0) {
+        lines.push(`- … ${omitted} more entr${omitted === 1 ? 'y' : 'ies'} omitted for brevity`);
+    }
+    return lines.join('\n');
+}
+function parseResolverResponse(text) {
+    const match = text.match(/\{[\s\S]*\}/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (parsed?.status === 'noop')
+            return { status: 'noop' };
+        if (parsed?.status === 'resolved' && Array.isArray(parsed.entries)) {
+            const entries = parsed.entries
+                .filter((e) => e &&
+                typeof e.phrase === 'string' &&
+                typeof e.resolvedTo === 'string' &&
+                typeof e.sourceKey === 'string')
+                .map((e) => ({ phrase: e.phrase, resolvedTo: e.resolvedTo, sourceKey: e.sourceKey }));
+            if (entries.length === 0)
+                return { status: 'noop' };
+            return { status: 'resolved', entries };
+        }
+        if (parsed?.status === 'ambiguous' &&
+            typeof parsed.reference === 'string' &&
+            Array.isArray(parsed.candidates)) {
+            const candidates = parsed.candidates
+                .filter((c) => c &&
+                typeof c.label === 'string' &&
+                typeof c.sourceKey === 'string' &&
+                typeof c.preview === 'string')
+                .slice(0, 4)
+                .map((c) => ({ label: c.label, sourceKey: c.sourceKey, preview: c.preview }));
+            if (candidates.length < 2)
+                return { status: 'noop' };
+            return { status: 'ambiguous', reference: parsed.reference, candidates };
+        }
+        if (parsed?.status === 'unknown' &&
+            typeof parsed.reference === 'string' &&
+            parsed.reference.trim().length > 0) {
+            return { status: 'unknown', reference: parsed.reference.trim() };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function validateAgainstMemory(result, memoryKeys, ragAvailable = false) {
+    const isValidSource = (key) => (ragAvailable && key === exports.RAG_SOURCE_KEY) || memoryKeys.has(key);
+    if (result.status === 'resolved') {
+        const safe = result.entries.filter((e) => isValidSource(e.sourceKey));
+        return safe.length === 0 ? { status: 'noop' } : { status: 'resolved', entries: safe };
+    }
+    if (result.status === 'ambiguous') {
+        const safe = result.candidates.filter((c) => isValidSource(c.sourceKey));
+        return safe.length < 2
+            ? { status: 'noop' }
+            : { status: 'ambiguous', reference: result.reference, candidates: safe };
+    }
+    return result;
+}
+async function resolveReferences(userInput, memoryStore, config, hints, abortSignal, ragStore, recentHistory) {
+    const contents = memoryStore.getAllMemoryContents();
+    contents.delete(memory_js_1.REWRITER_HINTS_KEY);
+    const memoryKeys = Array.from(contents.keys());
+    if (shouldSkipResolver(userInput)) {
+        (0, logger_js_1.debugLog)('reference-resolver:skip', {
+            reason: 'no-reference-tokens',
+            prompt: userInput,
+        });
+        return { status: 'noop' };
+    }
+    let ragFacts = [];
+    if (ragStore) {
+        try {
+            ragFacts = await ragStore.search(userInput);
+            (0, logger_js_1.debugLog)('reference-resolver:rag-hits', { count: ragFacts.length });
+        }
+        catch (err) {
+            (0, logger_js_1.debugLog)('reference-resolver:rag-error', err instanceof Error ? err.message : String(err));
+            ragFacts = [];
+        }
+    }
+    const historyBlock = recentHistory ? buildRecentTurnsBlock(recentHistory) : '';
+    const userMessage = [
+        `## User request\n${userInput}`,
+        historyBlock,
+        buildMemoryBlock(contents),
+        buildRagBlock(ragFacts),
+        buildHintsBlock(hints),
+    ]
+        .filter((s) => s.length > 0)
+        .join('\n\n');
+    (0, logger_js_1.debugLog)('reference-resolver:request', {
+        prompt: userInput,
+        memoryKeys,
+        ragFactCount: ragFacts.length,
+        recentTurnCount: historyBlock ? historyBlock.split('\n').length - 1 : 0,
+        hints: hints ? Array.from(hints.entries()) : [],
+    });
+    try {
+        const result = await (0, ai_1.generateText)({
+            model: (0, index_js_1.getModelForConfig)(config, config.provider, config.model),
+            providerOptions: (0, index_js_1.getProviderOptionsForConfig)(config, config.provider),
+            system: RESOLVER_SYSTEM_PROMPT,
+            messages: [{ role: 'user', content: userMessage }],
+            maxSteps: 1,
+            maxTokens: RESOLVER_MAX_TOKENS,
+            abortSignal,
+        });
+        if (!result.text) {
+            (0, logger_js_1.debugLog)('reference-resolver:empty-response', null);
+            return { status: 'noop' };
+        }
+        (0, logger_js_1.debugLog)('reference-resolver:response', result.text.slice(0, 200));
+        const parsed = parseResolverResponse(result.text);
+        if (!parsed) {
+            (0, logger_js_1.debugLog)('reference-resolver:parse-failed', result.text.slice(0, 200));
+            return { status: 'noop' };
+        }
+        const validated = validateAgainstMemory(parsed, new Set(memoryKeys), ragFacts.length > 0);
+        (0, logger_js_1.debugLog)('reference-resolver:result', validated);
+        return validated;
+    }
+    catch (err) {
+        (0, logger_js_1.debugLog)('reference-resolver:error', err instanceof Error ? err.message : String(err));
+        return { status: 'noop' };
+    }
+}
+const MAX_RENDERED_FIELD_CHARS = 200;
+function oneLine(value, max = MAX_RENDERED_FIELD_CHARS) {
+    const flat = value
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > max ? flat.slice(0, max) + '…' : flat;
+}
+function renderResolvedBlock(entries) {
+    if (entries.length === 0)
+        return '';
+    const lines = ['## Resolved References'];
+    lines.push("These references resolve phrases in the user's request from stored memory or the knowledge base. Treat as hints, not rules. If a resolution seems wrong for the current task, cross-check with the memory tool or ask.");
+    for (const e of entries) {
+        const phrase = oneLine(e.phrase, 80);
+        const resolvedTo = oneLine(e.resolvedTo);
+        if (e.sourceKey === exports.RAG_SOURCE_KEY) {
+            lines.push(`- "${phrase}" → ${resolvedTo} (from knowledge base)`);
+        }
+        else {
+            const sourceKey = (0, memory_js_1.sanitizeKey)(e.sourceKey);
+            lines.push(`- "${phrase}" → ${resolvedTo} (from memory: ${sourceKey})`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=reference-resolver.js.map

package/dist/reference-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-resolver.js","sourceRoot":"","sources":["../src/reference-resolver.ts"],"names":[],"mappings":";;;AAgBA,wDAMC;AA+DD,8DAQC;AAED,gDAKC;AA8BD,sDAkBC;AAoFD,sDAkBC;AAED,8CAgFC;AAYD,kDAiBC;AAzWD,2BAAoD;AACpD,mDAAsF;AACtF,2CAAuC;AACvC,2CAAgF;AAIhF,iFAAiF;AACpE,QAAA,cAAc,GAAG,KAAK,CAAC;AAEpC;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,SAAiB;IACtD,MAAM,QAAQ,GAAG,SAAS;SACvB,WAAW,EAAE;SACb,IAAI,EAAE;SACN,OAAO,CAAC,0CAA0C,EAAE,EAAE,CAAC,CAAC;IAC3D,OAAO,IAAA,uBAAW,EAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AACpD,CAAC;AAoBD,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;+FA0BgE,CAAC;AAEhG,MAAM,kBAAkB,GAAG,iCAAiC,CAAC;AAC7D,mGAAmG;AACnG,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AAE/D,MAAM,MAAM,GAAG,kBAAkB,CAAC;AAClC,MAAM,SAAS,GAAG,gDAAgD,CAAC;AACnE,MAAM,YAAY,GAAG,mCAAmC,CAAC;AACzD,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C;;;;GAIG;AACH,SAAgB,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI;SACR,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC;SAC1B,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAgB,kBAAkB,CAAC,SAAiB;IAClD,wFAAwF;IACxF,sFAAsF;IACtF,+DAA+D;IAC/D,OAAO,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,eAAe,CAAC,KAA2B;IAClD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAa,CAAC,uDAAuD,CAAC,CAAC;IAClF,KAAK,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,MAAM,MAAM,OAAO,SAAS,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,4BAA4B,GAAG,EAAE,CAAC;AACxC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AACnC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACjC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC,SAAS,kBAAkB,CAAC,GAAgB;IAC1C,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IACxD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAgB,qBAAqB,CAAC,OAAsB;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC,EAAE,EAAE,CAAC;QACtF,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW;YAAE,SAAS;QAC9D,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,GAAG,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5F,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,MAAM,KAAK,GAAa,CAAC,wBAAwB,CAAC,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,aAAa,CAAC,KAAwB;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,MAAM,KAAK,GAAa,CAAC,yBAAyB,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC;IACzD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACnD,MAAM,OAAO,GACX,OAAO,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QAC7F,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,gBAAgB,CAAC,QAA6B;IACrD,MAAM,KAAK,GAAa,CAAC,6BAA6B,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,4BAA4B,CAAC,CAAC;IAChE,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACpD,MAAM,OAAO,GACX,OAAO,CAAC,MAAM,GAAG,wBAAwB;YACvC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC,GAAG,GAAG;YAClD,CAAC,CAAC,OAAO,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IACjD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,aAAa,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,sBAAsB,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,MAAM,EAAE,MAAM,KAAK,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACzD,IAAI,MAAM,EAAE,MAAM,KAAK,UAAU,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACnE,MAAM,OAAO,GAAoB,MAAM,CAAC,OAAO;iBAC5C,MAAM,CACL,CAAC,CAAM,EAAE,EAAE,CACT,CAAC;gBACD,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;gBAC5B,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;gBAChC,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAClC;iBACA,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;YAC7F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YACpD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;QACzC,CAAC;QACD,IACE,MAAM,EAAE,MAAM,KAAK,WAAW;YAC9B,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YACpC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAChC,CAAC;YACD,MAAM,UAAU,GAAgB,MAAM,CAAC,UAAU;iBAC9C,MAAM,CACL,CAAC,CAAM,EAAE,EAAE,CACT,CAAC;gBACD,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;gBAC3B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;gBAC/B,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAChC;iBACA,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;iBACX,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACrF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YACrD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC;QAC1E,CAAC;QACD,IACE,MAAM,EAAE,MAAM,KAAK,SAAS;YAC5B,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YACpC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAClC,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAgB,qBAAqB,CACnC,MAAqB,EACrB,UAAuB,EACvB,eAAwB,KAAK;IAE7B,MAAM,aAAa,GAAG,CAAC,GAAW,EAAE,EAAE,CACpC,CAAC,YAAY,IAAI,GAAG,KAAK,sBAAc,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClE,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACxF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACzE,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC;YACpB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE;YACpB,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAEM,KAAK,UAAU,iBAAiB,CACrC,SAAiB,EACjB,WAAwB,EACxB,MAAqB,EACrB,KAA2B,EAC3B,WAAyB,EACzB,QAAmB,EACnB,aAA6B;IAE7B,MAAM,QAAQ,GAAG,WAAW,CAAC,oBAAoB,EAAE,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,8BAAkB,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAE/C,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,IAAA,oBAAQ,EAAC,yBAAyB,EAAE;YAClC,MAAM,EAAE,qBAAqB;YAC7B,MAAM,EAAE,SAAS;SAClB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,IAAI,QAAQ,GAAsB,EAAE,CAAC;IACrC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC5C,IAAA,oBAAQ,EAAC,6BAA6B,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAA,oBAAQ,EAAC,8BAA8B,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3F,QAAQ,GAAG,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/E,MAAM,WAAW,GAAG;QAClB,oBAAoB,SAAS,EAAE;QAC/B,YAAY;QACZ,gBAAgB,CAAC,QAAQ,CAAC;QAC1B,aAAa,CAAC,QAAQ,CAAC;QACvB,eAAe,CAAC,KAAK,CAAC;KACvB;SACE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SAC3B,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,IAAA,oBAAQ,EAAC,4BAA4B,EAAE;QACrC,MAAM,EAAE,SAAS;QACjB,UAAU;QACV,YAAY,EAAE,QAAQ,CAAC,MAAM;QAC7B,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;KAChD,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,iBAAY,EAAC;YAChC,KAAK,EAAE,IAAA,4BAAiB,EAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC;YAC/D,eAAe,EAAE,IAAA,sCAA2B,EAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC;YACrE,MAAM,EAAE,sBAAsB;YAC9B,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;YAClD,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,mBAAmB;YAC9B,WAAW;SACZ,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,IAAA,oBAAQ,EAAC,mCAAmC,EAAE,IAAI,CAAC,CAAC;YACpD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC5B,CAAC;QACD,IAAA,oBAAQ,EAAC,6BAA6B,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACnE,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAA,oBAAQ,EAAC,iCAAiC,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACvE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC5B,CAAC;QACD,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC1F,IAAA,oBAAQ,EAAC,2BAA2B,EAAE,SAAS,CAAC,CAAC;QACjD,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAA,oBAAQ,EAAC,0BAA0B,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACvF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,SAAS,OAAO,CAAC,KAAa,EAAE,MAAc,wBAAwB;IACpE,MAAM,IAAI,GAAG,KAAK;SACf,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC;SAC1B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IACV,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,SAAgB,mBAAmB,CAAC,OAAwB;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,KAAK,GAAa,CAAC,wBAAwB,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CACR,wNAAwN,CACzN,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACrC,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,CAAC,CAAC,SAAS,KAAK,sBAAc,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,MAAM,MAAM,OAAO,UAAU,wBAAwB,CAAC,CAAC;QACpE,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,GAAG,IAAA,uBAAW,EAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,MAAM,MAAM,OAAO,UAAU,kBAAkB,SAAS,GAAG,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/reference-tool-lookup.d.ts

@@ -0,0 +1,37 @@
+import type { BernardConfig } from './config.js';
+export type ReferenceLookupResult = {
+    status: 'none';
+} | {
+    status: 'found';
+    resolvedTo: string;
+    toolName: string;
+} | {
+    status: 'ambiguous';
+};
+/**
+ * Returns true when the named tool is safe for the resolver lookup pass.
+ *
+ * An MCP tool is identified by `__` in its name (the `@ai-sdk/mcp` convention).
+ * MCP tools must additionally match {@link READONLY_SUFFIX_RE}. Built-in tools
+ * are restricted to {@link ALWAYS_ALLOWED_BUILTINS} unless explicitly extended
+ * via `extraAllowed` (sourced from `BERNARD_LOOKUP_TOOLS`).
+ */
+export declare function isAllowedLookupTool(name: string, extraAllowed?: string[]): boolean;
+interface ToolDescriptor {
+    name: string;
+    description: string;
+    schema?: unknown;
+}
+interface SelectResult {
+    toolName: string;
+    args: unknown;
+}
+export declare function selectLookupTool(reference: string, candidates: ToolDescriptor[], config: BernardConfig, abortSignal?: AbortSignal): Promise<SelectResult | null>;
+export declare function executeLookupTool(toolName: string, args: unknown, tools: Record<string, any>, abortSignal?: AbortSignal): Promise<string | null>;
+export declare function interpretLookupResult(reference: string, toolName: string, toolResult: string, config: BernardConfig, abortSignal?: AbortSignal): Promise<ReferenceLookupResult>;
+/**
+ * Runs select → execute → interpret. Fail-open: any error yields
+ * `{ status: 'none' }` so the caller falls through to the user-prompt path.
+ */
+export declare function runReferenceLookup(reference: string, tools: Record<string, any>, config: BernardConfig, abortSignal?: AbortSignal): Promise<ReferenceLookupResult>;
+export {};