@oscharko-dev/keiko-server 0.2.0

package/dist/grounded-qa-multi-source.d.ts

@@ -0,0 +1,38 @@
+import { type ChatMessage as GatewayChatMessage } from "@oscharko-dev/keiko-model-gateway";
+import type { ModelPort } from "@oscharko-dev/keiko-harness";
+import { type ConnectedContextPack, type ExplorationBudget } from "@oscharko-dev/keiko-contracts/connected-context";
+import { type ChatConnectedScope, type GroundedAnswerContextPackSummary } from "@oscharko-dev/keiko-contracts/bff-wire";
+import type { RouteResult } from "./routes.js";
+import type { Redactor, UiHandlerDeps } from "./deps.js";
+import type { Chat } from "./store/index.js";
+import { type OrchestratorInput, type RetrievalOnlyOutput } from "./grounded-orchestrator.js";
+import { type GroundedAnswerPayload } from "./grounded-answer.js";
+export declare function buildConnectedScopes(chat: Chat): readonly ChatConnectedScope[];
+export declare function splitExplorationBudget(base: ExplorationBudget, n: number): ExplorationBudget;
+export declare function sourceLabels(scopes: readonly ChatConnectedScope[]): readonly string[];
+export declare function mergeContextPackSummaries(summaries: readonly GroundedAnswerContextPackSummary[]): GroundedAnswerContextPackSummary;
+export interface LabeledPack {
+    readonly label: string;
+    readonly pack: ConnectedContextPack;
+}
+export declare function buildMultiSourceGatewayMessages(question: string, labeledPacks: readonly LabeledPack[], redactor: Redactor): readonly GatewayChatMessage[];
+export type GroundedRetriever = (input: OrchestratorInput) => Promise<RetrievalOnlyOutput>;
+export declare function defaultRetriever(signal: AbortSignal): GroundedRetriever;
+export type MultiSourceAnswerer = (question: string, labeledPacks: readonly LabeledPack[]) => Promise<GroundedAnswerPayload>;
+export declare function createMultiSourceAnswerer(model: ModelPort, modelId: string, redactor: Redactor, signal: AbortSignal): MultiSourceAnswerer;
+export interface MultiSourceAskInput {
+    readonly chat: Chat;
+    readonly scopes: readonly ChatConnectedScope[];
+    readonly content: string;
+    readonly modelId: string;
+    readonly deps: UiHandlerDeps;
+    readonly retriever: GroundedRetriever;
+    readonly answerer: MultiSourceAnswerer;
+    readonly signal: AbortSignal;
+    readonly preSkipped?: readonly {
+        readonly label: string;
+        readonly message: string;
+    }[];
+}
+export declare function runMultiSourceAsk(ctx: MultiSourceAskInput): Promise<RouteResult>;
+//# sourceMappingURL=grounded-qa-multi-source.d.ts.map

package/dist/grounded-qa-multi-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounded-qa-multi-source.d.ts","sourceRoot":"","sources":["../src/grounded-qa-multi-source.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,WAAW,IAAI,kBAAkB,EACvC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAG7D,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAGvB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,gCAAgC,EAGtC,MAAM,wCAAwC,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB,MAAM,4BAA4B,CAAC;AAKpC,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,sBAAsB,CAAC;AA0B9B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,kBAAkB,EAAE,CAE9E;AAOD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAY5F;AAgBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,MAAM,EAAE,CAUrF;AAgFD,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,gCAAgC,EAAE,GACrD,gCAAgC,CAsBlC;AAID,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC;AAoBD,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,QAAQ,EAAE,QAAQ,GACjB,SAAS,kBAAkB,EAAE,CAE/B;AAmFD,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAI3F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAUvE;AAID,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,SAAS,WAAW,EAAE,KACjC,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAEpC,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,WAAW,GAClB,mBAAmB,CAqBrB;AAyBD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAG7B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvF;AAgND,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CA4CtF"}

package/dist/grounded-qa-multi-source.js

@@ -0,0 +1,461 @@
+// Epic #532 — multi-source (1+N) grounded retrieval merge. A chat may connect N folders/files at
+// once; asking one question must search EVERY connected source and return ONE merged answer with
+// per-source attribution. This module owns the new branch only. The single-source path
+// (`grounded-qa.ts`) is deliberately untouched so its wire output stays byte-identical (AC5).
+//
+// The path is split out of `grounded-qa.ts` to keep both files under the 400-LOC bound; it imports
+// the shared formatters/projection/persistence helpers (now exported) so the two paths build their
+// gateway messages, citations, and evidence from the exact same primitives.
+import { basename } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { ContextOverflowError, resolveCostClass, } from "@oscharko-dev/keiko-model-gateway";
+import { persistConnectedContextEvidence } from "@oscharko-dev/keiko-evidence";
+import { CANDIDATE_OMISSION_REASONS, DEFAULT_EXPLORATION_BUDGET, } from "@oscharko-dev/keiko-contracts/connected-context";
+import { buildGroundedAnswerContextPackSummary, } from "@oscharko-dev/keiko-contracts/bff-wire";
+import { currentRedactionSecrets } from "./deps.js";
+import { ClarificationNeededError, clarificationUserMessage, retrieveConnectedContextPack, } from "./grounded-orchestrator.js";
+import { microIndexForGroundedScope } from "./grounded-context-index.js";
+import { GROUNDED_SYSTEM_PROMPT } from "./grounded-prompt.js";
+import { rememberGroundedTurn } from "./grounded-turn-registry.js";
+import { assertUsableAssistantContent } from "./assistant-response.js";
+import { normalizeGroundedAnswerPayload, } from "./grounded-answer.js";
+import { buildCitations, buildQuery, buildSelectedScopeFrom, clarificationRequest, deriveScopeIdFrom, ensureNotCancelled, evidenceLines, internalError, isValidGroundedPack, mappedGatewayError, mappedWorkspaceError, modelInputPromptByteLimit, packBudgetSummary, persistGroundedExchange, promptByteLength, redactString, uncertaintyLines, withPromptExcerptByteLimit, } from "./grounded-qa.js";
+// ─── Canonical reader + label/budget helpers ──────────────────────────────────
+// Canonical reader rule (Epic #532 contract): `connectedScopes` supersedes the legacy single
+// `connectedScope`. Readers must NOT mix the two — the list, when present, is authoritative.
+export function buildConnectedScopes(chat) {
+    return chat.connectedScopes ?? (chat.connectedScope ? [chat.connectedScope] : []);
+}
+// Splits a base budget across n sources so total fan-out work stays bounded regardless of N.
+// Per-source dimensions floor-divide with a Math.max(1, …) floor so a source is never starved to
+// zero. `rerankCallsMax` is left UNCHANGED (it is 0 by default and is a per-source cap, not a
+// shared pool). n=1 returns the base unchanged so the single path is unaffected if it ever routes
+// through here.
+export function splitExplorationBudget(base, n) {
+    if (n <= 1)
+        return base;
+    const split = (value) => Math.max(1, Math.floor(value / n));
+    return {
+        searchCallsMax: split(base.searchCallsMax),
+        filesReadMax: split(base.filesReadMax),
+        excerptBytesMax: split(base.excerptBytesMax),
+        modelInputTokensMax: split(base.modelInputTokensMax),
+        modelOutputTokensMax: split(base.modelOutputTokensMax),
+        elapsedMsMax: split(base.elapsedMsMax),
+        rerankCallsMax: base.rerankCallsMax,
+    };
+}
+function rawSourceLabel(cs) {
+    return cs.root === undefined ? "project" : basename(cs.root);
+}
+function labelDisambiguator(cs) {
+    const hash = createHash("sha256")
+        .update(cs.root ?? "")
+        .digest("hex");
+    return `~${hash.slice(0, 6)}`;
+}
+// Human-readable per-source labels, stable in scopes order. Label = basename(root) or "project"
+// when root is undefined. Duplicate labels are disambiguated by appending a short hash of the full
+// root so two sources that share a basename remain distinguishable in citations.
+export function sourceLabels(scopes) {
+    const counts = new Map();
+    for (const cs of scopes) {
+        const raw = rawSourceLabel(cs);
+        counts.set(raw, (counts.get(raw) ?? 0) + 1);
+    }
+    return scopes.map((cs) => {
+        const raw = rawSourceLabel(cs);
+        return (counts.get(raw) ?? 0) > 1 ? `${raw}${labelDisambiguator(cs)}` : raw;
+    });
+}
+// ─── Merged context-pack summary ──────────────────────────────────────────────
+function zeroOmittedCounts() {
+    const counts = {};
+    for (const reason of CANDIDATE_OMISSION_REASONS)
+        counts[reason] = 0;
+    return counts;
+}
+function sumUsage(summaries) {
+    return summaries.reduce((acc, s) => ({
+        searchCalls: acc.searchCalls + s.usage.searchCalls,
+        filesRead: acc.filesRead + s.usage.filesRead,
+        excerptBytes: acc.excerptBytes + s.usage.excerptBytes,
+        modelInputTokens: acc.modelInputTokens + s.usage.modelInputTokens,
+        modelOutputTokens: acc.modelOutputTokens + s.usage.modelOutputTokens,
+        elapsedMs: acc.elapsedMs + s.usage.elapsedMs,
+        rerankCalls: acc.rerankCalls + s.usage.rerankCalls,
+    }), {
+        searchCalls: 0,
+        filesRead: 0,
+        excerptBytes: 0,
+        modelInputTokens: 0,
+        modelOutputTokens: 0,
+        elapsedMs: 0,
+        rerankCalls: 0,
+    });
+}
+function sumBudget(summaries) {
+    return summaries.reduce((acc, s) => ({
+        searchCallsMax: acc.searchCallsMax + s.budget.searchCallsMax,
+        filesReadMax: acc.filesReadMax + s.budget.filesReadMax,
+        excerptBytesMax: acc.excerptBytesMax + s.budget.excerptBytesMax,
+        modelInputTokensMax: acc.modelInputTokensMax + s.budget.modelInputTokensMax,
+        modelOutputTokensMax: acc.modelOutputTokensMax + s.budget.modelOutputTokensMax,
+        elapsedMsMax: acc.elapsedMsMax + s.budget.elapsedMsMax,
+        rerankCallsMax: acc.rerankCallsMax + s.budget.rerankCallsMax,
+    }), {
+        searchCallsMax: 0,
+        filesReadMax: 0,
+        excerptBytesMax: 0,
+        modelInputTokensMax: 0,
+        modelOutputTokensMax: 0,
+        elapsedMsMax: 0,
+        rerankCallsMax: 0,
+    });
+}
+function mergeOmittedCounts(summaries) {
+    const merged = zeroOmittedCounts();
+    for (const s of summaries) {
+        for (const reason of CANDIDATE_OMISSION_REASONS) {
+            merged[reason] += s.omittedCounts[reason];
+        }
+    }
+    return merged;
+}
+// `fileCount` is -1 (the workspace-root sentinel) if ANY source is a workspace-root scope; else it
+// is the sum of the per-source file counts. `scopeId` folds every source's display fingerprint into
+// one deterministic id so the merged summary is stable for a given chat-scope binding.
+function mergedFileCount(summaries) {
+    if (summaries.some((s) => s.fileCount === -1))
+        return -1;
+    return summaries.reduce((acc, s) => acc + s.fileCount, 0);
+}
+export function mergeContextPackSummaries(summaries) {
+    const [first] = summaries;
+    if (first === undefined) {
+        throw new Error("mergeContextPackSummaries requires at least one summary");
+    }
+    return {
+        schemaVersion: first.schemaVersion,
+        scopeId: `scope-${createHash("sha256")
+            .update(summaries.map((s) => s.scopeId).join("|"))
+            .digest("hex")
+            .slice(0, 8)}`,
+        scopeKind: first.scopeKind,
+        fileCount: mergedFileCount(summaries),
+        queryKind: first.queryKind,
+        usage: sumUsage(summaries),
+        budget: sumBudget(summaries),
+        citationCount: summaries.reduce((acc, s) => acc + s.citationCount, 0),
+        omittedCount: summaries.reduce((acc, s) => acc + s.omittedCount, 0),
+        omittedCounts: mergeOmittedCounts(summaries),
+        uncertaintyCount: summaries.reduce((acc, s) => acc + s.uncertaintyCount, 0),
+        elapsedMs: summaries.reduce((acc, s) => acc + s.elapsedMs, 0),
+    };
+}
+function sourceSection(entry, index, redactor) {
+    const { label, pack } = entry;
+    return [
+        `### Source ${String(index + 1)}: ${label}`,
+        `- budget/usage: ${packBudgetSummary(pack)}`,
+        `- omitted evidence atoms: ${String(pack.omitted.length)}`,
+        "",
+        "Repository evidence excerpts:",
+        ...evidenceLines(pack, redactor),
+        "",
+        "Known uncertainty from retrieval:",
+        ...uncertaintyLines(pack, redactor),
+        "",
+    ];
+}
+// Same system message as the single-source path; the user message lists each source under its own
+// header so the model can attribute every claim to a source label in addition to the file ref.
+export function buildMultiSourceGatewayMessages(question, labeledPacks, redactor) {
+    return budgetedMultiSourceGatewayMessages(question, labeledPacks, redactor);
+}
+function buildRawMultiSourceGatewayMessages(question, labeledPacks, redactor) {
+    const sections = labeledPacks.flatMap((entry, index) => sourceSection(entry, index, redactor));
+    const userContent = [
+        "User question:",
+        redactString(redactor, question),
+        "",
+        `Connected sources (${String(labeledPacks.length)}). For every repository claim, attribute it`,
+        "to its source label (e.g. [source: api] src/file.ts:10-20) in addition to the file reference.",
+        "",
+        ...sections,
+    ].join("\n");
+    return [
+        { role: "system", content: GROUNDED_SYSTEM_PROMPT },
+        { role: "user", content: userContent },
+    ];
+}
+function multiSourceExcerptCount(labeledPacks) {
+    return labeledPacks.reduce((count, entry) => count + entry.pack.files.reduce((fileCount, file) => fileCount + file.excerpts.length, 0), 0);
+}
+function withMultiSourcePromptExcerptByteLimit(labeledPacks, maxExcerptBytes) {
+    return labeledPacks.map((entry) => ({
+        ...entry,
+        pack: withPromptExcerptByteLimit(entry.pack, maxExcerptBytes),
+    }));
+}
+function budgetedMultiSourceGatewayMessages(question, labeledPacks, redactor) {
+    const limit = modelInputPromptByteLimit(labeledPacks.reduce((sum, entry) => sum + entry.pack.budget.modelInputTokensMax, 0));
+    let messages = buildRawMultiSourceGatewayMessages(question, labeledPacks, redactor);
+    if (limit === 0 || promptByteLength(messages) <= limit)
+        return messages;
+    const excerptCount = multiSourceExcerptCount(labeledPacks);
+    if (excerptCount === 0)
+        return messages;
+    const emptyPacks = withMultiSourcePromptExcerptByteLimit(labeledPacks, 0);
+    const overheadBytes = promptByteLength(buildRawMultiSourceGatewayMessages(question, emptyPacks, redactor));
+    // When overhead alone (system prompt + question + framing for all sources) exceeds the limit,
+    // no amount of excerpt trimming can bring the prompt within budget. Throw instead of sending
+    // an over-limit prompt to the provider which would result in an opaque 400 context-window error.
+    if (overheadBytes > limit) {
+        throw new ContextOverflowError(`Multi-source grounded prompt overhead (${String(overheadBytes)} bytes) exceeds model input limit (${String(limit)} bytes).`);
+    }
+    let maxExcerptBytes = Math.max(0, Math.floor((limit - overheadBytes) / excerptCount));
+    while (maxExcerptBytes >= 0) {
+        messages = buildRawMultiSourceGatewayMessages(question, withMultiSourcePromptExcerptByteLimit(labeledPacks, maxExcerptBytes), redactor);
+        if (promptByteLength(messages) <= limit || maxExcerptBytes === 0) {
+            return messages;
+        }
+        maxExcerptBytes = Math.max(0, Math.floor(maxExcerptBytes * 0.8));
+    }
+    return buildRawMultiSourceGatewayMessages(question, emptyPacks, redactor);
+}
+// Production retriever: retrieval-only orchestrator pass with a per-scope micro-index cache. No
+// modelId is needed — retrieval performs no model call.
+export function defaultRetriever(signal) {
+    return (input) => {
+        const nowMs = Date.now;
+        return retrieveConnectedContextPack(input, {
+            answerer: { answer: () => Promise.resolve("") },
+            nowMs,
+            signal,
+            microIndex: microIndexForGroundedScope(input.scope, nowMs),
+        });
+    };
+}
+export function createMultiSourceAnswerer(model, modelId, redactor, signal) {
+    return async (question, labeledPacks) => {
+        ensureNotCancelled(signal);
+        const response = await model.call({
+            modelId,
+            messages: buildMultiSourceGatewayMessages(question, labeledPacks, redactor),
+            stream: false,
+        }, signal);
+        const content = response.content.trim();
+        assertUsableAssistantContent(content, modelId);
+        return {
+            content,
+            usage: {
+                promptTokens: response.usage.promptTokens,
+                completionTokens: response.usage.completionTokens,
+            },
+        };
+    };
+}
+// ─── Retrieved-source record + worker ─────────────────────────────────────────
+const MAX_RETRIEVAL_CONCURRENCY = 4;
+// GRD-006: classify a thrown per-source retrieve error. A recoverable workspace error becomes a
+// skip (with the mapped RouteResult preserved as the all-bad fallback); anything else returns
+// undefined so the caller re-throws it to the outer handler (ClarificationNeededError, cancel, …).
+function classifyPerSourceRetrieveError(error, label) {
+    const mapped = mappedWorkspaceError(error);
+    if (mapped === undefined)
+        return undefined;
+    return {
+        skipped: {
+            label,
+            message: error instanceof Error ? error.message : "Connected source is not readable.",
+        },
+        mapped,
+    };
+}
+// Retrieve one source into the shared accumulator. GRD-006: a recoverable workspace error skips
+// just that source (preserving the all-bad 400 fallback in `firstError`); any other error
+// propagates to the outer handler.
+async function retrieveOneSource(ctx, query, perScopeBudget, labels, acc, i) {
+    ensureNotCancelled(ctx.signal);
+    const cs = ctx.scopes[i];
+    const label = labels[i];
+    if (cs === undefined || label === undefined)
+        return;
+    const scope = buildSelectedScopeFrom(ctx.chat, cs, deriveScopeIdFrom(ctx.chat, cs, i));
+    let out;
+    try {
+        out = await ctx.retriever({
+            scope,
+            query,
+            workspaceRoot: scope.workspaceRoot,
+            budget: perScopeBudget,
+        });
+    }
+    catch (error) {
+        const classified = classifyPerSourceRetrieveError(error, label);
+        if (classified === undefined)
+            throw error; // non-workspace error → outer handler
+        acc.skipped.push(classified.skipped);
+        acc.firstError ??= classified.mapped;
+        return;
+    }
+    if (!isValidGroundedPack(out.pack)) {
+        acc.skipped.push({ label, message: "Pack validation failed." });
+        acc.firstError ??= internalError("Grounded answer context pack failed validation.");
+        return;
+    }
+    acc.retrieved[i] = { label, pack: out.pack, elapsedMs: out.elapsedMs, scope, plan: out.plan };
+}
+async function retrieveAllSources(ctx, query, perScopeBudget, labels) {
+    const acc = {
+        retrieved: new Array(ctx.scopes.length),
+        skipped: [],
+        firstError: undefined,
+    };
+    let nextIndex = 0;
+    async function worker() {
+        for (;;) {
+            const i = nextIndex;
+            nextIndex += 1;
+            if (i >= ctx.scopes.length)
+                return;
+            await retrieveOneSource(ctx, query, perScopeBudget, labels, acc, i);
+        }
+    }
+    const workerCount = Math.min(MAX_RETRIEVAL_CONCURRENCY, Math.max(1, ctx.scopes.length));
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    const sources = acc.retrieved.filter((source) => source !== undefined);
+    const skipped = acc.skipped;
+    const firstError = acc.firstError;
+    if (sources.length === 0 && firstError !== undefined)
+        return firstError;
+    return { retrieved: sources, skipped, firstError };
+}
+function mergedCitations(sources, redactor) {
+    const citations = sources.flatMap((src) => buildCitations(src.pack, redactor).map((c) => ({ ...c, source: src.label })));
+    return [...citations].sort((a, b) => b.score - a.score);
+}
+function mergedUncertainty(sources, skipped, preSkipped, redactor) {
+    const fromPacks = sources.flatMap((src) => src.pack.uncertainty.map((u) => ({ kind: u.kind, claim: redactString(redactor, u.claim) })));
+    const allSkipped = [
+        ...preSkipped.map((s) => ({ label: s.label, message: s.message })),
+        ...skipped,
+    ];
+    const fromSkipped = allSkipped.map((entry) => ({
+        kind: "source-skipped",
+        claim: redactString(redactor, `Source ${entry.label} skipped: ${entry.message}`),
+    }));
+    return [...fromPacks, ...fromSkipped];
+}
+// Persists ONE evidence run per source, each naming the root that source actually searched (L1
+// honesty rule, mirrored from the single path). Returns the FIRST source's run id, which the
+// answer surfaces as its primary evidenceRunId, plus the full set for audit discovery.
+function persistPerSourceEvidence(ctx, sources) {
+    let firstRunId;
+    const runIds = [];
+    for (const src of sources) {
+        const finishedAt = Date.now();
+        const startedAt = Math.max(0, finishedAt - src.elapsedMs);
+        const runId = `grounded-${randomUUID()}`;
+        persistConnectedContextEvidence({
+            runId,
+            modelId: ctx.modelId,
+            workspaceRoot: src.scope.workspaceRoot,
+            chatId: ctx.chat.id,
+            plan: src.plan,
+            pack: src.pack,
+            citationCount: buildCitations(src.pack, ctx.deps.redactor).length,
+            elapsedMs: src.elapsedMs,
+            startedAt,
+            finishedAt,
+        }, {
+            store: ctx.deps.evidenceStore,
+            env: ctx.deps.env,
+            additionalSecrets: currentRedactionSecrets(ctx.deps),
+            costClassResolver: resolveCostClass,
+        });
+        firstRunId ??= runId;
+        runIds.push(runId);
+    }
+    return { firstRunId, runIds };
+}
+function assembleMultiSourceAnswer(ctx, sources, skipped, assistant, ids) {
+    const { redactor } = ctx.deps;
+    const citations = mergedCitations(sources, redactor);
+    const summaries = sources.map((src) => buildGroundedAnswerContextPackSummary(src.pack, buildCitations(src.pack, redactor).length, src.elapsedMs));
+    const mergedSummary = mergeContextPackSummaries(summaries);
+    const { firstRunId, runIds } = persistPerSourceEvidence(ctx, sources);
+    return {
+        groundingKind: "connected-context",
+        userMessageId: ids.userMessageId,
+        assistantMessageId: ids.assistantMessageId,
+        evidenceRunId: firstRunId,
+        evidenceRunIds: runIds,
+        content: redactString(redactor, assistant.content),
+        citations,
+        uncertainty: mergedUncertainty(sources, skipped, ctx.preSkipped ?? [], redactor),
+        omittedCount: sources.reduce((acc, src) => acc + src.pack.omitted.length, 0),
+        elapsedMs: sources.reduce((acc, src) => acc + src.elapsedMs, 0),
+        contextPack: {
+            ...mergedSummary,
+            usage: {
+                ...mergedSummary.usage,
+                modelInputTokens: mergedSummary.usage.modelInputTokens + assistant.usage.promptTokens,
+                modelOutputTokens: mergedSummary.usage.modelOutputTokens + assistant.usage.completionTokens,
+            },
+        },
+    };
+}
+export async function runMultiSourceAsk(ctx) {
+    const query = buildQuery(ctx.content, () => Date.now());
+    const labels = sourceLabels(ctx.scopes);
+    const perScopeBudget = splitExplorationBudget(DEFAULT_EXPLORATION_BUDGET, ctx.scopes.length);
+    let outcome;
+    try {
+        outcome = await retrieveAllSources(ctx, query, perScopeBudget, labels);
+    }
+    catch (error) {
+        return mapMultiSourceError(error, ctx.deps);
+    }
+    if (isRouteResult(outcome)) {
+        return outcome;
+    }
+    const { retrieved, skipped } = outcome;
+    let assistant;
+    try {
+        assistant = normalizeGroundedAnswerPayload(await ctx.answerer(ctx.content, retrieved.map((s) => ({ label: s.label, pack: s.pack }))));
+        ensureNotCancelled(ctx.signal);
+    }
+    catch (error) {
+        return mapMultiSourceError(error, ctx.deps);
+    }
+    const [userMessage, assistantMessage] = persistGroundedExchange(ctx.deps, ctx.chat.id, redactString(ctx.deps.redactor, ctx.content), redactString(ctx.deps.redactor, assistant.content));
+    const answer = assembleMultiSourceAnswer(ctx, retrieved, skipped, assistant, {
+        userMessageId: userMessage.id,
+        assistantMessageId: assistantMessage.id,
+    });
+    rememberGroundedTurn({
+        assistantMessageId: assistantMessage.id,
+        chatId: ctx.chat.id,
+        workspaceRoot: retrieved[0]?.pack.scope.workspaceRoot ?? ctx.chat.projectPath,
+        evidenceRunId: answer.evidenceRunId,
+        packs: retrieved.map((source) => source.pack),
+    });
+    return { status: 200, body: answer };
+}
+function isRouteResult(value) {
+    return "status" in value;
+}
+function mapMultiSourceError(error, deps) {
+    if (error instanceof ClarificationNeededError) {
+        return clarificationRequest(clarificationUserMessage(error));
+    }
+    const workspaceResult = mappedWorkspaceError(error);
+    if (workspaceResult !== undefined)
+        return workspaceResult;
+    const gatewayResult = mappedGatewayError(error, deps);
+    if (gatewayResult !== undefined)
+        return gatewayResult;
+    throw error;
+}

package/dist/grounded-qa.d.ts

@@ -0,0 +1,45 @@
+import { type ChatMessage as GatewayChatMessage } from "@oscharko-dev/keiko-model-gateway";
+import { type ConnectedContextPack, type RetrievalQuery, type SelectedScope } from "@oscharko-dev/keiko-contracts/connected-context";
+import { type GroundedEvidenceCitation, type GroundedUncertainty } from "@oscharko-dev/keiko-contracts/bff-wire";
+import type { RouteContext, RouteResult } from "./routes.js";
+import type { Redactor, UiHandlerDeps } from "./deps.js";
+import type { Chat, ChatConnectedScope, ChatMessage } from "./store/index.js";
+import { type OrchestratorInput, type OrchestratorOutput } from "./grounded-orchestrator.js";
+import { type GroundedRetriever, type MultiSourceAnswerer } from "./grounded-qa-multi-source.js";
+import { type ConnectorRetrieve, type FolderRetriever, type HybridAnswerer } from "./grounded-qa-hybrid.js";
+import { GROUNDED_SYSTEM_PROMPT } from "./grounded-prompt.js";
+export declare function badRequest(message: string): RouteResult;
+export declare function clarificationRequest(message: string): RouteResult;
+export declare function internalError(message: string): RouteResult;
+export declare function mappedGatewayError(error: unknown, deps: UiHandlerDeps): RouteResult | undefined;
+export declare function mappedWorkspaceError(error: unknown): RouteResult | undefined;
+export declare function isValidGroundedPack(pack: ConnectedContextPack): boolean;
+export declare function deriveScopeIdFrom(chat: Chat, cs: ChatConnectedScope, index: number): string;
+export declare function buildSelectedScopeFrom(chat: Chat, cs: ChatConnectedScope, scopeId: string): SelectedScope;
+export declare function buildQuery(content: string, nowMs: () => number): RetrievalQuery;
+export declare function ensureNotCancelled(signal: AbortSignal): void;
+export declare function promptSafeExcerptText(value: string): string;
+export declare function promptByteLength(messages: readonly GatewayChatMessage[]): number;
+export declare function modelInputPromptByteLimit(modelInputTokensMax: number): number;
+export declare function withPromptExcerptByteLimit(pack: ConnectedContextPack, maxExcerptBytes: number): ConnectedContextPack;
+export declare function packBudgetSummary(pack: ConnectedContextPack): string;
+export declare function evidenceLines(pack: ConnectedContextPack, redactor: Redactor): readonly string[];
+export declare function uncertaintyLines(pack: ConnectedContextPack, redactor: Redactor): readonly string[];
+export { GROUNDED_SYSTEM_PROMPT };
+export declare function buildGroundedGatewayMessages(question: string, pack: ConnectedContextPack, redactor: Redactor): readonly GatewayChatMessage[];
+export declare function redactString(redactor: Redactor, value: string): string;
+export declare function buildCitations(pack: ConnectedContextPack, redactor: Redactor): readonly GroundedEvidenceCitation[];
+export declare function buildUncertainty(pack: ConnectedContextPack, redactor: Redactor): readonly GroundedUncertainty[];
+export type GroundedRunner = (input: OrchestratorInput) => Promise<OrchestratorOutput>;
+export declare function persistGroundedExchange(deps: UiHandlerDeps, chatId: string, userContent: string, assistantContent: string): readonly [ChatMessage, ChatMessage];
+export interface MultiSourceSeam {
+    readonly retriever: GroundedRetriever;
+    readonly answerer: MultiSourceAnswerer;
+}
+export interface HybridSeam {
+    readonly folderRetriever?: FolderRetriever;
+    readonly connectorRetrieve?: ConnectorRetrieve;
+    readonly answer?: HybridAnswerer;
+}
+export declare function handleGroundedAsk(ctx: RouteContext, deps: UiHandlerDeps, runner?: GroundedRunner, multiSource?: MultiSourceSeam, hybrid?: HybridSeam): Promise<RouteResult>;
+//# sourceMappingURL=grounded-qa.d.ts.map

package/dist/grounded-qa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounded-qa.d.ts","sourceRoot":"","sources":["../src/grounded-qa.ts"],"names":[],"mappings":"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"}