@duckcodeailabs/dql-agent 1.14.0 → 1.14.2

package/dist/agentic/ledger-tools.js.map

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

package/dist/agentic/orchestrator-policy.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Which orchestrator handles a turn.
+ *
+ * The rebuild is a strangler, not a rewrite: the new loop runs BESIDE the
+ * 10k-line answer loop and takes traffic one lane at a time. `answer-loop.ts`
+ * grew from 4,532 to 10,105 lines over 300 commits because every fix had to land
+ * inside it; the only way that stops is for new behaviour to have somewhere else
+ * to go while the old path keeps serving.
+ *
+ * Default is `legacy` on purpose. A flag that defaults on is not a migration
+ * control, it is a release — and this one changes how every question is answered.
+ */
+export type OrchestratorMode = 'legacy' | 'shadow' | 'agentic';
+/**
+ * Lanes migrate independently, cheapest risk first. `certified` and `semantic`
+ * go early precisely because the agentic path for them is a BYPASS (no planner,
+ * no tools) — it is the <5s fast lane, not new reasoning.
+ */
+export type AgenticLane = 'conversational' | 'definition' | 'certified' | 'semantic' | 'generated' | 'research';
+export declare const AGENTIC_LANES: readonly AgenticLane[];
+export interface OrchestratorPolicy {
+    mode: OrchestratorMode;
+    lanes: ReadonlySet<AgenticLane>;
+    maxIterations: number;
+    /** Fall back to the legacy loop when the agentic path throws. */
+    fallbackOnError: boolean;
+}
+/** Bounded by default: an agent loop without a ceiling is an outage waiting to happen. */
+export declare const DEFAULT_MAX_ITERATIONS = 8;
+export declare const LEGACY_ORCHESTRATOR_POLICY: OrchestratorPolicy;
+/**
+ * Resolve the policy from project config plus an optional host override.
+ *
+ * Malformed input resolves to `legacy` rather than to a partial agentic policy.
+ * A typo in `dql.config.json` must not silently route real questions through an
+ * unproven path.
+ */
+export declare function resolveOrchestratorPolicy(input?: {
+    config?: {
+        mode?: unknown;
+        lanes?: unknown;
+        maxIterations?: unknown;
+        fallbackOnError?: unknown;
+    } | null;
+    /** Host-owned per-request override; never parsed from user-facing request fields. */
+    override?: {
+        mode?: unknown;
+        lanes?: unknown;
+    } | null;
+}): OrchestratorPolicy;
+/**
+ * Does this lane run on the agentic path?
+ *
+ * `shadow` deliberately answers NO. Shadow runs the new loop for comparison only;
+ * letting it serve the user would make "observe before switching" meaningless.
+ */
+export declare function laneUsesAgenticOrchestrator(policy: OrchestratorPolicy, lane: AgenticLane): boolean;
+/** Should the new loop run purely for comparison on this lane? */
+export declare function laneRunsShadowComparison(policy: OrchestratorPolicy, lane: AgenticLane): boolean;
+//# sourceMappingURL=orchestrator-policy.d.ts.map

package/dist/agentic/orchestrator-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-policy.d.ts","sourceRoot":"","sources":["../../src/agentic/orchestrator-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,UAAU,GACV,WAAW,GACX,UAAU,CAAC;AAEf,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAE/C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,0BAA0B,EAAE,kBAKxC,CAAC;AAgBF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,GAAE;IAC/C,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACxG,qFAAqF;IACrF,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAClD,GAAG,kBAAkB,CAa1B;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAElG;AAED,kEAAkE;AAClE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAE/F"}

package/dist/agentic/orchestrator-policy.js

@@ -0,0 +1,73 @@
+/**
+ * Which orchestrator handles a turn.
+ *
+ * The rebuild is a strangler, not a rewrite: the new loop runs BESIDE the
+ * 10k-line answer loop and takes traffic one lane at a time. `answer-loop.ts`
+ * grew from 4,532 to 10,105 lines over 300 commits because every fix had to land
+ * inside it; the only way that stops is for new behaviour to have somewhere else
+ * to go while the old path keeps serving.
+ *
+ * Default is `legacy` on purpose. A flag that defaults on is not a migration
+ * control, it is a release — and this one changes how every question is answered.
+ */
+export const AGENTIC_LANES = [
+    'conversational', 'definition', 'certified', 'semantic', 'generated', 'research',
+];
+/** Bounded by default: an agent loop without a ceiling is an outage waiting to happen. */
+export const DEFAULT_MAX_ITERATIONS = 8;
+export const LEGACY_ORCHESTRATOR_POLICY = {
+    mode: 'legacy',
+    lanes: new Set(),
+    maxIterations: DEFAULT_MAX_ITERATIONS,
+    fallbackOnError: true,
+};
+function parseMode(value) {
+    return value === 'legacy' || value === 'shadow' || value === 'agentic' ? value : undefined;
+}
+function parseLanes(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const lanes = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            continue;
+        if (AGENTIC_LANES.includes(entry))
+            lanes.add(entry);
+    }
+    return lanes;
+}
+/**
+ * Resolve the policy from project config plus an optional host override.
+ *
+ * Malformed input resolves to `legacy` rather than to a partial agentic policy.
+ * A typo in `dql.config.json` must not silently route real questions through an
+ * unproven path.
+ */
+export function resolveOrchestratorPolicy(input = {}) {
+    const mode = parseMode(input.override?.mode) ?? parseMode(input.config?.mode) ?? 'legacy';
+    const lanes = parseLanes(input.override?.lanes) ?? parseLanes(input.config?.lanes) ?? new Set();
+    const rawIterations = input.config?.maxIterations;
+    const maxIterations = typeof rawIterations === 'number' && Number.isFinite(rawIterations) && rawIterations > 0
+        ? Math.min(Math.floor(rawIterations), 40)
+        : DEFAULT_MAX_ITERATIONS;
+    return {
+        mode,
+        lanes,
+        maxIterations,
+        fallbackOnError: input.config?.fallbackOnError !== false,
+    };
+}
+/**
+ * Does this lane run on the agentic path?
+ *
+ * `shadow` deliberately answers NO. Shadow runs the new loop for comparison only;
+ * letting it serve the user would make "observe before switching" meaningless.
+ */
+export function laneUsesAgenticOrchestrator(policy, lane) {
+    return policy.mode === 'agentic' && policy.lanes.has(lane);
+}
+/** Should the new loop run purely for comparison on this lane? */
+export function laneRunsShadowComparison(policy, lane) {
+    return policy.mode === 'shadow' && policy.lanes.has(lane);
+}
+//# sourceMappingURL=orchestrator-policy.js.map

package/dist/agentic/orchestrator-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-policy.js","sourceRoot":"","sources":["../../src/agentic/orchestrator-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU;CACjF,CAAC;AAUF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,MAAM,CAAC,MAAM,0BAA0B,GAAuB;IAC5D,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,IAAI,GAAG,EAAe;IAC7B,aAAa,EAAE,sBAAsB;IACrC,eAAe,EAAE,IAAI;CACtB,CAAC;AAEF,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAe,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QACxC,IAAK,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,KAAoB,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAItC,EAAE;IACJ,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC;IAC1F,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,IAAI,GAAG,EAAe,CAAC;IAC7G,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC;IAClD,MAAM,aAAa,GAAG,OAAO,aAAa,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC;QAC5G,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;QACzC,CAAC,CAAC,sBAAsB,CAAC;IAC3B,OAAO;QACL,IAAI;QACJ,KAAK;QACL,aAAa;QACb,eAAe,EAAE,KAAK,CAAC,MAAM,EAAE,eAAe,KAAK,KAAK;KACzD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAA0B,EAAE,IAAiB;IACvF,OAAO,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,wBAAwB,CAAC,MAA0B,EAAE,IAAiB;IACpF,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5D,CAAC"}

package/dist/agentic/orchestrator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The strangler seam.
+ *
+ * `answer-loop.ts` grew from 4,532 to 10,105 lines over 300 commits because
+ * every fix had to land inside it — 12% of all commits in that window touched
+ * that one file. New behaviour only stops accreting there once it has somewhere
+ * else to go WHILE the old path keeps serving.
+ *
+ * `answerAgentic` has the same signature as `answer`, so the two are
+ * interchangeable at a single call site. Which one runs is a per-lane config
+ * decision, and the default is legacy: this file is a migration control, not a
+ * release.
+ */
+import type { AgentAnswer, AnswerLoopInput } from '../answer-loop.js';
+import { type AgenticLane, type OrchestratorPolicy } from './orchestrator-policy.js';
+/** The legacy loop, injected so this module never imports the 10k-line file's runtime. */
+export type LegacyAnswerFn = (input: AnswerLoopInput) => Promise<AgentAnswer>;
+/** The agentic path for one lane. Absent lanes fall through to legacy. */
+export type AgenticLaneHandler = (input: AnswerLoopInput) => Promise<AgentAnswer>;
+export interface AnswerAgenticOptions {
+    policy: OrchestratorPolicy;
+    /** Which lane this turn belongs to, decided by triage before dispatch. */
+    lane: AgenticLane;
+    legacy: LegacyAnswerFn;
+    /** Registered agentic handlers. A lane enabled with no handler falls back. */
+    handlers?: Partial<Record<AgenticLane, AgenticLaneHandler>>;
+    /** Non-fatal diagnostics, so a silent fallback cannot hide a broken lane. */
+    onDiagnostic?: (event: OrchestratorDiagnostic) => void;
+}
+export interface OrchestratorDiagnostic {
+    kind: 'fallback' | 'dispatch';
+    lane: AgenticLane;
+    mode: OrchestratorPolicy['mode'];
+    reason?: string;
+}
+/** Marker appended to the answer's route evidence when the agentic path bailed. */
+export declare const ORCHESTRATOR_FALLBACK_STEP = "orchestrator_fallback";
+/**
+ * Route one turn to the agentic loop or the legacy answer loop.
+ *
+ * Fallback is RECORDED on the answer's evidence rather than swallowed. A
+ * silently-degrading migration looks exactly like a working one until someone
+ * notices the new path never actually ran, so `orchestratorFallbackRate` has to
+ * be observable from the run itself.
+ */
+export declare function answerAgentic(input: AnswerLoopInput, options: AnswerAgenticOptions): Promise<AgentAnswer>;
+/**
+ * Stamp the fallback onto the answer's route evidence.
+ *
+ * Prepended, not appended: the first thing a reader of the trace should see is
+ * that this answer did not come from the path the config selected.
+ */
+export declare function withFallbackEvidence(answer: AgentAnswer, lane: AgenticLane, reason: string): AgentAnswer;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/agentic/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agentic/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAElC,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAE9E,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAElF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,0EAA0E;IAC1E,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC5D,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAqBtB;AAQD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAkBxG"}

package/dist/agentic/orchestrator.js

@@ -0,0 +1,67 @@
+import { laneUsesAgenticOrchestrator, } from './orchestrator-policy.js';
+/** Marker appended to the answer's route evidence when the agentic path bailed. */
+export const ORCHESTRATOR_FALLBACK_STEP = 'orchestrator_fallback';
+/**
+ * Route one turn to the agentic loop or the legacy answer loop.
+ *
+ * Fallback is RECORDED on the answer's evidence rather than swallowed. A
+ * silently-degrading migration looks exactly like a working one until someone
+ * notices the new path never actually ran, so `orchestratorFallbackRate` has to
+ * be observable from the run itself.
+ */
+export async function answerAgentic(input, options) {
+    const { policy, lane, legacy, handlers, onDiagnostic } = options;
+    const handler = handlers?.[lane];
+    if (!laneUsesAgenticOrchestrator(policy, lane) || !handler) {
+        return legacy(input);
+    }
+    onDiagnostic?.({ kind: 'dispatch', lane, mode: policy.mode });
+    try {
+        return await handler(input);
+    }
+    catch (error) {
+        // A cancellation is the user's decision, not a lane failure: re-running the
+        // legacy loop would ignore an abort the caller already made.
+        if (isCancellation(error))
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        onDiagnostic?.({ kind: 'fallback', lane, mode: policy.mode, reason });
+        if (!policy.fallbackOnError)
+            throw error;
+        const answer = await legacy(input);
+        return withFallbackEvidence(answer, lane, reason);
+    }
+}
+function isCancellation(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const name = error.name;
+    return name === 'AbortError' || name === 'CancellationError';
+}
+/**
+ * Stamp the fallback onto the answer's route evidence.
+ *
+ * Prepended, not appended: the first thing a reader of the trace should see is
+ * that this answer did not come from the path the config selected.
+ */
+export function withFallbackEvidence(answer, lane, reason) {
+    const evidence = answer.evidence;
+    if (!evidence)
+        return answer;
+    return {
+        ...answer,
+        evidence: {
+            ...evidence,
+            route: [
+                {
+                    tool: ORCHESTRATOR_FALLBACK_STEP,
+                    status: 'failed',
+                    label: `Agentic orchestration fell back to the legacy answer loop (${lane})`,
+                    detail: reason,
+                },
+                ...(evidence.route ?? []),
+            ],
+        },
+    };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/agentic/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../../src/agentic/orchestrator.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,2BAA2B,GAG5B,MAAM,0BAA0B,CAAC;AA0BlC,mFAAmF;AACnF,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAsB,EACtB,OAA6B;IAE7B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACjE,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;IAEjC,IAAI,CAAC,2BAA2B,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4EAA4E;QAC5E,6DAA6D;QAC7D,IAAI,cAAc,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,CAAC,eAAe;YAAE,MAAM,KAAK,CAAC;QACzC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;QACnC,OAAO,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;IAChD,OAAO,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,mBAAmB,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAmB,EAAE,IAAiB,EAAE,MAAc;IACzF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACjC,IAAI,CAAC,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC7B,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,EAAE;YACR,GAAG,QAAQ;YACX,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,0BAA0B;oBAChC,MAAM,EAAE,QAAiB;oBACzB,KAAK,EAAE,8DAA8D,IAAI,GAAG;oBAC5E,MAAM,EAAE,MAAM;iBACf;gBACD,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;aAC1B;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/agentic/preview-tool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `preview_query` — the tool that lets the loop ESTABLISH identifiers.
+ *
+ * The ledger can only admit names a tool returned, so without a way to run
+ * something the loop is limited to whatever search and compile happened to
+ * surface. That makes it a verifier of other tools' output rather than an
+ * investigator: it can reject a wrong column but never discover the right one.
+ *
+ * A bounded preview closes that. It executes the candidate SQL against the real
+ * warehouse and returns the COLUMN NAMES the engine actually produced — the
+ * strongest evidence a name exists short of the compiler emitting it, because
+ * the database itself resolved it.
+ *
+ * It returns no cell VALUES. The loop needs to know a column exists, not what is
+ * in it, and shipping rows here would route warehouse data to a provider outside
+ * the egress policy that governs narration.
+ */
+import type { AgentToolDefinition } from '../providers/types.js';
+export interface PreviewExecutor {
+    (sql: string): Promise<{
+        columns: unknown[];
+        rows: unknown[];
+        rowCount: number;
+    }>;
+}
+/**
+ * Wrap the candidate in a bounded outer SELECT.
+ *
+ * Wrapping rather than appending `LIMIT`: the candidate may already carry its
+ * own LIMIT, an ORDER BY, or a trailing comment, and appending to any of those
+ * produces either a syntax error or a silently different query. A subselect
+ * bounds it without rewriting what the model wrote.
+ */
+export declare function boundedPreviewSql(sql: string, limit?: number): string;
+export declare function buildPreviewQueryTool(execute: PreviewExecutor, limit?: number): AgentToolDefinition;
+//# sourceMappingURL=preview-tool.d.ts.map

package/dist/agentic/preview-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-tool.d.ts","sourceRoot":"","sources":["../../src/agentic/preview-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,IAAI,EAAE,OAAO,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnF;AAgBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,CAGhE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,SAAI,GAAG,mBAAmB,CA0C9F"}

package/dist/agentic/preview-tool.js

@@ -0,0 +1,71 @@
+/** Statements a read-only preview may run. */
+const READ_ONLY_START_RE = /^\s*(select|with)\b/i;
+const MUTATION_RE = /\b(insert|update|delete|drop|alter|create|truncate|grant|revoke|copy|attach|install|load|pragma|call|merge)\b/i;
+/** Column name from whatever shape the driver returns. */
+function columnName(column) {
+    if (typeof column === 'string')
+        return column;
+    if (column && typeof column === 'object') {
+        const name = column.name;
+        if (typeof name === 'string')
+            return name;
+    }
+    return undefined;
+}
+/**
+ * Wrap the candidate in a bounded outer SELECT.
+ *
+ * Wrapping rather than appending `LIMIT`: the candidate may already carry its
+ * own LIMIT, an ORDER BY, or a trailing comment, and appending to any of those
+ * produces either a syntax error or a silently different query. A subselect
+ * bounds it without rewriting what the model wrote.
+ */
+export function boundedPreviewSql(sql, limit = 5) {
+    const trimmed = sql.trim().replace(/;\s*$/, '');
+    return `SELECT * FROM (\n${trimmed}\n) AS dql_preview LIMIT ${Math.max(1, Math.min(limit, 50))}`;
+}
+export function buildPreviewQueryTool(execute, limit = 5) {
+    return {
+        name: 'preview_query',
+        description: 'Run candidate SQL against the real warehouse with a small row limit and get back the COLUMN NAMES it produced, plus whether it executed. Use this to confirm a query compiles and to learn the exact output column names before composing the final answer. Returns no cell values.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['sql'],
+            properties: {
+                sql: { type: 'string', description: 'A single read-only SELECT or WITH statement.' },
+            },
+        },
+        run: async (args) => {
+            const input = (args && typeof args === 'object' ? args : {});
+            const sql = typeof input.sql === 'string' ? input.sql.trim() : '';
+            if (!sql)
+                return { error: 'Pass the SQL to preview.' };
+            if (!READ_ONLY_START_RE.test(sql) || MUTATION_RE.test(sql)) {
+                return { error: 'preview_query runs one read-only SELECT or WITH statement. It cannot modify data.' };
+            }
+            try {
+                const result = await execute(boundedPreviewSql(sql, limit));
+                const columns = (result.columns ?? [])
+                    .map(columnName)
+                    .filter((name) => Boolean(name));
+                return {
+                    executed: true,
+                    // Names only — never cell values. See the module comment.
+                    columns,
+                    rowCount: typeof result.rowCount === 'number' ? result.rowCount : (result.rows?.length ?? 0),
+                };
+            }
+            catch (error) {
+                // A failure is INFORMATION, not an outage: the message names the column
+                // or table the warehouse rejected, which is exactly what the loop needs
+                // to correct itself. Swallowing it would leave the model guessing again.
+                return {
+                    executed: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=preview-tool.js.map

package/dist/agentic/preview-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-tool.js","sourceRoot":"","sources":["../../src/agentic/preview-tool.ts"],"names":[],"mappings":"AAuBA,8CAA8C;AAC9C,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAClD,MAAM,WAAW,GAAG,gHAAgH,CAAC;AAErI,0DAA0D;AAC1D,SAAS,UAAU,CAAC,MAAe;IACjC,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC9C,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,IAAI,GAAI,MAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,KAAK,GAAG,CAAC;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAChD,OAAO,oBAAoB,OAAO,4BAA4B,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;AACnG,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAwB,EAAE,KAAK,GAAG,CAAC;IACvE,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,qRAAqR;QACvR,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,oBAAoB,EAAE,KAAK;YAC3B,QAAQ,EAAE,CAAC,KAAK,CAAC;YACjB,UAAU,EAAE;gBACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8CAA8C,EAAE;aACrF;SACF;QACD,GAAG,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;YAC3B,MAAM,KAAK,GAAG,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAsB,CAAC;YAClF,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC,GAAG;gBAAE,OAAO,EAAE,KAAK,EAAE,0BAA0B,EAAE,CAAC;YACvD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3D,OAAO,EAAE,KAAK,EAAE,mFAAmF,EAAE,CAAC;YACxG,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;gBAC5D,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;qBACnC,GAAG,CAAC,UAAU,CAAC;qBACf,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;gBACnD,OAAO;oBACL,QAAQ,EAAE,IAAI;oBACd,0DAA0D;oBAC1D,OAAO;oBACP,QAAQ,EAAE,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC;iBAC7F,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wEAAwE;gBACxE,wEAAwE;gBACxE,yEAAyE;gBACzE,OAAO;oBACL,QAAQ,EAAE,KAAK;oBACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9D,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agentic/rerank.d.ts

@@ -0,0 +1,50 @@
+/**
+ * An LLM reranker over the fused candidate list.
+ *
+ * Retrieval fuses lanes with RRF and then applies a hand-tuned additive score.
+ * Neither reads the QUESTION: they rank by lexical overlap, vector distance,
+ * and type weights, so the object that actually answers the turn can sit at
+ * rank 30 behind ten near-synonyms and be cut by a top-N that never considered
+ * what was asked. A cross-encoder pass is the cheapest thing that reads both
+ * sides at once.
+ *
+ * Advisory by construction. It may REORDER what retrieval found and nothing
+ * else — it cannot introduce an id retrieval did not return, so it can never
+ * invent context, and any failure, timeout, or malformed reply leaves today's
+ * ordering exactly as it was. That property is what makes it safe to put in
+ * front of every governed answer.
+ */
+export interface RerankCandidate {
+    id: string;
+    /** One line the model ranks on: name, type, and description if there is one. */
+    summary: string;
+}
+export interface RerankOutcome {
+    /** Candidate ids, best first. Always a permutation of a subset of the input. */
+    order: string[];
+    /** Why the model put an id where it did, for the prompt and the trace. */
+    reasons: Map<string, string>;
+}
+interface RerankProvider {
+    generate(messages: {
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }[], options?: Record<string, unknown>): Promise<string>;
+}
+export declare function parseRerankReply(raw: string, allowed: ReadonlySet<string>): RerankOutcome | undefined;
+/**
+ * Reorder candidates, or return undefined and leave the caller's order alone.
+ *
+ * Bounded by a short timeout in the same spirit as `confirmMediumCertifiedFit`:
+ * retrieval quality is worth a couple of seconds, an answer is not worth
+ * waiting on a reranker that is not coming back.
+ */
+export declare function rerankCandidates(provider: RerankProvider, question: string, candidates: readonly RerankCandidate[], options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxCandidates?: number;
+}): Promise<RerankOutcome | undefined>;
+/** Apply an outcome to the caller's list: ranked ids first, everything else after. */
+export declare function applyRerank<T>(items: readonly T[], idOf: (item: T) => string, outcome: RerankOutcome | undefined): T[];
+export {};
+//# sourceMappingURL=rerank.d.ts.map

package/dist/agentic/rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../../src/agentic/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,UAAU,cAAc;IACtB,QAAQ,CACN,QAAQ,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,EACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAoCD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,aAAa,GAAG,SAAS,CAqBrG;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACjF,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA4BpC;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EACzB,OAAO,EAAE,aAAa,GAAG,SAAS,GACjC,CAAC,EAAE,CAUL"}

package/dist/agentic/rerank.js

@@ -0,0 +1,140 @@
+/**
+ * An LLM reranker over the fused candidate list.
+ *
+ * Retrieval fuses lanes with RRF and then applies a hand-tuned additive score.
+ * Neither reads the QUESTION: they rank by lexical overlap, vector distance,
+ * and type weights, so the object that actually answers the turn can sit at
+ * rank 30 behind ten near-synonyms and be cut by a top-N that never considered
+ * what was asked. A cross-encoder pass is the cheapest thing that reads both
+ * sides at once.
+ *
+ * Advisory by construction. It may REORDER what retrieval found and nothing
+ * else — it cannot introduce an id retrieval did not return, so it can never
+ * invent context, and any failure, timeout, or malformed reply leaves today's
+ * ordering exactly as it was. That property is what makes it safe to put in
+ * front of every governed answer.
+ */
+const PROMPT = `Rank the candidates by how directly each one would help answer the question.
+
+Reply with ONLY a JSON object:
+{"ranked":[{"id":"<candidate id>","why":"<one short clause>"}]}
+
+Rules:
+- Use ONLY ids from the list. An id that is not in the list is discarded.
+- Rank at most 15. Omit anything irrelevant rather than padding the list.
+- "why" is one clause about THIS question, not a restatement of the description.`;
+function extractJsonObject(raw) {
+    const trimmed = raw.trim();
+    const start = trimmed.indexOf('{');
+    if (start < 0)
+        return undefined;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < trimmed.length; i += 1) {
+        const char = trimmed[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (char === '{')
+            depth += 1;
+        else if (char === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(trimmed.slice(start, i + 1));
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export function parseRerankReply(raw, allowed) {
+    const parsed = extractJsonObject(raw);
+    const ranked = parsed?.ranked;
+    if (!Array.isArray(ranked))
+        return undefined;
+    const order = [];
+    const reasons = new Map();
+    const seen = new Set();
+    for (const entry of ranked) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        const id = typeof record.id === 'string' ? record.id.trim() : '';
+        // An id retrieval did not return cannot enter the pack. This is the whole
+        // safety property: the reranker reorders, it never introduces.
+        if (!id || !allowed.has(id) || seen.has(id))
+            continue;
+        seen.add(id);
+        order.push(id);
+        const why = typeof record.why === 'string' ? record.why.trim() : '';
+        if (why)
+            reasons.set(id, why);
+        if (order.length >= 15)
+            break;
+    }
+    return order.length > 0 ? { order, reasons } : undefined;
+}
+/**
+ * Reorder candidates, or return undefined and leave the caller's order alone.
+ *
+ * Bounded by a short timeout in the same spirit as `confirmMediumCertifiedFit`:
+ * retrieval quality is worth a couple of seconds, an answer is not worth
+ * waiting on a reranker that is not coming back.
+ */
+export async function rerankCandidates(provider, question, candidates, options = {}) {
+    const pool = candidates.slice(0, options.maxCandidates ?? 40);
+    // Below a handful there is nothing to reorder that a top-N would get wrong.
+    if (pool.length < 5)
+        return undefined;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 2_500);
+    const onAbort = () => controller.abort();
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        const raw = await provider.generate([
+            { role: 'system', content: PROMPT },
+            {
+                role: 'user',
+                content: `Question: ${question}\n\nCandidates:\n${pool.map((candidate) => `- ${candidate.id} :: ${candidate.summary}`).join('\n')}`,
+            },
+        ], { signal: controller.signal });
+        return parseRerankReply(raw, new Set(pool.map((candidate) => candidate.id)));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+    }
+}
+/** Apply an outcome to the caller's list: ranked ids first, everything else after. */
+export function applyRerank(items, idOf, outcome) {
+    if (!outcome)
+        return [...items];
+    const position = new Map(outcome.order.map((id, index) => [id, index]));
+    // Anything the model omitted keeps its original order BEHIND what it ranked.
+    // Dropping omissions would let one bad reply silently shrink the context.
+    return [...items].sort((left, right) => {
+        const leftRank = position.get(idOf(left)) ?? Number.MAX_SAFE_INTEGER;
+        const rightRank = position.get(idOf(right)) ?? Number.MAX_SAFE_INTEGER;
+        return leftRank - rightRank;
+    });
+}
+//# sourceMappingURL=rerank.js.map

package/dist/agentic/rerank.js.map

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