@kaelio/ktx 0.9.0 → 0.11.0

package/dist/context/ingest/ingest-bundle.runner.js

@@ -115,6 +115,10 @@ export class IngestBundleRunner {
         this.logger = deps.logger ?? noopLogger;
     }
     async run(job, ctx) {
+        const unsubscribeRateLimitGovernor = this.subscribeRateLimitGovernor({
+            trace: this.createTrace(job),
+            memoryFlow: ctx?.memoryFlow,
+        });
         const key = job.connectionId;
         const previous = this.chainByConnection.get(key);
         if (previous) {
@@ -139,9 +143,64 @@ export class IngestBundleRunner {
             throw error;
         }
         finally {
+            unsubscribeRateLimitGovernor();
             await this.maybeEmitIngestProfile(job.jobId);
         }
     }
+    formatRateLimitWait(state) {
+        const seconds = Math.ceil(state.remainingMs / 1_000);
+        const minutes = Math.floor(seconds / 60);
+        const remainder = seconds % 60;
+        const duration = minutes > 0 ? `${minutes}m${String(remainder).padStart(2, '0')}s` : `${seconds}s`;
+        const type = state.rateLimitType ? ` ${state.rateLimitType}` : '';
+        return `Rate-limited (${state.provider}${type}); resuming in ${duration}; Ctrl+C to stop`;
+    }
+    subscribeRateLimitGovernor(input) {
+        const governor = this.deps.settings.rateLimitGovernor;
+        if (!governor) {
+            return () => undefined;
+        }
+        return governor.subscribe((state) => {
+            if (state.kind === 'rate_limit_observed') {
+                void input.trace.event('info', 'rate_limit', 'rate_limit_observed', { ...state });
+                return;
+            }
+            if (state.kind === 'concurrency_adjusted') {
+                void input.trace.event('info', 'rate_limit', 'concurrency_adjusted', { ...state });
+                return;
+            }
+            void input.trace.event('info', 'rate_limit', state.kind, { ...state });
+            if (state.kind === 'wait_tick' || state.kind === 'wait_started') {
+                input.memoryFlow?.emit({
+                    type: 'rate_limit_wait',
+                    provider: state.provider,
+                    ...(state.rateLimitType ? { rateLimitType: state.rateLimitType } : {}),
+                    resumeAtMs: state.resumeAtMs,
+                    remainingMs: state.remainingMs,
+                });
+                input.memoryFlow?.emit({
+                    type: 'stage_progress',
+                    stage: 'integration',
+                    percent: 50,
+                    message: this.formatRateLimitWait(state),
+                    transient: true,
+                });
+            }
+        });
+    }
+    async withRateLimitWorkSlot(abortSignal, fn) {
+        const governor = this.deps.settings.rateLimitGovernor;
+        if (!governor) {
+            return fn();
+        }
+        const release = await governor.acquireWorkSlot(abortSignal);
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
     /**
      * When profiling is enabled — via the `KTX_PROFILE_INGEST` env var or the
      * `ingest.profile` config setting — read the job's trace + tool transcripts
@@ -711,7 +770,6 @@ export class IngestBundleRunner {
             type: 'work_unit_started',
             unitKey: input.wu.unitKey,
             skills: input.wuSkillNames,
-            stepBudget: input.workUnitSettings.stepBudget,
         });
         return executeWorkUnit({
             sessionWorktreeGit: input.worktree.git,
@@ -731,14 +789,30 @@ export class IngestBundleRunner {
                 slIndex: input.slIndex,
                 priorProvenance: input.priorProvenance,
             }),
-            buildToolSet: (wuInner) => wrapToolsWithLogger(buildWuToolSet({
-                sourceKey: input.job.sourceKey,
-                stagedDir: input.stagedDir,
-                wu: wuInner,
-                loadSkillTool,
-                emitUnmappedFallbackTool: wuEmitUnmappedFallbackTool,
-                toolsetTools: wuToolset.toRuntimeTools(wuToolContext),
-            }), join(input.transcriptDir, `${wuInner.unitKey}.jsonl`), wuInner.unitKey, { onEntry: input.recordTranscriptEntry(join(input.transcriptDir, `${wuInner.unitKey}.jsonl`)) }),
+            buildToolSet: (wuInner) => {
+                const transcriptPath = join(input.transcriptDir, `${wuInner.unitKey}.jsonl`);
+                const record = input.recordTranscriptEntry(transcriptPath);
+                return wrapToolsWithLogger(buildWuToolSet({
+                    sourceKey: input.job.sourceKey,
+                    stagedDir: input.stagedDir,
+                    wu: wuInner,
+                    loadSkillTool,
+                    emitUnmappedFallbackTool: wuEmitUnmappedFallbackTool,
+                    toolsetTools: wuToolset.toRuntimeTools(wuToolContext),
+                }), transcriptPath, wuInner.unitKey, {
+                    // Drive the live HUD heartbeat from real tool calls: each invocation
+                    // ticks the running per-unit count. This is an observed signal, not a
+                    // re-derived turn count, so it can never overshoot a budget.
+                    onEntry: (entry) => {
+                        const summary = record(entry);
+                        input.memoryFlow?.emit({
+                            type: 'work_unit_step',
+                            unitKey: wuInner.unitKey,
+                            toolCalls: summary.toolCallCount,
+                        });
+                    },
+                });
+            },
             captureSession: session,
             sessionActions,
             modelRole: 'candidateExtraction',
@@ -747,7 +821,7 @@ export class IngestBundleRunner {
             connectionId: input.job.connectionId,
             jobId: input.job.jobId,
             toolFailureCount: (unitKey) => input.transcriptSummaries.get(unitKey)?.fatalErrorCount ?? 0,
-            onStepFinish: input.onStepFinish,
+            abortSignal: input.abortSignal,
         }, input.wu);
     }
     async runInner(job, ctx) {
@@ -797,6 +871,7 @@ export class IngestBundleRunner {
                 const current = transcriptSummaries.get(entry.wuKey) ?? createMutableToolTranscriptSummary(entry.wuKey, path);
                 recordToolTranscriptEntry(current, entry);
                 transcriptSummaries.set(entry.wuKey, current);
+                return current;
             };
             const overrideReport = await this.loadOverrideReport(job);
             const stage1 = ctx?.startPhase(0.08);
@@ -1111,7 +1186,7 @@ export class IngestBundleRunner {
                         await stage3?.updateProgress(1.0, '0 of 0 work units complete');
                     }
                     try {
-                        await Promise.all(workUnits.map((wu, index) => limitWorkUnit(async () => {
+                        await Promise.all(workUnits.map((wu, index) => limitWorkUnit(() => this.withRateLimitWorkSlot(ctx?.abortSignal, async () => {
                             const outcome = await runIsolatedWorkUnit({
                                 unitIndex: index,
                                 ingestionBaseSha,
@@ -1119,6 +1194,7 @@ export class IngestBundleRunner {
                                 patchDir,
                                 trace: runTrace,
                                 workUnit: wu,
+                                abortSignal: ctx?.abortSignal,
                                 afterSuccess: (child) => copyTransientIngestEvidence(child.workdir, sessionWorktree.workdir),
                                 run: async (child) => {
                                     const scopedWikiService = this.deps.wikiService.forWorktree(child.workdir);
@@ -1147,11 +1223,9 @@ export class IngestBundleRunner {
                                         stageIndex,
                                         includeContextEvidenceTools: adapter.evidenceIndexing === 'documents' && !!contextReport,
                                         currentTableExists: (tableRef) => this.tableRefExistsInSemanticLayer(scopedSemanticLayerService, slConnectionIds, tableRef),
+                                        abortSignal: ctx?.abortSignal,
                                         memoryFlow,
                                         wuSkillNames,
-                                        onStepFinish: ({ stepIndex, stepBudget }) => {
-                                            memoryFlow?.emit({ type: 'work_unit_step', unitKey: wu.unitKey, stepIndex, stepBudget });
-                                        },
                                     });
                                 },
                             });
@@ -1173,7 +1247,7 @@ export class IngestBundleRunner {
                             });
                             completedWorkUnits += 1;
                             await stage3?.updateProgress(completedWorkUnits / workUnits.length, `${completedWorkUnits} of ${workUnits.length} work units complete`);
-                        })));
+                        }))));
                     }
                     catch (error) {
                         await this.deps.runs.markFailed(runRow.id);
@@ -1250,6 +1324,7 @@ export class IngestBundleRunner {
                                     reason: context.reason,
                                     maxAttempts: 1,
                                     stepBudget: 12,
+                                    abortSignal: ctx?.abortSignal,
                                 });
                                 emitStageProgress('integration', 82, result.status === 'repaired'
                                     ? `Resolved text conflict for ${context.unitKey}`
@@ -1267,6 +1342,7 @@ export class IngestBundleRunner {
                                     repairKind: 'patch_semantic_gate',
                                     maxAttempts: 1,
                                     stepBudget: 16,
+                                    abortSignal: ctx?.abortSignal,
                                 });
                                 emitStageProgress('integration', 83, result.status === 'repaired'
                                     ? `Repaired semantic gate for ${context.unitKey}`
@@ -1451,6 +1527,37 @@ export class IngestBundleRunner {
                 let curatorReport = null;
                 let curatorWarnings = [];
                 let reconcileOutcome;
+                // Reconcile shares the work-unit liveness model: the HUD heartbeat is driven
+                // by real tool calls (a monotonic, observed count), not a re-derived turn
+                // counter. The soft cap only paces the phase progress bar; it is never shown
+                // to the user, so it cannot read as a misleading "X/Y" fraction.
+                const reconcileTranscriptPath = join(transcriptDir, 'reconcile.jsonl');
+                const reconcileProgressSoftCap = 40;
+                const buildReconcileToolSetWithHeartbeat = () => {
+                    const record = recordTranscriptEntry(reconcileTranscriptPath);
+                    return wrapToolsWithLogger(buildReconcileToolSet({
+                        loadSkillTool: rcLoadSkill,
+                        stageListTool: rcStageListTool,
+                        stageDiffTool: rcStageDiffTool,
+                        evictionListTool: rcEvictionListTool,
+                        emitConflictResolutionTool: rcEmitConflictResolutionTool,
+                        emitEvictionDecisionTool: rcEmitEvictionDecisionTool,
+                        emitArtifactResolutionTool: rcEmitArtifactResolutionTool,
+                        emitUnmappedFallbackTool: rcEmitUnmappedFallbackTool,
+                        readRawSpanTool: rcRawSpanTool,
+                        toolsetTools: rcToolset.toRuntimeTools(rcToolContext),
+                    }), reconcileTranscriptPath, 'reconcile', {
+                        onEntry: (entry) => {
+                            const summary = record(entry);
+                            if (!stage4) {
+                                return;
+                            }
+                            const label = `Reconciling results · ${summary.toolCallCount} action${summary.toolCallCount === 1 ? '' : 's'}`;
+                            emitStageProgress('reconciliation', 85, label, { transient: true });
+                            void stage4.updateProgress(Math.min(0.95, summary.toolCallCount / reconcileProgressSoftCap), label);
+                        },
+                    });
+                };
                 const reconcileStartedAt = Date.now();
                 const reconcileMode = contextReport && this.deps.curatorPagination ? 'curator' : 'single';
                 if (contextReport && this.deps.curatorPagination) {
@@ -1471,25 +1578,9 @@ export class IngestBundleRunner {
                             canonicalPins: relevantCanonicalPins,
                         }),
                         buildUserPrompt: ({ summary, items, runState }) => buildReconcileUserPrompt(stageIndex, eviction, { summary, items }, reconcileNotes, runState),
-                        buildToolSet: (_passNumber) => wrapToolsWithLogger(buildReconcileToolSet({
-                            loadSkillTool: rcLoadSkill,
-                            stageListTool: rcStageListTool,
-                            stageDiffTool: rcStageDiffTool,
-                            evictionListTool: rcEvictionListTool,
-                            emitConflictResolutionTool: rcEmitConflictResolutionTool,
-                            emitEvictionDecisionTool: rcEmitEvictionDecisionTool,
-                            emitArtifactResolutionTool: rcEmitArtifactResolutionTool,
-                            emitUnmappedFallbackTool: rcEmitUnmappedFallbackTool,
-                            readRawSpanTool: rcRawSpanTool,
-                            toolsetTools: rcToolset.toRuntimeTools(rcToolContext),
-                        }), join(transcriptDir, 'reconcile.jsonl'), 'reconcile', { onEntry: recordTranscriptEntry(join(transcriptDir, 'reconcile.jsonl')) }),
+                        buildToolSet: (_passNumber) => buildReconcileToolSetWithHeartbeat(),
                         getReconciliationActions: () => reconcileActions,
-                        onStepFinish: stage4
-                            ? ({ passNumber, stepIndex, stepBudget }) => {
-                                emitStageProgress('reconciliation', 85, `Reconciling results: pass ${passNumber} step ${stepIndex}/${stepBudget}`, { transient: true });
-                                void stage4.updateProgress(stepIndex / stepBudget, `Reconciling results · pass ${passNumber} step ${stepIndex}`);
-                            }
-                            : undefined,
+                        abortSignal: ctx?.abortSignal,
                     });
                     curatorReport = curatorOutcome.report;
                     curatorWarnings = curatorOutcome.warnings;
@@ -1512,31 +1603,13 @@ export class IngestBundleRunner {
                             canonicalPins: relevantCanonicalPins,
                         }),
                         buildUserPrompt: (idx, ev) => buildReconcileUserPrompt(idx, ev, undefined, reconcileNotes),
-                        buildToolSet: () => wrapToolsWithLogger(buildReconcileToolSet({
-                            loadSkillTool: rcLoadSkill,
-                            stageListTool: rcStageListTool,
-                            stageDiffTool: rcStageDiffTool,
-                            evictionListTool: rcEvictionListTool,
-                            emitConflictResolutionTool: rcEmitConflictResolutionTool,
-                            emitEvictionDecisionTool: rcEmitEvictionDecisionTool,
-                            emitArtifactResolutionTool: rcEmitArtifactResolutionTool,
-                            emitUnmappedFallbackTool: rcEmitUnmappedFallbackTool,
-                            readRawSpanTool: rcRawSpanTool,
-                            toolsetTools: rcToolset.toRuntimeTools(rcToolContext),
-                        }), join(transcriptDir, 'reconcile.jsonl'), 'reconcile', { onEntry: recordTranscriptEntry(join(transcriptDir, 'reconcile.jsonl')) }),
+                        buildToolSet: () => buildReconcileToolSetWithHeartbeat(),
                         modelRole: 'reconcile',
                         stepBudget: 60,
                         sourceKey: job.sourceKey,
                         jobId: job.jobId,
                         force: !!overrideReport,
-                        onStepFinish: stage4
-                            ? ({ stepIndex, stepBudget }) => {
-                                emitStageProgress('reconciliation', 85, `Reconciling results: step ${stepIndex}/${stepBudget}`, {
-                                    transient: true,
-                                });
-                                void stage4.updateProgress(stepIndex / stepBudget, `Reconciling results · step ${stepIndex}`);
-                            }
-                            : undefined,
+                        abortSignal: ctx?.abortSignal,
                     });
                 }
                 await runTrace.event('debug', 'reconciliation', 'reconciliation_executed', {
@@ -1890,6 +1963,7 @@ export class IngestBundleRunner {
                         repairKind: 'final_artifact_gate',
                         maxAttempts: 1,
                         stepBudget: 16,
+                        abortSignal: ctx?.abortSignal,
                     });
                     isolatedDiffSummary.gateRepairAttempts += gateRepair.attempts;
                     if (gateRepair.status === 'failed') {

package/dist/context/ingest/isolated-diff/textual-conflict-resolver.d.ts

@@ -19,5 +19,6 @@ export interface ResolveTextualConflictInput {
     reason: string;
     maxAttempts?: number;
     stepBudget?: number;
+    abortSignal?: AbortSignal;
 }
 export declare function resolveTextualConflict(input: ResolveTextualConflictInput): Promise<TextualConflictResolutionResult>;

package/dist/context/ingest/isolated-diff/textual-conflict-resolver.js

@@ -165,6 +165,7 @@ export async function resolveTextualConflict(input) {
                 jobId: input.trace.context.jobId,
                 unitKey: input.unitKey,
             },
+            abortSignal: input.abortSignal,
         }));
         if (result.stopReason === 'error') {
             lastFailure = result.error?.message ?? 'resolver agent loop errored';

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

@@ -9,6 +9,7 @@ export interface RunIsolatedWorkUnitInput {
     patchDir: string;
     trace: IngestTraceWriter;
     workUnit: WorkUnit;
+    abortSignal?: AbortSignal;
     run(child: IngestSessionWorktree): Promise<WorkUnitOutcome>;
     afterSuccess?(child: IngestSessionWorktree): Promise<void>;
 }

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

@@ -8,6 +8,7 @@ import { SessionWorktreeService } from '../../context/core/session-worktree.serv
 import { createRuntimeToolDescriptorFromAiTool } from '../../context/llm/runtime-tools.js';
 import { createLocalKtxLlmRuntimeFromConfig } from '../../context/llm/local-config.js';
 import { KtxIngestEmbeddingPortAdapter } from '../../context/llm/embedding-port.js';
+import { createRateLimitGovernorConfig, RateLimitGovernor } from '../../context/llm/rate-limit-governor.js';
 import { RuntimeAgentRunner } from '../../context/llm/runtime-port.js';
 import { ktxLocalStateDbPath } from '../../context/project/local-state-db.js';
 import { PromptService } from '../../context/prompts/prompt.service.js';
@@ -491,15 +492,16 @@ function localIngestLlmProviderGuardMessage(projectDir) {
         '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`,
+        `  ktx setup --project-dir ${projectDir} --llm-backend codex --no-input`,
+        `  ktx setup --project-dir ${projectDir} --llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY --no-input`,
     ].join('\n');
 }
-function resolveAgentRunner(options) {
+function resolveAgentRunner(options, rateLimitGovernor) {
     const llmRuntime = options.llmRuntime ??
         (options.createLlmRuntime ?? createLocalKtxLlmRuntimeFromConfig)(options.project.config.llm, {
             projectDir: options.project.projectDir,
             env: process.env,
+            rateLimitGovernor,
         }) ??
         undefined;
     if (options.agentRunner) {
@@ -536,7 +538,11 @@ export function createLocalBundleIngestRuntime(options) {
     const knowledgeIndex = new LocalKnowledgeIndex(options.project, embedding);
     const knowledgeEvents = new NoopKnowledgeEventPort();
     const wikiService = new KnowledgeWikiService(rootFileStore, embedding, knowledgeIndex, options.project.git, logger);
-    const { agentRunner, llmRuntime } = resolveAgentRunner(options);
+    const rateLimitGovernor = new RateLimitGovernor(createRateLimitGovernorConfig({
+        ...options.project.config.ingest.rateLimit,
+        maxConcurrency: options.project.config.ingest.workUnits.maxConcurrency,
+    }));
+    const { agentRunner, llmRuntime } = resolveAgentRunner(options, rateLimitGovernor);
     const promptService = new PromptService({ promptsDir, partials: [], logger });
     const storage = new LocalIngestStorage(options.project);
     const registry = registerAdapters(options.adapters);
@@ -575,6 +581,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,
+            rateLimitGovernor,
             profileIngest: options.project.config.ingest.profile,
             ingestTraceLevel: ingestTraceLevelFromEnv(),
         },

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

@@ -25,6 +25,7 @@ export interface RunLocalIngestOptions {
     queryExecutor?: KtxSqlQueryExecutorPort;
     logger?: KtxLogger;
     embeddingProvider?: import('../../llm/types.js').KtxEmbeddingProvider | null;
+    abortSignal?: AbortSignal;
 }
 export interface LocalIngestResult {
     result: IngestBundleResult;

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

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { cp, mkdir, rm } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
+import { createAbortError, isAbortError } from '../../context/core/abort.js';
 import { ktxLocalStateDbPath } from '../../context/project/local-state-db.js';
 import { planMetabaseFanoutChildren } from './adapters/metabase/fanout-planner.js';
 import { KtxYamlMetabaseSourceStateReader, LocalMetabaseDiscoveryCache } from './adapters/metabase/local-source-state-store.js';
@@ -36,10 +37,11 @@ function findAdapter(adapters, source) {
     }
     return adapter;
 }
-function localJobContext(jobId, memoryFlow) {
+function localJobContext(jobId, memoryFlow, abortSignal) {
     return {
         jobId,
         ...(memoryFlow ? { memoryFlow } : {}),
+        ...(abortSignal ? { abortSignal } : {}),
         startPhase() {
             return new LocalIngestPhase();
         },
@@ -62,7 +64,7 @@ async function runScheduledPullJob(options) {
         sourceKey: options.adapter.source,
         trigger: options.trigger ?? 'manual_resync',
         bundleRef: { kind: 'scheduled_pull', config: options.pullConfig },
-    }, localJobContext(jobId, options.memoryFlow));
+    }, localJobContext(jobId, options.memoryFlow, options.abortSignal));
     const report = await runtime.store.findByJobId(jobId);
     if (!report) {
         throw new Error(`Local ingest report for job "${jobId}" was not created`);
@@ -102,6 +104,7 @@ export async function runLocalIngest(options) {
             queryExecutor: options.queryExecutor,
             logger: options.logger,
             embeddingProvider: options.embeddingProvider,
+            abortSignal: options.abortSignal,
         });
     }
     const result = await runtime.runner.run({
@@ -110,7 +113,7 @@ export async function runLocalIngest(options) {
         sourceKey: adapter.source,
         trigger: options.trigger ?? (options.sourceDir ? 'upload' : 'manual_resync'),
         bundleRef,
-    }, localJobContext(jobId, options.memoryFlow));
+    }, localJobContext(jobId, options.memoryFlow, options.abortSignal));
     const report = await runtime.store.findByJobId(jobId);
     if (!report) {
         throw new Error(`Local ingest report for job "${jobId}" was not created`);
@@ -226,6 +229,9 @@ export async function runLocalMetabaseIngest(options) {
     });
     const children = [];
     for (const childPlan of childPlans) {
+        if (options.abortSignal?.aborted) {
+            throw createAbortError();
+        }
         const targetConnectionId = safeSegment('target connection id', childPlan.targetConnectionId);
         if (!options.project.config.connections[targetConnectionId]) {
             throw new Error(`Target connection "${targetConnectionId}" is not configured in ktx.yaml`);
@@ -255,9 +261,13 @@ export async function runLocalMetabaseIngest(options) {
                 queryExecutor: options.queryExecutor,
                 logger: options.logger,
                 embeddingProvider: options.embeddingProvider,
+                abortSignal: options.abortSignal,
             });
         }
         catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
             child = await recordLocalMetabaseChildFailure({
                 project: options.project,
                 jobId: childJobId,

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

@@ -127,7 +127,7 @@ export function ingestReportToMemoryFlowReplay(report, options = {}) {
     }
     const actions = allReportActions(report);
     const workUnitEvents = report.body.workUnits.flatMap((workUnit) => [
-        { type: 'work_unit_started', unitKey: workUnit.unitKey, skills: [], stepBudget: 0 },
+        { type: 'work_unit_started', unitKey: workUnit.unitKey, skills: [] },
         ...workUnit.actions.map((action) => ({
             type: 'candidate_action',
             unitKey: workUnit.unitKey,

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

@@ -64,17 +64,22 @@ const memoryFlowEventSchema = z.discriminatedUnion('type', [
         message: z.string().min(1),
         transient: z.boolean().optional(),
     }),
+    eventSchema({
+        type: z.literal('rate_limit_wait'),
+        provider: z.string(),
+        rateLimitType: z.string().optional(),
+        resumeAtMs: z.number().int().nonnegative(),
+        remainingMs: z.number().int().nonnegative(),
+    }),
     eventSchema({
         type: z.literal('work_unit_started'),
         unitKey: z.string().min(1),
         skills: z.array(z.string().min(1)),
-        stepBudget: z.number().int().min(0),
     }),
     eventSchema({
         type: z.literal('work_unit_step'),
         unitKey: z.string().min(1),
-        stepIndex: z.number().int().min(0),
-        stepBudget: z.number().int().min(0),
+        toolCalls: z.number().int().min(0),
     }),
     eventSchema({
         type: z.literal('candidate_action'),

package/dist/context/ingest/memory-flow/types.d.ts

@@ -44,16 +44,20 @@ type MemoryFlowEventPayload = {
     percent: number;
     message: string;
     transient?: boolean;
+} | {
+    type: 'rate_limit_wait';
+    provider: string;
+    rateLimitType?: string;
+    resumeAtMs: number;
+    remainingMs: number;
 } | {
     type: 'work_unit_started';
     unitKey: string;
     skills: string[];
-    stepBudget: number;
 } | {
     type: 'work_unit_step';
     unitKey: string;
-    stepIndex: number;
-    stepBudget: number;
+    toolCalls: number;
 } | {
     type: 'candidate_action';
     unitKey: string;

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

@@ -5,6 +5,7 @@ import type { KtxFileStorePort } from '../../context/core/file-store.js';
 import type { KtxLogger } from '../../context/core/config.js';
 import type { SessionOutcome } from '../../context/core/session-worktree.service.js';
 import type { AgentRunnerPort, KtxLlmRuntimePort, KtxRuntimeToolSet } from '../../context/llm/runtime-port.js';
+import type { RateLimitGovernor } from '../llm/rate-limit-governor.js';
 import type { MemoryAction, MemoryKnowledgeSlRefsPort } from '../../context/memory/types.js';
 import type { PromptService } from '../../context/prompts/prompt.service.js';
 import type { SkillsRegistryService } from '../../context/skills/skills-registry.service.js';
@@ -111,6 +112,7 @@ interface IngestSettingsPort {
     workUnitMaxConcurrency?: number;
     workUnitStepBudget?: number;
     workUnitFailureMode?: 'abort' | 'continue';
+    rateLimitGovernor?: RateLimitGovernor;
     /** 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;
@@ -282,11 +284,7 @@ export interface CuratorPaginationPort {
         }) => string;
         buildToolSet: (passNumber: number) => KtxRuntimeToolSet;
         getReconciliationActions: () => MemoryAction[];
-        onStepFinish?: (info: {
-            passNumber: number;
-            stepIndex: number;
-            stepBudget: number;
-        }) => void;
+        abortSignal?: AbortSignal;
     }): Promise<ReconciliationOutcome & {
         report: CuratorPaginationReport;
         warnings: string[];

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

@@ -25,10 +25,7 @@ export interface WorkUnitExecutionDeps {
     sourceKey: string;
     connectionId: string;
     jobId: string;
-    onStepFinish?: (info: {
-        stepIndex: number;
-        stepBudget: number;
-    }) => void;
+    abortSignal?: AbortSignal;
     toolFailureCount?: (unitKey: string) => number;
 }
 export interface WorkUnitOutcome {

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

@@ -1,3 +1,4 @@
+import { isAbortError } from '../../core/abort.js';
 import { listTouchedSlSources } from '../../../context/tools/touched-sl-sources.js';
 const MAX_WORK_UNIT_PROMPT_CHARS = 240_000;
 export async function executeWorkUnit(deps, wu) {
@@ -51,10 +52,13 @@ export async function executeWorkUnit(deps, wu) {
                 unitKey: wu.unitKey,
                 jobId: deps.jobId,
             },
-            onStepFinish: deps.onStepFinish,
+            abortSignal: deps.abortSignal,
         });
     }
     catch (error) {
+        if (isAbortError(error)) {
+            throw error;
+        }
         return failWithResetFromCurrentHead(error instanceof Error ? error.message : String(error));
     }
     const postSha = (await deps.sessionWorktreeGit.revParseHead()) ?? preSha;

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

@@ -14,10 +14,7 @@ export interface ReconciliationContext {
     sourceKey: string;
     jobId: string;
     force?: boolean;
-    onStepFinish?: (info: {
-        stepIndex: number;
-        stepBudget: number;
-    }) => void;
+    abortSignal?: AbortSignal;
     forceRun?: boolean;
 }
 export interface ReconciliationOutcome {

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

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

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

@@ -198,6 +198,7 @@ export interface IngestJobPhase {
 export interface IngestJobContext {
     jobId: string;
     memoryFlow?: MemoryFlowEventSink;
+    abortSignal?: AbortSignal;
     startPhase(weight: number): IngestJobPhase;
 }
 export {};

package/dist/context/llm/ai-sdk-runtime.d.ts

@@ -3,6 +3,7 @@ import { type TelemetrySettings } from 'ai';
 import type { z } from 'zod';
 import { type KtxLogger } from '../../context/core/config.js';
 import { type KtxLlmDebugRequestRecorder } from './debug-request-recorder.js';
+import type { RateLimitGovernor } from './rate-limit-governor.js';
 import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, RunLoopParams, RunLoopResult } from './runtime-port.js';
 interface AgentTelemetryPort {
     createTelemetry(tags: Record<string, string>): TelemetrySettings;
@@ -12,11 +13,13 @@ export interface AiSdkKtxLlmRuntimeDeps {
     telemetry?: AgentTelemetryPort;
     logger?: KtxLogger;
     debugRequestRecorder?: KtxLlmDebugRequestRecorder;
+    rateLimitGovernor?: Pick<RateLimitGovernor, 'waitForReady' | 'report' | 'maxRetryAttempts'>;
 }
 export declare class AiSdkKtxLlmRuntime implements KtxLlmRuntimePort {
     private readonly deps;
     private readonly logger;
     constructor(deps: AiSdkKtxLlmRuntimeDeps);
+    private generateTextWithRateLimitRetry;
     generateText(input: KtxGenerateTextInput): Promise<string>;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;
     runAgentLoop(params: RunLoopParams): Promise<RunLoopResult>;