@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/agentic/sql-authorization.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Exact generated-SQL execution authorization.
+ *
+ * This is deliberately a server-only, in-memory capability. It is created by
+ * the analyst loop, passed through one call chain, and consumed by the local
+ * execution host. It is never an artifact, response field, cache entry, or
+ * bearer token.
+ */
+export type IdentifierEvidence = 'compiler' | 'preview' | 'schema_tool' | 'catalog';
+export interface ExecutionAuthorizationBindingV1 {
+    runId: string;
+    executionId: string;
+    snapshotId: string;
+    /** The router plan that selected the target, when a plan exists. */
+    planId?: string;
+    /** The server-observed physical execution target. */
+    targetFingerprint?: string;
+    /** Canonical host bindings, never raw parameter values. */
+    bindingsFingerprint: string;
+}
+export interface FinalSqlAuthorizationV1 extends ExecutionAuthorizationBindingV1 {
+    version: 1;
+    /** Fully-qualified identities proven during this exact loop. */
+    provenIdentifiers: string[];
+    /** Catalog evidence informs retrieval only and never authorizes execution. */
+    evidence: Record<string, IdentifierEvidence>;
+    /** SHA-256 of the exact prepared bytes sent to the connector. */
+    sqlFingerprint: string;
+    mintedAt: string;
+}
+/**
+ * Opaque handoff from the analyst loop to its host execution closure. Do not
+ * persist or surface this type; its only valid lifetime is one request/child.
+ */
+export interface AgenticSqlExecutionCapabilityV1 extends Omit<ExecutionAuthorizationBindingV1, 'planId' | 'targetFingerprint'> {
+    version: 1;
+    /** Generated execution never proceeds without a frozen plan and target. */
+    planId: string;
+    targetFingerprint: string;
+    candidateSqlFingerprint: string;
+    provenIdentifiers: string[];
+    evidence: Record<string, IdentifierEvidence>;
+}
+export interface SqlAuthorizationVerdict {
+    ok: boolean;
+    unproven: string[];
+    drifted: boolean;
+    reason?: string;
+}
+export interface SqlAuthorizationCheck {
+    bindings?: unknown;
+    runId?: string;
+    executionId?: string;
+    snapshotId?: string;
+    planId?: string;
+    targetFingerprint?: string;
+}
+/**
+ * Per-invocation, server-only one-shot gate for analyst capabilities.
+ *
+ * The host creates one gate for one answer/compound child. It has no registry,
+ * static state, persistence, or bearer representation; it merely prevents the
+ * exact same capability from crossing the physical execution boundary twice.
+ */
+export declare class AgenticExecutionCapabilityGate {
+    private readonly consumed;
+    consume(capability: Pick<AgenticSqlExecutionCapabilityV1, 'runId' | 'executionId'>): boolean;
+}
+/** Parsed references supplied by the established SQL validator. */
+export interface SqlAuthorizationReferences {
+    relations?: readonly string[];
+    columns?: ReadonlyArray<{
+        relation?: string;
+        column: string;
+    }>;
+}
+/**
+ * Historical export retained for callers. No SQL rewriting is permitted at
+ * this boundary: lowercasing or stripping comments changes string literals and
+ * can turn two different queries into the same authorization fingerprint.
+ */
+export declare function normalizeSqlForFingerprint(sql: string): string;
+/** Hash exact SQL bytes. Formatting drift is execution drift here. */
+export declare function fingerprintSql(sql: string): string;
+/** Stable, redacted fingerprint for positional/named bindings. */
+export declare function fingerprintSqlBindings(bindings: unknown): string;
+export declare function createAgenticSqlExecutionCapability(input: {
+    sql: string;
+    proven: ReadonlyArray<{
+        identifier: string;
+        evidence: IdentifierEvidence;
+    }>;
+    runId?: string;
+    executionId?: string;
+    snapshotId?: string;
+    planId?: string;
+    targetFingerprint?: string;
+    bindings?: unknown;
+}): AgenticSqlExecutionCapabilityV1 | undefined;
+export declare function mintFinalSqlAuthorization(input: {
+    sql: string;
+    proven: ReadonlyArray<{
+        identifier: string;
+        evidence: IdentifierEvidence;
+    }>;
+    runId?: string;
+    executionId?: string;
+    snapshotId?: string;
+    planId?: string;
+    targetFingerprint?: string;
+    bindings?: unknown;
+    now?: () => Date;
+}): FinalSqlAuthorizationV1;
+/**
+ * Validate that the host is still executing the precise analyst proposal before
+ * preparation. The subsequent final authorization binds the prepared bytes.
+ */
+export declare function verifyAgenticSqlExecutionCapability(capability: AgenticSqlExecutionCapabilityV1, candidateSql: string, check?: SqlAuthorizationCheck): SqlAuthorizationVerdict;
+/**
+ * Does the exact prepared statement reference only observed, non-catalog
+ * identities and still match its run/target/binding authority?
+ */
+export declare function verifyFinalSql(authorization: FinalSqlAuthorizationV1, sql: string, referenced: ReadonlyArray<string>, check?: SqlAuthorizationCheck): SqlAuthorizationVerdict;
+/**
+ * Convert validator references into fully-qualified execution identities using
+ * only aliases declared inside the same SQL statement. This is not a leaf-name
+ * fallback: an unqualified column in a multi-relation query stays unqualified
+ * and is therefore refused by the capability check.
+ */
+export declare function qualifyAuthorizationReferences(sql: string, references: SqlAuthorizationReferences): string[];
+//# sourceMappingURL=sql-authorization.d.ts.map

package/dist/agentic/sql-authorization.d.ts.map

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

package/dist/agentic/sql-authorization.js

@@ -0,0 +1,232 @@
+/**
+ * Exact generated-SQL execution authorization.
+ *
+ * This is deliberately a server-only, in-memory capability. It is created by
+ * the analyst loop, passed through one call chain, and consumed by the local
+ * execution host. It is never an artifact, response field, cache entry, or
+ * bearer token.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+/**
+ * Per-invocation, server-only one-shot gate for analyst capabilities.
+ *
+ * The host creates one gate for one answer/compound child. It has no registry,
+ * static state, persistence, or bearer representation; it merely prevents the
+ * exact same capability from crossing the physical execution boundary twice.
+ */
+export class AgenticExecutionCapabilityGate {
+    consumed = new Set();
+    consume(capability) {
+        const identity = `${capability.runId}\u0000${capability.executionId}`;
+        if (this.consumed.has(identity))
+            return false;
+        this.consumed.add(identity);
+        return true;
+    }
+}
+/**
+ * Historical export retained for callers. No SQL rewriting is permitted at
+ * this boundary: lowercasing or stripping comments changes string literals and
+ * can turn two different queries into the same authorization fingerprint.
+ */
+export function normalizeSqlForFingerprint(sql) {
+    return sql;
+}
+/** Hash exact SQL bytes. Formatting drift is execution drift here. */
+export function fingerprintSql(sql) {
+    return createHash('sha256').update(sql, 'utf8').digest('hex').slice(0, 32);
+}
+/** Stable, redacted fingerprint for positional/named bindings. */
+export function fingerprintSqlBindings(bindings) {
+    return createHash('sha256').update(stableBindingsValue(bindings), 'utf8').digest('hex').slice(0, 32);
+}
+export function createAgenticSqlExecutionCapability(input) {
+    const runId = requiredCapabilityIdentity(input.runId);
+    const snapshotId = requiredCapabilityIdentity(input.snapshotId);
+    const planId = requiredCapabilityIdentity(input.planId);
+    const targetFingerprint = requiredCapabilityIdentity(input.targetFingerprint);
+    if (!runId || !snapshotId || !planId || !targetFingerprint)
+        return undefined;
+    const normalizedProof = normalizeProof(input.proven);
+    return {
+        version: 1,
+        runId,
+        executionId: input.executionId?.trim() || randomUUID(),
+        snapshotId,
+        planId,
+        targetFingerprint,
+        bindingsFingerprint: fingerprintSqlBindings(input.bindings ?? {}),
+        candidateSqlFingerprint: fingerprintSql(input.sql),
+        ...normalizedProof,
+    };
+}
+export function mintFinalSqlAuthorization(input) {
+    const normalizedProof = normalizeProof(input.proven);
+    return {
+        version: 1,
+        runId: requiredIdentity(input.runId, 'run'),
+        executionId: input.executionId?.trim() || randomUUID(),
+        snapshotId: requiredIdentity(input.snapshotId, 'snapshot'),
+        ...(input.planId?.trim() ? { planId: input.planId.trim() } : {}),
+        ...(input.targetFingerprint?.trim() ? { targetFingerprint: input.targetFingerprint.trim() } : {}),
+        bindingsFingerprint: fingerprintSqlBindings(input.bindings ?? {}),
+        sqlFingerprint: fingerprintSql(input.sql),
+        ...normalizedProof,
+        mintedAt: (input.now?.() ?? new Date()).toISOString(),
+    };
+}
+/**
+ * Validate that the host is still executing the precise analyst proposal before
+ * preparation. The subsequent final authorization binds the prepared bytes.
+ */
+export function verifyAgenticSqlExecutionCapability(capability, candidateSql, check = {}) {
+    if (fingerprintSql(candidateSql) !== capability.candidateSqlFingerprint) {
+        return failure('The generated SQL differs from the analyst-approved proposal.', true);
+    }
+    return verifyBinding(capability, check);
+}
+/**
+ * Does the exact prepared statement reference only observed, non-catalog
+ * identities and still match its run/target/binding authority?
+ */
+export function verifyFinalSql(authorization, sql, referenced, check = {}) {
+    if (fingerprintSql(sql) !== authorization.sqlFingerprint) {
+        return failure('The statement about to execute is not the one that was authorized.', true);
+    }
+    const binding = verifyBinding(authorization, check);
+    if (!binding.ok)
+        return binding;
+    const executable = new Set(authorization.provenIdentifiers.filter((id) => authorization.evidence[id] !== 'catalog'));
+    const unproven = [...new Set(referenced
+            .map(normalizeQualifiedIdentifier)
+            .filter(Boolean)
+            // No leaf fallback. `warehouse_a.orders.id` and `warehouse_b.orders.id`
+            // are distinct capabilities even when their last component is the same.
+            .filter((name) => !executable.has(name)))];
+    if (unproven.length > 0) {
+        return { ok: false, unproven, drifted: false, reason: `Nothing in this run proved: ${unproven.join(', ')}.` };
+    }
+    return { ok: true, unproven: [], drifted: false };
+}
+/**
+ * Convert validator references into fully-qualified execution identities using
+ * only aliases declared inside the same SQL statement. This is not a leaf-name
+ * fallback: an unqualified column in a multi-relation query stays unqualified
+ * and is therefore refused by the capability check.
+ */
+export function qualifyAuthorizationReferences(sql, references) {
+    const relations = [...new Set((references.relations ?? []).filter(Boolean))];
+    const aliases = relationAliasesInSql(sql);
+    const byNormalizedRelation = new Map(relations.map((relation) => [normalizeQualifiedIdentifier(relation), relation]));
+    const resolveRelation = (relation) => {
+        if (relation) {
+            const normalized = normalizeQualifiedIdentifier(relation);
+            return aliases.get(normalized) ?? byNormalizedRelation.get(normalized);
+        }
+        return relations.length === 1 ? relations[0] : undefined;
+    };
+    return [
+        ...relations,
+        ...(references.columns ?? []).map((column) => {
+            const relation = resolveRelation(column.relation);
+            return relation ? `${relation}.${column.column}` : column.column;
+        }),
+    ];
+}
+function normalizeProof(proven) {
+    const evidence = {};
+    for (const entry of proven) {
+        const key = normalizeQualifiedIdentifier(entry.identifier);
+        if (!key)
+            continue;
+        const existing = evidence[key];
+        if (!existing || evidenceRank(entry.evidence) > evidenceRank(existing))
+            evidence[key] = entry.evidence;
+    }
+    return { evidence, provenIdentifiers: Object.keys(evidence).sort() };
+}
+function verifyBinding(authority, check) {
+    if (check.bindings !== undefined && fingerprintSqlBindings(check.bindings) !== authority.bindingsFingerprint) {
+        return failure('The SQL bindings differ from the authorized execution.', true);
+    }
+    for (const field of ['runId', 'executionId', 'snapshotId', 'planId', 'targetFingerprint']) {
+        const expected = check[field];
+        const actual = authority[field];
+        if (expected !== undefined && expected !== actual) {
+            return failure(`The execution ${field} does not match the authorized request.`, true);
+        }
+    }
+    return { ok: true, unproven: [], drifted: false };
+}
+function failure(reason, drifted) {
+    return { ok: false, unproven: [], drifted, reason };
+}
+function requiredIdentity(value, label) {
+    const normalized = value?.trim();
+    // A runless host cannot accidentally turn a global/default execution into a
+    // valid capability. The random fallback is isolated per invocation, never
+    // shared in a registry, and is useful only inside the supplied closure.
+    return normalized || `${label}:${randomUUID()}`;
+}
+/** Missing generated-execution scope is a fail-closed condition, not a value to mint. */
+function requiredCapabilityIdentity(value) {
+    const normalized = value?.trim();
+    return normalized || undefined;
+}
+function normalizeQualifiedIdentifier(value) {
+    return value
+        .trim()
+        .split('.')
+        .map((part) => part.trim().replace(/^["`\[]|["`\]]$/g, '').toLowerCase())
+        .filter(Boolean)
+        .join('.');
+}
+function relationAliasesInSql(sql) {
+    const aliases = new Map();
+    const stopwords = new Set(['where', 'group', 'order', 'limit', 'having', 'join', 'left', 'right', 'inner', 'outer', 'full', 'cross', 'on', 'union']);
+    // The validator remains the authority for SQL parsing. This small parser only
+    // maps a parser-reported alias back to its exact relation spelling, and does
+    // not try to infer a relation from the last segment of an identifier.
+    const relation = '(?:"[^"]+"|`[^`]+`|\\[[^\\]]+\\]|[A-Za-z_][A-Za-z0-9_$]*)(?:\\s*\\.\\s*(?:"[^"]+"|`[^`]+`|\\[[^\\]]+\\]|[A-Za-z_][A-Za-z0-9_$]*))*';
+    const matcher = new RegExp(`\\b(?:from|join)\\s+(${relation})(?:\\s+(?:as\\s+)?([A-Za-z_][A-Za-z0-9_$]*))?`, 'gi');
+    for (const match of sql.matchAll(matcher)) {
+        const source = match[1]?.trim();
+        const alias = match[2]?.trim();
+        if (!source)
+            continue;
+        aliases.set(normalizeQualifiedIdentifier(source), source);
+        if (alias && !stopwords.has(alias.toLowerCase()))
+            aliases.set(normalizeQualifiedIdentifier(alias), source);
+    }
+    return aliases;
+}
+function evidenceRank(source) {
+    switch (source) {
+        case 'compiler': return 3;
+        case 'preview': return 2;
+        case 'schema_tool': return 1;
+        case 'catalog': return 0;
+    }
+}
+function stableBindingsValue(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'bigint')
+        return JSON.stringify(value.toString());
+    if (value instanceof Date)
+        return JSON.stringify(value.toISOString());
+    if (Array.isArray(value))
+        return `[${value.map(stableBindingsValue).join(',')}]`;
+    if (typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableBindingsValue(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(String(value));
+}
+//# sourceMappingURL=sql-authorization.js.map

package/dist/agentic/sql-authorization.js.map

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

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

@@ -33,6 +33,35 @@ export interface AgenticToolLoopOptions extends ProviderToolLoopOptions {
  * providers already use), so callers can record evidence regardless of transport.
  */
 export declare function runAgenticToolLoop(provider: AgentProvider, messages: AgentMessage[], tools: AgentToolDefinition[], options?: AgenticToolLoopOptions): Promise<string>;
+/**
+ * Run the agentic loop while retaining its terminal reason for internal
+ * callers. The public `runAgenticToolLoop` compatibility API remains a string,
+ * but an analytical caller must not mistake a budget-stopped tool request for
+ * final SQL.
+ */
+export declare function runAgenticToolLoopDetailed(provider: AgentProvider, messages: AgentMessage[], tools: AgentToolDefinition[], options?: AgenticToolLoopOptions): Promise<TextToolLoopResult>;
+/**
+ * Internal terminal state for the text transport.
+ *
+ * The public compatibility API above intentionally remains `Promise<string>`:
+ * callers outside the analyst lane use it as a normal completion helper.  The
+ * text transport itself must not, however, confuse "the model asked for a
+ * tool after its budget" with a normal final answer.  Keeping that distinction
+ * here makes a caller able to turn it into a typed, non-executing outcome.
+ */
+export interface TextToolLoopResult {
+    text: string;
+    stop: 'final' | 'tool_budget_exhausted' | 'provider_dispatch_budget_exhausted';
+    toolCalls: number;
+}
+/**
+ * Text-only providers do not have a server-side tool protocol, so DQL drives a
+ * real bounded conversation: model -> one tool -> observation -> model.  One
+ * physical dispatch is always reserved for a final answer.  This mirrors native
+ * tool use and prevents the old one-tool implementation from collecting schema
+ * evidence and then forcing a premature, SQL-less completion.
+ */
+export declare function runTextProtocolToolLoopDetailed(provider: AgentProvider, baseMessages: AgentMessage[], tools: AgentToolDefinition[], options: AgenticToolLoopOptions): Promise<TextToolLoopResult>;
 interface TextToolCall {
     name: string;
     input?: Record<string, unknown>;

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

@@ -1 +1 @@
-{"version":3,"file":"tool-loop.d.ts","sourceRoot":"","sources":["../../src/agentic/tool-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,mBAAmB,EAAE,EAC5B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAoID,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAsBvE"}
+{"version":3,"file":"tool-loop.d.ts","sourceRoot":"","sources":["../../src/agentic/tool-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,mBAAmB,EAAE,EAC5B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,mBAAmB,EAAE,EAC5B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAmC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,uBAAuB,GAAG,oCAAoC,CAAC;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AA+CD;;;;;;GAMG;AACH,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,aAAa,EACvB,YAAY,EAAE,YAAY,EAAE,EAC5B,KAAK,EAAE,mBAAmB,EAAE,EAC5B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CA+G7B;AAUD,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAsBvE"}

package/dist/agentic/tool-loop.js

@@ -26,6 +26,15 @@ import { assertProviderPayloadAllowed, boundProviderResultRows } from '../provid
  * providers already use), so callers can record evidence regardless of transport.
  */
 export async function runAgenticToolLoop(provider, messages, tools, options = {}) {
+    return (await runAgenticToolLoopDetailed(provider, messages, tools, options)).text;
+}
+/**
+ * Run the agentic loop while retaining its terminal reason for internal
+ * callers. The public `runAgenticToolLoop` compatibility API remains a string,
+ * but an analytical caller must not mistake a budget-stopped tool request for
+ * final SQL.
+ */
+export async function runAgenticToolLoopDetailed(provider, messages, tools, options = {}) {
     const resultRowBudgetUsage = new Map();
     const usable = tools
         .filter((tool) => tool.name && tool.description)
@@ -34,13 +43,41 @@ export async function runAgenticToolLoop(provider, messages, tools, options = {}
         ? [{ role: 'system', content: options.toolPolicy }]
         : [];
     if (usable.length === 0) {
-        return provider.generate([...messages, ...policyMessages], options);
+        try {
+            return { text: await provider.generate([...messages, ...policyMessages], options), stop: 'final', toolCalls: 0 };
+        }
+        catch (error) {
+            const terminal = providerDispatchTerminal(error);
+            if (terminal)
+                return terminal;
+            throw error;
+        }
     }
     // Native tool use owns its own loop; hand it the same policy + tools.
     if (provider.generateWithTools) {
-        return provider.generateWithTools([...messages, ...policyMessages], usable, options);
+        try {
+            return {
+                text: await provider.generateWithTools([...messages, ...policyMessages], usable, options),
+                stop: 'final',
+                toolCalls: 0,
+            };
+        }
+        catch (error) {
+            const terminal = providerDispatchTerminal(error);
+            if (terminal)
+                return terminal;
+            throw error;
+        }
     }
-    return runTextProtocolToolLoop(provider, [...messages, ...policyMessages], usable, options);
+    return runTextProtocolToolLoopDetailed(provider, [...messages, ...policyMessages], usable, options);
+}
+function providerDispatchTerminal(error) {
+    const code = error && typeof error === 'object' && 'code' in error
+        ? error.code
+        : undefined;
+    return code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED'
+        ? { text: '', stop: 'provider_dispatch_budget_exhausted', toolCalls: 0 }
+        : undefined;
 }
 function guardToolOutput(tool, options, resultRowBudgetUsage) {
     const policy = options.providerPayloadGuard;
@@ -75,19 +112,25 @@ function guardToolOutput(tool, options, resultRowBudgetUsage) {
     };
 }
 /**
- * Text-protocol ReAct loop for providers without native tool use. The model
- * chooses ONE action per turn: call a tool, or emit the final answer. We parse its
- * JSON, execute, feed back an observation, and repeat until it answers or the tool
- * budget is spent.
+ * Text-only providers do not have a server-side tool protocol, so DQL drives a
+ * real bounded conversation: model -> one tool -> observation -> model.  One
+ * physical dispatch is always reserved for a final answer.  This mirrors native
+ * tool use and prevents the old one-tool implementation from collecting schema
+ * evidence and then forcing a premature, SQL-less completion.
  */
-async function runTextProtocolToolLoop(provider, baseMessages, tools, options) {
+export async function runTextProtocolToolLoopDetailed(provider, baseMessages, tools, options) {
     const maxToolCalls = Math.max(0, Math.min(30, options.maxToolCalls ?? 8));
     const toolMap = new Map(tools.map((tool) => [tool.name, tool]));
     // Preserve the complete transport contract across both text-protocol turns.
     // Reconstructing a small options subset silently dropped the physical-send
     // observer, dispatch cap, redaction guard, and egress accounting for CLI and
     // Ollama providers.
-    const dispatchLimit = Math.max(1, Math.min(30, options.maxProviderDispatches ?? 2));
+    // A tool turn without a following answer is not useful.  When callers do
+    // not set a dispatch cap, make room for every permitted tool plus the final
+    // composition turn.  When they do set one, reserve its last slot for that
+    // composition instead of silently spending it on another observation.
+    const dispatchLimit = Math.max(1, Math.min(30, options.maxProviderDispatches ?? (maxToolCalls + 1)));
+    const effectiveToolBudget = Math.min(maxToolCalls, Math.max(0, dispatchLimit - 1));
     let physicalDispatches = 0;
     const outerObserver = options.onProviderDispatch;
     const runOptions = {
@@ -102,56 +145,90 @@ async function runTextProtocolToolLoop(provider, baseMessages, tools, options) {
     };
     const messages = [
         ...baseMessages,
-        { role: 'system', content: buildTextToolContract(tools, maxToolCalls) },
+        // Tell the model the *effective* ceiling, not a larger policy cap that
+        // cannot physically leave room for its final response.
+        { role: 'system', content: buildTextToolContract(tools, effectiveToolBudget) },
     ];
     let lastText = '';
-    const text = await provider.generate(messages, runOptions);
-    if (text.trim())
-        lastText = text;
-    const call = maxToolCalls > 0 ? parseTextToolCall(text) : undefined;
-    if (!call)
-        return text || lastText;
-    const tool = toolMap.get(call.name);
-    let output;
-    let isError = false;
-    const startedAt = Date.now();
-    if (!tool) {
-        output = { error: `Unknown tool: ${call.name}. Available: ${tools.map((t) => t.name).join(', ')}` };
-        isError = true;
-    }
-    else {
+    let toolCalls = 0;
+    while (true) {
+        let text;
         try {
-            assertMayStartToolCall(options);
-            output = await tool.run(call.input ?? {});
+            text = await provider.generate(messages, runOptions);
         }
-        catch (err) {
-            output = { error: err instanceof Error ? err.message : String(err) };
+        catch (error) {
+            const code = error && typeof error === 'object' && 'code' in error
+                ? error.code
+                : undefined;
+            if (code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED') {
+                return { text: lastText, stop: 'provider_dispatch_budget_exhausted', toolCalls };
+            }
+            throw error;
+        }
+        if (text.trim())
+            lastText = text;
+        const requestedCall = parseTextToolCall(text);
+        if (!requestedCall)
+            return { text: text || lastText, stop: 'final', toolCalls };
+        // A tool-shaped reply is not a final answer merely because the host has no
+        // dispatch left for another observation. Keep this typed distinction so a
+        // caller cannot mistake it for executable SQL or prose.
+        if (toolCalls >= effectiveToolBudget) {
+            return { text: text || lastText, stop: 'tool_budget_exhausted', toolCalls };
+        }
+        const call = requestedCall;
+        const tool = toolMap.get(call.name);
+        let output;
+        let isError = false;
+        const startedAt = Date.now();
+        if (!tool) {
+            output = { error: `Unknown tool: ${call.name}. Available: ${tools.map((t) => t.name).join(', ')}` };
             isError = true;
         }
+        else {
+            try {
+                assertMayStartToolCall(options);
+                output = await tool.run(call.input ?? {});
+            }
+            catch (err) {
+                output = { error: err instanceof Error ? err.message : String(err) };
+                isError = true;
+            }
+        }
+        toolCalls += 1;
+        options.onToolCall?.({ name: call.name, input: call.input, output, isError, durationMs: Date.now() - startedAt });
+        messages.push({ role: 'assistant', content: text });
+        messages.push({ role: 'user', content: renderObservation(call.name, output) });
+        if (toolCalls >= effectiveToolBudget) {
+            messages.push({
+                role: 'user',
+                content: 'Tool budget reached — do not call any more tools. Answer now using only the tool results above, as a single ```json fenced object with summary, sql, viz, outputs.',
+            });
+            // The next iteration is the reserved final dispatch.  If the model
+            // nevertheless emits a tool shape, `call` is deliberately disabled and
+            // the caller receives that text as a typed terminal, not an execution.
+            const finalText = await provider.generate(messages, runOptions).catch((error) => {
+                const code = error && typeof error === 'object' && 'code' in error
+                    ? error.code
+                    : undefined;
+                if (code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED')
+                    return '';
+                throw error;
+            });
+            if (!finalText.trim()) {
+                return {
+                    text: lastText,
+                    stop: 'provider_dispatch_budget_exhausted',
+                    toolCalls,
+                };
+            }
+            return {
+                text: finalText,
+                stop: parseTextToolCall(finalText) ? 'tool_budget_exhausted' : 'final',
+                toolCalls,
+            };
+        }
     }
-    options.onToolCall?.({ name: call.name, input: call.input, output, isError, durationMs: Date.now() - startedAt });
-    messages.push({ role: 'assistant', content: text });
-    messages.push({ role: 'user', content: renderObservation(call.name, output) });
-    // One provider proposal plus one final generation is the complete ordinary
-    // tool round. The final instruction prohibits a second tool proposal.
-    messages.push({
-        role: 'user',
-        content: 'Tool budget reached — do not call any more tools. Answer now using only the tool results above, as a single ```json fenced object with summary, sql, viz, outputs.',
-    });
-    const finalText = await provider.generate(messages, runOptions).catch((error) => {
-        const code = error && typeof error === 'object' && 'code' in error
-            ? error.code
-            : undefined;
-        // Running out of wall clock is not a reason to discard a usable draft: the
-        // model already produced text and a tool observation. Fall back to that
-        // instead of failing the whole run with nothing.
-        if (code === 'RUN_DEADLINE_INSUFFICIENT' && lastText.trim())
-            return '';
-        if (code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED')
-            throw error;
-        return '';
-    });
-    return finalText.trim() ? finalText : lastText;
 }
 function assertMayStartToolCall(options) {
     if (options.mayStartToolCall?.() === false) {