@kaelio/ktx 0.6.0 → 0.8.0

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',
@@ -28,6 +41,21 @@ 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;
@@ -124,7 +152,7 @@ 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 (message.type === 'assistant' && message.parent_tool_use_id === null) {
+        if (countsAsAssistantTurn(message)) {
             await params.onAssistantTurn?.();
         }
         if (isResult(message)) {
@@ -153,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'),
@@ -160,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;
@@ -185,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'),
@@ -192,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;
@@ -203,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,
@@ -219,6 +253,7 @@ export class ClaudeCodeKtxLlmRuntime {
                 expectedMcpServerNames: expectedMcpServerNames(params.toolSet),
                 onAssistantTurn: async () => {
                     stepIndex += 1;
+                    stepBoundariesMs.push(Date.now() - startedAt);
                     if (!params.onStepFinish) {
                         return;
                     }
@@ -232,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/runtime-port.d.ts

@@ -17,6 +17,22 @@ export interface RunLoopStepInfo {
     stepIndex: number;
     stepBudget: number;
 }
+export interface LlmTokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+/** Timing and token metrics for a multi-step agent loop, used for ingest profiling. */
+export interface RunLoopMetrics {
+    /** Wall-clock time around the whole `generateText` call, in milliseconds. */
+    totalMs: number;
+    /** Aggregate token usage across all steps. */
+    usage: LlmTokenUsage;
+    /** Number of agent steps (model round-trips) that actually ran. */
+    stepCount: number;
+    /** Wall-clock offset (ms from loop start) at which each step finished. */
+    stepBoundariesMs: number[];
+}
 export interface RunLoopParams {
     modelRole: KtxModelRole;
     systemPrompt: string;
@@ -29,6 +45,7 @@ export interface RunLoopParams {
 export interface RunLoopResult {
     stopReason: RunLoopStopReason;
     error?: Error;
+    metrics?: RunLoopMetrics;
 }
 export interface KtxGenerateTextInput {
     role: KtxModelRole;
@@ -36,6 +53,10 @@ export interface KtxGenerateTextInput {
     system?: string;
     tools?: KtxRuntimeToolSet;
     temperature?: number;
+    onMetrics?: (metrics: {
+        totalMs: number;
+        usage: LlmTokenUsage;
+    }) => void;
 }
 export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutput>> {
     role: KtxModelRole;
@@ -44,6 +65,10 @@ export interface KtxGenerateObjectInput<TOutput, TSchema extends z.ZodType<TOutp
     tools?: KtxRuntimeToolSet;
     temperature?: number;
     schema: TSchema;
+    onMetrics?: (metrics: {
+        totalMs: number;
+        usage: LlmTokenUsage;
+    }) => void;
 }
 export interface KtxLlmRuntimePort {
     generateText(input: KtxGenerateTextInput): Promise<string>;

package/dist/context/mcp/context-tools.d.ts

@@ -1,11 +1,12 @@
 import type { KtxCliIo } from '../../cli-runtime.js';
-import type { KtxMcpContextPorts, KtxMcpServerLike, KtxMcpToolResult, KtxMcpUserContext, NonArrayObject } from './types.js';
+import type { KtxMcpClientInfo, KtxMcpContextPorts, KtxMcpServerLike, KtxMcpToolResult, KtxMcpUserContext, NonArrayObject } from './types.js';
 export interface RegisterKtxContextToolsDeps {
     server: KtxMcpServerLike;
     ports: KtxMcpContextPorts;
     userContext: KtxMcpUserContext;
     projectDir?: string;
     io?: KtxCliIo;
+    getClientInfo?: () => KtxMcpClientInfo | undefined;
 }
 /** @internal */
 export declare function jsonToolResult<T extends NonArrayObject>(structuredContent: T): KtxMcpToolResult<T>;