@cortexkit/anthropic-auth-core 1.19.0 → 1.20.0

package/dist/auth.js

@@ -1,5 +1,5 @@
-import { AUTHORIZE_URLS, AXIOS_USER_AGENT, CLIENT_ID, CODE_CALLBACK_URL, OAUTH_SCOPES, REFRESH_SCOPE, TOKEN_URL, } from "./constants.js";
-import { generatePKCE } from "./pkce.js";
+import { AUTHORIZE_URLS, AXIOS_USER_AGENT, CLIENT_ID, CODE_CALLBACK_URL, OAUTH_SCOPES, REFRESH_SCOPE, TOKEN_URL, } from './constants.js';
+import { generatePKCE } from './pkce.js';
 export function parseRetryAfterHeader(value) {
     if (!value)
         return undefined;
@@ -47,11 +47,12 @@ export async function refreshClaudeOAuthToken(input) {
     const fetchImpl = input.fetchImpl ?? fetch;
     const maxRetries = input.maxRetries ?? 2;
     const baseDelayMs = input.baseDelayMs ?? 500;
+    const setTimeoutImpl = input.setTimeoutImpl ?? globalThis.setTimeout;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             if (attempt > 0) {
                 const delay = baseDelayMs * 2 ** (attempt - 1);
-                await new Promise((resolve) => setTimeout(resolve, delay));
+                await new Promise((resolve) => setTimeoutImpl(resolve, delay));
             }
             const response = await fetchImpl(TOKEN_URL, {
                 method: 'POST',
@@ -82,6 +83,7 @@ export async function refreshClaudeOAuthToken(input) {
                 refresh: json.refresh_token ?? input.refreshToken,
                 expires: refreshedAt + json.expires_in * 1000,
                 expiresIn: json.expires_in,
+                authLineageId: input.authLineageId,
             };
         }
         catch (error) {

package/dist/cache1h.d.ts

@@ -13,7 +13,7 @@ export type Cache1hCommandAction = {
     type: 'usage';
 };
 export declare function isCache1hEnabled(): boolean;
-export declare function getCache1hMode(): "explicit" | "automatic" | "hybrid";
+export declare function getCache1hMode(): "automatic" | "explicit" | "hybrid";
 export declare function setCache1hEnabled(enabled: boolean): void;
 export declare function setCache1hMode(mode: Cache1hMode): void;
 export declare function setCache1hState(input: {

package/dist/cache1h.js

@@ -1,4 +1,4 @@
-import { DEFAULT_CACHE_1H_MODE } from "./constants.js";
+import { DEFAULT_CACHE_1H_MODE } from './constants.js';
 export const CACHE_1H_COMMAND_NAME = 'claude-cache';
 const CACHE_1H_STATUS_TITLE = '## Claude Cache Status';
 const CACHE_1H_ENABLED_TITLE = '## Claude Cache Enabled';

package/dist/cachekeep.d.ts

@@ -7,8 +7,10 @@ export declare const CACHE_KEEP_TICK_MS = 60000;
 export declare const CACHE_KEEP_EXTENDED_TTL_BETA = "extended-cache-ttl-2025-04-11";
 export declare const CACHE_KEEP_MAX_TARGETS = 32;
 export declare const CACHE_KEEP_MAX_BODY_BYTES: number;
-export declare const CACHE_KEEP_STALE_TARGET_MS: number;
 export declare const CACHE_KEEP_PREWARM_TIMEOUT_MS = 30000;
+export declare const CACHE_KEEP_RETRY_BASE_MS = 60000;
+export declare const CACHE_KEEP_RETRY_MAX_MS: number;
+export declare const CACHE_KEEP_RETRY_JITTER_MAX_MS = 30000;
 export type CacheKeepWindow = {
     startHour: number;
     endHour: number;
@@ -70,8 +72,11 @@ export type CacheKeepTarget = {
     headers: Record<string, string>;
     bodyText: string;
     cacheExpiresAt: number;
+    nextPrewarmAt: number;
+    consecutiveFailures: number;
     dayKey: string;
     oauthAccountId?: string;
+    isSubagent: boolean;
 };
 export type CacheKeepPrewarmResult = {
     ok: true;
@@ -84,18 +89,30 @@ export type CacheKeepPrewarmResult = {
     ok: false;
     reason: string;
     status?: number;
+    transient?: true;
 };
 export declare class CacheKeepManager {
     private readonly options;
     private readonly targets;
     private timer;
+    private tickPromise;
     constructor(options: {
         loadStorage: () => Promise<AccountStorage | null>;
         fetchImpl?: typeof fetch;
         now?: () => number;
         prewarmTimeoutMs?: number;
+        setIntervalImpl?: typeof globalThis.setInterval;
+        clearIntervalImpl?: typeof globalThis.clearInterval;
         prepareHeaders?: (headers: Headers, target: CacheKeepTarget) => Promise<Headers> | Headers;
         onTrackedSessionsChanged?: (sessions: readonly CacheKeepTrackedSession[]) => Promise<void> | void;
+        prepareBody?: (bodyText: string, target: CacheKeepTarget) => string | Promise<string>;
+        onResponse?: (input: {
+            target: CacheKeepTarget;
+            bodyText: string;
+            status: number;
+            data: unknown;
+            receivedAt: number;
+        }) => void | Promise<void>;
     });
     start(): void;
     stop(): void;
@@ -120,12 +137,13 @@ export declare class CacheKeepManager {
         storage: AccountStorage | null;
         cacheMode: string;
         oauthAccountId?: string;
+        isSubagent?: boolean;
     }): {
         tracked: boolean;
         reason: string;
     } | {
-        tracked: boolean;
         reason?: undefined;
+        tracked: boolean;
     };
     prewarmNow(input: {
         sessionId: string;
@@ -133,8 +151,10 @@ export declare class CacheKeepManager {
         headers: Headers;
         bodyText: string;
         oauthAccountId?: string;
+        isSubagent?: boolean;
     }): Promise<CacheKeepPrewarmResult>;
     tick(): Promise<void>;
+    private runTick;
     private sendPrewarm;
     private prewarm;
 }

package/dist/cachekeep.js

@@ -1,6 +1,7 @@
-import { signRequestBody } from "./cch.js";
-import { orderClaudeCodeBody } from "./claude-code.js";
-import { logger } from "./logger.js";
+import { signRequestBody } from './cch.js';
+import { orderClaudeCodeBody } from './claude-code.js';
+import { dumpDirectRequest, dumpResponseArtifact } from './dump.js';
+import { logger } from './logger.js';
 export const CLAUDE_CACHE_KEEP_COMMAND_NAME = 'claude-cachekeep';
 export const CACHE_KEEP_TTL_MS = 60 * 60_000;
 export const CACHE_KEEP_PREWARM_LEAD_MS = 5 * 60_000;
@@ -8,8 +9,10 @@ export const CACHE_KEEP_TICK_MS = 60_000;
 export const CACHE_KEEP_EXTENDED_TTL_BETA = 'extended-cache-ttl-2025-04-11';
 export const CACHE_KEEP_MAX_TARGETS = 32;
 export const CACHE_KEEP_MAX_BODY_BYTES = 16 * 1024 * 1024;
-export const CACHE_KEEP_STALE_TARGET_MS = 2 * CACHE_KEEP_TTL_MS;
 export const CACHE_KEEP_PREWARM_TIMEOUT_MS = 30_000;
+export const CACHE_KEEP_RETRY_BASE_MS = 60_000;
+export const CACHE_KEEP_RETRY_MAX_MS = 15 * 60_000;
+export const CACHE_KEEP_RETRY_JITTER_MAX_MS = 30_000;
 const STATUS_TITLE = '## Claude Cache Keep Status';
 const ENABLED_TITLE = '## Claude Cache Keep Enabled';
 const DISABLED_TITLE = '## Claude Cache Keep Disabled';
@@ -228,10 +231,22 @@ export async function buildCacheKeepPrewarmBody(bodyText) {
     const signedBodyText = await signRequestBody(JSON.stringify(orderClaudeCodeBody(warm)));
     return { ok: true, bodyText: signedBodyText };
 }
+function cacheKeepRetryDelayMs(targetId, failureCount) {
+    const exponential = Math.min(CACHE_KEEP_RETRY_MAX_MS, CACHE_KEEP_RETRY_BASE_MS * 2 ** Math.min(Math.max(failureCount - 1, 0), 8));
+    let hash = 2_166_136_261;
+    for (const character of `${targetId}:${failureCount}`) {
+        hash ^= character.charCodeAt(0);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    const jitter = (hash >>> 0) %
+        (Math.min(CACHE_KEEP_RETRY_JITTER_MAX_MS, exponential / 4) + 1);
+    return exponential + jitter;
+}
 export class CacheKeepManager {
     options;
     targets = new Map();
     timer = null;
+    tickPromise = null;
     constructor(options) {
         this.options = options;
     }
@@ -239,7 +254,7 @@ export class CacheKeepManager {
         if (this.timer)
             return;
         logger.debug('cachekeep', 'started');
-        this.timer = setInterval(() => {
+        this.timer = (this.options.setIntervalImpl ?? globalThis.setInterval)(() => {
             void this.tick().catch((error) => {
                 logger.warn('cachekeep', 'tick failed', {
                     error: error instanceof Error ? error.message : String(error),
@@ -253,14 +268,15 @@ export class CacheKeepManager {
         if (!this.timer)
             return;
         logger.debug('cachekeep', 'stopped');
-        clearInterval(this.timer);
+        const clearIntervalImpl = this.options.clearIntervalImpl ?? globalThis.clearInterval;
+        clearIntervalImpl(this.timer);
         this.timer = null;
     }
     stats(window, now = this.options.now?.() ?? Date.now(), always = false) {
         const today = always ? 'always' : localWindowKey(window, new Date(now));
         const targets = [...this.targets.values()].filter((target) => target.dayKey === today);
         const nextPrewarmAt = targets.length
-            ? Math.min(...targets.map((target) => target.cacheExpiresAt - CACHE_KEEP_PREWARM_LEAD_MS))
+            ? Math.min(...targets.map((target) => target.nextPrewarmAt))
             : undefined;
         return { trackedSessions: targets.length, nextPrewarmAt };
     }
@@ -269,7 +285,7 @@ export class CacheKeepManager {
             .map((target) => ({
             id: target.id,
             cacheExpiresAt: target.cacheExpiresAt,
-            nextPrewarmAt: target.cacheExpiresAt - CACHE_KEEP_PREWARM_LEAD_MS,
+            nextPrewarmAt: target.nextPrewarmAt,
         }))
             .sort((left, right) => left.id.localeCompare(right.id));
     }
@@ -311,9 +327,8 @@ export class CacheKeepManager {
                 this.targets.delete(id);
                 continue;
             }
-            if (now - target.cacheExpiresAt > CACHE_KEEP_STALE_TARGET_MS) {
+            if (now >= target.cacheExpiresAt)
                 this.targets.delete(id);
-            }
         }
         while (this.targets.size > CACHE_KEEP_MAX_TARGETS)
             this.evictOldestTarget();
@@ -355,8 +370,11 @@ export class CacheKeepManager {
             headers,
             bodyText: input.bodyText,
             cacheExpiresAt: now + CACHE_KEEP_TTL_MS,
+            nextPrewarmAt: now + CACHE_KEEP_TTL_MS - CACHE_KEEP_PREWARM_LEAD_MS,
+            consecutiveFailures: 0,
             dayKey: today,
             oauthAccountId: input.oauthAccountId,
+            isSubagent: input.isSubagent ?? false,
         });
         this.pruneTargets(now, today);
         this.publishTrackedSessions();
@@ -374,12 +392,26 @@ export class CacheKeepManager {
             headers,
             bodyText: input.bodyText,
             cacheExpiresAt: this.options.now?.() ?? Date.now(),
+            nextPrewarmAt: this.options.now?.() ?? Date.now(),
+            consecutiveFailures: 0,
             dayKey: '',
             oauthAccountId: input.oauthAccountId,
+            isSubagent: input.isSubagent ?? false,
         };
         return this.sendPrewarm(target);
     }
-    async tick() {
+    tick() {
+        if (this.tickPromise)
+            return this.tickPromise;
+        let run;
+        run = this.runTick().finally(() => {
+            if (this.tickPromise === run)
+                this.tickPromise = null;
+        });
+        this.tickPromise = run;
+        return run;
+    }
+    async runTick() {
         const storage = await this.options.loadStorage();
         const window = getCacheKeepWindow(storage);
         const now = this.options.now?.() ?? Date.now();
@@ -403,49 +435,120 @@ export class CacheKeepManager {
             return;
         }
         logger.debug('cachekeep', 'fired', { targets: this.targets.size });
-        const dueAt = now + CACHE_KEEP_PREWARM_LEAD_MS;
         for (const target of this.targets.values()) {
-            if (target.cacheExpiresAt > dueAt)
+            if (target.nextPrewarmAt > now)
                 continue;
-            await this.prewarm(target, now);
+            try {
+                await this.prewarm(target, now);
+            }
+            catch (error) {
+                logger.warn('cachekeep', 'prewarm failed', {
+                    session: target.id,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+                target.consecutiveFailures += 1;
+                target.nextPrewarmAt =
+                    now + cacheKeepRetryDelayMs(target.id, target.consecutiveFailures);
+            }
         }
         this.publishTrackedSessions();
     }
     async sendPrewarm(target) {
-        const prewarm = await buildCacheKeepPrewarmBody(target.bodyText);
+        let bodyText = target.bodyText;
+        if (this.options.prepareBody) {
+            try {
+                bodyText = await this.options.prepareBody(bodyText, target);
+            }
+            catch (error) {
+                logger.warn('cachekeep', 'prepare body failed', {
+                    session: target.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const preparedTarget = { ...target, bodyText };
+        const prewarm = await buildCacheKeepPrewarmBody(bodyText);
         if (!prewarm.ok)
             return prewarm;
         const fetchImpl = this.options.fetchImpl ?? fetch;
-        const prewarmTarget = { ...target, bodyText: prewarm.bodyText };
+        const prewarmTarget = { ...preparedTarget, bodyText: prewarm.bodyText };
         const headers = this.options.prepareHeaders
             ? await this.options.prepareHeaders(new Headers(target.headers), prewarmTarget)
             : new Headers(target.headers);
         headers.delete('content-length');
         headers.delete('transfer-encoding');
-        const response = await fetchImpl(target.url, {
-            method: 'POST',
-            headers,
-            body: prewarm.bodyText,
-            signal: AbortSignal.timeout(this.options.prewarmTimeoutMs ?? CACHE_KEEP_PREWARM_TIMEOUT_MS),
-        });
+        let response;
+        try {
+            response = await fetchImpl(target.url, {
+                method: 'POST',
+                headers,
+                body: prewarm.bodyText,
+                signal: AbortSignal.timeout(this.options.prewarmTimeoutMs ?? CACHE_KEEP_PREWARM_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: error instanceof Error ? error.message : String(error),
+                transient: true,
+            };
+        }
+        const receivedAt = this.options.now?.() ?? Date.now();
+        const raw = await response.text().catch(() => '');
+        let data = null;
+        try {
+            data = raw ? JSON.parse(raw) : null;
+        }
+        catch { }
+        try {
+            await this.options.onResponse?.({
+                target,
+                bodyText: prewarm.bodyText,
+                status: response.status,
+                data,
+                receivedAt,
+            });
+        }
+        catch { }
+        try {
+            const dumpHandle = await dumpDirectRequest({
+                affinity: target.id,
+                route: 'cachekeep',
+                status: response.status,
+                bodyText: prewarm.bodyText,
+                url: target.url,
+                method: 'POST',
+                headers,
+                tag: 'cachekeep',
+            });
+            await dumpResponseArtifact(dumpHandle, {
+                status: response.status,
+                message: data,
+            });
+        }
+        catch (error) {
+            logger.debug('cachekeep', 'dump failed', {
+                session: target.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
         if (!response.ok) {
             return {
                 ok: false,
-                reason: await response
-                    .text()
-                    .catch(() => '')
-                    .then((body) => body || `HTTP ${response.status}`),
+                reason: raw || `HTTP ${response.status}`,
                 status: response.status,
             };
         }
-        const data = (await response.json().catch(() => null));
-        const usage = data?.usage;
+        const objectData = data && typeof data === 'object' && !Array.isArray(data)
+            ? data
+            : null;
+        const usage = objectData?.usage;
         return { ok: true, ...(usage && { usage }) };
     }
     async prewarm(target, now) {
         const result = await this.sendPrewarm(target);
         if (!result.ok) {
-            if (result.status == null) {
+            if (result.status == null && !result.transient) {
                 logger.debug('cachekeep', 'prewarm skipped', {
                     session: target.id,
                     reason: result.reason,
@@ -458,11 +561,15 @@ export class CacheKeepManager {
                     status: result.status,
                     reason: result.reason,
                 });
-                target.cacheExpiresAt = now + CACHE_KEEP_PREWARM_LEAD_MS + 5 * 60_000;
+                target.consecutiveFailures += 1;
+                target.nextPrewarmAt =
+                    now + cacheKeepRetryDelayMs(target.id, target.consecutiveFailures);
             }
             return;
         }
         target.cacheExpiresAt = now + CACHE_KEEP_TTL_MS;
+        target.nextPrewarmAt = target.cacheExpiresAt - CACHE_KEEP_PREWARM_LEAD_MS;
+        target.consecutiveFailures = 0;
         logger.debug('cachekeep', 'prewarm succeeded', {
             session: target.id,
             ...(result.usage && { usage: result.usage }),

package/dist/cch.d.ts

@@ -18,6 +18,7 @@ export declare function extractFirstUserMessageText(messages: Message[]): string
  * masks to 20 bits, and writes that value into the billing-header placeholder.
  */
 export declare function computeCCH(bodyBytes: Uint8Array): Promise<string>;
+export declare function computeXxhash64Hex(value: string): Promise<string>;
 export declare function resetBillingHeaderCCH(bodyString: string): string;
 export declare function extractBillingHeaderCCH(bodyString: string): string | null;
 export declare function signRequestBody(bodyString: string): Promise<string>;

package/dist/cch.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import xxhashInit from 'xxhash-wasm';
-import { CLAUDE_CODE_BUILD_HASH, CLAUDE_CODE_VERSION } from "./constants.js";
+import { CLAUDE_CODE_BUILD_HASH, CLAUDE_CODE_VERSION } from './constants.js';
 const CCH_SEED = 0x6e52736ac806831en;
 const CCH_PLACEHOLDER = 'cch=00000;';
 export const CCH_PATTERN = /\bcch=([0-9a-f]{5});/;
@@ -46,6 +46,11 @@ export async function computeCCH(bodyBytes) {
     const hash = xxhash64Raw?.(bodyBytes, CCH_SEED) ?? 0n;
     return (hash & 0xfffffn).toString(16).padStart(5, '0');
 }
+export async function computeXxhash64Hex(value) {
+    await ensureXxhash();
+    const hash = xxhash64Raw?.(new TextEncoder().encode(value), 0n) ?? 0n;
+    return hash.toString(16).padStart(16, '0').slice(0, 16);
+}
 export function resetBillingHeaderCCH(bodyString) {
     return bodyString.replace(BILLING_HEADER_CCH_PATTERN, `$1${CCH_PLACEHOLDER}`);
 }

package/dist/claude-code.d.ts

@@ -3,11 +3,12 @@ export type ClaudeCodeIdentity = {
     accountUuid?: string;
     sessionId: string;
 };
+export declare function setBounded<K, V>(map: Map<K, V>, key: K, value: V, limit?: number): void;
 export declare function getClaudeCodeIdentity(seed: string): ClaudeCodeIdentity;
 export declare function resolveClaudeCodeIdentity(accessToken: string, model?: string): Promise<ClaudeCodeIdentity>;
 export declare function buildClaudeCodeMetadataUserId(identity: ClaudeCodeIdentity): string | null;
 export declare function applyClaudeCodeMetadata(body: Record<string, unknown>, identity: ClaudeCodeIdentity): boolean;
-export declare const CLAUDE_CODE_FULL_AGENT_BETAS: readonly ["oauth-2025-04-20", "interleaved-thinking-2025-05-14", "thinking-token-count-2026-05-13", "context-management-2025-06-27", "prompt-caching-scope-2026-01-05", "claude-code-20250219", "advisor-tool-2026-03-01", "advanced-tool-use-2025-11-20", "extended-cache-ttl-2025-04-11", "cache-diagnosis-2026-04-07"];
+export declare const CLAUDE_CODE_FULL_AGENT_BETAS: readonly ['oauth-2025-04-20', 'interleaved-thinking-2025-05-14', 'thinking-token-count-2026-05-13', 'context-management-2025-06-27', 'prompt-caching-scope-2026-01-05', 'claude-code-20250219', 'advisor-tool-2026-03-01', 'advanced-tool-use-2025-11-20', 'extended-cache-ttl-2025-04-11', 'cache-diagnosis-2026-04-07'];
 export declare function selectClaudeCodeBetas(body?: Record<string, unknown> | null, extraBetas?: string[]): string;
 export declare function applyClaudeCodeHeaders(headers: Headers, accessToken: string, options?: {
     body?: Record<string, unknown> | null;

package/dist/claude-code.js

@@ -1,9 +1,9 @@
 import { randomBytes, randomUUID } from 'node:crypto';
-import { CLAUDE_CODE_BUILD_HASH, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_STAINLESS_PACKAGE_VERSION, CLAUDE_CODE_STAINLESS_RUNTIME_VERSION, CLAUDE_CODE_VERSION, FAST_MODE_BETA, USER_AGENT, } from "./constants.js";
+import { CLAUDE_CODE_BUILD_HASH, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_STAINLESS_PACKAGE_VERSION, CLAUDE_CODE_STAINLESS_RUNTIME_VERSION, CLAUDE_CODE_VERSION, FAST_MODE_BETA, USER_AGENT, } from './constants.js';
 const IDENTITY_CACHE_LIMIT = 1_000;
 const identityCache = new Map();
-function setBounded(map, key, value) {
-    if (!map.has(key) && map.size >= IDENTITY_CACHE_LIMIT) {
+export function setBounded(map, key, value, limit = IDENTITY_CACHE_LIMIT) {
+    if (!map.has(key) && map.size >= limit) {
         const oldest = map.keys().next().value;
         if (oldest !== undefined)
             map.delete(oldest);

package/dist/commands/account.js

@@ -1,4 +1,4 @@
-import { formatOAuthAccountTier } from "../oauth-profile.js";
+import { formatOAuthAccountTier } from '../oauth-profile.js';
 export const CLAUDE_ACCOUNT_COMMAND_NAME = 'claude-account';
 export function parseAccountCommandAction(argumentsText) {
     const parts = argumentsText.trim().split(/\s+/).filter(Boolean);

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
 export declare const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 export declare const AUTHORIZE_URLS: {
-    readonly console: "https://platform.claude.com/oauth/authorize";
-    readonly max: "https://claude.com/cai/oauth/authorize";
+    readonly console: 'https://platform.claude.com/oauth/authorize';
+    readonly max: 'https://claude.com/cai/oauth/authorize';
 };
 export declare const CODE_CALLBACK_URL = "https://platform.claude.com/oauth/code/callback";
 export declare const TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
@@ -24,7 +24,7 @@ export declare const CLAUDE_CODE_ENTRYPOINT = "cli";
 export declare const CLAUDE_CODE_STAINLESS_PACKAGE_VERSION = "0.94.0";
 export declare const CLAUDE_CODE_STAINLESS_RUNTIME_VERSION = "v24.3.0";
 export declare const USER_AGENT = "claude-cli/2.1.177 (external, cli)";
-export declare const CACHE_1H_MODES: readonly ["explicit", "automatic", "hybrid"];
+export declare const CACHE_1H_MODES: readonly ['explicit', 'automatic', 'hybrid'];
 export type Cache1hMode = (typeof CACHE_1H_MODES)[number];
 export declare const DEFAULT_CACHE_1H_MODE: Cache1hMode;
 /**

package/dist/dump.d.ts

@@ -9,6 +9,11 @@ export type DumpCommandAction = {
 } | {
     type: 'usage';
 };
+export type DumpTag = 'cachekeep' | 'start';
+export type DumpHandle = {
+    responsePath: string;
+    tag?: DumpTag;
+};
 export declare function isDumpEnabled(): boolean;
 export declare function setDumpEnabled(enabled: boolean): void;
 export declare function resetDumpState(): void;
@@ -49,7 +54,8 @@ export declare function dumpDirectRequest(input: {
     url?: string;
     method?: string;
     headers?: DumpHeaders;
-}): Promise<void>;
+    tag?: DumpTag;
+}): Promise<DumpHandle | null>;
 export declare function dumpRelayRequest(input: {
     affinity: string;
     transport: 'http' | 'websocket';
@@ -60,5 +66,10 @@ export declare function dumpRelayRequest(input: {
     previousBodyText?: string;
     payload: unknown;
     relayBytes: number;
+    tag?: DumpTag;
+}): Promise<DumpHandle | null>;
+export declare function dumpResponseArtifact(handle: DumpHandle | null, input: {
+    status: number;
+    message: unknown;
 }): Promise<void>;
 export {};