@duckcodeailabs/dql-agent 1.6.30 → 1.6.32

package/dist/providers/reasoning-effort.js

@@ -0,0 +1,81 @@
+export const REASONING_EFFORTS = ['low', 'medium', 'high'];
+/** Narrowing type-guard for untrusted input (settings JSON, env vars, request bodies). */
+export function isReasoningEffort(value) {
+    return value === 'low' || value === 'medium' || value === 'high';
+}
+/** Coerce untrusted input to a valid effort, or `undefined` when unset/invalid. */
+export function coerceReasoningEffort(value) {
+    if (value == null || value === '')
+        return undefined;
+    const normalized = String(value).trim().toLowerCase();
+    return isReasoningEffort(normalized) ? normalized : undefined;
+}
+const RANK = { low: 0, medium: 1, high: 2 };
+/**
+ * Clamp a desired effort to a ceiling. The user's global Settings choice acts as
+ * the ceiling; the engine's per-route effort is the desired value. So "Low"
+ * globally is always honored, while "High" lets the engine pick per task.
+ */
+export function clampReasoningEffort(desired, ceiling) {
+    return RANK[desired] <= RANK[ceiling] ? desired : ceiling;
+}
+/** Bump one level (a failed cheap pass earns more reasoning on the repair). Saturates at `high`. */
+export function bumpReasoningEffort(effort) {
+    return effort === 'low' ? 'medium' : 'high';
+}
+/**
+ * Whether a provider+model actually accepts a reasoning parameter. Gating here
+ * keeps us from sending an unsupported field to a model that would reject the
+ * request (e.g. `gpt-4.1-mini`, older Claude, plain Gemini Flash).
+ */
+export function supportsReasoningEffort(provider, model) {
+    const m = (model ?? '').toLowerCase();
+    switch (provider) {
+        case 'claude':
+            // `output_config.effort` is supported on Opus 4.5+, Sonnet 4.6+, Sonnet 5+,
+            // and Fable 5+ (and explicit `:thinking` virtual ids). It is REJECTED on
+            // Sonnet 4.5 and Haiku 4.5, so those must not match — a false positive here
+            // 400s the request. Kept intentionally conservative; a defensive retry in
+            // ClaudeProvider strips the field if a model/gateway still rejects it.
+            if (m.includes(':thinking'))
+                return true;
+            if (/opus-4-([5-9]|\d\d)/.test(m) || /opus-[5-9]/.test(m))
+                return true;
+            if (/sonnet-4-([6-9]|\d\d)/.test(m) || /sonnet-[5-9]/.test(m))
+                return true;
+            if (/fable-[5-9]/.test(m))
+                return true;
+            return false;
+        case 'openai':
+            // o-series (o1, o3, o4-mini, …) and the gpt-5 family take reasoning_effort.
+            // Allow a leading provider namespace (e.g. `openai/o3-mini`).
+            return /(^|\/)o\d/.test(m) || m.includes('gpt-5') || m.includes('gpt5');
+        case 'gemini':
+            return geminiReasoningStyle(model) !== null;
+        default:
+            return false;
+    }
+}
+export function geminiReasoningStyle(model) {
+    const m = (model ?? '').toLowerCase();
+    if (m.includes('gemini-3'))
+        return 'level';
+    if (m.includes('gemini-2.5') || m.includes('flash-thinking'))
+        return 'budget';
+    return null;
+}
+/** Token budgets for budget-style thinking providers (Anthropic-native / Gemini 2.5). */
+const EFFORT_BUDGET = { low: 2048, medium: 8192, high: 16384 };
+/**
+ * Map effort → a thinking-token budget, kept strictly below the answer's
+ * `maxTokens` (with headroom) so the budget can never starve the response.
+ * Anthropic requires a floor of 1024.
+ */
+export function effortToThinkingBudget(effort, maxTokens) {
+    const base = EFFORT_BUDGET[effort];
+    if (typeof maxTokens === 'number' && maxTokens > 0) {
+        return Math.max(1024, Math.min(base, Math.floor(maxTokens * 0.8)));
+    }
+    return base;
+}
+//# sourceMappingURL=reasoning-effort.js.map

package/dist/providers/reasoning-effort.js.map

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

package/dist/providers/tool-output.d.ts

@@ -0,0 +1,2 @@
+export declare function compactToolOutput(output: unknown, limit?: number): string;
+//# sourceMappingURL=tool-output.d.ts.map

package/dist/providers/tool-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-output.d.ts","sourceRoot":"","sources":["../../src/providers/tool-output.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAA4B,GAAG,MAAM,CAS5F"}

package/dist/providers/tool-output.js

@@ -0,0 +1,22 @@
+/**
+ * Compact a tool result for inclusion in a provider tool-loop message.
+ *
+ * Tool outputs can be large; we cap them so a single result can't blow the
+ * context budget. When capping, we must NOT slice a serialized JSON string
+ * mid-token — that yields malformed JSON the model then tries to parse. Instead
+ * we return a valid JSON envelope carrying an explicit `truncated` marker and a
+ * bounded preview, so the result always parses and the model is told it was cut.
+ */
+const DEFAULT_TOOL_OUTPUT_LIMIT = 12000;
+export function compactToolOutput(output, limit = DEFAULT_TOOL_OUTPUT_LIMIT) {
+    const text = typeof output === 'string' ? output : JSON.stringify(output) ?? 'null';
+    if (text.length <= limit)
+        return text;
+    return JSON.stringify({
+        truncated: true,
+        originalLength: text.length,
+        note: `Tool result truncated to ${limit} characters. Issue a narrower query to see the rest.`,
+        preview: text.slice(0, limit),
+    });
+}
+//# sourceMappingURL=tool-output.js.map

package/dist/providers/tool-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-output.js","sourceRoot":"","sources":["../../src/providers/tool-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAExC,MAAM,UAAU,iBAAiB,CAAC,MAAe,EAAE,KAAK,GAAG,yBAAyB;IAClF,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC;IACpF,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,SAAS,EAAE,IAAI;QACf,cAAc,EAAE,IAAI,CAAC,MAAM;QAC3B,IAAI,EAAE,4BAA4B,KAAK,sDAAsD;QAC7F,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;KAC9B,CAAC,CAAC;AACL,CAAC"}

package/dist/providers/types.d.ts

@@ -23,9 +23,32 @@ export interface ProviderRunOptions {
     maxTokens?: number;
     /** Sampling temperature (0..1). */
     temperature?: number;
+    /**
+     * Reasoning effort (low/medium/high). Providers with a reasoning surface
+     * translate it into their native param; the rest ignore it. See
+     * `./reasoning-effort.ts`.
+     */
+    reasoningEffort?: import('./reasoning-effort.js').ReasoningEffort;
     /** Caller-supplied AbortSignal — providers honor it. */
     signal?: AbortSignal;
 }
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    run(args: unknown): Promise<unknown>;
+}
+export interface ProviderToolLoopOptions extends ProviderRunOptions {
+    /** Hard cap for provider-visible tool calls in this turn. Default 8. */
+    maxToolCalls?: number;
+    /** Optional trace hook for tests/UI instrumentation. */
+    onToolCall?: (event: {
+        name: string;
+        input: unknown;
+        output?: unknown;
+        isError?: boolean;
+    }) => void;
+}
 export interface AgentProvider {
     readonly name: ProviderName;
     /**
@@ -33,6 +56,12 @@ export interface AgentProvider {
      * Throws on transport / API errors.
      */
     generate(messages: AgentMessage[], options?: ProviderRunOptions): Promise<string>;
+    /**
+     * Optional bounded tool loop. Providers that implement native tool use should
+     * call supplied tools, append their observations, and resolve with the final
+     * assistant text. Callers must keep a one-shot generate() fallback.
+     */
+    generateWithTools?(messages: AgentMessage[], tools: AgentToolDefinition[], options?: ProviderToolLoopOptions): Promise<string>;
     /**
      * Optional token streaming. Calls `onDelta` with each text chunk as it arrives
      * and resolves with the full concatenated text. Providers that omit this fall

package/dist/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClF;;;;OAIG;IACH,cAAc,CAAC,CACb,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAC/B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,uEAAuE;IACvE,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAC/B,OAAO,CAAC,MAAM,CAAC,CAOjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,uBAAuB,EAAE,eAAe,CAAC;IAClE,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CACrG;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClF;;;;OAIG;IACH,iBAAiB,CAAC,CAChB,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,mBAAmB,EAAE,EAC5B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,CACb,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAC/B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,uEAAuE;IACvE,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAC/B,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/providers/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyCH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAuB,EACvB,QAAwB,EACxB,OAA2B,EAC3B,OAAgC;IAEhC,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAuB,EACvB,QAAwB,EACxB,OAA2B,EAC3B,OAAgC;IAEhC,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/semantic-bridge/compose.d.ts

@@ -0,0 +1,89 @@
+import type { ComposeQueryResult, DqlArtifactReference, SemanticLayer } from '@duckcodeailabs/dql-core';
+import type { KGNode } from '../kg/types.js';
+import type { AnalysisQuestionPlan } from '../metadata/analysis-planner.js';
+export interface SemanticBridgeFilter {
+    dimension: string;
+    operator: string;
+    values: string[];
+}
+export interface SemanticBridgeOrderBy {
+    name: string;
+    direction: 'asc' | 'desc';
+}
+export interface SemanticDqlArtifactInput {
+    question: string;
+    name?: string;
+    metrics: string[];
+    domain?: string;
+    titleFallback?: string;
+    dimensions: string[];
+    filters: SemanticBridgeFilter[];
+    timeDimension?: {
+        name: string;
+        granularity: string;
+    };
+    orderBy?: SemanticBridgeOrderBy[];
+    limit?: number;
+}
+export interface SemanticBridgeQueryResult {
+    sql: string;
+    /** Primary metric kept for backward-compatible route labels and citations. */
+    metric: string;
+    metrics: string[];
+    dimensions: string[];
+    filters: SemanticBridgeFilter[];
+    timeDimension?: {
+        name: string;
+        granularity: string;
+    };
+    orderBy?: SemanticBridgeOrderBy[];
+    limit?: number;
+    dqlArtifact: DqlArtifactReference & {
+        kind: 'semantic_block';
+    };
+    composeResult: ComposeQueryResult;
+}
+export interface ComposeSemanticQueryInput {
+    semanticLayer: SemanticLayer;
+    question: string;
+    questionPlan: AnalysisQuestionPlan;
+    matchedMetric?: KGNode;
+    driver?: string;
+    tableMapping?: Record<string, string>;
+    /**
+     * Resolve a filter literal to the physical column name(s) whose sampled values
+     * contain it (from the runtime value index / schema sample values). Lets us bind
+     * a value like "beverage" to whichever dimension actually carries it, instead of
+     * hard-coding project-specific value→dimension guesses.
+     */
+    filterValueColumns?: (value: string) => string[];
+}
+export declare function composeSemanticQueryForQuestion(input: ComposeSemanticQueryInput): SemanticBridgeQueryResult | undefined;
+/** A validated member selection, e.g. from an LLM emitting the query_semantic_model contract. */
+export interface SemanticMemberSelection {
+    metrics: string[];
+    dimensions?: string[];
+    timeDimension?: {
+        name: string;
+        granularity: string;
+    };
+    filters?: SemanticBridgeFilter[];
+    orderBy?: SemanticBridgeOrderBy[];
+    limit?: number;
+}
+/**
+ * Compose from an EXPLICIT member selection (metrics/dimensions/grain/filters),
+ * validating each member against the layer before compiling. This is the Lane-2
+ * fallback when deterministic token-overlap selection misses but the semantic
+ * layer still covers the question — an LLM picks members, the compiler owns SQL.
+ */
+export declare function composeSemanticQueryFromMembers(input: {
+    semanticLayer: SemanticLayer;
+    question: string;
+    selection: SemanticMemberSelection;
+    driver?: string;
+    tableMapping?: Record<string, string>;
+}): SemanticBridgeQueryResult | undefined;
+export declare function renderSemanticDqlArtifact(input: SemanticDqlArtifactInput): string;
+export declare function semanticDqlArtifactName(input: SemanticDqlArtifactInput): string;
+//# sourceMappingURL=compose.d.ts.map

package/dist/semantic-bridge/compose.d.ts.map

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