@kaelio/ktx 0.9.0 → 0.11.0

package/dist/context/llm/ai-sdk-runtime.js

@@ -1,6 +1,7 @@
 import { KtxMessageBuilder, splitKtxSystemMessages } from '../../llm/message-builder.js';
 import { generateText, Output, stepCountIs } from 'ai';
 import { noopLogger } from '../../context/core/config.js';
+import { isAbortError } from '../core/abort.js';
 import { summarizeKtxLlmDebugRequest } from './debug-request-recorder.js';
 import { createAiSdkToolSet } from './runtime-tools.js';
 function toLlmTokenUsage(usage) {
@@ -16,6 +17,108 @@ function toLlmTokenUsage(usage) {
 function hasTools(tools) {
     return Object.keys(tools).length > 0;
 }
+function modelProviderName(model) {
+    const provider = model.provider ?? '';
+    return provider.includes('vertex') || provider.includes('google') ? 'vertex' : 'anthropic-api';
+}
+const RATE_LIMIT_HEADER_PAIRS = [
+    {
+        limit: 'anthropic-ratelimit-requests-limit',
+        remaining: 'anthropic-ratelimit-requests-remaining',
+        rateLimitType: 'rpm',
+    },
+    {
+        limit: 'anthropic-ratelimit-tokens-limit',
+        remaining: 'anthropic-ratelimit-tokens-remaining',
+        rateLimitType: 'tpm',
+    },
+    {
+        limit: 'anthropic-ratelimit-input-tokens-limit',
+        remaining: 'anthropic-ratelimit-input-tokens-remaining',
+        rateLimitType: 'itpm',
+    },
+    {
+        limit: 'anthropic-ratelimit-output-tokens-limit',
+        remaining: 'anthropic-ratelimit-output-tokens-remaining',
+        rateLimitType: 'otpm',
+    },
+    {
+        limit: 'x-ratelimit-limit-requests',
+        remaining: 'x-ratelimit-remaining-requests',
+        rateLimitType: 'rpm',
+    },
+    {
+        limit: 'x-ratelimit-limit-tokens',
+        remaining: 'x-ratelimit-remaining-tokens',
+        rateLimitType: 'tpm',
+    },
+];
+function normalizeHeaders(headers) {
+    if (!headers || typeof headers !== 'object') {
+        return {};
+    }
+    const get = headers.get;
+    if (typeof get === 'function') {
+        const out = {};
+        for (const pair of RATE_LIMIT_HEADER_PAIRS) {
+            const limit = get.call(headers, pair.limit);
+            const remaining = get.call(headers, pair.remaining);
+            if (typeof limit === 'string')
+                out[pair.limit] = limit;
+            if (typeof remaining === 'string')
+                out[pair.remaining] = remaining;
+        }
+        return out;
+    }
+    return Object.fromEntries(Object.entries(headers)
+        .filter((entry) => typeof entry[1] === 'string' || typeof entry[1] === 'number')
+        .map(([key, value]) => [key.toLowerCase(), String(value)]));
+}
+function numericHeader(headers, key) {
+    const value = Number(headers[key]);
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function utilizationForPair(headers, pair) {
+    const limit = numericHeader(headers, pair.limit);
+    const remaining = numericHeader(headers, pair.remaining);
+    if (limit === undefined || remaining === undefined || limit <= 0) {
+        return undefined;
+    }
+    return 1 - Math.min(limit, remaining) / limit;
+}
+function aiSdkHeaderRateLimitSignal(provider, result) {
+    const headers = normalizeHeaders(result.response?.headers);
+    let best;
+    for (const pair of RATE_LIMIT_HEADER_PAIRS) {
+        const utilization = utilizationForPair(headers, pair);
+        if (utilization === undefined) {
+            continue;
+        }
+        if (!best || utilization > best.utilization) {
+            best = { utilization, rateLimitType: pair.rateLimitType };
+        }
+    }
+    if (!best) {
+        return undefined;
+    }
+    return {
+        provider,
+        status: 'allowed',
+        rateLimitType: best.rateLimitType,
+        utilization: Number(best.utilization.toFixed(4)),
+    };
+}
+function retryAfterMs(error) {
+    const value = error.retryAfter;
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return value < 1_000 ? value * 1_000 : value;
+    }
+    return undefined;
+}
+function isAiSdkRateLimitError(error) {
+    const record = error;
+    return record.name === 'TooManyRequestsError' || record.statusCode === 429 || record.status === 429;
+}
 export class AiSdkKtxLlmRuntime {
     deps;
     logger;
@@ -23,6 +126,37 @@ export class AiSdkKtxLlmRuntime {
         this.deps = deps;
         this.logger = deps.logger ?? noopLogger;
     }
+    async generateTextWithRateLimitRetry(provider, abortSignal, run) {
+        // maxRetryAttempts() returns 1 when no governor is present or pacing is
+        // disabled, so a 429 throws immediately instead of hammering the provider
+        // with no backoff; the AI SDK's own maxRetries still handles transient 429s.
+        const maxAttempts = this.deps.rateLimitGovernor?.maxRetryAttempts() ?? 1;
+        let attempt = 0;
+        while (true) {
+            await this.deps.rateLimitGovernor?.waitForReady(abortSignal);
+            try {
+                const result = await run();
+                const signal = aiSdkHeaderRateLimitSignal(provider, result);
+                if (signal) {
+                    this.deps.rateLimitGovernor?.report(signal);
+                }
+                return result;
+            }
+            catch (error) {
+                if (isAbortError(error) || !isAiSdkRateLimitError(error) || attempt >= maxAttempts - 1) {
+                    throw error;
+                }
+                attempt += 1;
+                const retryAfter = retryAfterMs(error);
+                this.deps.rateLimitGovernor?.report({
+                    provider,
+                    status: 'rejected',
+                    rateLimitType: 'http_429',
+                    ...(retryAfter !== undefined ? { retryAfterMs: retryAfter } : {}),
+                });
+            }
+        }
+    }
     async generateText(input) {
         const model = this.deps.llmProvider.getModel(input.role);
         if (model.provider === 'deterministic') {
@@ -37,12 +171,13 @@ export class AiSdkKtxLlmRuntime {
         });
         const split = splitKtxSystemMessages(built.messages);
         const startedAt = Date.now();
-        const result = await generateText({
+        const request = {
             model,
             temperature: input.temperature ?? 0,
             ...(split.system ? { system: split.system } : {}),
             messages: split.messages,
             tools: built.tools,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
             ...(hasTools(tools)
                 ? {
                     experimental_repairToolCall: this.deps.llmProvider.repairToolCallHandler({
@@ -50,7 +185,8 @@ export class AiSdkKtxLlmRuntime {
                     }),
                 }
                 : {}),
-        });
+        };
+        const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), input.abortSignal, () => generateText(request));
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: toLlmTokenUsage(result.totalUsage ?? result.usage) });
         if (typeof result.text !== 'string') {
             throw new Error('KTX LLM text generation returned no text');
@@ -68,12 +204,13 @@ export class AiSdkKtxLlmRuntime {
         });
         const split = splitKtxSystemMessages(built.messages);
         const startedAt = Date.now();
-        const result = await generateText({
+        const request = {
             model,
             temperature: input.temperature ?? 0,
             ...(split.system ? { system: split.system } : {}),
             messages: split.messages,
             tools: built.tools,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
             ...(hasTools(tools)
                 ? {
                     experimental_repairToolCall: this.deps.llmProvider.repairToolCallHandler({
@@ -82,7 +219,8 @@ export class AiSdkKtxLlmRuntime {
                 }
                 : {}),
             output: Output.object({ schema: input.schema }),
-        });
+        };
+        const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), input.abortSignal, () => generateText(request));
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: toLlmTokenUsage(result.totalUsage ?? result.usage) });
         if (result.output == null) {
             throw new Error('KTX LLM object generation returned no output');
@@ -114,7 +252,7 @@ export class AiSdkKtxLlmRuntime {
                 messages: built.messages,
                 tools: built.tools,
             }));
-            const result = await generateText({
+            const request = {
                 model,
                 temperature: 0,
                 stopWhen: stepCountIs(params.stepBudget),
@@ -125,20 +263,15 @@ export class AiSdkKtxLlmRuntime {
                 ...(promptMessages.system ? { system: promptMessages.system } : {}),
                 messages: promptMessages.messages,
                 tools: built.tools,
-                onStepFinish: async () => {
+                ...(params.abortSignal ? { abortSignal: params.abortSignal } : {}),
+                // Count model round-trips locally for metrics. `stepCountIs(stepBudget)`
+                // caps the loop, so this counter never exceeds the budget.
+                onStepFinish: () => {
                     stepIndex += 1;
                     stepBoundariesMs.push(Date.now() - startedAt);
-                    if (!params.onStepFinish) {
-                        return;
-                    }
-                    try {
-                        await params.onStepFinish({ stepIndex, stepBudget: params.stepBudget });
-                    }
-                    catch (err) {
-                        this.logger.warn(`[agent-runner] onStepFinish callback threw; ignoring: ${err instanceof Error ? err.message : String(err)}`);
-                    }
                 },
-            });
+            };
+            const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), params.abortSignal, () => generateText(request));
             return {
                 stopReason: 'natural',
                 metrics: {
@@ -150,6 +283,9 @@ export class AiSdkKtxLlmRuntime {
             };
         }
         catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
             const err = error instanceof Error ? error : new Error(String(error));
             this.logger.warn(`[agent-runner] loop failed: ${err.message}`);
             return {

package/dist/context/llm/claude-code-runtime.d.ts

@@ -1,8 +1,11 @@
 import { query as defaultQuery, type SDKMessage, type SDKResultMessage } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
-import { type KtxLogger } from '../../context/core/config.js';
+import type { RateLimitGovernor } from './rate-limit-governor.js';
 import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, RunLoopParams, RunLoopResult, RunLoopStopReason } from './runtime-port.js';
-type QueryFn = (params: Parameters<typeof defaultQuery>[0]) => AsyncIterable<SDKMessage>;
+type QueryResult = AsyncIterable<SDKMessage> & {
+    interrupt?: () => void | Promise<void>;
+};
+type QueryFn = (params: Parameters<typeof defaultQuery>[0]) => QueryResult;
 export interface ClaudeCodeKtxLlmRuntimeDeps {
     projectDir: string;
     modelSlots: {
@@ -10,14 +13,13 @@ export interface ClaudeCodeKtxLlmRuntimeDeps {
     } & Partial<Record<string, string>>;
     query?: QueryFn;
     env?: NodeJS.ProcessEnv;
-    logger?: KtxLogger;
+    rateLimitGovernor?: Pick<RateLimitGovernor, 'waitForReady' | 'report' | 'maxRetryAttempts'>;
 }
 /** @internal */
 export declare function mapClaudeCodeStopReason(result: SDKResultMessage): RunLoopStopReason;
 export declare class ClaudeCodeKtxLlmRuntime implements KtxLlmRuntimePort {
     private readonly deps;
     private readonly runQuery;
-    private readonly logger;
     constructor(deps: ClaudeCodeKtxLlmRuntimeDeps);
     generateText(input: KtxGenerateTextInput): Promise<string>;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;

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>;