@kaelio/ktx 0.8.0 → 0.10.0

package/dist/context/llm/rate-limit-governor.js

@@ -0,0 +1,285 @@
+import { createAbortError, throwIfAborted } from '../core/abort.js';
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(createAbortError());
+        return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timeout);
+        reject(createAbortError());
+    }, { once: true });
+});
+export function createRateLimitGovernorConfig(input = {}) {
+    return {
+        enabled: input.enabled ?? true,
+        maxConcurrency: input.maxConcurrency ?? 1,
+        throttleThreshold: input.throttleThreshold ?? 0.8,
+        minConcurrencyUnderPressure: input.minConcurrencyUnderPressure ?? 1,
+        ...(input.maxWaitMs !== undefined ? { maxWaitMs: input.maxWaitMs } : {}),
+        waitStateTickMs: input.waitStateTickMs ?? 1_000,
+        retry: {
+            maxAttempts: input.retry?.maxAttempts ?? 6,
+            baseDelayMs: input.retry?.baseDelayMs ?? 1_000,
+            maxDelayMs: input.retry?.maxDelayMs ?? 60_000,
+            jitter: input.retry?.jitter ?? true,
+        },
+    };
+}
+export class RateLimitGovernor {
+    config;
+    now;
+    sleep;
+    random;
+    subscribers = new Set();
+    waiters = [];
+    active = 0;
+    effectiveLimit;
+    pausedUntilMs = null;
+    pausedProvider = null;
+    pausedRateLimitType;
+    pausedTickMs = null;
+    opaqueAttempts = new Map();
+    pauseGeneration = 0;
+    visibleWaitAbort = null;
+    constructor(config, deps = {}) {
+        this.config = config;
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.random = deps.random ?? Math.random;
+        this.effectiveLimit = Math.max(1, config.maxConcurrency);
+    }
+    currentLimit() {
+        return this.config.enabled ? this.effectiveLimit : this.config.maxConcurrency;
+    }
+    /**
+     * Total attempts a runtime should make for a single rate-limited LLM call,
+     * including the first try. Returns 1 (no outer retry) when pacing is disabled:
+     * the outer retry loop only exists to cooperate with this governor's pause, so
+     * without active pacing there is no backoff to apply and the backend's own
+     * retry handles transient rejections.
+     */
+    maxRetryAttempts() {
+        return this.config.enabled ? Math.max(1, this.config.retry.maxAttempts) : 1;
+    }
+    activeSlots() {
+        return this.active;
+    }
+    subscribe(cb) {
+        this.subscribers.add(cb);
+        if (this.pausedUntilMs !== null) {
+            this.startVisibleWaitTicker();
+        }
+        return () => {
+            this.subscribers.delete(cb);
+            if (this.subscribers.size === 0) {
+                this.stopVisibleWaitTicker();
+                this.wakeWaiters();
+            }
+        };
+    }
+    report(signal) {
+        if (!this.config.enabled) {
+            return;
+        }
+        this.emit({
+            kind: 'rate_limit_observed',
+            provider: signal.provider,
+            status: signal.status,
+            ...(signal.rateLimitType ? { rateLimitType: signal.rateLimitType } : {}),
+            ...(signal.resetAtMs !== undefined ? { resetAtMs: signal.resetAtMs } : {}),
+            ...(signal.retryAfterMs !== undefined ? { retryAfterMs: signal.retryAfterMs } : {}),
+            ...(signal.utilization !== undefined ? { utilization: signal.utilization } : {}),
+        });
+        if (signal.status === 'rejected') {
+            this.applyPause(signal);
+            return;
+        }
+        if (signal.status === 'warning' || (signal.utilization ?? 0) >= this.config.throttleThreshold) {
+            this.adjustLimit(Math.max(1, this.config.minConcurrencyUnderPressure), signal, 'provider pressure');
+            return;
+        }
+        this.opaqueAttempts.delete(signal.provider);
+        if ((signal.utilization ?? 0) < this.config.throttleThreshold) {
+            this.adjustLimit(Math.max(1, this.config.maxConcurrency), signal, 'provider recovered');
+        }
+    }
+    async waitForReady(signal) {
+        throwIfAborted(signal);
+        if (!this.config.enabled) {
+            return;
+        }
+        await this.waitForPause(signal);
+        throwIfAborted(signal);
+    }
+    async acquireWorkSlot(signal) {
+        throwIfAborted(signal);
+        if (!this.config.enabled) {
+            this.active += 1;
+            return () => {
+                this.active -= 1;
+            };
+        }
+        while (true) {
+            throwIfAborted(signal);
+            await this.waitForPause(signal);
+            throwIfAborted(signal);
+            if (this.active < this.effectiveLimit) {
+                this.active += 1;
+                let released = false;
+                return () => {
+                    if (released)
+                        return;
+                    released = true;
+                    this.active -= 1;
+                    this.wakeWaiters();
+                };
+            }
+            await this.waitForSlot(signal);
+        }
+    }
+    applyPause(signal) {
+        const resumeAtMs = this.resumeAtMsFor(signal);
+        const boundedResumeAtMs = this.config.maxWaitMs === undefined ? resumeAtMs : Math.min(resumeAtMs, this.now() + this.config.maxWaitMs);
+        if (this.pausedUntilMs === null || boundedResumeAtMs > this.pausedUntilMs) {
+            this.pausedUntilMs = boundedResumeAtMs;
+            this.pausedProvider = signal.provider;
+            this.pausedRateLimitType = signal.rateLimitType;
+            this.pausedTickMs = signal.rateLimitType === 'opaque' ? Math.max(1, boundedResumeAtMs - this.now()) : null;
+            this.emitWait('wait_started');
+            this.startVisibleWaitTicker();
+            this.wakeWaiters();
+        }
+        this.adjustLimit(Math.max(1, this.config.minConcurrencyUnderPressure), signal, 'provider rejected');
+    }
+    resumeAtMsFor(signal) {
+        if (signal.resetAtMs !== undefined) {
+            return signal.resetAtMs;
+        }
+        if (signal.retryAfterMs !== undefined) {
+            return this.now() + signal.retryAfterMs;
+        }
+        const attempts = this.opaqueAttempts.get(signal.provider) ?? 0;
+        this.opaqueAttempts.set(signal.provider, Math.min(attempts + 1, this.config.retry.maxAttempts));
+        const base = Math.min(this.config.retry.maxDelayMs, this.config.retry.baseDelayMs * 2 ** Math.min(attempts, this.config.retry.maxAttempts - 1));
+        const jitterMultiplier = this.config.retry.jitter ? 0.75 + this.random() * 0.5 : 1;
+        return this.now() + Math.round(base * jitterMultiplier);
+    }
+    adjustLimit(to, signal, reason) {
+        const bounded = Math.max(1, Math.min(this.config.maxConcurrency, to));
+        if (bounded === this.effectiveLimit) {
+            return;
+        }
+        const from = this.effectiveLimit;
+        this.effectiveLimit = bounded;
+        this.emit({
+            kind: 'concurrency_adjusted',
+            provider: signal.provider,
+            from,
+            to: bounded,
+            reason,
+            ...(signal.rateLimitType ? { rateLimitType: signal.rateLimitType } : {}),
+            ...(signal.utilization !== undefined ? { utilization: signal.utilization } : {}),
+        });
+        this.wakeWaiters();
+    }
+    startVisibleWaitTicker() {
+        if (this.subscribers.size === 0 || this.pausedUntilMs === null) {
+            return;
+        }
+        this.stopVisibleWaitTicker();
+        const generation = (this.pauseGeneration += 1);
+        const controller = new AbortController();
+        this.visibleWaitAbort = controller;
+        void this.runVisibleWaitTicker(generation, controller.signal).catch(() => undefined);
+    }
+    stopVisibleWaitTicker() {
+        this.visibleWaitAbort?.abort();
+        this.visibleWaitAbort = null;
+    }
+    async runVisibleWaitTicker(generation, signal) {
+        while (!signal.aborted && generation === this.pauseGeneration && this.pausedUntilMs !== null) {
+            const remainingMs = this.pausedUntilMs - this.now();
+            if (remainingMs <= 0) {
+                this.finishPause(generation);
+                return;
+            }
+            this.emitWait('wait_tick');
+            await this.sleep(Math.min(this.pausedTickMs ?? this.config.waitStateTickMs, remainingMs), signal);
+        }
+    }
+    finishPause(generation) {
+        if (generation !== undefined && generation !== this.pauseGeneration) {
+            return;
+        }
+        this.emitWait('wait_finished');
+        this.pausedUntilMs = null;
+        this.pausedProvider = null;
+        this.pausedRateLimitType = undefined;
+        this.pausedTickMs = null;
+        this.stopVisibleWaitTicker();
+        this.wakeWaiters();
+    }
+    async waitForPause(signal) {
+        throwIfAborted(signal);
+        while (this.pausedUntilMs !== null) {
+            const remainingMs = this.pausedUntilMs - this.now();
+            if (remainingMs <= 0) {
+                this.finishPause();
+                return;
+            }
+            if (this.visibleWaitAbort !== null) {
+                await this.waitForSlot(signal);
+            }
+            else {
+                await this.sleep(Math.min(this.pausedTickMs ?? this.config.waitStateTickMs, remainingMs), signal);
+            }
+            throwIfAborted(signal);
+        }
+    }
+    waitForSlot(signal) {
+        if (signal?.aborted) {
+            return Promise.reject(createAbortError());
+        }
+        return new Promise((resolve, reject) => {
+            const wake = () => {
+                cleanup();
+                resolve();
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(createAbortError());
+            };
+            const cleanup = () => {
+                this.waiters = this.waiters.filter((candidate) => candidate !== wake);
+                signal?.removeEventListener('abort', onAbort);
+            };
+            this.waiters.push(wake);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    wakeWaiters() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const waiter of waiters) {
+            waiter();
+        }
+    }
+    emitWait(kind) {
+        if (this.pausedUntilMs === null || this.pausedProvider === null) {
+            return;
+        }
+        this.emit({
+            kind,
+            provider: this.pausedProvider,
+            ...(this.pausedRateLimitType ? { rateLimitType: this.pausedRateLimitType } : {}),
+            resumeAtMs: this.pausedUntilMs,
+            remainingMs: Math.max(0, this.pausedUntilMs - this.now()),
+        });
+    }
+    emit(state) {
+        for (const subscriber of this.subscribers) {
+            subscriber(state);
+        }
+    }
+}

package/dist/context/llm/runtime-port.d.ts

@@ -12,11 +12,6 @@ export interface KtxRuntimeToolDescriptor<TInput = unknown, TOutput = unknown> {
 }
 export type KtxRuntimeToolSet = Record<string, KtxRuntimeToolDescriptor>;
 export type RunLoopStopReason = 'budget' | 'natural' | 'error';
-/** @internal */
-export interface RunLoopStepInfo {
-    stepIndex: number;
-    stepBudget: number;
-}
 export interface LlmTokenUsage {
     inputTokens?: number;
     outputTokens?: number;
@@ -40,7 +35,7 @@ export interface RunLoopParams {
     toolSet: KtxRuntimeToolSet;
     stepBudget: number;
     telemetryTags: Record<string, string>;
-    onStepFinish?: (info: RunLoopStepInfo) => void | Promise<void>;
+    abortSignal?: AbortSignal;
 }
 export interface RunLoopResult {
     stopReason: RunLoopStopReason;
@@ -57,6 +52,7 @@ export interface KtxGenerateTextInput {
         totalMs: number;
         usage: LlmTokenUsage;
     }) => void;
+    abortSignal?: AbortSignal;
 }
 export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutput>> {
     role: KtxModelRole;
@@ -69,6 +65,7 @@ export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutp
         totalMs: number;
         usage: LlmTokenUsage;
     }) => void;
+    abortSignal?: AbortSignal;
 }
 export interface KtxLlmRuntimePort {
     generateText(input: KtxGenerateTextInput): Promise<string>;

package/dist/context/mcp/context-tools.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { emitTelemetryEvent, mcpTelemetrySampleRate, shouldEmitMcpTelemetry } from '../../telemetry/index.js';
+import { emitTelemetryEvent, mcpTelemetrySampleRate, reportException, shouldEmitMcpTelemetry, } from '../../telemetry/index.js';
+import { collectTelemetryRedactionSecrets } from '../../telemetry/redaction-secrets.js';
 import { scrubErrorClass } from '../../telemetry/scrubber.js';
 const connectionIdSchema = z.string().min(1);
 const unknownRecordSchema = z.record(z.string(), z.unknown());
@@ -405,12 +406,26 @@ function mcpProgressCallback(context) {
         });
     };
 }
-function registerParsedTool(server, name, config, schema, handler) {
+function registerParsedTool(server, name, config, schema, handler, telemetry) {
     server.registerTool(name, config, async (input, context) => {
         try {
             return await handler(schema.parse(input), context);
         }
         catch (error) {
+            if (telemetry?.io) {
+                await reportException({
+                    error,
+                    context: { source: `mcp:${name}`, handled: true, fatal: false },
+                    projectDir: telemetry.projectDir,
+                    io: telemetry.io,
+                    redactionSecrets: await collectTelemetryRedactionSecrets({
+                        projectDir: telemetry.projectDir,
+                        includeLlm: true,
+                        includeEmbeddings: true,
+                        env: process.env,
+                    }),
+                });
+            }
             return jsonErrorToolResult(formatToolError(error));
         }
     });
@@ -452,6 +467,20 @@ function instrumentMcpServer(server, telemetry) {
                     return result;
                 }
                 catch (error) {
+                    if (telemetry.io) {
+                        await reportException({
+                            error,
+                            context: { source: `mcp:${name}`, handled: true, fatal: false },
+                            projectDir: telemetry.projectDir,
+                            io: telemetry.io,
+                            redactionSecrets: await collectTelemetryRedactionSecrets({
+                                projectDir: telemetry.projectDir,
+                                includeLlm: true,
+                                includeEmbeddings: true,
+                                env: process.env,
+                            }),
+                        });
+                    }
                     if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
                         const errorClass = scrubErrorClass(error);
                         await emitTelemetryEvent({
@@ -476,6 +505,7 @@ function instrumentMcpServer(server, telemetry) {
 }
 export function registerKtxContextTools(deps) {
     const { ports, userContext } = deps;
+    const toolTelemetry = { projectDir: deps.projectDir, io: deps.io };
     const server = instrumentMcpServer(deps.server, {
         projectDir: deps.projectDir,
         io: deps.io,
@@ -489,7 +519,7 @@ export function registerKtxContextTools(deps) {
             inputSchema: connectionListSchema.shape,
             outputSchema: connectionListOutputSchema,
             annotations: toolAnnotations.connection_list,
-        }, connectionListSchema, async () => jsonToolResult({ connections: await connections.list() }));
+        }, connectionListSchema, async () => jsonToolResult({ connections: await connections.list() }), toolTelemetry);
     }
     if (ports.knowledge) {
         const knowledge = ports.knowledge;
@@ -503,7 +533,7 @@ export function registerKtxContextTools(deps) {
             userId: userContext.userId,
             query: input.query,
             limit: input.limit,
-        })));
+        })), toolTelemetry);
         registerParsedTool(server, 'wiki_read', {
             title: toolAnnotations.wiki_read.title,
             description: toolDescriptions.wiki_read,
@@ -513,7 +543,7 @@ export function registerKtxContextTools(deps) {
         }, knowledgeReadSchema, async (input) => {
             const page = await knowledge.read({ userId: userContext.userId, key: input.key });
             return page ? jsonToolResult(page) : jsonErrorToolResult(`Wiki page "${input.key}" was not found.`);
-        });
+        }, toolTelemetry);
     }
     if (ports.semanticLayer) {
         const semanticLayer = ports.semanticLayer;
@@ -528,7 +558,7 @@ export function registerKtxContextTools(deps) {
             return source
                 ? jsonToolResult(source)
                 : jsonErrorToolResult(`Semantic-layer source "${input.sourceName}" was not found.`);
-        });
+        }, toolTelemetry);
         registerParsedTool(server, 'sl_query', {
             title: toolAnnotations.sl_query.title,
             description: toolDescriptions.sl_query,
@@ -550,7 +580,7 @@ export function registerKtxContextTools(deps) {
                 },
             }, onProgress ? { onProgress } : undefined);
             return jsonToolResult(projectSlQueryResult(result, input.include));
-        });
+        }, toolTelemetry);
     }
     if (ports.entityDetails) {
         const entityDetails = ports.entityDetails;
@@ -560,7 +590,7 @@ export function registerKtxContextTools(deps) {
             inputSchema: entityDetailsSchema.shape,
             outputSchema: entityDetailsOutputSchema,
             annotations: toolAnnotations.entity_details,
-        }, entityDetailsSchema, async (input) => jsonToolResult(await entityDetails.read(input)));
+        }, entityDetailsSchema, async (input) => jsonToolResult(await entityDetails.read(input)), toolTelemetry);
     }
     if (ports.dictionarySearch) {
         const dictionarySearch = ports.dictionarySearch;
@@ -570,7 +600,7 @@ export function registerKtxContextTools(deps) {
             inputSchema: dictionarySearchSchema.shape,
             outputSchema: dictionarySearchOutputSchema,
             annotations: toolAnnotations.dictionary_search,
-        }, dictionarySearchSchema, async (input) => jsonToolResult(await dictionarySearch.search(input)));
+        }, dictionarySearchSchema, async (input) => jsonToolResult(await dictionarySearch.search(input)), toolTelemetry);
     }
     if (ports.discover) {
         const discover = ports.discover;
@@ -580,7 +610,7 @@ export function registerKtxContextTools(deps) {
             inputSchema: discoverDataSchema.shape,
             outputSchema: discoverDataOutputSchema,
             annotations: toolAnnotations.discover_data,
-        }, discoverDataSchema, async (input) => jsonToolResult({ refs: await discover.search(input) }));
+        }, discoverDataSchema, async (input) => jsonToolResult({ refs: await discover.search(input) }), toolTelemetry);
     }
     if (ports.sqlExecution) {
         const sqlExecution = ports.sqlExecution;
@@ -597,7 +627,7 @@ export function registerKtxContextTools(deps) {
                 sql: input.sql,
                 maxRows: input.maxRows ?? 1000,
             }, onProgress ? { onProgress } : undefined));
-        });
+        }, toolTelemetry);
     }
     if (ports.memoryIngest) {
         const memoryIngest = ports.memoryIngest;
@@ -617,7 +647,7 @@ export function registerKtxContextTools(deps) {
                 sourceType: 'external_ingest',
             };
             return jsonToolResult(await memoryIngest.ingest(ingestInput));
-        });
+        }, toolTelemetry);
         registerParsedTool(server, 'memory_ingest_status', {
             title: toolAnnotations.memory_ingest_status.title,
             description: toolDescriptions.memory_ingest_status,
@@ -627,6 +657,6 @@ export function registerKtxContextTools(deps) {
         }, memoryIngestStatusSchema, async (input) => {
             const status = await memoryIngest.status(input.runId);
             return status ? jsonToolResult(status) : jsonErrorToolResult(`Memory ingest run "${input.runId}" was not found.`);
-        });
+        }, toolTelemetry);
     }
 }

package/dist/context/project/config.d.ts

@@ -6,6 +6,7 @@ declare const llmSchema: z.ZodObject<{
             vertex: "vertex";
             gateway: "gateway";
             "claude-code": "claude-code";
+            codex: "codex";
             none: "none";
         }>>;
         vertex: z.ZodOptional<z.ZodObject<{
@@ -327,6 +328,7 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
                 vertex: "vertex";
                 gateway: "gateway";
                 "claude-code": "claude-code";
+                codex: "codex";
                 none: "none";
             }>>;
             vertex: z.ZodOptional<z.ZodObject<{
@@ -395,6 +397,18 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strict>>;
+        rateLimit: z.ZodPrefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            throttleThreshold: z.ZodDefault<z.ZodNumber>;
+            minConcurrencyUnderPressure: z.ZodDefault<z.ZodInt>;
+            maxWaitMs: z.ZodOptional<z.ZodInt>;
+            retry: z.ZodPrefault<z.ZodObject<{
+                maxAttempts: z.ZodDefault<z.ZodInt>;
+                baseDelayMs: z.ZodDefault<z.ZodInt>;
+                maxDelayMs: z.ZodDefault<z.ZodInt>;
+                jitter: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
         profile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"json">]>>;
     }, z.core.$strict>>;
     agent: z.ZodPrefault<z.ZodObject<{

package/dist/context/project/config.js

@@ -2,7 +2,7 @@ import { KTX_MODEL_ROLES } from '../../llm/types.js';
 import YAML from 'yaml';
 import * as z from 'zod';
 import { connectionConfigSchema } from './driver-schemas.js';
-const KTX_LLM_BACKENDS = ['none', 'anthropic', 'vertex', 'gateway', 'claude-code'];
+const KTX_LLM_BACKENDS = ['none', 'anthropic', 'vertex', 'gateway', 'claude-code', 'codex'];
 const KTX_EMBEDDING_BACKENDS = ['none', 'openai', 'sentence-transformers'];
 const KTX_PROMPT_CACHE_TTLS = ['5m', '1h'];
 const KTX_ENRICHMENT_MODES = ['none', 'deterministic', 'llm'];
@@ -32,7 +32,7 @@ const llmProviderSchema = z
     backend: z
         .enum(KTX_LLM_BACKENDS)
         .default('none')
-        .describe('LLM provider backend. "none" disables LLM features; "anthropic" / "vertex" / "gateway" require the matching nested credentials block; "claude-code" uses the local Claude Code session.'),
+        .describe('LLM provider backend. "none" disables LLM features; "anthropic" / "vertex" / "gateway" require the matching nested credentials block; "claude-code" uses the local Claude Code session; "codex" uses the local Codex session.'),
     vertex: vertexProviderSchema.optional().describe('Vertex AI credentials, used when backend is "vertex".'),
     anthropic: apiCredentialsSchema.optional().describe('Anthropic API credentials, used when backend is "anthropic".'),
     gateway: apiCredentialsSchema.optional().describe('AI Gateway credentials, used when backend is "gateway".'),
@@ -86,6 +86,40 @@ const workUnitsSchema = z
         .describe('Behavior when a work unit fails: "abort" stops the whole ingest run; "continue" records the failure and keeps going.'),
 })
     .describe('Concurrency and failure handling for ingest work units.');
+const ingestRateLimitRetrySchema = z
+    .strictObject({
+    maxAttempts: z
+        .int()
+        .positive()
+        .default(6)
+        .describe('Maximum attempts for a single rate-limited LLM call before the failure surfaces, counting the first try. Also bounds how far opaque backoff grows for providers that do not expose a reset time.'),
+    baseDelayMs: z.int().positive().default(1_000).describe('Initial opaque retry delay in milliseconds.'),
+    maxDelayMs: z.int().positive().default(60_000).describe('Maximum opaque retry delay in milliseconds.'),
+    jitter: z.boolean().default(true).describe('When true, apply bounded jitter to opaque retry delays.'),
+})
+    .describe('Retry policy for rate-limit responses that do not include a reset time or retry-after value.');
+const ingestRateLimitSchema = z
+    .strictObject({
+    enabled: z.boolean().default(true).describe('Master switch for ingest LLM rate-limit pacing and visible waits.'),
+    throttleThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.8)
+        .describe('Provider utilization at or above which ingest throttles new work-unit starts.'),
+    minConcurrencyUnderPressure: z
+        .int()
+        .positive()
+        .default(1)
+        .describe('Effective work-unit concurrency while a provider is under rate-limit pressure.'),
+    maxWaitMs: z
+        .int()
+        .positive()
+        .optional()
+        .describe('Optional cap on a single provider reset wait. Omit to wait indefinitely until the provider reset time.'),
+    retry: ingestRateLimitRetrySchema.prefault({}).describe('Opaque retry policy for providers without reset hints.'),
+})
+    .describe('Rate-limit pacing and wait policy for ingest LLM calls.');
 const ingestSchema = z
     .strictObject({
     adapters: z
@@ -96,6 +130,7 @@ const ingestSchema = z
         .prefault({ backend: 'none' })
         .describe('Embedding configuration used when ingest adapters need to embed documents.'),
     workUnits: workUnitsSchema.prefault({}).describe('Concurrency and failure handling for ingest work units.'),
+    rateLimit: ingestRateLimitSchema.prefault({}).describe('LLM rate-limit pacing and visible-wait policy for ingest.'),
     profile: z
         .union([z.boolean(), z.literal('json')])
         .default(false)

package/dist/context/scan/types.d.ts

@@ -233,10 +233,23 @@ export interface KtxTableListEntry {
     name: string;
     kind: 'table' | 'view';
 }
-interface KtxConnectorTestResult {
+export interface KtxConnectorTestResult {
     success: boolean;
     error?: string;
-}
+    /**
+     * The original error thrown by the driver, preserved unflattened so the
+     * connection-test path can re-throw it. Keeping the real error object lets
+     * telemetry record the driver's actual error class (e.g. `ConnectionError`)
+     * and `.code` (e.g. `ELOGIN`) instead of collapsing every failure to `Error`.
+     */
+    cause?: unknown;
+}
+/**
+ * Single source of truth for a failed connector test result. Captures the
+ * driver's message for display while preserving the original error as `cause`
+ * so callers can surface its real class and code.
+ */
+export declare function connectorTestFailure(error: unknown): KtxConnectorTestResult;
 export interface KtxScanConnector {
     id: string;
     driver: KtxConnectionDriver;

package/dist/context/scan/types.js

@@ -11,3 +11,15 @@ export function createKtxConnectorCapabilities(capabilities = {}) {
         estimatedRowCounts: capabilities.estimatedRowCounts ?? false,
     };
 }
+/**
+ * Single source of truth for a failed connector test result. Captures the
+ * driver's message for display while preserving the original error as `cause`
+ * so callers can surface its real class and code.
+ */
+export function connectorTestFailure(error) {
+    return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        cause: error,
+    };
+}

package/dist/context/sl/description-normalization.js

@@ -39,12 +39,6 @@ function humanizeIdentifier(value) {
         .trim()
         .toLowerCase();
 }
-function formatCount(count, singular, plural = `${singular}s`) {
-    if (count <= 0) {
-        return null;
-    }
-    return `${count} ${count === 1 ? singular : plural}`;
-}
 function sourceFallback(source, sourceName) {
     const table = cleanText(source.table);
     const sql = cleanText(source.sql);
@@ -54,14 +48,10 @@ function sourceFallback(source, sourceName) {
     if (sql) {
         return `Semantic-layer source for ${sourceName} backed by curated SQL.`;
     }
-    const counts = [
-        formatCount(Array.isArray(source.measures) ? source.measures.length : 0, 'measure'),
-        formatCount(Array.isArray(source.segments) ? source.segments.length : 0, 'segment'),
-        formatCount(Array.isArray(source.columns) ? source.columns.length : 0, 'computed column'),
-    ].filter((item) => Boolean(item));
-    return counts.length > 0
-        ? `Semantic-layer overlay for ${sourceName} defining ${counts.join(', ')}.`
-        : `Semantic-layer overlay for ${sourceName}.`;
+    // Measure/segment/column counts are rendered live from the body at list/read
+    // time, so baking them into stored prose freezes a derived value that drifts
+    // as the source later gains measures. Keep the auto fallback count-free.
+    return `Semantic-layer overlay for ${sourceName}.`;
 }
 function columnFallback(column, sourceName) {
     const columnName = cleanText(column.name) ?? 'column';