@kaelio/ktx 0.7.0 → 0.9.0

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 KtxLogger } from '../core/config.js';
+import { type CodexRuntimeMcpServerHandle } from './codex-mcp-runtime-server.js';
+import { type CodexSdkRunner } from './codex-sdk-runner.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>;
+    logger?: KtxLogger;
+}
+export declare class CodexKtxLlmRuntime implements KtxLlmRuntimePort {
+    private readonly deps;
+    private readonly runner;
+    private readonly logger;
+    constructor(deps: CodexKtxLlmRuntimeDeps);
+    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;
+}>;

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

@@ -0,0 +1,304 @@
+import { z } from 'zod';
+import { noopLogger } from '../core/config.js';
+import { isCompletedAgentStep, summarizeCodexExecEvents } from './codex-exec-events.js';
+import { startCodexRuntimeMcpServer, } from './codex-mcp-runtime-server.js';
+import { resolveCodexModel } from './codex-models.js';
+import { buildCodexRuntimeConfig } from './codex-runtime-config.js';
+import { CodexSdkCliRunner } from './codex-sdk-runner.js';
+function modelForRole(modelSlots, role) {
+    return resolveCodexModel(modelSlots[role] ?? modelSlots.default);
+}
+function promptWithSystem(system, prompt) {
+    return [system, prompt].filter(Boolean).join('\n\n');
+}
+function eventRecord(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}
+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
+ * 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,
+ * matching the metrics summary and the AI SDK backend.
+ */
+async function collectEvents(events, options = {}) {
+    const collected = [];
+    let completedSteps = 0;
+    let sawActionStep = false;
+    let budgetExceeded = false;
+    let streamError;
+    // The SDK yields every stdout event, then throws on a non-zero codex exec
+    // exit. Catch that throw so the events already collected (which carry the
+    // real `turn.failed`/`error` reason) survive for the summary; the masked
+    // exit message is kept only as a fallback when no error event was emitted.
+    try {
+        for await (const event of events) {
+            collected.push(event);
+            const isActionStep = isCompletedAgentStep(event);
+            if (isActionStep) {
+                sawActionStep = true;
+            }
+            else if (sawActionStep || !isTurnCompleted(event)) {
+                // Only fall back to counting a bare turn as a step when the turn produced
+                // no agent actions; a completed turn is terminal, so it never aborts.
+                continue;
+            }
+            completedSteps += 1;
+            await options.onStep?.(completedSteps);
+            if (isActionStep && options.stepBudget !== undefined && completedSteps >= options.stepBudget) {
+                budgetExceeded = true;
+                options.abortController?.abort();
+                break;
+            }
+        }
+    }
+    catch (error) {
+        streamError = error instanceof Error ? error : new Error(String(error));
+    }
+    return { events: collected, budgetExceeded, ...(streamError ? { streamError } : {}) };
+}
+function metrics(summary, startedAt) {
+    return { totalMs: Date.now() - startedAt, usage: summary.usage };
+}
+function summaryError(summary, streamError) {
+    // A `turn.failed`/`error` event carries the real reason; prefer it over the
+    // SDK's generic non-zero-exit throw. Fall back to the stream error only when
+    // no event explained the failure (e.g. spawn failure or auth before a turn).
+    if (summary.error) {
+        return summary.error;
+    }
+    if (summary.toolFailures.length > 0) {
+        return new Error(`Codex runtime tool call failed: ${summary.toolFailures.join('; ')}`);
+    }
+    return streamError;
+}
+function assertSuccessfulText(summary, streamError) {
+    const error = summaryError(summary, streamError);
+    if (error) {
+        throw error;
+    }
+    if (!summary.finalText.trim()) {
+        throw new Error('Codex completed without an agent message');
+    }
+    return summary.finalText;
+}
+function parseStructuredOutput(schema, text) {
+    try {
+        return schema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Codex structured output failed validation: ${message}`);
+    }
+}
+async function mcpForTools(input) {
+    if (!input.toolSet || Object.keys(input.toolSet).length === 0) {
+        return undefined;
+    }
+    return (input.startMcpServer ?? startCodexRuntimeMcpServer)({
+        projectDir: input.projectDir,
+        toolSet: input.toolSet,
+    });
+}
+function runtimeToolNames(toolSet) {
+    return Object.values(toolSet ?? {}).map((descriptor) => descriptor.name);
+}
+export class CodexKtxLlmRuntime {
+    deps;
+    runner;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.runner = deps.runner ?? new CodexSdkCliRunner();
+        this.logger = deps.logger ?? noopLogger;
+    }
+    async generateText(input) {
+        const startedAt = Date.now();
+        const model = modelForRole(this.deps.modelSlots, input.role);
+        const mcp = await mcpForTools({
+            projectDir: this.deps.projectDir,
+            toolSet: input.tools,
+            startMcpServer: this.deps.startMcpServer,
+        });
+        try {
+            const config = buildCodexRuntimeConfig({
+                model,
+                ...(mcp
+                    ? {
+                        mcp: {
+                            url: mcp.url,
+                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
+                            bearerToken: mcp.bearerToken,
+                            toolNames: runtimeToolNames(input.tools),
+                        },
+                    }
+                    : {}),
+            });
+            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);
+        }
+        finally {
+            await mcp?.close();
+        }
+    }
+    async generateObject(input) {
+        const startedAt = Date.now();
+        const model = modelForRole(this.deps.modelSlots, input.role);
+        const mcp = await mcpForTools({
+            projectDir: this.deps.projectDir,
+            toolSet: input.tools,
+            startMcpServer: this.deps.startMcpServer,
+        });
+        try {
+            const config = buildCodexRuntimeConfig({
+                model,
+                ...(mcp
+                    ? {
+                        mcp: {
+                            url: mcp.url,
+                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
+                            bearerToken: mcp.bearerToken,
+                            toolNames: runtimeToolNames(input.tools),
+                        },
+                    }
+                    : {}),
+            });
+            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));
+        }
+        finally {
+            await mcp?.close();
+        }
+    }
+    async runAgentLoop(params) {
+        const startedAt = Date.now();
+        const model = modelForRole(this.deps.modelSlots, params.modelRole);
+        let mcp;
+        try {
+            mcp = await mcpForTools({
+                projectDir: this.deps.projectDir,
+                toolSet: params.toolSet,
+                startMcpServer: this.deps.startMcpServer,
+            });
+            const config = buildCodexRuntimeConfig({
+                model,
+                ...(mcp
+                    ? {
+                        mcp: {
+                            url: mcp.url,
+                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
+                            bearerToken: mcp.bearerToken,
+                            toolNames: runtimeToolNames(params.toolSet),
+                        },
+                    }
+                    : {}),
+            });
+            const abortController = new AbortController();
+            const onStep = async (stepIndex) => {
+                try {
+                    await params.onStepFinish?.({ stepIndex, stepBudget: params.stepBudget });
+                }
+                catch (error) {
+                    this.logger.warn(`[codex-runner] onStepFinish callback threw; ignoring: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            };
+            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;
+            return {
+                stopReason,
+                ...(stopReason === 'error' && error ? { error } : {}),
+                metrics: {
+                    totalMs: Date.now() - startedAt,
+                    usage: summary.usage,
+                    stepCount: summary.stepCount,
+                    stepBoundariesMs: summary.stepBoundariesMs,
+                },
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return {
+                stopReason: 'error',
+                error: err,
+                metrics: { totalMs: Date.now() - startedAt, usage: {}, stepCount: 0, stepBoundariesMs: [] },
+            };
+        }
+        finally {
+            await mcp?.close();
+        }
+    }
+}
+// A rejected model is not an auth failure: Codex authenticated, connected, and
+// the API refused the model id. These markers come from the API error envelope
+// (e.g. "model is not supported", "invalid_request_error").
+const MODEL_UNAVAILABLE_MARKERS = /\bnot supported\b|\bnot available\b|\bdoes not exist\b|invalid_request_error|\bunknown model\b|\bunsupported model\b/i;
+function describeCodexProbeFailure(model, message) {
+    if (MODEL_UNAVAILABLE_MARKERS.test(message)) {
+        const fix = `Run \`codex\` to see the models your account supports, then set llm.models.default in ktx.yaml (or rerun \`ktx setup\`).`;
+        return {
+            message: `Codex is authenticated, but the configured model "${model}" is not available for this Codex account. ${fix} Details: ${message}`,
+            fix,
+        };
+    }
+    const fix = `Authenticate Codex locally with the Codex CLI, verify the Codex CLI is installed, then rerun setup or \`ktx status\`.`;
+    return {
+        message: `Codex authentication is not usable. ${fix} Details: ${message}`,
+        fix,
+    };
+}
+export async function runCodexAuthProbe(input) {
+    let model;
+    try {
+        model = resolveCodexModel(input.model);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+            fix: 'Set llm.models.default in ktx.yaml to a supported codex model (codex, default, or a gpt-* / codex-* id), or rerun `ktx setup`.',
+        };
+    }
+    const runtime = new CodexKtxLlmRuntime({
+        projectDir: input.projectDir,
+        modelSlots: { default: model },
+        ...(input.runner ? { runner: input.runner } : {}),
+    });
+    try {
+        await runtime.generateText({ role: 'default', prompt: 'Reply with exactly: ok' });
+        return { ok: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, ...describeCodexProbeFailure(model, message) };
+    }
+}

package/dist/context/llm/codex-sdk-runner.d.ts

@@ -0,0 +1,21 @@
+export interface CodexSdkRunnerInput {
+    projectDir: string;
+    model: string;
+    prompt: string;
+    configOverrides?: Record<string, unknown>;
+    env?: Record<string, string>;
+    outputSchema?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface CodexSdkRunner {
+    runStreamed(input: CodexSdkRunnerInput): Promise<AsyncIterable<unknown>>;
+}
+export interface CodexSdkCliRunnerOptions {
+    envBase?: NodeJS.ProcessEnv;
+    codexPathOverride?: string;
+}
+export declare class CodexSdkCliRunner implements CodexSdkRunner {
+    private readonly options;
+    constructor(options?: CodexSdkCliRunnerOptions);
+    runStreamed(input: CodexSdkRunnerInput): Promise<AsyncIterable<unknown>>;
+}