@kaelio/ktx 0.8.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-exec-events.d.ts

@@ -0,0 +1,20 @@
+import type { LlmTokenUsage, RunLoopStopReason } from './runtime-port.js';
+export interface CodexExecEventSummary {
+    finalText: string;
+    stopReason: RunLoopStopReason;
+    usage: LlmTokenUsage;
+    stepCount: number;
+    stepBoundariesMs: number[];
+    toolCallCount: number;
+    toolFailures: string[];
+    error?: Error;
+}
+interface CodexEventParseOptions {
+    startedAt?: number;
+    now?: () => number;
+}
+export declare function isCompletedAgentStep(event: unknown): boolean;
+/** @internal */
+export declare function parseCodexExecEventLine(line: string): unknown;
+export declare function summarizeCodexExecEvents(events: Iterable<unknown>, options?: CodexEventParseOptions): CodexExecEventSummary;
+export {};

package/dist/context/llm/codex-exec-events.js

@@ -0,0 +1,155 @@
+function record(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}
+/**
+ * Codex thread items that represent a discrete agent action consuming one loop
+ * step. The step budget caps the total number of these regardless of which
+ * capability the agent reaches for, so built-in `command_execution` (and any
+ * file/web action the public Codex surface still exposes) count alongside our
+ * own `mcp_tool_call` items rather than only the MCP ones.
+ */
+const AGENT_STEP_ITEM_TYPES = new Set(['command_execution', 'mcp_tool_call', 'file_change', 'web_search']);
+export function isCompletedAgentStep(event) {
+    const eventRecord = record(event);
+    if (eventRecord?.type !== 'item.completed') {
+        return false;
+    }
+    const itemType = record(eventRecord.item)?.type;
+    return typeof itemType === 'string' && AGENT_STEP_ITEM_TYPES.has(itemType);
+}
+function text(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function usageFrom(value) {
+    const usage = record(value);
+    if (!usage) {
+        return {};
+    }
+    const inputTokens = numberValue(usage.input_tokens ?? usage.inputTokens);
+    const outputTokens = numberValue(usage.output_tokens ?? usage.outputTokens);
+    const explicitTotalTokens = numberValue(usage.total_tokens ?? usage.totalTokens);
+    const totalTokens = explicitTotalTokens ??
+        (inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined);
+    return {
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {}),
+    };
+}
+function stopReasonFrom(value) {
+    const reason = text(value)?.toLowerCase();
+    if (reason && /(budget|max_turn|max-turn|limit)/.test(reason)) {
+        return 'budget';
+    }
+    return 'natural';
+}
+function errorMessageFrom(value) {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    const asRecord = record(value);
+    const message = text(asRecord?.message);
+    return message ?? text(value) ?? 'Codex turn failed';
+}
+/**
+ * Codex serializes API failures as a JSON envelope inside the event message
+ * (e.g. `{"type":"error","status":400,"error":{"message":"…"}}`). Surface the
+ * human-readable inner message so callers don't leak raw JSON; pass plain
+ * strings through unchanged.
+ */
+function unwrapCodexApiErrorMessage(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('{')) {
+        return raw;
+    }
+    try {
+        const parsed = record(JSON.parse(trimmed));
+        return text(record(parsed?.error)?.message) ?? text(parsed?.message) ?? raw;
+    }
+    catch {
+        return raw;
+    }
+}
+/** @internal */
+export function parseCodexExecEventLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (error) {
+        throw new Error(`Codex JSONL event stream was malformed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function summarizeCodexExecEvents(events, options = {}) {
+    const startedAt = options.startedAt ?? Date.now();
+    const now = options.now ?? Date.now;
+    let finalText = '';
+    let stopReason = 'natural';
+    let usage = {};
+    let turnCount = 0;
+    let completedStepCount = 0;
+    const stepBoundariesMs = [];
+    let toolCallCount = 0;
+    const toolFailures = [];
+    let error;
+    for (const event of events) {
+        const eventRecord = record(event);
+        const eventType = text(eventRecord?.type);
+        if (!eventRecord || !eventType) {
+            continue;
+        }
+        if (eventType === 'turn.started') {
+            turnCount += 1;
+            continue;
+        }
+        const item = record(eventRecord.item);
+        const itemType = text(item?.type);
+        if (eventType === 'item.started' && itemType === 'mcp_tool_call') {
+            toolCallCount += 1;
+            continue;
+        }
+        if (isCompletedAgentStep(event)) {
+            completedStepCount += 1;
+            stepBoundariesMs.push(now() - startedAt);
+            // Only MCP tool calls fail the loop: a non-zero `command_execution` exit
+            // is normal agent exploration, not a runtime error. `status` is the
+            // authoritative signal (the SDK always sets it); the SDK also serializes
+            // `error: null` on successful calls, so an explicit-null `error` must NOT
+            // be read as a failure — only a populated error object counts.
+            if (itemType === 'mcp_tool_call' && (item?.status === 'failed' || (item?.error !== undefined && item?.error !== null))) {
+                const name = text(item?.name) ?? text(item?.tool) ?? text(item?.tool_name) ?? 'unknown';
+                toolFailures.push(`${name}: ${errorMessageFrom(item?.error)}`);
+            }
+            continue;
+        }
+        if (eventType === 'item.completed' && itemType === 'agent_message') {
+            finalText = text(item?.text) ?? finalText;
+            continue;
+        }
+        if (eventType === 'turn.completed') {
+            usage = usageFrom(eventRecord.usage);
+            if (completedStepCount === 0) {
+                stepBoundariesMs.push(now() - startedAt);
+            }
+            stopReason = stopReasonFrom(eventRecord.reason ?? eventRecord.stop_reason ?? eventRecord.terminal_reason);
+            continue;
+        }
+        if (eventType === 'turn.failed' || eventType === 'error') {
+            stopReason = 'error';
+            error = new Error(unwrapCodexApiErrorMessage(errorMessageFrom(eventRecord.error ?? eventRecord.message)));
+            continue;
+        }
+    }
+    return {
+        finalText,
+        stopReason,
+        usage,
+        stepCount: completedStepCount > 0 ? completedStepCount : turnCount,
+        stepBoundariesMs,
+        toolCallCount,
+        toolFailures,
+        ...(error ? { error } : {}),
+    };
+}

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

@@ -0,0 +1,3 @@
+export declare const CODEX_ISOLATION_WARNING = "Codex backend isolation is limited by the public Codex SDK/CLI surface: ktx restricts the runtime MCP server to the current ktx tool set, disables Codex web search, asks for a read-only sandbox, and sets approval_policy=never, but Codex may still load user Codex config and built-in command execution or read-only file capabilities.";
+export declare const CODEX_ISOLATION_WARNING_FIX = "Use llm.provider.backend: claude-code when you need stricter Claude-Code-style runtime tool isolation, or remove host Codex MCP/tool config before running untrusted prompts through the codex backend.";
+export declare function formatCodexIsolationWarning(): string;

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

@@ -0,0 +1,5 @@
+export const CODEX_ISOLATION_WARNING = 'Codex backend isolation is limited by the public Codex SDK/CLI surface: ktx restricts the runtime MCP server to the current ktx tool set, disables Codex web search, asks for a read-only sandbox, and sets approval_policy=never, but Codex may still load user Codex config and built-in command execution or read-only file capabilities.';
+export const CODEX_ISOLATION_WARNING_FIX = 'Use llm.provider.backend: claude-code when you need stricter Claude-Code-style runtime tool isolation, or remove host Codex MCP/tool config before running untrusted prompts through the codex backend.';
+export function formatCodexIsolationWarning() {
+    return `${CODEX_ISOLATION_WARNING} ${CODEX_ISOLATION_WARNING_FIX}`;
+}

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

@@ -0,0 +1,24 @@
+import type { KtxMcpServerLike } from '../mcp/types.js';
+import { runKtxMcpHttpServer } from '../../mcp-http-server.js';
+import type { KtxRuntimeToolSet } from './runtime-port.js';
+/** @internal */
+export interface CreateCodexRuntimeMcpServerInput {
+    server?: KtxMcpServerLike;
+    toolSet: KtxRuntimeToolSet;
+}
+export interface CodexRuntimeMcpServerHandle {
+    url: string;
+    bearerTokenEnvVar: 'KTX_CODEX_RUNTIME_MCP_TOKEN';
+    bearerToken: string;
+    close(): Promise<void>;
+}
+type RunServer = typeof runKtxMcpHttpServer;
+export interface StartCodexRuntimeMcpServerInput {
+    projectDir: string;
+    toolSet: KtxRuntimeToolSet;
+    runServer?: RunServer;
+}
+/** @internal */
+export declare function createCodexRuntimeMcpServer(input: CreateCodexRuntimeMcpServerInput): KtxMcpServerLike;
+export declare function startCodexRuntimeMcpServer(input: StartCodexRuntimeMcpServerInput): Promise<CodexRuntimeMcpServerHandle>;
+export {};

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

@@ -0,0 +1,51 @@
+import { randomBytes } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { runKtxMcpHttpServer } from '../../mcp-http-server.js';
+import { normalizeKtxRuntimeToolOutput } from './runtime-tools.js';
+/** @internal */
+export function createCodexRuntimeMcpServer(input) {
+    const server = input.server ??
+        new McpServer({
+            name: 'ktx-runtime',
+            version: '0.0.0',
+        });
+    for (const descriptor of Object.values(input.toolSet)) {
+        server.registerTool(descriptor.name, {
+            description: descriptor.description,
+            inputSchema: descriptor.inputSchema.shape,
+        }, async (toolInput) => {
+            const normalized = normalizeKtxRuntimeToolOutput(await descriptor.execute(toolInput));
+            return {
+                content: [{ type: 'text', text: normalized.markdown }],
+                ...(normalized.structured !== undefined && normalized.structured !== null && typeof normalized.structured === 'object'
+                    ? { structuredContent: normalized.structured }
+                    : {}),
+            };
+        });
+    }
+    return server;
+}
+function serverPort(server, fallback) {
+    const address = server.address();
+    return typeof address === 'object' && address ? address.port : fallback;
+}
+export async function startCodexRuntimeMcpServer(input) {
+    const bearerToken = randomBytes(32).toString('hex');
+    const runServer = input.runServer ?? runKtxMcpHttpServer;
+    const handle = (await runServer({
+        projectDir: input.projectDir,
+        host: '127.0.0.1',
+        port: 0,
+        token: bearerToken,
+        allowedHosts: ['127.0.0.1', 'localhost'],
+        allowedOrigins: [],
+        createMcpServer: () => createCodexRuntimeMcpServer({ toolSet: input.toolSet }),
+    }));
+    const port = serverPort(handle.server, 0);
+    return {
+        url: `http://127.0.0.1:${port}/mcp`,
+        bearerTokenEnvVar: 'KTX_CODEX_RUNTIME_MCP_TOKEN',
+        bearerToken,
+        close: () => handle.close(),
+    };
+}

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

@@ -0,0 +1,2 @@
+export declare const DEFAULT_CODEX_MODEL = "gpt-5.5";
+export declare function resolveCodexModel(model: string): string;

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

@@ -0,0 +1,17 @@
+export const DEFAULT_CODEX_MODEL = 'gpt-5.5';
+const CODEX_MODEL_ALIASES = {
+    codex: DEFAULT_CODEX_MODEL,
+    default: DEFAULT_CODEX_MODEL,
+};
+const EXPLICIT_CODEX_MODEL_ID = /^(?:gpt|codex)-[a-z0-9][a-z0-9._-]*$/i;
+export function resolveCodexModel(model) {
+    const normalized = model.trim();
+    const alias = CODEX_MODEL_ALIASES[normalized];
+    if (alias) {
+        return alias;
+    }
+    if (EXPLICIT_CODEX_MODEL_ID.test(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Unsupported Codex model "${model}". Use codex, default, or a gpt-* / codex-* model id.`);
+}

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

@@ -0,0 +1,16 @@
+interface CodexRuntimeMcpConfig {
+    url: string;
+    bearerTokenEnvVar: string;
+    bearerToken: string;
+    toolNames: string[];
+}
+export interface BuildCodexRuntimeConfigInput {
+    model: string;
+    mcp?: CodexRuntimeMcpConfig;
+}
+export interface CodexRuntimeConfig {
+    configOverrides: Record<string, unknown>;
+    env: Record<string, string>;
+}
+export declare function buildCodexRuntimeConfig(input: BuildCodexRuntimeConfigInput): CodexRuntimeConfig;
+export {};

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

@@ -0,0 +1,19 @@
+export function buildCodexRuntimeConfig(input) {
+    const configOverrides = {
+        history: { persistence: 'none' },
+    };
+    const env = {};
+    if (input.mcp) {
+        configOverrides.mcp_servers = {
+            ktx: {
+                url: input.mcp.url,
+                bearer_token_env_var: input.mcp.bearerTokenEnvVar,
+                enabled_tools: input.mcp.toolNames,
+                default_tools_approval_mode: 'approve',
+                required: true,
+            },
+        };
+        env[input.mcp.bearerTokenEnvVar] = input.mcp.bearerToken;
+    }
+    return { configOverrides, env };
+}

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

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+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;
+    modelSlots: {
+        default: string;
+    } & Partial<Record<string, string>>;
+    runner?: CodexSdkRunner;
+    startMcpServer?: (input: {
+        projectDir: string;
+        toolSet: KtxRuntimeToolSet;
+    }) => Promise<CodexRuntimeMcpServerHandle>;
+    rateLimitGovernor?: Pick<RateLimitGovernor, 'waitForReady' | 'report' | 'maxRetryAttempts'>;
+}
+export declare class CodexKtxLlmRuntime implements KtxLlmRuntimePort {
+    private readonly deps;
+    private readonly runner;
+    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>;
+}
+export declare function runCodexAuthProbe(input: {
+    projectDir: string;
+    model: string;
+    runner?: CodexSdkRunner;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    fix: string;
+}>;