@kaelio/ktx 0.8.0 → 0.10.0

package/dist/context/llm/codex-runtime.js

@@ -0,0 +1,347 @@
+import { z } from 'zod';
+import { isAbortError, linkAbortSignal } from '../core/abort.js';
+import { isCompletedAgentStep, summarizeCodexExecEvents } from './codex-exec-events.js';
+import { startCodexRuntimeMcpServer, } from './codex-mcp-runtime-server.js';
+import { resolveCodexModel } from './codex-models.js';
+import { buildCodexRuntimeConfig } from './codex-runtime-config.js';
+import { CodexSdkCliRunner } from './codex-sdk-runner.js';
+function modelForRole(modelSlots, role) {
+    return resolveCodexModel(modelSlots[role] ?? modelSlots.default);
+}
+function promptWithSystem(system, prompt) {
+    return [system, prompt].filter(Boolean).join('\n\n');
+}
+function eventRecord(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}
+function isTurnCompleted(event) {
+    return eventRecord(event)?.type === 'turn.completed';
+}
+/**
+ * Drains the Codex stream once, counting each completed agent action so the
+ * step budget is enforced mid-run. Every
+ * completed agent-action item counts (see {@link isCompletedAgentStep}), so
+ * built-in `command_execution` steps decrement the budget the same as
+ * `mcp_tool_call`s. A turn that produced no actions still counts as one step,
+ * matching the metrics summary and the AI SDK backend.
+ */
+async function collectEvents(events, options = {}) {
+    const collected = [];
+    let completedSteps = 0;
+    let sawActionStep = false;
+    let budgetExceeded = false;
+    let streamError;
+    // The SDK yields every stdout event, then throws on a non-zero codex exec
+    // exit. Catch that throw so the events already collected (which carry the
+    // real `turn.failed`/`error` reason) survive for the summary; the masked
+    // exit message is kept only as a fallback when no error event was emitted.
+    try {
+        for await (const event of events) {
+            collected.push(event);
+            const isActionStep = isCompletedAgentStep(event);
+            if (isActionStep) {
+                sawActionStep = true;
+            }
+            else if (sawActionStep || !isTurnCompleted(event)) {
+                // Only fall back to counting a bare turn as a step when the turn produced
+                // no agent actions; a completed turn is terminal, so it never aborts.
+                continue;
+            }
+            completedSteps += 1;
+            if (isActionStep && options.stepBudget !== undefined && completedSteps >= options.stepBudget) {
+                budgetExceeded = true;
+                options.abortController?.abort();
+                break;
+            }
+        }
+    }
+    catch (error) {
+        streamError = error instanceof Error ? error : new Error(String(error));
+    }
+    return { events: collected, budgetExceeded, ...(streamError ? { streamError } : {}) };
+}
+function metrics(summary, startedAt) {
+    return { totalMs: Date.now() - startedAt, usage: summary.usage };
+}
+function summaryError(summary, streamError) {
+    // A `turn.failed`/`error` event carries the real reason; prefer it over the
+    // SDK's generic non-zero-exit throw. Fall back to the stream error only when
+    // no event explained the failure (e.g. spawn failure or auth before a turn).
+    if (summary.error) {
+        return summary.error;
+    }
+    if (summary.toolFailures.length > 0) {
+        return new Error(`Codex runtime tool call failed: ${summary.toolFailures.join('; ')}`);
+    }
+    return streamError;
+}
+function assertSuccessfulText(summary, streamError) {
+    const error = summaryError(summary, streamError);
+    if (error) {
+        throw error;
+    }
+    if (!summary.finalText.trim()) {
+        throw new Error('Codex completed without an agent message');
+    }
+    return summary.finalText;
+}
+function parseStructuredOutput(schema, text) {
+    try {
+        return schema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Codex structured output failed validation: ${message}`);
+    }
+}
+async function mcpForTools(input) {
+    if (!input.toolSet || Object.keys(input.toolSet).length === 0) {
+        return undefined;
+    }
+    return (input.startMcpServer ?? startCodexRuntimeMcpServer)({
+        projectDir: input.projectDir,
+        toolSet: input.toolSet,
+    });
+}
+function runtimeToolNames(toolSet) {
+    return Object.values(toolSet ?? {}).map((descriptor) => descriptor.name);
+}
+const CODEX_RATE_LIMIT_MARKERS = /\b429\b|rate limit|too many requests|quota exceeded|temporarily overloaded/i;
+function isCodexRateLimitError(error) {
+    return !!error && CODEX_RATE_LIMIT_MARKERS.test(error.message);
+}
+export class CodexKtxLlmRuntime {
+    deps;
+    runner;
+    constructor(deps) {
+        this.deps = deps;
+        this.runner = deps.runner ?? new CodexSdkCliRunner();
+    }
+    async runWithRateLimitRetry(abortSignal, run, getError) {
+        // maxRetryAttempts() returns 1 when no governor is present or pacing is
+        // disabled, so an opaque rate-limit failure surfaces on the first attempt
+        // instead of being retried with no backoff.
+        const maxAttempts = this.deps.rateLimitGovernor?.maxRetryAttempts() ?? 1;
+        for (let attempt = 0;; attempt += 1) {
+            await this.deps.rateLimitGovernor?.waitForReady(abortSignal);
+            const lastAttempt = attempt >= maxAttempts - 1;
+            try {
+                const result = await run();
+                const error = getError(result);
+                if (!isCodexRateLimitError(error) || lastAttempt) {
+                    return result;
+                }
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (!isCodexRateLimitError(err) || lastAttempt) {
+                    throw error;
+                }
+            }
+            this.deps.rateLimitGovernor?.report({ provider: 'codex', status: 'rejected', rateLimitType: 'opaque' });
+        }
+    }
+    async generateText(input) {
+        const startedAt = Date.now();
+        const model = modelForRole(this.deps.modelSlots, input.role);
+        const mcp = await mcpForTools({
+            projectDir: this.deps.projectDir,
+            toolSet: input.tools,
+            startMcpServer: this.deps.startMcpServer,
+        });
+        try {
+            const config = buildCodexRuntimeConfig({
+                model,
+                ...(mcp
+                    ? {
+                        mcp: {
+                            url: mcp.url,
+                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
+                            bearerToken: mcp.bearerToken,
+                            toolNames: runtimeToolNames(input.tools),
+                        },
+                    }
+                    : {}),
+            });
+            const result = await this.runWithRateLimitRetry(input.abortSignal, async () => {
+                const collected = await collectEvents(await this.runner.runStreamed({
+                    projectDir: this.deps.projectDir,
+                    model,
+                    prompt: promptWithSystem(input.system, input.prompt),
+                    configOverrides: config.configOverrides,
+                    env: config.env,
+                    ...(input.abortSignal ? { signal: input.abortSignal } : {}),
+                }));
+                const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+                return { collected, summary };
+            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+            input.onMetrics?.(metrics(result.summary, startedAt));
+            return assertSuccessfulText(result.summary, result.collected.streamError);
+        }
+        finally {
+            await mcp?.close();
+        }
+    }
+    async generateObject(input) {
+        const startedAt = Date.now();
+        const model = modelForRole(this.deps.modelSlots, input.role);
+        const mcp = await mcpForTools({
+            projectDir: this.deps.projectDir,
+            toolSet: input.tools,
+            startMcpServer: this.deps.startMcpServer,
+        });
+        try {
+            const config = buildCodexRuntimeConfig({
+                model,
+                ...(mcp
+                    ? {
+                        mcp: {
+                            url: mcp.url,
+                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
+                            bearerToken: mcp.bearerToken,
+                            toolNames: runtimeToolNames(input.tools),
+                        },
+                    }
+                    : {}),
+            });
+            const result = await this.runWithRateLimitRetry(input.abortSignal, async () => {
+                const collected = await collectEvents(await this.runner.runStreamed({
+                    projectDir: this.deps.projectDir,
+                    model,
+                    prompt: promptWithSystem(input.system, input.prompt),
+                    configOverrides: config.configOverrides,
+                    env: config.env,
+                    outputSchema: z.toJSONSchema(input.schema, { target: 'draft-7' }),
+                    ...(input.abortSignal ? { signal: input.abortSignal } : {}),
+                }));
+                const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+                return { collected, summary };
+            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+            input.onMetrics?.(metrics(result.summary, startedAt));
+            return parseStructuredOutput(input.schema, assertSuccessfulText(result.summary, result.collected.streamError));
+        }
+        finally {
+            await mcp?.close();
+        }
+    }
+    async runAgentLoop(params) {
+        const startedAt = Date.now();
+        const model = modelForRole(this.deps.modelSlots, params.modelRole);
+        let mcp;
+        try {
+            mcp = await mcpForTools({
+                projectDir: this.deps.projectDir,
+                toolSet: params.toolSet,
+                startMcpServer: this.deps.startMcpServer,
+            });
+            const config = buildCodexRuntimeConfig({
+                model,
+                ...(mcp
+                    ? {
+                        mcp: {
+                            url: mcp.url,
+                            bearerTokenEnvVar: mcp.bearerTokenEnvVar,
+                            bearerToken: mcp.bearerToken,
+                            toolNames: runtimeToolNames(params.toolSet),
+                        },
+                    }
+                    : {}),
+            });
+            const result = await this.runWithRateLimitRetry(params.abortSignal, async () => {
+                const linked = linkAbortSignal(params.abortSignal);
+                const abortController = linked.controller;
+                try {
+                    const collected = await collectEvents(await this.runner.runStreamed({
+                        projectDir: this.deps.projectDir,
+                        model,
+                        prompt: promptWithSystem(params.systemPrompt, params.userPrompt),
+                        configOverrides: config.configOverrides,
+                        env: config.env,
+                        signal: abortController.signal,
+                    }), { stepBudget: params.stepBudget, abortController });
+                    const summary = summarizeCodexExecEvents(collected.events, { startedAt });
+                    return { collected, summary };
+                }
+                finally {
+                    linked.dispose();
+                }
+            }, ({ collected, summary }) => summaryError(summary, collected.streamError));
+            const error = summaryError(result.summary, result.collected.streamError);
+            if (isAbortError(error)) {
+                throw error;
+            }
+            const stopReason = result.collected.budgetExceeded ? 'budget' : error ? 'error' : result.summary.stopReason;
+            return {
+                stopReason,
+                ...(stopReason === 'error' && error ? { error } : {}),
+                metrics: {
+                    totalMs: Date.now() - startedAt,
+                    usage: result.summary.usage,
+                    stepCount: result.summary.stepCount,
+                    stepBoundariesMs: result.summary.stepBoundariesMs,
+                },
+            };
+        }
+        catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
+            const err = error instanceof Error ? error : new Error(String(error));
+            return {
+                stopReason: 'error',
+                error: err,
+                metrics: { totalMs: Date.now() - startedAt, usage: {}, stepCount: 0, stepBoundariesMs: [] },
+            };
+        }
+        finally {
+            await mcp?.close();
+        }
+    }
+}
+// A rejected model is not an auth failure: Codex authenticated, connected, and
+// the API refused the model id. These markers come from the API error envelope
+// (e.g. "model is not supported", "invalid_request_error").
+const MODEL_UNAVAILABLE_MARKERS = /\bnot supported\b|\bnot available\b|\bdoes not exist\b|invalid_request_error|\bunknown model\b|\bunsupported model\b/i;
+function describeCodexProbeFailure(model, message) {
+    if (MODEL_UNAVAILABLE_MARKERS.test(message)) {
+        const fix = `Run \`codex\` to see the models your account supports, then set llm.models.default in ktx.yaml (or rerun \`ktx setup\`).`;
+        return {
+            message: `Codex is authenticated, but the configured model "${model}" is not available for this Codex account. ${fix} Details: ${message}`,
+            fix,
+        };
+    }
+    const fix = `Authenticate Codex locally with the Codex CLI, verify the Codex CLI is installed, then rerun setup or \`ktx status\`.`;
+    return {
+        message: `Codex authentication is not usable. ${fix} Details: ${message}`,
+        fix,
+    };
+}
+export async function runCodexAuthProbe(input) {
+    let model;
+    try {
+        model = resolveCodexModel(input.model);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+            fix: 'Set llm.models.default in ktx.yaml to a supported codex model (codex, default, or a gpt-* / codex-* id), or rerun `ktx setup`.',
+        };
+    }
+    const runtime = new CodexKtxLlmRuntime({
+        projectDir: input.projectDir,
+        modelSlots: { default: model },
+        ...(input.runner ? { runner: input.runner } : {}),
+    });
+    try {
+        await runtime.generateText({ role: 'default', prompt: 'Reply with exactly: ok' });
+        return { ok: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, ...describeCodexProbeFailure(model, message) };
+    }
+}

package/dist/context/llm/codex-sdk-runner.d.ts

@@ -0,0 +1,21 @@
+export interface CodexSdkRunnerInput {
+    projectDir: string;
+    model: string;
+    prompt: string;
+    configOverrides?: Record<string, unknown>;
+    env?: Record<string, string>;
+    outputSchema?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface CodexSdkRunner {
+    runStreamed(input: CodexSdkRunnerInput): Promise<AsyncIterable<unknown>>;
+}
+export interface CodexSdkCliRunnerOptions {
+    envBase?: NodeJS.ProcessEnv;
+    codexPathOverride?: string;
+}
+export declare class CodexSdkCliRunner implements CodexSdkRunner {
+    private readonly options;
+    constructor(options?: CodexSdkCliRunnerOptions);
+    runStreamed(input: CodexSdkRunnerInput): Promise<AsyncIterable<unknown>>;
+}

package/dist/context/llm/codex-sdk-runner.js

@@ -0,0 +1,63 @@
+import { Codex } from '@openai/codex-sdk';
+const CODEX_ENV_ALLOWLIST = new Set([
+    'HOME',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'XDG_CONFIG_HOME',
+    'CODEX_HOME',
+    'CODEX_API_KEY',
+    'OPENAI_API_KEY',
+    'PATH',
+    'Path',
+    'SYSTEMROOT',
+    'COMSPEC',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'NODE_EXTRA_CA_CERTS',
+    'HTTPS_PROXY',
+    'HTTP_PROXY',
+    'ALL_PROXY',
+    'NO_PROXY',
+]);
+function buildCodexSdkEnv(baseEnv, overrides) {
+    const env = {};
+    for (const key of CODEX_ENV_ALLOWLIST) {
+        const value = baseEnv[key];
+        if (typeof value === 'string') {
+            env[key] = value;
+        }
+    }
+    return { ...env, ...(overrides ?? {}) };
+}
+export class CodexSdkCliRunner {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async runStreamed(input) {
+        const CodexClass = Codex;
+        const codex = new CodexClass({
+            ...(input.configOverrides ? { config: input.configOverrides } : {}),
+            env: buildCodexSdkEnv(this.options.envBase ?? process.env, input.env),
+            ...(this.options.codexPathOverride ? { codexPathOverride: this.options.codexPathOverride } : {}),
+        });
+        const thread = codex.startThread({
+            workingDirectory: input.projectDir,
+            skipGitRepoCheck: true,
+            model: input.model,
+            sandboxMode: 'read-only',
+            webSearchMode: 'disabled',
+            approvalPolicy: 'never',
+        });
+        const turnOptions = {
+            ...(input.outputSchema ? { outputSchema: input.outputSchema } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+        };
+        const streamed = await thread.runStreamed(input.prompt, Object.keys(turnOptions).length > 0 ? turnOptions : undefined);
+        return streamed.events;
+    }
+}

package/dist/context/llm/local-config.d.ts

@@ -2,17 +2,29 @@ import { createKtxEmbeddingProvider } from '../../llm/embedding-provider.js';
 import { createKtxLlmProvider } from '../../llm/model-provider.js';
 import type { KtxEmbeddingConfig, KtxEmbeddingProvider, KtxLlmConfig, KtxLlmProvider } from '../../llm/types.js';
 import type { KtxProjectEmbeddingConfig, KtxProjectLlmConfig } from '../project/config.js';
+import { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
 import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+import { CodexKtxLlmRuntime } from './codex-runtime.js';
+import type { RateLimitGovernor } from './rate-limit-governor.js';
 import type { KtxLlmRuntimePort } from './runtime-port.js';
+type ClaudeCodeRuntimeDeps = ConstructorParameters<typeof ClaudeCodeKtxLlmRuntime>[0] & {
+    rateLimitGovernor?: RateLimitGovernor;
+};
+type CodexRuntimeDeps = ConstructorParameters<typeof CodexKtxLlmRuntime>[0] & {
+    rateLimitGovernor?: RateLimitGovernor;
+};
+type AiSdkRuntimeDeps = ConstructorParameters<typeof AiSdkKtxLlmRuntime>[0] & {
+    rateLimitGovernor?: RateLimitGovernor;
+};
 interface LocalConfigDeps {
     env?: NodeJS.ProcessEnv;
     projectDir?: string;
+    rateLimitGovernor?: RateLimitGovernor;
     createKtxLlmProvider?: typeof createKtxLlmProvider;
     createKtxEmbeddingProvider?: typeof createKtxEmbeddingProvider;
-    createClaudeCodeRuntime?: (deps: ConstructorParameters<typeof ClaudeCodeKtxLlmRuntime>[0]) => KtxLlmRuntimePort;
-    createAiSdkRuntime?: (deps: {
-        llmProvider: KtxLlmProvider;
-    }) => KtxLlmRuntimePort;
+    createClaudeCodeRuntime?: (deps: ClaudeCodeRuntimeDeps) => KtxLlmRuntimePort;
+    createCodexRuntime?: (deps: CodexRuntimeDeps) => KtxLlmRuntimePort;
+    createAiSdkRuntime?: (deps: AiSdkRuntimeDeps) => KtxLlmRuntimePort;
 }
 export declare function resolveLocalKtxLlmConfig(config: KtxProjectLlmConfig, env: NodeJS.ProcessEnv): KtxLlmConfig | null;
 /** @internal */

package/dist/context/llm/local-config.js

@@ -3,6 +3,7 @@ import { createKtxLlmProvider } from '../../llm/model-provider.js';
 import { resolveKtxConfigReference } from '../core/config-reference.js';
 import { AiSdkKtxLlmRuntime } from './ai-sdk-runtime.js';
 import { ClaudeCodeKtxLlmRuntime } from './claude-code-runtime.js';
+import { CodexKtxLlmRuntime } from './codex-runtime.js';
 function resolveOptional(value, env) {
     return resolveKtxConfigReference(value, env) || undefined;
 }
@@ -70,7 +71,7 @@ export function resolveLocalKtxLlmConfig(config, env) {
 /** @internal */
 export function createLocalKtxLlmProviderFromConfig(config, deps = {}) {
     const resolved = resolveLocalKtxLlmConfig(config, deps.env ?? process.env);
-    if (!resolved || resolved.backend === 'claude-code') {
+    if (!resolved || resolved.backend === 'claude-code' || resolved.backend === 'codex') {
         return null;
     }
     return (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
@@ -89,10 +90,25 @@ export function createLocalKtxLlmRuntimeFromConfig(config, deps = {}) {
             projectDir,
             modelSlots: resolved.modelSlots,
             env: deps.env,
+            rateLimitGovernor: deps.rateLimitGovernor,
+        });
+    }
+    if (resolved.backend === 'codex') {
+        const projectDir = deps.projectDir;
+        if (!projectDir) {
+            throw new Error('projectDir is required when creating the codex LLM runtime');
+        }
+        return (deps.createCodexRuntime ?? ((runtimeDeps) => new CodexKtxLlmRuntime(runtimeDeps)))({
+            projectDir,
+            modelSlots: resolved.modelSlots,
+            rateLimitGovernor: deps.rateLimitGovernor,
         });
     }
     const llmProvider = (deps.createKtxLlmProvider ?? createKtxLlmProvider)(resolved);
-    return (deps.createAiSdkRuntime ?? ((runtimeDeps) => new AiSdkKtxLlmRuntime(runtimeDeps)))({ llmProvider });
+    return (deps.createAiSdkRuntime ?? ((runtimeDeps) => new AiSdkKtxLlmRuntime(runtimeDeps)))({
+        llmProvider,
+        rateLimitGovernor: deps.rateLimitGovernor,
+    });
 }
 export function resolveLocalKtxEmbeddingConfig(config, env) {
     if (config.backend === 'none') {

package/dist/context/llm/rate-limit-governor.d.ts

@@ -0,0 +1,103 @@
+export type RateLimitProvider = 'claude-subscription' | 'anthropic-api' | 'vertex' | 'codex';
+type RateLimitSignalStatus = 'allowed' | 'warning' | 'rejected';
+export interface RateLimitSignal {
+    provider: RateLimitProvider;
+    status: RateLimitSignalStatus;
+    resetAtMs?: number;
+    retryAfterMs?: number;
+    utilization?: number;
+    rateLimitType?: string;
+}
+export interface RateLimitRetryConfig {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: boolean;
+}
+export interface RateLimitGovernorConfig {
+    enabled: boolean;
+    maxConcurrency: number;
+    throttleThreshold: number;
+    minConcurrencyUnderPressure: number;
+    maxWaitMs?: number;
+    waitStateTickMs: number;
+    retry: RateLimitRetryConfig;
+}
+export type RateLimitWaitState = {
+    kind: 'rate_limit_observed';
+    provider: RateLimitProvider;
+    status: RateLimitSignalStatus;
+    rateLimitType?: string;
+    resetAtMs?: number;
+    retryAfterMs?: number;
+    utilization?: number;
+} | {
+    kind: 'concurrency_adjusted';
+    provider: RateLimitProvider;
+    from: number;
+    to: number;
+    reason: string;
+    rateLimitType?: string;
+    utilization?: number;
+} | {
+    kind: 'wait_started' | 'wait_tick' | 'wait_finished';
+    provider: RateLimitProvider;
+    rateLimitType?: string;
+    resumeAtMs: number;
+    remainingMs: number;
+};
+export interface RateLimitGovernorDeps {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random?: () => number;
+}
+export type RateLimitRelease = () => void;
+type Subscriber = (state: RateLimitWaitState) => void;
+export declare function createRateLimitGovernorConfig(input?: Partial<RateLimitGovernorConfig> & {
+    retry?: Partial<RateLimitRetryConfig>;
+}): RateLimitGovernorConfig;
+export declare class RateLimitGovernor {
+    private readonly config;
+    private readonly now;
+    private readonly sleep;
+    private readonly random;
+    private readonly subscribers;
+    private waiters;
+    private active;
+    private effectiveLimit;
+    private pausedUntilMs;
+    private pausedProvider;
+    private pausedRateLimitType;
+    private pausedTickMs;
+    private opaqueAttempts;
+    private pauseGeneration;
+    private visibleWaitAbort;
+    constructor(config: RateLimitGovernorConfig, deps?: RateLimitGovernorDeps);
+    currentLimit(): number;
+    /**
+     * Total attempts a runtime should make for a single rate-limited LLM call,
+     * including the first try. Returns 1 (no outer retry) when pacing is disabled:
+     * the outer retry loop only exists to cooperate with this governor's pause, so
+     * without active pacing there is no backoff to apply and the backend's own
+     * retry handles transient rejections.
+     */
+    maxRetryAttempts(): number;
+    activeSlots(): number;
+    subscribe(cb: Subscriber): () => void;
+    report(signal: RateLimitSignal): void;
+    waitForReady(signal?: AbortSignal): Promise<void>;
+    acquireWorkSlot(signal?: AbortSignal): Promise<RateLimitRelease>;
+    private applyPause;
+    private resumeAtMsFor;
+    private adjustLimit;
+    private startVisibleWaitTicker;
+    private stopVisibleWaitTicker;
+    private runVisibleWaitTicker;
+    private finishPause;
+    private waitForPause;
+    private waitForSlot;
+    private wakeWaiters;
+    private emitWait;
+    private emit;
+}
+export {};