@kaelio/ktx 0.9.0 → 0.10.0

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

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

@@ -1,6 +1,7 @@
 import { KtxMessageBuilder, splitKtxSystemMessages } from '../../llm/message-builder.js';
 import { generateText, Output, stepCountIs } from 'ai';
 import { noopLogger } from '../../context/core/config.js';
+import { isAbortError } from '../core/abort.js';
 import { summarizeKtxLlmDebugRequest } from './debug-request-recorder.js';
 import { createAiSdkToolSet } from './runtime-tools.js';
 function toLlmTokenUsage(usage) {
@@ -16,6 +17,108 @@ function toLlmTokenUsage(usage) {
 function hasTools(tools) {
     return Object.keys(tools).length > 0;
 }
+function modelProviderName(model) {
+    const provider = model.provider ?? '';
+    return provider.includes('vertex') || provider.includes('google') ? 'vertex' : 'anthropic-api';
+}
+const RATE_LIMIT_HEADER_PAIRS = [
+    {
+        limit: 'anthropic-ratelimit-requests-limit',
+        remaining: 'anthropic-ratelimit-requests-remaining',
+        rateLimitType: 'rpm',
+    },
+    {
+        limit: 'anthropic-ratelimit-tokens-limit',
+        remaining: 'anthropic-ratelimit-tokens-remaining',
+        rateLimitType: 'tpm',
+    },
+    {
+        limit: 'anthropic-ratelimit-input-tokens-limit',
+        remaining: 'anthropic-ratelimit-input-tokens-remaining',
+        rateLimitType: 'itpm',
+    },
+    {
+        limit: 'anthropic-ratelimit-output-tokens-limit',
+        remaining: 'anthropic-ratelimit-output-tokens-remaining',
+        rateLimitType: 'otpm',
+    },
+    {
+        limit: 'x-ratelimit-limit-requests',
+        remaining: 'x-ratelimit-remaining-requests',
+        rateLimitType: 'rpm',
+    },
+    {
+        limit: 'x-ratelimit-limit-tokens',
+        remaining: 'x-ratelimit-remaining-tokens',
+        rateLimitType: 'tpm',
+    },
+];
+function normalizeHeaders(headers) {
+    if (!headers || typeof headers !== 'object') {
+        return {};
+    }
+    const get = headers.get;
+    if (typeof get === 'function') {
+        const out = {};
+        for (const pair of RATE_LIMIT_HEADER_PAIRS) {
+            const limit = get.call(headers, pair.limit);
+            const remaining = get.call(headers, pair.remaining);
+            if (typeof limit === 'string')
+                out[pair.limit] = limit;
+            if (typeof remaining === 'string')
+                out[pair.remaining] = remaining;
+        }
+        return out;
+    }
+    return Object.fromEntries(Object.entries(headers)
+        .filter((entry) => typeof entry[1] === 'string' || typeof entry[1] === 'number')
+        .map(([key, value]) => [key.toLowerCase(), String(value)]));
+}
+function numericHeader(headers, key) {
+    const value = Number(headers[key]);
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function utilizationForPair(headers, pair) {
+    const limit = numericHeader(headers, pair.limit);
+    const remaining = numericHeader(headers, pair.remaining);
+    if (limit === undefined || remaining === undefined || limit <= 0) {
+        return undefined;
+    }
+    return 1 - Math.min(limit, remaining) / limit;
+}
+function aiSdkHeaderRateLimitSignal(provider, result) {
+    const headers = normalizeHeaders(result.response?.headers);
+    let best;
+    for (const pair of RATE_LIMIT_HEADER_PAIRS) {
+        const utilization = utilizationForPair(headers, pair);
+        if (utilization === undefined) {
+            continue;
+        }
+        if (!best || utilization > best.utilization) {
+            best = { utilization, rateLimitType: pair.rateLimitType };
+        }
+    }
+    if (!best) {
+        return undefined;
+    }
+    return {
+        provider,
+        status: 'allowed',
+        rateLimitType: best.rateLimitType,
+        utilization: Number(best.utilization.toFixed(4)),
+    };
+}
+function retryAfterMs(error) {
+    const value = error.retryAfter;
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return value < 1_000 ? value * 1_000 : value;
+    }
+    return undefined;
+}
+function isAiSdkRateLimitError(error) {
+    const record = error;
+    return record.name === 'TooManyRequestsError' || record.statusCode === 429 || record.status === 429;
+}
 export class AiSdkKtxLlmRuntime {
     deps;
     logger;
@@ -23,6 +126,37 @@ export class AiSdkKtxLlmRuntime {
         this.deps = deps;
         this.logger = deps.logger ?? noopLogger;
     }
+    async generateTextWithRateLimitRetry(provider, abortSignal, run) {
+        // maxRetryAttempts() returns 1 when no governor is present or pacing is
+        // disabled, so a 429 throws immediately instead of hammering the provider
+        // with no backoff; the AI SDK's own maxRetries still handles transient 429s.
+        const maxAttempts = this.deps.rateLimitGovernor?.maxRetryAttempts() ?? 1;
+        let attempt = 0;
+        while (true) {
+            await this.deps.rateLimitGovernor?.waitForReady(abortSignal);
+            try {
+                const result = await run();
+                const signal = aiSdkHeaderRateLimitSignal(provider, result);
+                if (signal) {
+                    this.deps.rateLimitGovernor?.report(signal);
+                }
+                return result;
+            }
+            catch (error) {
+                if (isAbortError(error) || !isAiSdkRateLimitError(error) || attempt >= maxAttempts - 1) {
+                    throw error;
+                }
+                attempt += 1;
+                const retryAfter = retryAfterMs(error);
+                this.deps.rateLimitGovernor?.report({
+                    provider,
+                    status: 'rejected',
+                    rateLimitType: 'http_429',
+                    ...(retryAfter !== undefined ? { retryAfterMs: retryAfter } : {}),
+                });
+            }
+        }
+    }
     async generateText(input) {
         const model = this.deps.llmProvider.getModel(input.role);
         if (model.provider === 'deterministic') {
@@ -37,12 +171,13 @@ export class AiSdkKtxLlmRuntime {
         });
         const split = splitKtxSystemMessages(built.messages);
         const startedAt = Date.now();
-        const result = await generateText({
+        const request = {
             model,
             temperature: input.temperature ?? 0,
             ...(split.system ? { system: split.system } : {}),
             messages: split.messages,
             tools: built.tools,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
             ...(hasTools(tools)
                 ? {
                     experimental_repairToolCall: this.deps.llmProvider.repairToolCallHandler({
@@ -50,7 +185,8 @@ export class AiSdkKtxLlmRuntime {
                     }),
                 }
                 : {}),
-        });
+        };
+        const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), input.abortSignal, () => generateText(request));
         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');
@@ -68,12 +204,13 @@ export class AiSdkKtxLlmRuntime {
         });
         const split = splitKtxSystemMessages(built.messages);
         const startedAt = Date.now();
-        const result = await generateText({
+        const request = {
             model,
             temperature: input.temperature ?? 0,
             ...(split.system ? { system: split.system } : {}),
             messages: split.messages,
             tools: built.tools,
+            ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
             ...(hasTools(tools)
                 ? {
                     experimental_repairToolCall: this.deps.llmProvider.repairToolCallHandler({
@@ -82,7 +219,8 @@ export class AiSdkKtxLlmRuntime {
                 }
                 : {}),
             output: Output.object({ schema: input.schema }),
-        });
+        };
+        const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), input.abortSignal, () => generateText(request));
         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');
@@ -114,7 +252,7 @@ export class AiSdkKtxLlmRuntime {
                 messages: built.messages,
                 tools: built.tools,
             }));
-            const result = await generateText({
+            const request = {
                 model,
                 temperature: 0,
                 stopWhen: stepCountIs(params.stepBudget),
@@ -125,20 +263,15 @@ export class AiSdkKtxLlmRuntime {
                 ...(promptMessages.system ? { system: promptMessages.system } : {}),
                 messages: promptMessages.messages,
                 tools: built.tools,
-                onStepFinish: async () => {
+                ...(params.abortSignal ? { abortSignal: params.abortSignal } : {}),
+                // Count model round-trips locally for metrics. `stepCountIs(stepBudget)`
+                // caps the loop, so this counter never exceeds the budget.
+                onStepFinish: () => {
                     stepIndex += 1;
                     stepBoundariesMs.push(Date.now() - startedAt);
-                    if (!params.onStepFinish) {
-                        return;
-                    }
-                    try {
-                        await params.onStepFinish({ stepIndex, stepBudget: params.stepBudget });
-                    }
-                    catch (err) {
-                        this.logger.warn(`[agent-runner] onStepFinish callback threw; ignoring: ${err instanceof Error ? err.message : String(err)}`);
-                    }
                 },
-            });
+            };
+            const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), params.abortSignal, () => generateText(request));
             return {
                 stopReason: 'natural',
                 metrics: {
@@ -150,6 +283,9 @@ export class AiSdkKtxLlmRuntime {
             };
         }
         catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
             const err = error instanceof Error ? error : new Error(String(error));
             this.logger.warn(`[agent-runner] loop failed: ${err.message}`);
             return {

package/dist/context/llm/claude-code-runtime.d.ts

@@ -1,8 +1,11 @@
 import { query as defaultQuery, type SDKMessage, type SDKResultMessage } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
-import { type KtxLogger } from '../../context/core/config.js';
+import type { RateLimitGovernor } from './rate-limit-governor.js';
 import type { KtxGenerateObjectInput, KtxGenerateTextInput, KtxLlmRuntimePort, RunLoopParams, RunLoopResult, RunLoopStopReason } from './runtime-port.js';
-type QueryFn = (params: Parameters<typeof defaultQuery>[0]) => AsyncIterable<SDKMessage>;
+type QueryResult = AsyncIterable<SDKMessage> & {
+    interrupt?: () => void | Promise<void>;
+};
+type QueryFn = (params: Parameters<typeof defaultQuery>[0]) => QueryResult;
 export interface ClaudeCodeKtxLlmRuntimeDeps {
     projectDir: string;
     modelSlots: {
@@ -10,14 +13,13 @@ export interface ClaudeCodeKtxLlmRuntimeDeps {
     } & Partial<Record<string, string>>;
     query?: QueryFn;
     env?: NodeJS.ProcessEnv;
-    logger?: KtxLogger;
+    rateLimitGovernor?: Pick<RateLimitGovernor, 'waitForReady' | 'report' | 'maxRetryAttempts'>;
 }
 /** @internal */
 export declare function mapClaudeCodeStopReason(result: SDKResultMessage): RunLoopStopReason;
 export declare class ClaudeCodeKtxLlmRuntime implements KtxLlmRuntimePort {
     private readonly deps;
     private readonly runQuery;
-    private readonly logger;
     constructor(deps: ClaudeCodeKtxLlmRuntimeDeps);
     generateText(input: KtxGenerateTextInput): Promise<string>;
     generateObject<TOutput, TSchema extends z.ZodType<TOutput>>(input: KtxGenerateObjectInput<TOutput, TSchema>): Promise<TOutput>;