@kaelio/ktx 0.9.0 → 0.10.0

package/dist/context/llm/claude-code-runtime.js

@@ -1,6 +1,6 @@
 import { createSdkMcpServer, query as defaultQuery, } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
-import { noopLogger } from '../../context/core/config.js';
+import { createAbortError, isAbortError, throwIfAborted } from '../core/abort.js';
 import { createKtxClaudeCodeEnv } from './claude-code-env.js';
 import { resolveClaudeCodeModel } from './claude-code-models.js';
 import { createClaudeSdkTools, mcpToolIds } from './runtime-tools.js';
@@ -41,21 +41,6 @@ const STRUCTURED_OUTPUT_TOOL_NAME = 'StructuredOutput';
 function isResult(message) {
     return message.type === 'result';
 }
-// Skip emissions the SDK does not count toward `num_turns`: `pause_turn` continuations and
-// errored partials (e.g. `max_output_tokens`) it retries internally. Without this, the
-// runtime's step counter outruns `maxTurns` and the HUD renders e.g. `step 69/40`.
-function countsAsAssistantTurn(message) {
-    if (message.type !== 'assistant' || message.parent_tool_use_id !== null) {
-        return false;
-    }
-    if (message.error !== undefined) {
-        return false;
-    }
-    if (message.message.stop_reason === 'pause_turn') {
-        return false;
-    }
-    return true;
-}
 function resultError(result) {
     if (result.subtype === 'success') {
         return undefined;
@@ -104,6 +89,67 @@ function assertInitIsolation(message, allowedToolIds, expectedMcpServerNames) {
 function expectedMcpServerNames(tools) {
     return tools && Object.keys(tools).length > 0 ? new Set([KTX_MCP_SERVER_NAME]) : new Set();
 }
+const CLAUDE_RATE_LIMIT_ERROR_MARKERS = /\b429\b|rate limit|too many requests|quota exceeded|overloaded|max_retries/i;
+function normalizeClaudeResetAtMs(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return Math.round(value < 10_000_000_000 ? value * 1_000 : value);
+    }
+    if (typeof value === 'string') {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric) && numeric > 0) {
+            return normalizeClaudeResetAtMs(numeric);
+        }
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function isClaudeRateLimitResult(result, rejectedSignal) {
+    const error = resultError(result);
+    if (!error) {
+        return false;
+    }
+    if (rejectedSignal?.status === 'rejected') {
+        return true;
+    }
+    const resultDetails = result;
+    const details = [
+        error.message,
+        resultDetails.stop_reason,
+        resultDetails.terminal_reason,
+        ...(resultDetails.errors ?? []),
+    ]
+        .filter((value) => typeof value === 'string' && value.length > 0)
+        .join('\n');
+    return CLAUDE_RATE_LIMIT_ERROR_MARKERS.test(details);
+}
+function claudeRateLimitSignal(message) {
+    const record = message;
+    if (record.type === 'rate_limit_event') {
+        const info = record.rate_limit_info;
+        if (!info)
+            return null;
+        const rawStatus = typeof info.status === 'string' ? info.status : 'allowed';
+        const resetAtMs = normalizeClaudeResetAtMs(info.resetsAt);
+        return {
+            provider: 'claude-subscription',
+            status: rawStatus === 'rejected' ? 'rejected' : rawStatus === 'allowed_warning' ? 'warning' : 'allowed',
+            ...(resetAtMs !== undefined ? { resetAtMs } : {}),
+            ...(typeof info.rateLimitType === 'string' ? { rateLimitType: info.rateLimitType } : {}),
+            ...(typeof info.utilization === 'number' ? { utilization: info.utilization } : {}),
+        };
+    }
+    if (record.subtype === 'api_retry' || record.type === 'api_retry') {
+        const retryDelayMs = typeof record.retry_delay_ms === 'number' ? record.retry_delay_ms : undefined;
+        return {
+            provider: 'claude-subscription',
+            status: 'warning',
+            ...(retryDelayMs !== undefined ? { retryAfterMs: retryDelayMs } : {}),
+            rateLimitType: 'api_retry',
+        };
+    }
+    return null;
+}
 function managedMcpSettings(serverNames) {
     return {
         allowManagedMcpServersOnly: true,
@@ -150,28 +196,63 @@ function baseOptions(input) {
 }
 async function collectResult(params) {
     let result;
-    for await (const message of params.query({ prompt: params.prompt, options: params.options })) {
-        assertInitIsolation(message, params.allowedToolIds, params.expectedMcpServerNames);
-        if (countsAsAssistantTurn(message)) {
-            await params.onAssistantTurn?.();
-        }
-        if (isResult(message)) {
-            result = message;
+    let rejectedRateLimitSignal;
+    throwIfAborted(params.abortSignal);
+    await params.rateLimitGovernor?.waitForReady(params.abortSignal);
+    throwIfAborted(params.abortSignal);
+    const queryResult = params.query({ prompt: params.prompt, options: params.options });
+    const onAbort = () => {
+        void Promise.resolve(queryResult.interrupt?.()).catch(() => undefined);
+    };
+    params.abortSignal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for await (const message of queryResult) {
+            throwIfAborted(params.abortSignal);
+            const rateLimitSignal = claudeRateLimitSignal(message);
+            if (rateLimitSignal) {
+                if (rateLimitSignal.status === 'rejected') {
+                    rejectedRateLimitSignal = rateLimitSignal;
+                }
+                params.rateLimitGovernor?.report(rateLimitSignal);
+            }
+            assertInitIsolation(message, params.allowedToolIds, params.expectedMcpServerNames);
+            if (isResult(message)) {
+                result = message;
+            }
         }
     }
+    finally {
+        params.abortSignal?.removeEventListener('abort', onAbort);
+    }
+    if (params.abortSignal?.aborted) {
+        throw createAbortError();
+    }
     if (!result) {
         throw new Error('Claude Code query returned no result message');
     }
-    return result;
+    return {
+        result,
+        ...(rejectedRateLimitSignal ? { rejectedRateLimitSignal } : {}),
+    };
+}
+async function collectResultWithRateLimitRetry(params) {
+    // maxRetryAttempts() returns 1 when no governor is present or pacing is
+    // disabled, so a rate-limited result surfaces without an extra query; the
+    // Claude Code SDK applies its own backoff for transient rejections.
+    const maxAttempts = params.rateLimitGovernor?.maxRetryAttempts() ?? 1;
+    for (let attempt = 0;; attempt += 1) {
+        const outcome = await collectResult(params);
+        if (!isClaudeRateLimitResult(outcome.result, outcome.rejectedRateLimitSignal) || attempt >= maxAttempts - 1) {
+            return outcome.result;
+        }
+    }
 }
 export class ClaudeCodeKtxLlmRuntime {
     deps;
     runQuery;
-    logger;
     constructor(deps) {
         this.deps = deps;
         this.runQuery = deps.query ?? defaultQuery;
-        this.logger = deps.logger ?? noopLogger;
     }
     async generateText(input) {
         const options = baseOptions({
@@ -182,12 +263,14 @@ export class ClaudeCodeKtxLlmRuntime {
             tools: input.tools,
         });
         const startedAt = Date.now();
-        const result = await collectResult({
+        const result = await collectResultWithRateLimitRetry({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
             options,
             allowedToolIds: new Set(mcpToolIds(input.tools ?? {})),
             expectedMcpServerNames: expectedMcpServerNames(input.tools),
+            rateLimitGovernor: this.deps.rateLimitGovernor,
+            abortSignal: input.abortSignal,
         });
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
@@ -216,12 +299,14 @@ export class ClaudeCodeKtxLlmRuntime {
             outputFormat: { type: 'json_schema', schema: jsonSchema(input.schema) },
         };
         const startedAt = Date.now();
-        const result = await collectResult({
+        const result = await collectResultWithRateLimitRetry({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
             options,
             allowedToolIds: new Set([...mcpToolIds(input.tools ?? {}), STRUCTURED_OUTPUT_TOOL_NAME]),
             expectedMcpServerNames: expectedMcpServerNames(input.tools),
+            rateLimitGovernor: this.deps.rateLimitGovernor,
+            abortSignal: input.abortSignal,
         });
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
@@ -234,9 +319,7 @@ export class ClaudeCodeKtxLlmRuntime {
         return input.schema.parse(result.structured_output);
     }
     async runAgentLoop(params) {
-        let stepIndex = 0;
         const startedAt = Date.now();
-        const stepBoundariesMs = [];
         try {
             const options = baseOptions({
                 projectDir: this.deps.projectDir,
@@ -245,25 +328,14 @@ export class ClaudeCodeKtxLlmRuntime {
                 maxTurns: params.stepBudget,
                 tools: params.toolSet,
             });
-            const result = await collectResult({
+            const result = await collectResultWithRateLimitRetry({
                 query: this.runQuery,
                 prompt: params.userPrompt,
                 options: { ...options, systemPrompt: params.systemPrompt },
                 allowedToolIds: new Set(mcpToolIds(params.toolSet)),
                 expectedMcpServerNames: expectedMcpServerNames(params.toolSet),
-                onAssistantTurn: async () => {
-                    stepIndex += 1;
-                    stepBoundariesMs.push(Date.now() - startedAt);
-                    if (!params.onStepFinish) {
-                        return;
-                    }
-                    try {
-                        await params.onStepFinish({ stepIndex, stepBudget: params.stepBudget });
-                    }
-                    catch (error) {
-                        this.logger.warn(`[claude-code-runner] onStepFinish callback threw; ignoring: ${error instanceof Error ? error.message : String(error)}`);
-                    }
-                },
+                rateLimitGovernor: this.deps.rateLimitGovernor,
+                abortSignal: params.abortSignal,
             });
             const stopReason = mapClaudeCodeStopReason(result);
             const error = resultError(result);
@@ -272,18 +344,25 @@ export class ClaudeCodeKtxLlmRuntime {
                 ...(stopReason === 'error' && error ? { error } : {}),
                 metrics: {
                     totalMs: Date.now() - startedAt,
-                    stepCount: stepIndex,
-                    stepBoundariesMs,
+                    // Authoritative turn count from the SDK result. The runtime no longer
+                    // re-derives a per-turn counter: it could not match the SDK's `num_turns`
+                    // and overshot `maxTurns` (the source of the misleading `step 70/40`).
+                    // Per-step boundaries require that counter and are not consumed anywhere.
+                    stepCount: result.num_turns,
+                    stepBoundariesMs: [],
                     usage: claudeTokenUsage(result),
                 },
             };
         }
         catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
             const err = error instanceof Error ? error : new Error(String(error));
             return {
                 stopReason: 'error',
                 error: err,
-                metrics: { totalMs: Date.now() - startedAt, stepCount: stepIndex, stepBoundariesMs, usage: {} },
+                metrics: { totalMs: Date.now() - startedAt, stepCount: 0, stepBoundariesMs: [], usage: {} },
             };
         }
     }
@@ -306,7 +385,7 @@ export async function runClaudeCodeAuthProbe(input) {
             env: input.env,
             maxTurns: 1,
         });
-        const result = await collectResult({
+        const result = await collectResultWithRateLimitRetry({
             query: input.query ?? defaultQuery,
             prompt: 'Reply with exactly: ok',
             options,

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { type KtxLogger } from '../core/config.js';
 import { type CodexRuntimeMcpServerHandle } from './codex-mcp-runtime-server.js';
 import { type CodexSdkRunner } from './codex-sdk-runner.js';
+import type { RateLimitGovernor } from './rate-limit-governor.js';
 import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, KtxRuntimeToolSet, RunLoopParams, RunLoopResult } from './runtime-port.js';
 export interface CodexKtxLlmRuntimeDeps {
     projectDir: string;
@@ -13,13 +13,13 @@ export interface CodexKtxLlmRuntimeDeps {
         projectDir: string;
         toolSet: KtxRuntimeToolSet;
     }) => Promise<CodexRuntimeMcpServerHandle>;
-    logger?: KtxLogger;
+    rateLimitGovernor?: Pick<RateLimitGovernor, 'waitForReady' | 'report' | 'maxRetryAttempts'>;
 }
 export declare class CodexKtxLlmRuntime implements KtxLlmRuntimePort {
     private readonly deps;
     private readonly runner;
-    private readonly logger;
     constructor(deps: CodexKtxLlmRuntimeDeps);
+    private runWithRateLimitRetry;
     generateText(input: KtxGenerateTextInput): Promise<string>;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;
     runAgentLoop(params: RunLoopParams): Promise<RunLoopResult>;

package/dist/context/llm/codex-runtime.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { noopLogger } from '../core/config.js';
+import { isAbortError, linkAbortSignal } from '../core/abort.js';
 import { isCompletedAgentStep, summarizeCodexExecEvents } from './codex-exec-events.js';
 import { startCodexRuntimeMcpServer, } from './codex-mcp-runtime-server.js';
 import { resolveCodexModel } from './codex-models.js';
@@ -18,8 +18,8 @@ function isTurnCompleted(event) {
     return eventRecord(event)?.type === 'turn.completed';
 }
 /**
- * Drains the Codex stream once, emitting a step as each agent action completes
- * so callers see live progress and the step budget is enforced mid-run. Every
+ * Drains the Codex stream once, counting each completed agent action so the
+ * step budget is enforced mid-run. Every
  * completed agent-action item counts (see {@link isCompletedAgentStep}), so
  * built-in `command_execution` steps decrement the budget the same as
  * `mcp_tool_call`s. A turn that produced no actions still counts as one step,
@@ -48,7 +48,6 @@ async function collectEvents(events, options = {}) {
                 continue;
             }
             completedSteps += 1;
-            await options.onStep?.(completedSteps);
             if (isActionStep && options.stepBudget !== undefined && completedSteps >= options.stepBudget) {
                 budgetExceeded = true;
                 options.abortController?.abort();
@@ -107,14 +106,43 @@ async function mcpForTools(input) {
 function runtimeToolNames(toolSet) {
     return Object.values(toolSet ?? {}).map((descriptor) => descriptor.name);
 }
+const CODEX_RATE_LIMIT_MARKERS = /\b429\b|rate limit|too many requests|quota exceeded|temporarily overloaded/i;
+function isCodexRateLimitError(error) {
+    return !!error && CODEX_RATE_LIMIT_MARKERS.test(error.message);
+}
 export class CodexKtxLlmRuntime {
     deps;
     runner;
-    logger;
     constructor(deps) {
         this.deps = deps;
         this.runner = deps.runner ?? new CodexSdkCliRunner();
-        this.logger = deps.logger ?? noopLogger;
+    }
+    async runWithRateLimitRetry(abortSignal, run, getError) {
+        // maxRetryAttempts() returns 1 when no governor is present or pacing is
+        // disabled, so an opaque rate-limit failure surfaces on the first attempt
+        // instead of being retried with no backoff.
+        const maxAttempts = this.deps.rateLimitGovernor?.maxRetryAttempts() ?? 1;
+        for (let attempt = 0;; attempt += 1) {
+            await this.deps.rateLimitGovernor?.waitForReady(abortSignal);
+            const lastAttempt = attempt >= maxAttempts - 1;
+            try {
+                const result = await run();
+                const error = getError(result);
+                if (!isCodexRateLimitError(error) || lastAttempt) {
+                    return result;
+                }
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (!isCodexRateLimitError(err) || lastAttempt) {
+                    throw error;
+                }
+            }
+            this.deps.rateLimitGovernor?.report({ provider: 'codex', status: 'rejected', rateLimitType: 'opaque' });
+        }
     }
     async generateText(input) {
         const startedAt = Date.now();
@@ -138,16 +166,20 @@ export class CodexKtxLlmRuntime {
                     }
                     : {}),
             });
-            const collected = await collectEvents(await this.runner.runStreamed({
-                projectDir: this.deps.projectDir,
-                model,
-                prompt: promptWithSystem(input.system, input.prompt),
-                configOverrides: config.configOverrides,
-                env: config.env,
-            }));
-            const summary = summarizeCodexExecEvents(collected.events, { startedAt });
-            input.onMetrics?.(metrics(summary, startedAt));
-            return assertSuccessfulText(summary, collected.streamError);
+            const result = await this.runWithRateLimitRetry(input.abortSignal, async () => {
+                const collected = await collectEvents(await this.runner.runStreamed({
+                    projectDir: this.deps.projectDir,
+                    model,
+                    prompt: promptWithSystem(input.system, input.prompt),
+                    configOverrides: config.configOverrides,
+                    env: config.env,
+                    ...(input.abortSignal ? { signal: input.abortSignal } : {}),
+                }));
+                const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+                return { collected, summary };
+            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+            input.onMetrics?.(metrics(result.summary, startedAt));
+            return assertSuccessfulText(result.summary, result.collected.streamError);
         }
         finally {
             await mcp?.close();
@@ -175,17 +207,21 @@ export class CodexKtxLlmRuntime {
                     }
                     : {}),
             });
-            const collected = await collectEvents(await this.runner.runStreamed({
-                projectDir: this.deps.projectDir,
-                model,
-                prompt: promptWithSystem(input.system, input.prompt),
-                configOverrides: config.configOverrides,
-                env: config.env,
-                outputSchema: z.toJSONSchema(input.schema, { target: 'draft-7' }),
-            }));
-            const summary = summarizeCodexExecEvents(collected.events, { startedAt });
-            input.onMetrics?.(metrics(summary, startedAt));
-            return parseStructuredOutput(input.schema, assertSuccessfulText(summary, collected.streamError));
+            const result = await this.runWithRateLimitRetry(input.abortSignal, async () => {
+                const collected = await collectEvents(await this.runner.runStreamed({
+                    projectDir: this.deps.projectDir,
+                    model,
+                    prompt: promptWithSystem(input.system, input.prompt),
+                    configOverrides: config.configOverrides,
+                    env: config.env,
+                    outputSchema: z.toJSONSchema(input.schema, { target: 'draft-7' }),
+                    ...(input.abortSignal ? { signal: input.abortSignal } : {}),
+                }));
+                const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+                return { collected, summary };
+            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+            input.onMetrics?.(metrics(result.summary, startedAt));
+            return parseStructuredOutput(input.schema, assertSuccessfulText(result.summary, result.collected.streamError));
         }
         finally {
             await mcp?.close();
@@ -214,38 +250,45 @@ export class CodexKtxLlmRuntime {
                     }
                     : {}),
             });
-            const abortController = new AbortController();
-            const onStep = async (stepIndex) => {
+            const result = await this.runWithRateLimitRetry(params.abortSignal, async () => {
+                const linked = linkAbortSignal(params.abortSignal);
+                const abortController = linked.controller;
                 try {
-                    await params.onStepFinish?.({ stepIndex, stepBudget: params.stepBudget });
+                    const collected = await collectEvents(await this.runner.runStreamed({
+                        projectDir: this.deps.projectDir,
+                        model,
+                        prompt: promptWithSystem(params.systemPrompt, params.userPrompt),
+                        configOverrides: config.configOverrides,
+                        env: config.env,
+                        signal: abortController.signal,
+                    }), { stepBudget: params.stepBudget, abortController });
+                    const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+                    return { collected, summary };
                 }
-                catch (error) {
-                    this.logger.warn(`[codex-runner] onStepFinish callback threw; ignoring: ${error instanceof Error ? error.message : String(error)}`);
+                finally {
+                    linked.dispose();
                 }
-            };
-            const collected = await collectEvents(await this.runner.runStreamed({
-                projectDir: this.deps.projectDir,
-                model,
-                prompt: promptWithSystem(params.systemPrompt, params.userPrompt),
-                configOverrides: config.configOverrides,
-                env: config.env,
-                signal: abortController.signal,
-            }), { stepBudget: params.stepBudget, abortController, onStep });
-            const summary = summarizeCodexExecEvents(collected.events, { startedAt });
-            const error = summaryError(summary, collected.streamError);
-            const stopReason = collected.budgetExceeded ? 'budget' : error ? 'error' : summary.stopReason;
+            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+            const error = summaryError(result.summary, result.collected.streamError);
+            if (isAbortError(error)) {
+                throw error;
+            }
+            const stopReason = result.collected.budgetExceeded ? 'budget' : error ? 'error' : result.summary.stopReason;
             return {
                 stopReason,
                 ...(stopReason === 'error' && error ? { error } : {}),
                 metrics: {
                     totalMs: Date.now() - startedAt,
-                    usage: summary.usage,
-                    stepCount: summary.stepCount,
-                    stepBoundariesMs: summary.stepBoundariesMs,
+                    usage: result.summary.usage,
+                    stepCount: result.summary.stepCount,
+                    stepBoundariesMs: result.summary.stepBoundariesMs,
                 },
             };
         }
         catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
             const err = error instanceof Error ? error : new Error(String(error));
             return {
                 stopReason: 'error',

package/dist/context/llm/local-config.d.ts

@@ -2,19 +2,29 @@ import { createKtxEmbeddingProvider } from '../../llm/embedding-provider.js';
 import { createKtxLlmProvider } from '../../llm/model-provider.js';
 import type { KtxEmbeddingConfig, KtxEmbeddingProvider, KtxLlmConfig, KtxLlmProvider } from '../../llm/types.js';
 import type { KtxProjectEmbeddingConfig, KtxProjectLlmConfig } from '../project/config.js';
+import { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
 import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
 import { CodexKtxLlmRuntime } from './codex-runtime.js';
+import type { RateLimitGovernor } from './rate-limit-governor.js';
 import type { KtxLlmRuntimePort } from './runtime-port.js';
+type ClaudeCodeRuntimeDeps = ConstructorParameters<typeof ClaudeCodeKtxLlmRuntime>[0] & {
+    rateLimitGovernor?: RateLimitGovernor;
+};
+type CodexRuntimeDeps = ConstructorParameters<typeof CodexKtxLlmRuntime>[0] & {
+    rateLimitGovernor?: RateLimitGovernor;
+};
+type AiSdkRuntimeDeps = ConstructorParameters<typeof AiSdkKtxLlmRuntime>[0] & {
+    rateLimitGovernor?: RateLimitGovernor;
+};
 interface LocalConfigDeps {
     env?: NodeJS.ProcessEnv;
     projectDir?: string;
+    rateLimitGovernor?: RateLimitGovernor;
     createKtxLlmProvider?: typeof createKtxLlmProvider;
     createKtxEmbeddingProvider?: typeof createKtxEmbeddingProvider;
-    createClaudeCodeRuntime?: (deps: ConstructorParameters<typeof ClaudeCodeKtxLlmRuntime>[0]) => KtxLlmRuntimePort;
-    createCodexRuntime?: (deps: ConstructorParameters<typeof CodexKtxLlmRuntime>[0]) => KtxLlmRuntimePort;
-    createAiSdkRuntime?: (deps: {
-        llmProvider: KtxLlmProvider;
-    }) => KtxLlmRuntimePort;
+    createClaudeCodeRuntime?: (deps: ClaudeCodeRuntimeDeps) => KtxLlmRuntimePort;
+    createCodexRuntime?: (deps: CodexRuntimeDeps) => KtxLlmRuntimePort;
+    createAiSdkRuntime?: (deps: AiSdkRuntimeDeps) => KtxLlmRuntimePort;
 }
 export declare function resolveLocalKtxLlmConfig(config: KtxProjectLlmConfig, env: NodeJS.ProcessEnv): KtxLlmConfig | null;
 /** @internal */

package/dist/context/llm/local-config.js

@@ -90,6 +90,7 @@ export function createLocalKtxLlmRuntimeFromConfig(config, deps = {}) {
             projectDir,
             modelSlots: resolved.modelSlots,
             env: deps.env,
+            rateLimitGovernor: deps.rateLimitGovernor,
         });
     }
     if (resolved.backend === 'codex') {
@@ -100,10 +101,14 @@ export function createLocalKtxLlmRuntimeFromConfig(config, deps = {}) {
         return (deps.createCodexRuntime ?? ((runtimeDeps) => new CodexKtxLlmRuntime(runtimeDeps)))({
             projectDir,
             modelSlots: resolved.modelSlots,
+            rateLimitGovernor: deps.rateLimitGovernor,
         });
     }
     const llmProvider = (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
-    return (deps.createAiSdkRuntime ?? ((runtimeDeps) => new AiSdkKtxLlmRuntime(runtimeDeps)))({ llmProvider });
+    return (deps.createAiSdkRuntime ?? ((runtimeDeps) => new AiSdkKtxLlmRuntime(runtimeDeps)))({
+        llmProvider,
+        rateLimitGovernor: deps.rateLimitGovernor,
+    });
 }
 export function resolveLocalKtxEmbeddingConfig(config, env) {
     if (config.backend === 'none') {

package/dist/context/llm/rate-limit-governor.d.ts

@@ -0,0 +1,103 @@
+export type RateLimitProvider = 'claude-subscription' | 'anthropic-api' | 'vertex' | 'codex';
+type RateLimitSignalStatus = 'allowed' | 'warning' | 'rejected';
+export interface RateLimitSignal {
+    provider: RateLimitProvider;
+    status: RateLimitSignalStatus;
+    resetAtMs?: number;
+    retryAfterMs?: number;
+    utilization?: number;
+    rateLimitType?: string;
+}
+export interface RateLimitRetryConfig {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: boolean;
+}
+export interface RateLimitGovernorConfig {
+    enabled: boolean;
+    maxConcurrency: number;
+    throttleThreshold: number;
+    minConcurrencyUnderPressure: number;
+    maxWaitMs?: number;
+    waitStateTickMs: number;
+    retry: RateLimitRetryConfig;
+}
+export type RateLimitWaitState = {
+    kind: 'rate_limit_observed';
+    provider: RateLimitProvider;
+    status: RateLimitSignalStatus;
+    rateLimitType?: string;
+    resetAtMs?: number;
+    retryAfterMs?: number;
+    utilization?: number;
+} | {
+    kind: 'concurrency_adjusted';
+    provider: RateLimitProvider;
+    from: number;
+    to: number;
+    reason: string;
+    rateLimitType?: string;
+    utilization?: number;
+} | {
+    kind: 'wait_started' | 'wait_tick' | 'wait_finished';
+    provider: RateLimitProvider;
+    rateLimitType?: string;
+    resumeAtMs: number;
+    remainingMs: number;
+};
+export interface RateLimitGovernorDeps {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random?: () => number;
+}
+export type RateLimitRelease = () => void;
+type Subscriber = (state: RateLimitWaitState) => void;
+export declare function createRateLimitGovernorConfig(input?: Partial<RateLimitGovernorConfig> & {
+    retry?: Partial<RateLimitRetryConfig>;
+}): RateLimitGovernorConfig;
+export declare class RateLimitGovernor {
+    private readonly config;
+    private readonly now;
+    private readonly sleep;
+    private readonly random;
+    private readonly subscribers;
+    private waiters;
+    private active;
+    private effectiveLimit;
+    private pausedUntilMs;
+    private pausedProvider;
+    private pausedRateLimitType;
+    private pausedTickMs;
+    private opaqueAttempts;
+    private pauseGeneration;
+    private visibleWaitAbort;
+    constructor(config: RateLimitGovernorConfig, deps?: RateLimitGovernorDeps);
+    currentLimit(): number;
+    /**
+     * 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(): number;
+    activeSlots(): number;
+    subscribe(cb: Subscriber): () => void;
+    report(signal: RateLimitSignal): void;
+    waitForReady(signal?: AbortSignal): Promise<void>;
+    acquireWorkSlot(signal?: AbortSignal): Promise<RateLimitRelease>;
+    private applyPause;
+    private resumeAtMsFor;
+    private adjustLimit;
+    private startVisibleWaitTicker;
+    private stopVisibleWaitTicker;
+    private runVisibleWaitTicker;
+    private finishPause;
+    private waitForPause;
+    private waitForSlot;
+    private wakeWaiters;
+    private emitWait;
+    private emit;
+}
+export {};