dsh-plugin-subscriptions 0.4.0 → 0.4.2

package/lib/providers/catalog-store.js

@@ -71,6 +71,9 @@ function sanitizeModel(value) {
     const reasoning = raw.reasoning === undefined ? undefined : sanitizeReasoning(raw.reasoning);
     if (raw.reasoning !== undefined && reasoning === undefined)
         return undefined;
+    const thinkingType = raw.thinkingType;
+    if (thinkingType !== undefined && thinkingType !== 'enabled' && thinkingType !== 'adaptive')
+        return undefined;
     return {
         id: raw.id,
         name: raw.name,
@@ -78,6 +81,7 @@ function sanitizeModel(value) {
         ...raw.contextWindow === undefined ? {} : { contextWindow: raw.contextWindow },
         ...raw.priority === undefined ? {} : { priority: raw.priority },
         ...reasoning === undefined ? {} : { reasoning },
+        ...thinkingType === undefined ? {} : { thinkingType: thinkingType },
     };
 }
 /**

package/lib/providers/claude.d.ts

@@ -9,14 +9,23 @@ import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { ClaudeSession } from '../auth/store.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import { TokenManager } from './common.js';
-import type { FetchFn, ModelEntry, ProviderUsage } from './common.js';
+import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const CLAUDE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
-export declare const CLAUDE_AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
-export declare const CLAUDE_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+export declare const CLAUDE_AUTHORIZE_URL = "https://claude.com/cai/oauth/authorize";
+export declare const CLAUDE_TOKEN_URL = "https://claude.ai/v1/oauth/token";
 export declare const CLAUDE_API_URL = "https://api.anthropic.com/v1/messages?beta=true";
 export declare const CLAUDE_PROFILE_URL = "https://api.anthropic.com/api/oauth/profile";
+export declare const CLAUDE_MODELS_URL = "https://api.anthropic.com/v1/models?beta=true";
 /** Refresh when the access token has less than this much life left. */
 export declare const CLAUDE_PREEMPT_MS: number;
+/**
+ * The subscription endpoint only serves requests presenting as Claude Code,
+ * so these headers impersonate the CLI; the harness attribution user-agent
+ * cannot be sent here (one user-agent slot, and the CLI's wins).
+ */
+export declare const CLAUDE_CLI_FALLBACK_VERSION = "2.1.234";
+export declare function detectClaudeVersion(): string;
+export declare const CLAUDE_BETA_FALLBACK: string;
 /** Static claude flow facts for the OAuth flow engine. */
 export declare const claudeFlow: FlowSpec;
 /**
@@ -52,21 +61,44 @@ export declare const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usa
  * @returns the mapped usage snapshot.
  */
 export declare function fetchClaudeUsage(session: ClaudeSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<ProviderUsage>;
+/** Fetch the live model catalog from the subscription endpoint. */
+export declare function fetchClaudeModels(session: ClaudeSession, fetchFn?: FetchFn): Promise<DiscoveredModel[]>;
 /** Constructor dependencies for {@link ClaudeAdapter}. */
 export interface ClaudeAdapterOptions {
     models: readonly ModelEntry[];
     streamIdleTimeoutMs: number;
     tokens: TokenManager<ClaudeSession>;
+    /** Whether to fetch the live catalog when logged in (false when config `models` overrides). */
+    discovery: boolean;
+    fetchFn?: FetchFn;
+    onWarn?: (message: string) => void;
+    /** Max retries on a retryable failure before giving up; matches Claude Code's own client-side retry count. Defaults to the dsh-llm default (2) when unset. */
+    maxRetries?: number;
     /** Resolve the attachment service per request; absent means image requests fail loudly. */
     resolveAttachments?: () => AttachmentStore | undefined;
+    /** Durable catalog store seeding capability metadata across restarts. */
+    catalogStore?: CatalogPersistence;
 }
 /** Claude wire adapter: one instance serves the `claude` provider route. */
 export declare class ClaudeAdapter extends LlmAdapter {
     private readonly options;
+    private readonly catalog;
     constructor(options: ClaudeAdapterOptions);
+    private fetchCatalog;
+    private discovered;
+    private staticModels;
     providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): import("@deepseek-ai/dsh-llm").ResolvedRetryPolicy | undefined;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * `display: 'summarized'` is set explicitly on both shapes: `adaptive`-type
+     * models default to `display: 'omitted'`, which returns thinking blocks with
+     * an empty `thinking` field — without this override the "Think" panel would
+     * always render empty even though real reasoning (and billed thinking_tokens)
+     * ran.
+     */
+    private thinkingParam;
     private request;
 }

package/lib/providers/claude.js

@@ -3,15 +3,17 @@
  * platform.claude.com with the Claude Code client id, and streaming against
  * the Anthropic Messages API with the Claude Code identity headers.
  */
-import { EMPTY_RESPONSE_CODE, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
+import { execFileSync } from 'node:child_process';
+import { EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError, ReasoningEffortId, resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
 import { resolveImages } from '../translate/resolved.js';
 import { streamAnthropic, toAnthropicMessages, toAnthropicSystem, toAnthropicTools, } from '../translate/anthropic.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
 export const CLAUDE_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
-export const CLAUDE_AUTHORIZE_URL = 'https://claude.ai/oauth/authorize';
-export const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
+export const CLAUDE_AUTHORIZE_URL = 'https://claude.com/cai/oauth/authorize';
+export const CLAUDE_TOKEN_URL = 'https://claude.ai/v1/oauth/token';
 export const CLAUDE_API_URL = 'https://api.anthropic.com/v1/messages?beta=true';
 export const CLAUDE_PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
+export const CLAUDE_MODELS_URL = 'https://api.anthropic.com/v1/models?beta=true';
 const CLAUDE_SCOPE = 'org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload';
 const CLAUDE_CALLBACK_PATH = '/callback';
 const CLAUDE_CONTEXT_WINDOW = 200_000;
@@ -23,19 +25,39 @@ export const CLAUDE_PREEMPT_MS = 5 * 60_000;
  * so these headers impersonate the CLI; the harness attribution user-agent
  * cannot be sent here (one user-agent slot, and the CLI's wins).
  */
-const CLAUDE_CLI_USER_AGENT = 'claude-cli/2.1.97 (external, cli)';
-const CLAUDE_BETA_FLAGS = 'claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27';
+export const CLAUDE_CLI_FALLBACK_VERSION = '2.1.234';
+export function detectClaudeVersion() {
+    try {
+        const raw = execFileSync('claude', ['--version'], { timeout: 3000, encoding: 'utf8' });
+        const match = raw.match(/^(\d+\.\d+\.\d+)/);
+        if (match)
+            return match[1];
+    }
+    catch { }
+    return CLAUDE_CLI_FALLBACK_VERSION;
+}
+const CLAUDE_CLI_USER_AGENT = `claude-cli/${detectClaudeVersion()} (external, cli)`;
+export const CLAUDE_BETA_FALLBACK = [
+    'claude-code-20250219',
+    'oauth-2025-04-20',
+    'interleaved-thinking-2025-05-14',
+    'context-management-2025-06-27',
+    'effort-2025-11-24',
+    'compact-2026-01-12',
+    'files-api-2025-04-14',
+].join(',');
+const CLAUDE_BETA_FLAGS = CLAUDE_BETA_FALLBACK;
 /** Static claude flow facts for the OAuth flow engine. */
 export const claudeFlow = {
     callbackPath: CLAUDE_CALLBACK_PATH,
     // The redirect URI embeds the port, so it must be an ephemeral one.
-    listen: { host: 'localhost', ports: [0] },
+    listen: { host: '127.0.0.1', ports: [0] },
     buildAuthorizeUrl({ redirectUri, state, pkce }) {
         const params = new URLSearchParams({
             code: 'true',
             client_id: CLAUDE_CLIENT_ID,
             response_type: 'code',
-            redirect_uri: redirectUri,
+            redirect_uri: 'https://platform.claude.com/oauth/code/callback',
             scope: CLAUDE_SCOPE,
             code_challenge: pkce.challenge,
             code_challenge_method: 'S256',
@@ -236,24 +258,88 @@ export async function fetchClaudeUsage(session, fetchFn = fetch, signal) {
     }
     return { supported: true, windows };
 }
+function claudeThinkingType(capabilities) {
+    const types = capabilities?.thinking?.types;
+    if (types?.enabled?.supported === true)
+        return 'enabled';
+    if (types?.adaptive?.supported === true)
+        return 'adaptive';
+    return undefined;
+}
+/** Effort levels in display order; a model exposes only the ones it advertises as supported. */
+const CLAUDE_EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+function claudeReasoning(capabilities) {
+    const effort = capabilities?.effort;
+    if (effort?.supported !== true)
+        return undefined;
+    const efforts = CLAUDE_EFFORT_LEVELS
+        .filter(level => effort[level]?.supported === true)
+        .map(level => ({ id: ReasoningEffortId(level), name: level[0].toUpperCase() + level.slice(1) }));
+    return efforts.length > 0 ? { efforts } : undefined;
+}
+/** Fetch the live model catalog from the subscription endpoint. */
+export async function fetchClaudeModels(session, fetchFn = fetch) {
+    const response = await fetchFn(CLAUDE_MODELS_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            'anthropic-version': '2023-06-01',
+            'user-agent': CLAUDE_CLI_USER_AGENT,
+            'anthropic-dangerous-direct-browser-access': 'true',
+            'accept': 'application/json',
+        },
+    });
+    if (!response.ok)
+        throw await httpLlmError(response, 'claude models API');
+    const payload = await response.json();
+    if (!Array.isArray(payload.data)) {
+        throw new Error('claude models API returned an invalid catalog');
+    }
+    const models = payload.data
+        .filter((m) => typeof m.id === 'string')
+        .map((m) => {
+        const thinkingType = claudeThinkingType(m.capabilities);
+        const reasoning = claudeReasoning(m.capabilities);
+        return {
+            id: m.id,
+            name: m.display_name ?? m.id,
+            ...thinkingType === undefined ? {} : { thinkingType },
+            ...reasoning === undefined ? {} : { reasoning },
+        };
+    });
+    if (models.length === 0) {
+        throw new Error('claude models API returned an empty catalog');
+    }
+    return models;
+}
+/**
+ * Claude Code's own SDK retry shape: exponential backoff starting at 1s,
+ * doubling per attempt, capped at 60s, plus jitter. `maxRetries` is the
+ * count of retries after the first attempt (Claude Code defaults to 10).
+ */
+const CLAUDE_RETRY_INITIAL_DELAY_MS = 1_000;
+const CLAUDE_RETRY_MAX_DELAY_MS = 60_000;
+const CLAUDE_RETRY_JITTER_RATIO = 0.2;
 /** The Claude 4.5 family accepts image input. */
 const CLAUDE_MODALITIES = ['text', 'image'];
 /** Claude wire adapter: one instance serves the `claude` provider route. */
 export class ClaudeAdapter extends LlmAdapter {
     options;
+    catalog;
     constructor(options) {
         super();
         this.options = options;
+        this.catalog = new ModelCatalogCache(options.catalogStore);
     }
-    providerInfo(provider) {
-        return { id: provider, name: 'Claude (Subscription)' };
+    async fetchCatalog() {
+        return fetchClaudeModels(await this.options.tokens.session(), this.options.fetchFn);
     }
-    async listModels(provider) {
-        // Not logged in → empty catalog, so the web picker drops the provider.
-        // Claude has no subscription model-list endpoint, so the static catalog
-        // is the whole answer when logged in.
-        if (!await this.options.tokens.hasSession())
-            return [];
+    async discovered(model) {
+        if (!this.options.discovery)
+            return undefined;
+        const models = await this.catalog.resolve(() => this.fetchCatalog());
+        return models?.find(entry => entry.id === model);
+    }
+    staticModels(provider) {
         return this.options.models.map(model => ({
             provider,
             id: model.id,
@@ -261,18 +347,61 @@ export class ClaudeAdapter extends LlmAdapter {
             inputModalities: model.inputModalities ?? CLAUDE_MODALITIES,
         }));
     }
-    resolveModel(provider, model) {
+    providerInfo(provider) {
+        return { id: provider, name: 'Claude (Subscription)' };
+    }
+    providerRetryPolicy(provider) {
+        if (this.options.maxRetries === undefined)
+            return undefined;
+        return resolveRetryPolicy({
+            mode: 'normal',
+            maxRetries: this.options.maxRetries,
+            backoff: {
+                initialDelayMs: CLAUDE_RETRY_INITIAL_DELAY_MS,
+                maxDelayMs: CLAUDE_RETRY_MAX_DELAY_MS,
+                jitterRatio: CLAUDE_RETRY_JITTER_RATIO,
+            },
+        }, `claude: provider "${provider}" retryPolicy`);
+    }
+    async listModels(provider) {
+        if (await this.options.tokens.peek() === undefined)
+            return [];
+        if (!this.options.discovery)
+            return this.staticModels(provider);
+        try {
+            const models = await this.catalog.get(() => this.fetchCatalog());
+            return models.map(model => ({
+                provider,
+                id: model.id,
+                name: model.name,
+                inputModalities: CLAUDE_MODALITIES,
+            }));
+        }
+        catch (error) {
+            if (error instanceof LlmError
+                && (error.code === 'MISSING_CREDENTIAL' || error.code === 'INVALID_CREDENTIAL'))
+                return [];
+            if (error instanceof LlmError && error.code === 'AUTH')
+                this.catalog.invalidate();
+            this.options.onWarn?.(`claude model discovery failed; using the built-in catalog (${errorChain(error)})`);
+            return this.staticModels(provider);
+        }
+    }
+    async resolveModel(provider, model) {
+        const disc = await this.discovered(model);
         const configured = this.options.models.find(entry => entry.id === model);
-        return Promise.resolve({
+        const reasoning = disc?.reasoning;
+        return {
             provider,
             id: model,
-            name: configured?.name ?? model,
+            name: disc?.name ?? configured?.name ?? model,
             inputModalities: configured?.inputModalities ?? CLAUDE_MODALITIES,
-            context: { contextWindow: configured?.contextWindow ?? CLAUDE_CONTEXT_WINDOW },
+            context: {
+                contextWindow: disc?.contextWindow ?? configured?.contextWindow ?? CLAUDE_CONTEXT_WINDOW,
+            },
             defaultMaxTokens: configured?.maxTokens ?? CLAUDE_DEFAULT_MAX_TOKENS,
-            // No reasoning metadata: the subscription endpoint's thinking support is
-            // not exercised, so effort requests reject as unsupported.
-        });
+            ...(reasoning === undefined ? {} : { reasoning }),
+        };
     }
     async *stream(options) {
         const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
@@ -280,7 +409,6 @@ export class ClaudeAdapter extends LlmAdapter {
             let session = await this.options.tokens.session();
             let response = await this.request(options, session, watchdog.signal);
             if (response.status === 401) {
-                // One forced refresh + retry on an unexpired-but-rejected token.
                 session = await this.options.tokens.session(true);
                 response = await this.request(options, session, watchdog.signal);
             }
@@ -298,18 +426,44 @@ export class ClaudeAdapter extends LlmAdapter {
             watchdog.stop();
         }
     }
+    /**
+     * `display: 'summarized'` is set explicitly on both shapes: `adaptive`-type
+     * models default to `display: 'omitted'`, which returns thinking blocks with
+     * an empty `thinking` field — without this override the "Think" panel would
+     * always render empty even though real reasoning (and billed thinking_tokens)
+     * ran.
+     */
+    thinkingParam(thinkingType, maxTokens) {
+        if (thinkingType === 'adaptive')
+            return { type: 'adaptive', display: 'summarized' };
+        if (thinkingType === 'enabled') {
+            const budget = Math.min(Math.max(1_024, Math.floor(maxTokens * 0.5)), maxTokens - 100);
+            if (budget < 1_024)
+                return undefined;
+            return { type: 'enabled', budget_tokens: budget, display: 'summarized' };
+        }
+        return undefined;
+    }
     async request(options, session, signal) {
         const messages = await resolveImages(options.messages, this.options.resolveAttachments?.(), signal);
+        const maxTokens = options.maxTokens
+            ?? this.options.models.find(entry => entry.id === options.model)?.maxTokens
+            ?? CLAUDE_DEFAULT_MAX_TOKENS;
+        const disc = await this.discovered(options.model);
+        const thinking = this.thinkingParam(disc?.thinkingType, maxTokens);
+        const effort = options.reasoningEffort !== undefined && disc?.reasoning !== undefined
+            ? { output_config: { effort: String(options.reasoningEffort) } }
+            : {};
         const body = {
             model: options.model,
-            max_tokens: options.maxTokens
-                ?? this.options.models.find(entry => entry.id === options.model)?.maxTokens
-                ?? CLAUDE_DEFAULT_MAX_TOKENS,
+            max_tokens: maxTokens,
             system: toAnthropicSystem(options.system, messages),
             messages: toAnthropicMessages(messages),
             ...options.tools !== undefined && options.tools.length > 0
                 ? { tools: toAnthropicTools(options.tools) }
                 : {},
+            ...thinking === undefined ? {} : { thinking },
+            ...effort,
             stream: true,
             ...options.sessionId !== undefined ? { metadata: { user_id: String(options.sessionId) } } : {},
         };

package/lib/providers/common.d.ts

@@ -175,6 +175,8 @@ export interface DiscoveredModel {
         }[];
         defaultEffort?: ReasoningEffortId;
     };
+    /** Claude-specific: which extended-thinking wire shape this model accepts. */
+    thinkingType?: 'enabled' | 'adaptive';
 }
 /** How long a discovered catalog is trusted before re-fetching. */
 export declare const DISCOVERY_TTL_MS: number;

package/lib/tools/image-generate.d.ts

@@ -1,27 +1,37 @@
 /**
- * `image_generate` tool: generate images through the ChatGPT/Codex
- * subscription's image endpoint, save them as PNG files under the harness
- * home, and — when the deployment mounts an attachment store and the calling
- * route declares image input — also commit the bytes as durable attachments
- * so the images render inline and enter model context (the same path
- * `read_image` uses). Mirrors codex-rs `codex-api/src/images.rs`: POST
- * `/backend-api/codex/images/generations` with the responses call's auth
- * headers; the response carries base64 PNG data.
+ * `image_generate` tool: generate images through a subscription image
+ * endpoint, save them under the harness home, and — when the deployment
+ * mounts an attachment store and the calling route declares image input —
+ * also commit the bytes as durable attachments so the images render inline
+ * and enter model context (the same path `read_image` uses).
+ *
+ * Provider selection: the `provider` argument names the preferred provider
+ * (default `gpt`, i.e. the ChatGPT/Codex subscription serving gpt-image-2 —
+ * mirrors codex-rs `codex-api/src/images.rs`); when the preferred one is
+ * logged out the other serves as fallback (`grok` is grok-imagine-image-2.0
+ * via `api.x.ai/v1/images/generations` with `response_format: 'b64_json'`).
+ * Both answer the OpenAI images shape (`data[].b64_json`).
  */
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { LlmRuntime } from '@deepseek-ai/dsh-llm';
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
-import type { CodexSession } from '../auth/store.js';
+import type { CodexSession, GrokSession } from '../auth/store.js';
 import { TokenManager } from '../providers/common.js';
 import type { FetchFn } from '../providers/common.js';
-/** Endpoint the generation request is posted to. */
+/** Endpoint the codex generation request is posted to. */
 export declare const IMAGE_GENERATE_URL = "https://chatgpt.com/backend-api/codex/images/generations";
 /** The image model the codex subscription endpoint serves. */
 export declare const IMAGE_GENERATE_MODEL = "gpt-image-2";
+/** Endpoint the grok generation request is posted to. */
+export declare const GROK_IMAGE_GENERATE_URL = "https://api.x.ai/v1/images/generations";
+/** The image model the grok subscription endpoint serves. */
+export declare const GROK_IMAGE_GENERATE_MODEL = "grok-imagine-image-2.0";
 /** Dependencies of the `image_generate` tool. */
 export interface ImageGenerateToolOptions {
-    /** Codex session source; a missing session throws the log-in hint. */
-    tokens: TokenManager<CodexSession>;
+    /** Codex session source; the default preferred provider (`provider: 'gpt'`). */
+    codexTokens?: TokenManager<CodexSession>;
+    /** Grok session source; preferred when the call passes `provider: 'grok'`. */
+    grokTokens?: TokenManager<GrokSession>;
     /** Fetch implementation (injectable for tests). */
     fetchFn?: FetchFn;
     /** Directory override for saved images (defaults under the harness home). */
@@ -38,15 +48,33 @@ export interface ImageGenerateRequestBody {
     size?: string;
     quality?: string;
 }
-/**
- * Assemble the request body from tool arguments (hand-checks the non-empty
- * prompt the schema DSL cannot express).
- */
-export declare function buildImageGenerateBody(args: {
+/** The tool's own argument shape, shared by both provider body builders. */
+export interface ImageGenerateArgs {
     prompt: string;
     size?: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
     quality?: 'low' | 'medium' | 'high' | 'auto';
-}): ImageGenerateRequestBody;
+    /** Preferred provider; the other one serves when the preferred is logged out. */
+    provider?: 'gpt' | 'grok';
+}
+/**
+ * Assemble the codex request body from tool arguments (hand-checks the
+ * non-empty prompt the schema DSL cannot express).
+ */
+export declare function buildImageGenerateBody(args: ImageGenerateArgs): ImageGenerateRequestBody;
+/** The wire request body for one grok generation call. */
+export interface GrokImageGenerateRequestBody {
+    prompt: string;
+    model: string;
+    response_format: 'b64_json';
+    aspect_ratio?: string;
+    quality?: 'low' | 'medium';
+}
+/**
+ * Assemble the grok request body from the same tool arguments: `size` maps
+ * onto the nearest `aspect_ratio`, and `quality` folds into grok's low/medium
+ * pair (`high` → `medium`, `auto` → provider default).
+ */
+export declare function buildGrokImageGenerateBody(args: ImageGenerateArgs): GrokImageGenerateRequestBody;
 /** One generated image decoded from the response. */
 export interface GeneratedImage {
     /** PNG bytes. */
@@ -59,8 +87,16 @@ export interface GeneratedImage {
  * payload carries no usable `b64_json` entries.
  */
 export declare function parseImageGenerateResponse(payload: unknown): GeneratedImage[];
-/** Directory the generated PNG files are written to. */
+/** Directory the generated image files are written to. */
 export declare function imagesDirectory(): string;
+/** Media types the attachment store accepts and this tool can produce. */
+export type GeneratedImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp';
+/**
+ * Sniff a generated image's media type from its magic bytes (codex serves
+ * PNG; grok's format is undocumented, so trust the bytes). Unrecognized data
+ * defaults to PNG, matching the historical behavior.
+ */
+export declare function sniffImageMediaType(data: Buffer): GeneratedImageMediaType;
 /**
  * Build the `image_generate` tool definition.
  * @param options - codex session source, fetch implementation, and image directory.