@kaelio/ktx 0.7.0 → 0.9.0

package/dist/context/ingest/isolated-diff/patch-integrator.js

@@ -85,18 +85,88 @@ export async function integrateWorkUnitPatch(input) {
             });
         }
         catch (semanticError) {
-            if (preApplyHead) {
-                await input.integrationGit.resetHardTo(preApplyHead);
-            }
+            const reason = errorMessage(semanticError);
             await input.trace.event('error', 'integration', 'patch_semantic_conflict_after_textual_resolution', {
                 unitKey: input.unitKey,
                 patchPath: input.patchPath,
                 touchedPaths: textualResolution.changedPaths,
-                reason: errorMessage(semanticError),
+                reason,
             });
+            // A textual conflict and a semantic-gate failure can co-occur: the resolver
+            // reconciles the text but can leave wiki sl_refs pointing at measures the
+            // merged source no longer defines. Recover via the same gate repair the
+            // clean-apply branch uses, instead of hard-failing the whole job.
+            if (input.repairGateFailure) {
+                const gateRepair = await input.repairGateFailure({
+                    unitKey: input.unitKey,
+                    patchPath: input.patchPath,
+                    touchedPaths: textualResolution.changedPaths,
+                    reason,
+                });
+                if (gateRepair.status !== 'failed') {
+                    // The resolver wrote its merge to the worktree (unstaged); the repair
+                    // edited a subset on top. Commit the union so neither is dropped.
+                    const resolvedAndRepairedPaths = [
+                        ...new Set([...textualResolution.changedPaths, ...gateRepair.changedPaths]),
+                    ].sort();
+                    try {
+                        await traceTimed(input.trace, 'integration', 'semantic_gate_after_gate_repair', { unitKey: input.unitKey, touchedPaths: gateRepair.changedPaths }, async () => {
+                            await input.validateAppliedTree(gateRepair.changedPaths);
+                        });
+                        const commit = await input.integrationGit.commitFiles(resolvedAndRepairedPaths, `ingest: resolve WorkUnit ${input.unitKey} conflict`, input.author.name, input.author.email);
+                        if (commit.created) {
+                            await input.trace.event('debug', 'integration', 'patch_accepted_after_textual_resolution', {
+                                unitKey: input.unitKey,
+                                commitSha: commit.commitHash,
+                                touchedPaths: resolvedAndRepairedPaths,
+                                attempts: textualResolution.attempts,
+                                gateRepairAttempts: gateRepair.attempts,
+                            });
+                            return {
+                                status: 'accepted',
+                                commitSha: commit.commitHash,
+                                touchedPaths: resolvedAndRepairedPaths,
+                                textualResolution,
+                                gateRepair,
+                            };
+                        }
+                    }
+                    catch (repairValidationError) {
+                        if (preApplyHead) {
+                            await input.integrationGit.resetHardTo(preApplyHead);
+                        }
+                        await input.trace.event('error', 'integration', 'patch_semantic_conflict_after_textual_resolution', {
+                            unitKey: input.unitKey,
+                            patchPath: input.patchPath,
+                            touchedPaths: gateRepair.changedPaths,
+                            reason: errorMessage(repairValidationError),
+                        });
+                        return {
+                            status: 'semantic_conflict',
+                            reason: errorMessage(repairValidationError),
+                            touchedPaths: gateRepair.changedPaths,
+                            textualResolution,
+                            gateRepair,
+                        };
+                    }
+                }
+                if (preApplyHead) {
+                    await input.integrationGit.resetHardTo(preApplyHead);
+                }
+                return {
+                    status: 'semantic_conflict',
+                    reason: gateRepair.status === 'failed' ? gateRepair.reason : reason,
+                    touchedPaths: textualResolution.changedPaths,
+                    textualResolution,
+                    gateRepair,
+                };
+            }
+            if (preApplyHead) {
+                await input.integrationGit.resetHardTo(preApplyHead);
+            }
             return {
                 status: 'semantic_conflict',
-                reason: errorMessage(semanticError),
+                reason,
                 touchedPaths: textualResolution.changedPaths,
                 textualResolution,
             };

package/dist/context/ingest/isolated-diff/work-unit-executor.js

@@ -8,15 +8,37 @@ function patchFileName(unitIndex, unitKey) {
 export async function runIsolatedWorkUnit(input) {
     const sessionKey = `${input.trace.context.jobId}-${input.workUnit.unitKey}`;
     let cleanupOutcome = 'crash';
+    const createStartedAt = Date.now();
     const child = await input.sessionWorktreeService.create(sessionKey, input.ingestionBaseSha);
     await input.trace.event('debug', 'work_unit', 'work_unit_child_created', {
         unitKey: input.workUnit.unitKey,
         unitIndex: input.unitIndex,
         worktreePath: child.workdir,
         baseSha: input.ingestionBaseSha,
-    });
+    }, undefined, Date.now() - createStartedAt);
     try {
+        const runStartedAt = Date.now();
         const outcome = await input.run(child);
+        await input.trace.event('debug', 'work_unit', 'work_unit_executed', {
+            unitKey: input.workUnit.unitKey,
+            unitIndex: input.unitIndex,
+            status: outcome.status,
+            ...(outcome.metrics
+                ? {
+                    agentLoopMs: outcome.metrics.totalMs,
+                    stepCount: outcome.metrics.stepCount,
+                    ...(outcome.metrics.usage.inputTokens !== undefined
+                        ? { inputTokens: outcome.metrics.usage.inputTokens }
+                        : {}),
+                    ...(outcome.metrics.usage.outputTokens !== undefined
+                        ? { outputTokens: outcome.metrics.usage.outputTokens }
+                        : {}),
+                    ...(outcome.metrics.usage.totalTokens !== undefined
+                        ? { totalTokens: outcome.metrics.usage.totalTokens }
+                        : {}),
+                }
+                : {}),
+        }, undefined, Date.now() - runStartedAt);
         if (outcome.status !== 'success') {
             cleanupOutcome = 'success';
             await input.trace.event('error', 'work_unit', 'work_unit_failed_before_patch', {
@@ -51,11 +73,12 @@ export async function runIsolatedWorkUnit(input) {
         throw error;
     }
     finally {
+        const cleanupStartedAt = Date.now();
         await input.sessionWorktreeService.cleanup(child, cleanupOutcome);
         await input.trace.event('trace', 'work_unit', 'work_unit_child_cleanup', {
             unitKey: input.workUnit.unitKey,
             outcome: cleanupOutcome,
             worktreePath: child.workdir,
-        });
+        }, undefined, Date.now() - cleanupStartedAt);
     }
 }

package/dist/context/ingest/local-adapters.js

@@ -7,6 +7,7 @@ import { DbtSourceAdapter } from './adapters/dbt/dbt.adapter.js';
 import { FakeSourceAdapter } from './adapters/fake/fake.adapter.js';
 import { HistoricSqlSourceAdapter } from './adapters/historic-sql/historic-sql.adapter.js';
 import { PostgresPgssReader } from './adapters/historic-sql/postgres-pgss-reader.js';
+import { resolveQueryHistoryScopeFloor } from './adapters/historic-sql/scope-floor.js';
 import { HISTORIC_SQL_SOURCE_KEY, historicSqlUnifiedPullConfigSchema, } from './adapters/historic-sql/types.js';
 import { createDaemonLiveDatabaseIntrospection, } from './adapters/live-database/daemon-introspection.js';
 import { LiveDatabaseSourceAdapter } from './adapters/live-database/live-database.adapter.js';
@@ -113,14 +114,30 @@ function queryHistoryRecord(connection) {
     const queryHistory = isRecord(context?.queryHistory) ? context.queryHistory : null;
     return queryHistory;
 }
-function queryHistoryPullConfig(connection) {
+async function queryHistoryPullConfig(project, connectionId, connection) {
     const queryHistory = queryHistoryRecord(connection);
     if (queryHistory?.enabled !== true || !isRecord(connection))
         return null;
-    const dialect = historicSqlDialectByDriver.get(String(connection.driver ?? '').toLowerCase());
+    const driver = String(connection.driver ?? '').toLowerCase();
+    const dialect = historicSqlDialectByDriver.get(driver);
     if (!dialect)
         return null;
-    return { ...queryHistory, dialect };
+    const scopeFloor = await resolveQueryHistoryScopeFloor({
+        projectDir: project.projectDir,
+        connectionId,
+        driver,
+        connection,
+        storedQueryHistory: queryHistory,
+    });
+    const { enabled: _enabled, dialect: _dialect, enabledTables: _enabledTables, enabledSchemas: _enabledSchemas, scopeFloorWarnings: _scopeFloorWarnings, ...stored } = queryHistory;
+    return {
+        ...stored,
+        dialect,
+        ...(scopeFloor.enabledTables.length > 0 ? { enabledTables: scopeFloor.enabledTables } : {}),
+        ...(scopeFloor.enabledSchemas.length > 0 ? { enabledSchemas: scopeFloor.enabledSchemas } : {}),
+        ...(scopeFloor.modeledTableCatalog.length > 0 ? { modeledTableCatalog: scopeFloor.modeledTableCatalog } : {}),
+        ...(scopeFloor.warnings.length > 0 ? { scopeFloorWarnings: scopeFloor.warnings } : {}),
+    };
 }
 function stringField(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
@@ -168,7 +185,7 @@ export async function localPullConfigForAdapter(project, adapter, connectionId,
         if (options.historicSqlPullConfigOverride) {
             return historicSqlUnifiedPullConfigSchema.parse(options.historicSqlPullConfigOverride);
         }
-        const queryHistory = queryHistoryPullConfig(connection);
+        const queryHistory = await queryHistoryPullConfig(project, connectionId, connection);
         if (!queryHistory) {
             throw new Error(`Connection "${connectionId}" does not have context.queryHistory.enabled: true`);
         }

package/dist/context/ingest/local-bundle-runtime.js

@@ -488,9 +488,10 @@ function nextLocalJobId() {
 }
 function localIngestLlmProviderGuardMessage(projectDir) {
     return [
-        'ktx ingest requires llm.provider.backend: anthropic, vertex, gateway, or claude-code, or an injected agentRunner.',
-        'Configure a local Claude Code session or API-backed LLM, then rerun ingest:',
+        'ktx ingest requires llm.provider.backend: anthropic, vertex, gateway, claude-code, or codex, or an injected agentRunner.',
+        'Configure a local Claude Code/Codex session or API-backed LLM, then rerun ingest:',
         `  ktx setup --project-dir ${projectDir} --llm-backend claude-code --no-input`,
+        `  ktx setup --project-dir ${projectDir} --llm-backend codex --llm-model gpt-5.5 --no-input`,
         `  ktx setup --project-dir ${projectDir} --llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY --llm-model claude-sonnet-4-6 --no-input`,
     ].join('\n');
 }
@@ -574,6 +575,7 @@ export function createLocalBundleIngestRuntime(options) {
             workUnitMaxConcurrency: options.project.config.ingest.workUnits.maxConcurrency,
             workUnitStepBudget: options.project.config.ingest.workUnits.stepBudget,
             workUnitFailureMode: options.project.config.ingest.workUnits.failureMode,
+            profileIngest: options.project.config.ingest.profile,
             ingestTraceLevel: ingestTraceLevelFromEnv(),
         },
         skillsRegistry: new SkillsRegistryService({ skillsDir, logger }),

package/dist/context/ingest/local-ingest.d.ts

@@ -67,7 +67,7 @@ export interface LocalMetabaseFanoutProgress {
         metabaseDatabaseId: number;
         targetConnectionId: string;
         jobId: string;
-        status: 'done' | 'failed';
+        status: 'done' | 'partial' | 'failed';
     }): void;
 }
 export interface RunLocalMetabaseIngestOptions extends Omit<RunLocalIngestOptions, 'adapter' | 'connectionId' | 'sourceDir' | 'jobId'> {

package/dist/context/ingest/local-ingest.js

@@ -7,6 +7,7 @@ import { KtxYamlMetabaseSourceStateReader, LocalMetabaseDiscoveryCache } from '.
 import { localPullConfigForAdapter } from './local-adapters.js';
 import { createLocalBundleIngestRuntime } from './local-bundle-runtime.js';
 import { buildSyncId } from './raw-sources-paths.js';
+import { ingestReportOutcome } from './reports.js';
 import { SqliteBundleIngestStore } from './sqlite-bundle-ingest-store.js';
 class LocalIngestPhase {
     async updateProgress() { }
@@ -117,11 +118,11 @@ export async function runLocalIngest(options) {
     return { result, report };
 }
 function metabaseFanoutStatus(children) {
-    const succeeded = children.filter((child) => child.report.body.failedWorkUnits.length === 0).length;
-    if (succeeded === children.length) {
+    const outcomes = children.map((child) => ingestReportOutcome(child.report));
+    if (outcomes.every((outcome) => outcome === 'done')) {
         return 'all_succeeded';
     }
-    if (succeeded === 0) {
+    if (outcomes.every((outcome) => outcome === 'error')) {
         return 'all_failed';
     }
     return 'partial_failure';
@@ -266,12 +267,13 @@ export async function runLocalMetabaseIngest(options) {
                 error,
             });
         }
+        const childOutcome = ingestReportOutcome(child.report);
         options.progress?.onMetabaseChildCompleted?.({
             metabaseConnectionId,
             metabaseDatabaseId: childPlan.metabaseDatabaseId,
             targetConnectionId,
             jobId: child.report.jobId,
-            status: child.report.body.failedWorkUnits.length > 0 ? 'failed' : 'done',
+            status: childOutcome === 'error' ? 'failed' : childOutcome,
         });
         children.push({
             jobId: child.report.jobId,

package/dist/context/ingest/memory-flow/events.js

@@ -1,3 +1,4 @@
+import { ingestReportOutcome } from '../reports.js';
 function plannedWorkUnitFromLocal(workUnit) {
     return {
         unitKey: workUnit.unitKey,
@@ -39,7 +40,7 @@ function fullModeMetadata(input) {
     };
 }
 function reportStatus(report) {
-    return report.body.failedWorkUnits.length > 0 ? 'error' : 'done';
+    return ingestReportOutcome(report) === 'error' ? 'error' : 'done';
 }
 function reportCreatedEvent(report) {
     return { type: 'report_created', runId: report.runId, reportPath: report.id };

package/dist/context/ingest/ports.d.ts

@@ -111,6 +111,8 @@ interface IngestSettingsPort {
     workUnitMaxConcurrency?: number;
     workUnitStepBudget?: number;
     workUnitFailureMode?: 'abort' | 'continue';
+    /** Print a timing breakdown to stderr at the end of each run (config-driven; see also KTX_PROFILE_INGEST). `'json'` emits the raw structured profile. */
+    profileIngest?: boolean | 'json';
     ingestTraceLevel?: IngestTraceLevel;
 }
 interface IngestGitAuthor {

package/dist/context/ingest/reports.d.ts

@@ -116,5 +116,8 @@ export interface IngestSavedMemoryCounts {
     slCount: number;
 }
 export declare function savedMemoryCountsForReport(report: IngestReportSnapshot): IngestSavedMemoryCounts;
+/** @internal */
+export type IngestReportOutcome = 'done' | 'partial' | 'error';
+export declare function ingestReportOutcome(report: IngestReportSnapshot): IngestReportOutcome;
 export declare function buildStageIndexFromReportBody(jobId: string, connectionId: string, body: IngestReportBody): StageIndex;
 export {};

package/dist/context/ingest/reports.js

@@ -8,6 +8,16 @@ export function savedMemoryCountsForReport(report) {
         slCount: actions.filter((action) => action.target === 'sl').length,
     };
 }
+export function ingestReportOutcome(report) {
+    if (report.body.status === 'failed') {
+        return 'error';
+    }
+    if (report.body.failedWorkUnits.length === 0) {
+        return 'done';
+    }
+    const { wikiCount, slCount } = savedMemoryCountsForReport(report);
+    return wikiCount + slCount > 0 ? 'partial' : 'error';
+}
 export function buildStageIndexFromReportBody(jobId, connectionId, body) {
     return {
         jobId,

package/dist/context/ingest/stages/stage-3-work-units.d.ts

@@ -1,5 +1,5 @@
 import type { KtxModelRole } from '../../../llm/types.js';
-import type { AgentRunnerPort, KtxRuntimeToolSet } from '../../../context/llm/runtime-port.js';
+import type { AgentRunnerPort, KtxRuntimeToolSet, RunLoopMetrics } from '../../../context/llm/runtime-port.js';
 import type { CaptureSession, MemoryAction } from '../../../context/memory/types.js';
 import { type TouchedSlSource } from '../../../context/tools/touched-sl-sources.js';
 import type { WorkUnit } from '../types.js';
@@ -44,6 +44,8 @@ export interface WorkUnitOutcome {
     patchPath?: string;
     patchTouchedPaths?: string[];
     childWorktreePath?: string;
+    /** Timing and token metrics for the work-unit agent loop, used for ingest profiling. */
+    metrics?: RunLoopMetrics;
 }
 export declare function executeWorkUnit(deps: WorkUnitExecutionDeps, wu: WorkUnit): Promise<WorkUnitOutcome>;
 export {};

package/dist/context/ingest/stages/stage-3-work-units.js

@@ -72,6 +72,7 @@ export async function executeWorkUnit(deps, wu) {
             touchedSlSources: [],
             slDisallowed: wu.slDisallowed,
             slDisallowedReason: wu.slDisallowedReason,
+            ...(runResult.metrics ? { metrics: runResult.metrics } : {}),
         };
     };
     if (runResult.stopReason === 'error') {
@@ -104,5 +105,6 @@ export async function executeWorkUnit(deps, wu) {
         touchedSlSources: touched,
         slDisallowed: wu.slDisallowed,
         slDisallowedReason: wu.slDisallowedReason,
+        ...(runResult.metrics ? { metrics: runResult.metrics } : {}),
     };
 }

package/dist/context/ingest/stages/stage-4-reconciliation.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRunnerPort, KtxRuntimeToolSet } from '../../../context/llm/runtime-port.js';
+import type { AgentRunnerPort, KtxRuntimeToolSet, RunLoopMetrics } from '../../../context/llm/runtime-port.js';
 import type { KtxModelRole } from '../../../llm/types.js';
 import type { EvictionUnit } from '../types.js';
 import type { StageIndex } from './stage-index.types.js';
@@ -24,5 +24,6 @@ export interface ReconciliationOutcome {
     skipped: boolean;
     stopReason?: 'budget' | 'natural' | 'error';
     error?: Error;
+    metrics?: RunLoopMetrics;
 }
 export declare function runReconciliationStage4(ctx: ReconciliationContext): Promise<ReconciliationOutcome>;

package/dist/context/ingest/stages/stage-4-reconciliation.js

@@ -13,5 +13,5 @@ export async function runReconciliationStage4(ctx) {
         telemetryTags: { operationName: 'ingest-bundle-reconcile', source: ctx.sourceKey, jobId: ctx.jobId },
         onStepFinish: ctx.onStepFinish,
     });
-    return { skipped: false, stopReason: run.stopReason, error: run.error };
+    return { skipped: false, stopReason: run.stopReason, error: run.error, ...(run.metrics ? { metrics: run.metrics } : {}) };
 }

package/dist/context/ingest/tools/tool-call-logger.d.ts

@@ -30,4 +30,10 @@ interface ToolCallLoggerOptions {
  * effectively single-writer and lines land in call order.
  */
 export declare function wrapToolsWithLogger<T extends KtxRuntimeToolSet>(tools: T, logFilePath: string, wuKey: string, options?: ToolCallLoggerOptions): T;
+/**
+ * Await all in-flight tool-call log writes (best-effort, bounded by `timeoutMs`
+ * so it can never hang a caller). Lets readers such as the ingest profiler see
+ * complete transcripts despite the fire-and-forget append design.
+ */
+export declare function flushToolCallLogs(timeoutMs?: number): Promise<void>;
 export {};

package/dist/context/ingest/tools/tool-call-logger.js

@@ -59,8 +59,12 @@ export function wrapToolsWithLogger(tools, logFilePath, wuKey, options = {}) {
     }
     return wrapped;
 }
+// Fire-and-forget appends are intentional (the agent hot path must never block
+// or fail on logging), but readers like the ingest profiler need to know when
+// the writes have settled. Track in-flight appends so a consumer can flush.
+const pendingWrites = new Set();
 function appendEntry(path, entry) {
-    void (async () => {
+    const write = (async () => {
         try {
             await mkdir(dirname(path), { recursive: true });
             await appendFile(path, `${safeStringify(entry)}\n`, 'utf-8');
@@ -69,6 +73,37 @@ function appendEntry(path, entry) {
             // best-effort
         }
     })();
+    pendingWrites.add(write);
+    void write.finally(() => pendingWrites.delete(write));
+}
+/**
+ * Await all in-flight tool-call log writes (best-effort, bounded by `timeoutMs`
+ * so it can never hang a caller). Lets readers such as the ingest profiler see
+ * complete transcripts despite the fire-and-forget append design.
+ */
+export async function flushToolCallLogs(timeoutMs = 5000) {
+    const pending = [...pendingWrites];
+    if (pending.length === 0) {
+        return;
+    }
+    const settled = Promise.allSettled(pending).then(() => undefined);
+    if (timeoutMs <= 0) {
+        await settled;
+        return;
+    }
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([settled, timeout]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
 }
 function safeStringify(v) {
     try {

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

@@ -3,6 +3,16 @@ import { generateText, Output, stepCountIs } from 'ai';
 import { noopLogger } from '../../context/core/config.js';
 import { summarizeKtxLlmDebugRequest } from './debug-request-recorder.js';
 import { createAiSdkToolSet } from './runtime-tools.js';
+function toLlmTokenUsage(usage) {
+    if (!usage) {
+        return {};
+    }
+    return {
+        ...(usage.inputTokens !== undefined ? { inputTokens: usage.inputTokens } : {}),
+        ...(usage.outputTokens !== undefined ? { outputTokens: usage.outputTokens } : {}),
+        ...(usage.totalTokens !== undefined ? { totalTokens: usage.totalTokens } : {}),
+    };
+}
 function hasTools(tools) {
     return Object.keys(tools).length > 0;
 }
@@ -26,6 +36,7 @@ export class AiSdkKtxLlmRuntime {
             model,
         });
         const split = splitKtxSystemMessages(built.messages);
+        const startedAt = Date.now();
         const result = await generateText({
             model,
             temperature: input.temperature ?? 0,
@@ -40,6 +51,7 @@ export class AiSdkKtxLlmRuntime {
                 }
                 : {}),
         });
+        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');
         }
@@ -55,6 +67,7 @@ export class AiSdkKtxLlmRuntime {
             model,
         });
         const split = splitKtxSystemMessages(built.messages);
+        const startedAt = Date.now();
         const result = await generateText({
             model,
             temperature: input.temperature ?? 0,
@@ -70,6 +83,7 @@ export class AiSdkKtxLlmRuntime {
                 : {}),
             output: Output.object({ schema: input.schema }),
         });
+        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');
         }
@@ -77,6 +91,8 @@ export class AiSdkKtxLlmRuntime {
     }
     async runAgentLoop(params) {
         let stepIndex = 0;
+        const startedAt = Date.now();
+        const stepBoundariesMs = [];
         try {
             const model = this.deps.llmProvider.getModel(params.modelRole);
             const tools = createAiSdkToolSet(params.toolSet);
@@ -98,7 +114,7 @@ export class AiSdkKtxLlmRuntime {
                 messages: built.messages,
                 tools: built.tools,
             }));
-            await generateText({
+            const result = await generateText({
                 model,
                 temperature: 0,
                 stopWhen: stepCountIs(params.stepBudget),
@@ -111,6 +127,7 @@ export class AiSdkKtxLlmRuntime {
                 tools: built.tools,
                 onStepFinish: async () => {
                     stepIndex += 1;
+                    stepBoundariesMs.push(Date.now() - startedAt);
                     if (!params.onStepFinish) {
                         return;
                     }
@@ -122,12 +139,24 @@ export class AiSdkKtxLlmRuntime {
                     }
                 },
             });
-            return { stopReason: 'natural' };
+            return {
+                stopReason: 'natural',
+                metrics: {
+                    totalMs: Date.now() - startedAt,
+                    stepCount: stepIndex,
+                    stepBoundariesMs,
+                    usage: toLlmTokenUsage(result.totalUsage ?? result.usage),
+                },
+            };
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
             this.logger.warn(`[agent-runner] loop failed: ${err.message}`);
-            return { stopReason: 'error', error: err };
+            return {
+                stopReason: 'error',
+                error: err,
+                metrics: { totalMs: Date.now() - startedAt, stepCount: stepIndex, stepBoundariesMs, usage: {} },
+            };
         }
     }
 }

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

@@ -4,6 +4,19 @@ import { noopLogger } from '../../context/core/config.js';
 import { createKtxClaudeCodeEnv } from './claude-code-env.js';
 import { resolveClaudeCodeModel } from './claude-code-models.js';
 import { createClaudeSdkTools, mcpToolIds } from './runtime-tools.js';
+function claudeTokenUsage(result) {
+    const usage = result.usage;
+    if (!usage) {
+        return {};
+    }
+    const { input_tokens: inputTokens, output_tokens: outputTokens } = usage;
+    const totalTokens = inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined;
+    return {
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {}),
+    };
+}
 const BUILTIN_TOOLS = [
     'Agent',
     'Task',
@@ -168,6 +181,7 @@ export class ClaudeCodeKtxLlmRuntime {
             maxTurns: 1,
             tools: input.tools,
         });
+        const startedAt = Date.now();
         const result = await collectResult({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
@@ -175,6 +189,7 @@ export class ClaudeCodeKtxLlmRuntime {
             allowedToolIds: new Set(mcpToolIds(input.tools ?? {})),
             expectedMcpServerNames: expectedMcpServerNames(input.tools),
         });
+        input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
         if (error) {
             throw error;
@@ -200,6 +215,7 @@ export class ClaudeCodeKtxLlmRuntime {
             }),
             outputFormat: { type: 'json_schema', schema: jsonSchema(input.schema) },
         };
+        const startedAt = Date.now();
         const result = await collectResult({
             query: this.runQuery,
             prompt: [input.system, input.prompt].filter(Boolean).join('\n\n'),
@@ -207,6 +223,7 @@ export class ClaudeCodeKtxLlmRuntime {
             allowedToolIds: new Set([...mcpToolIds(input.tools ?? {}), STRUCTURED_OUTPUT_TOOL_NAME]),
             expectedMcpServerNames: expectedMcpServerNames(input.tools),
         });
+        input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: claudeTokenUsage(result) });
         const error = resultError(result);
         if (error) {
             throw error;
@@ -218,6 +235,8 @@ export class ClaudeCodeKtxLlmRuntime {
     }
     async runAgentLoop(params) {
         let stepIndex = 0;
+        const startedAt = Date.now();
+        const stepBoundariesMs = [];
         try {
             const options = baseOptions({
                 projectDir: this.deps.projectDir,
@@ -234,6 +253,7 @@ export class ClaudeCodeKtxLlmRuntime {
                 expectedMcpServerNames: expectedMcpServerNames(params.toolSet),
                 onAssistantTurn: async () => {
                     stepIndex += 1;
+                    stepBoundariesMs.push(Date.now() - startedAt);
                     if (!params.onStepFinish) {
                         return;
                     }
@@ -247,11 +267,24 @@ export class ClaudeCodeKtxLlmRuntime {
             });
             const stopReason = mapClaudeCodeStopReason(result);
             const error = resultError(result);
-            return { stopReason, ...(stopReason === 'error' && error ? { error } : {}) };
+            return {
+                stopReason,
+                ...(stopReason === 'error' && error ? { error } : {}),
+                metrics: {
+                    totalMs: Date.now() - startedAt,
+                    stepCount: stepIndex,
+                    stepBoundariesMs,
+                    usage: claudeTokenUsage(result),
+                },
+            };
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            return { stopReason: 'error', error: err };
+            return {
+                stopReason: 'error',
+                error: err,
+                metrics: { totalMs: Date.now() - startedAt, stepCount: stepIndex, stepBoundariesMs, usage: {} },
+            };
         }
     }
 }

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