@kaelio/ktx 0.8.0 → 0.10.0

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