@pure01fx/dsh-openai-codex-auth 0.8.0 → 0.10.0

package/lib/cloud-search.js

@@ -0,0 +1,172 @@
+/** Wire contract: Codex b348fc26674189f758d5941cdab3f78f258b2aa7, codex-api/src/search.rs. */
+import { createHash } from 'node:crypto';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+const MAX_REQUEST_BYTES = 256 * 1024;
+const MAX_OUTPUT_BYTES = 128 * 1024;
+const MAX_RESULTS_BYTES = 256 * 1024;
+const invalid = () => new LlmError('Invalid codex_web arguments; check command fields and limits', 'INVALID_ARGS');
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype)
+        throw invalid();
+    return value;
+}
+function text(value, empty = false) {
+    if (typeof value !== 'string' || (!empty && !value.trim()) || value.length > MAX_REQUEST_BYTES)
+        throw invalid();
+    return value;
+}
+const string = value => text(value);
+const uint = value => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw invalid();
+    return value;
+};
+const strings = value => {
+    if (!Array.isArray(value) || value.length > 100)
+        throw invalid();
+    return value.map(item => text(item));
+};
+const bool = value => { if (typeof value !== 'boolean')
+    throw invalid(); return value; };
+const choice = (...values) => value => { if (typeof value !== 'string' || !values.includes(value))
+    throw invalid(); return value; };
+const date = value => {
+    const s = text(value);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(s) || !Number.isFinite(Date.parse(s)) || new Date(s).toISOString().slice(0, 10) !== s)
+        throw invalid();
+    return s;
+};
+function fields(value, rules, required = []) {
+    const input = object(value);
+    if (required.some(key => input[key] === undefined))
+        throw invalid();
+    const result = {};
+    for (const [key, item] of Object.entries(input)) {
+        if (!Object.hasOwn(rules, key))
+            throw invalid();
+        if (item !== undefined)
+            result[key] = rules[key](item);
+    }
+    return result;
+}
+const query = { q: string, recency: uint, domains: strings };
+const operations = {
+    search_query: { rules: query, required: ['q'] },
+    image_query: { rules: query, required: ['q'] },
+    open: { rules: { ref_id: string, lineno: uint }, required: ['ref_id'] },
+    click: { rules: { ref_id: string, id: uint }, required: ['ref_id', 'id'] },
+    find: { rules: { ref_id: string, pattern: string }, required: ['ref_id', 'pattern'] },
+    screenshot: { rules: { ref_id: string, pageno: uint }, required: ['ref_id', 'pageno'] },
+    finance: { rules: { ticker: string, type: choice('equity', 'fund', 'crypto', 'index'), market: value => text(value, true) }, required: ['ticker', 'type'] },
+    weather: { rules: { location: string, start: date, duration: uint }, required: ['location'] },
+    sports: { rules: { tool: choice('sports'), fn: choice('schedule', 'standings'), league: choice('nba', 'wnba', 'nfl', 'nhl', 'mlb', 'epl', 'ncaamb', 'ncaawb', 'ipl'), team: string, opponent: string, date_from: date, date_to: date, num_games: uint, locale: string }, required: ['fn', 'league'] },
+    time: { rules: { utc_offset: value => {
+                const s = text(value);
+                if (!/^[+-](?:0\d|1\d|2[0-3]):[0-5]\d$/.test(s))
+                    throw invalid();
+                return s;
+            } }, required: ['utc_offset'] },
+};
+function boundedRequest(value) {
+    try {
+        if (Buffer.byteLength(JSON.stringify(value)) > MAX_REQUEST_BYTES)
+            throw invalid();
+    }
+    catch {
+        throw invalid();
+    }
+}
+export function parseCloudSearchArgs(value) {
+    const input = object(value);
+    const parsed = fields(input, {
+        commands: value => {
+            const commands = object(value);
+            const result = {};
+            let count = 0;
+            for (const [key, items] of Object.entries(commands)) {
+                if (key === 'response_length') {
+                    result[key] = choice('short', 'medium', 'long')(items);
+                    continue;
+                }
+                if (!Object.hasOwn(operations, key) || !Array.isArray(items) || items.length === 0 || items.length > 100)
+                    throw invalid();
+                const operation = operations[key];
+                count += items.length;
+                result[key] = items.map(item => fields(item, operation.rules, operation.required));
+            }
+            if (count === 0 || count > 100)
+                throw invalid();
+            return result;
+        },
+        model: string, context: value => text(value, true), mode: choice('cached', 'indexed', 'live'),
+        search_context_size: choice('low', 'medium', 'high'),
+        user_location: value => fields(value, { country: string, region: string, city: string, timezone: string }),
+        filters: value => fields(value, { allowed_domains: strings, blocked_domains: strings }),
+        image_settings: value => fields(value, { max_results: uint, caption: bool }),
+    }, ['commands']);
+    boundedRequest(parsed);
+    return parsed;
+}
+/** The caller selects the model and visible context using the same request credential. */
+export function buildCloudSearchRequest(args, context) {
+    const parsed = parseCloudSearchArgs(args);
+    const id = createHash('sha256').update(JSON.stringify(['dsh-codex-search-v1', text(context.sessionId), text(context.accountId)])).digest('hex');
+    const settings = { allowed_callers: ['direct'], external_web_access: parsed.mode === 'cached' ? false : parsed.mode === 'indexed' ? 'indexed' : true };
+    for (const key of ['search_context_size', 'filters', 'image_settings'])
+        if (parsed[key] !== undefined)
+            settings[key] = parsed[key];
+    if (parsed.user_location !== undefined)
+        settings.user_location = { type: 'approximate', ...parsed.user_location };
+    const selected = parsed.context ?? context.input;
+    const input = typeof selected === 'string' ? [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: selected }] }] : selected;
+    if (input !== undefined && typeof input !== 'string' && !Array.isArray(input))
+        throw invalid();
+    const result = { id, model: text(context.model), commands: parsed.commands, settings, ...(input === undefined ? {} : { input }) };
+    boundedRequest(result);
+    return result;
+}
+/** Keep whole opaque result entries and identify any omitted data explicitly. */
+export function parseCloudSearchResponse(body) {
+    let data;
+    try {
+        data = object(body);
+    }
+    catch {
+        throw new LlmError('Invalid Codex search response', 'CODEX_CLOUD_FAILED');
+    }
+    if (typeof data.output !== 'string' || (data.results != null && !Array.isArray(data.results)))
+        throw new LlmError('Invalid Codex search response', 'CODEX_CLOUD_FAILED');
+    let output = data.output;
+    let truncated = false;
+    if (Buffer.byteLength(output) > MAX_OUTPUT_BYTES) {
+        // Truncate only at complete UTF-8 boundaries; the notice warns that references may be omitted.
+        output = new TextDecoder().decode(Buffer.from(output).subarray(0, MAX_OUTPUT_BYTES)).replace(/\uFFFD$/, '');
+        truncated = true;
+    }
+    let results;
+    if (Array.isArray(data.results)) {
+        results = [];
+        let bytes = 2;
+        for (const item of data.results) {
+            let serialized;
+            try {
+                serialized = JSON.stringify(item);
+            }
+            catch {
+                throw new LlmError('Invalid Codex search results', 'CODEX_CLOUD_FAILED');
+            }
+            if (serialized === undefined)
+                throw new LlmError('Invalid Codex search results', 'CODEX_CLOUD_FAILED');
+            const size = Buffer.byteLength(serialized) + 1;
+            if (results.length >= 100 || bytes + size > MAX_RESULTS_BYTES) {
+                truncated = true;
+                continue;
+            }
+            results.push(JSON.parse(serialized));
+            bytes += size;
+        }
+    }
+    if (truncated)
+        output += '\n[Search response truncated; some content or references were omitted. Narrow the request to retrieve them.]';
+    return { output, ...(results === undefined ? {} : { results }), truncated };
+}

package/lib/cloud-tools.d.ts

@@ -0,0 +1,25 @@
+/** Ordinary DSH image tools; cloud credentials never enter tool arguments. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type NativeCodexModelCatalog } from './catalog.js';
+import { NativeCodexCloudClient } from './cloud-http.js';
+import type { NativeCodexHttpOptions } from './native-http.js';
+import type { CodexImageDetail } from './responses.js';
+export interface CloudToolsConfig {
+    enabled?: boolean;
+    search?: boolean;
+    imageGeneration?: boolean;
+    imageEditing?: boolean;
+    imageInspection?: boolean;
+    searchModel?: string;
+    visionModel?: string;
+    imageModel?: string;
+    searchMode?: 'cached' | 'indexed' | 'live';
+    visionDetail?: CodexImageDetail;
+}
+export interface CloudToolsDependencies {
+    client: NativeCodexCloudClient;
+    catalog: NativeCodexModelCatalog;
+    transport: NativeCodexHttpOptions;
+    config: CloudToolsConfig;
+}
+export declare function registerCodexImageTools(ctx: Context, deps: CloudToolsDependencies): void;

package/lib/cloud-tools.js

@@ -0,0 +1,129 @@
+import { nativeCodexAuthorityHash } from './catalog.js';
+import { buildImageGenerationRequest, buildImageEditRequest, parseImageResponse, validateImageEditArgs } from './cloud-images.js';
+import { resolveImageSources, saveImageOutputs } from './cloud-media.js';
+import { inspectCloudImages, parseCloudVisionArgs } from './cloud-vision.js';
+import { chooseCloudModel, visibleCloudImages } from './cloud-context.js';
+const imageRefs = { type: 'array', minItems: 1, maxItems: 5, description: 'Images visible in this session, or absolute file paths read under your file policy. Preserve order.', items: {
+        oneOf: [
+            { type: 'object', properties: { attachment_id: { type: 'string' } }, required: ['attachment_id'], additionalProperties: false },
+            { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false },
+        ],
+    } };
+const common = {
+    prompt: { type: 'string', description: 'Describe the image to generate or the edits to perform.', minLength: 1, maxLength: 32000 },
+    model: { type: 'string', description: 'Optional Codex image model; defaults to configured imageModel or gpt-image-2.' },
+    quality: { type: 'string', enum: ['auto', 'low', 'medium', 'high'] },
+    background: { type: 'string', enum: ['auto', 'transparent', 'opaque'] },
+    size: { type: 'string', description: 'auto or a service-supported WIDTHxHEIGHT, such as 1024x1024.' },
+    n: { type: 'integer', minimum: 1, maximum: 4, description: 'Optional number of images; omitted by default.' },
+};
+const resultSchema = { type: 'object', additionalProperties: true };
+function render(_args, value) {
+    const row = value;
+    const content = [{ type: 'text', text: JSON.stringify(value) }];
+    if (row.image_output)
+        for (const image of row.images ?? [])
+            if (image.attachment)
+                content.push({ type: 'image', attachment: image.attachment });
+    return content;
+}
+function requireAgent(exec) {
+    if (!exec.agent)
+        throw new Error('Codex cloud tools require an agent session');
+}
+const recentImages = new WeakMap();
+function mediaContext(exec) {
+    requireAgent(exec);
+    const ctx = exec.agent.ctx;
+    const workspace = exec.agent.session.header.cwd;
+    if (!workspace || !ctx.fs || !ctx.attachments)
+        throw new Error('Codex image tools require the caller workspace, filesystem and attachment services');
+    const messages = exec.agent.session.deriveMessages();
+    const cached = recentImages.get(exec.agent.session);
+    const visible = visibleCloudImages(messages);
+    if (cached?.historyLength === messages.length) {
+        for (const ref of cached.refs)
+            if (!visible.some(value => value.attachmentId === ref.attachmentId))
+                visible.push(ref);
+    }
+    else
+        recentImages.delete(exec.agent.session);
+    return { fs: ctx.fs, attachments: ctx.attachments, workspace, signal: exec.signal, visibleImages: visible };
+}
+async function imageOutputSupported(exec) {
+    requireAgent(exec);
+    const { provider, model } = exec.agent.options;
+    if (!provider || !model || !exec.agent.ctx.llm)
+        return false;
+    try {
+        return (await exec.agent.ctx.llm.resolveModelInfo(provider, model, exec.signal)).inputModalities?.includes('image') ?? false;
+    }
+    catch {
+        exec.signal.throwIfAborted();
+        return false;
+    }
+}
+export function registerCodexImageTools(ctx, deps) {
+    const config = deps.config;
+    if (config.enabled === false)
+        return;
+    const output = { schema: resultSchema, render };
+    for (const kind of ['generate', 'edit']) {
+        if (kind === 'generate' ? config.imageGeneration === false : config.imageEditing === false)
+            continue;
+        const tool = {
+            name: 'codex_image_' + kind,
+            description: kind === 'generate' ? 'Generate images using the current Codex account. Returns original file paths and image attachments for display or further editing.'
+                : 'Edit 1–5 images with the current Codex account. Use explicit images OR num_last_images_to_include. Returns originals and preview attachments. Does not support mask/seed parameters.',
+            parameters: { type: 'object', additionalProperties: false, properties: { ...common, ...(kind === 'edit' ? {
+                        images: imageRefs, num_last_images_to_include: { type: 'integer', minimum: 1, maximum: 5, description: 'Use the most recent visible session images; mutually exclusive with images.' },
+                    } : {}) }, required: ['prompt'] },
+            output, timeoutMs: 180_000, isConcurrencySafe: () => false,
+            async execute(value, exec) {
+                requireAgent(exec);
+                const media = mediaContext(exec);
+                const scope = exec.agent.ctx;
+                if (!scope.shell?.sandboxMode || !scope.sandboxPolicy)
+                    throw new Error('Codex image output requires the policy-enforcing shell and sandboxPolicy services');
+                const policy = scope.sandboxPolicy.resolve({ session: exec.agent.session });
+                const credential = await deps.client.resolveCredential(exec.signal);
+                const args = kind === 'edit' ? validateImageEditArgs(value, config.imageModel) : buildImageGenerationRequest(value, config.imageModel);
+                const request = kind === 'edit' ? buildImageEditRequest(value, await resolveImageSources(validateImageEditArgs(value, config.imageModel), media), config.imageModel) : { ...args };
+                const result = await deps.client.post(kind === 'edit' ? 'images/edits' : 'images/generations', request, { credential, signal: exec.signal });
+                const saved = await saveImageOutputs(parseImageResponse(result.body, result.requestId), { ...media, shell: scope.shell, policy });
+                const image_output = await imageOutputSupported(exec);
+                const old = recentImages.get(exec.agent.session)?.refs ?? [];
+                recentImages.set(exec.agent.session, { historyLength: exec.agent.session.deriveMessages().length,
+                    refs: [...old, ...saved.images.map(image => image.attachment)].slice(-20) });
+                return { ...saved, image_output };
+            },
+        };
+        ctx.tools.register(tool);
+    }
+    if (config.imageInspection !== false)
+        ctx.tools.register({
+            name: 'codex_image_inspect',
+            description: 'Ask a Codex vision model to analyze images, OCR, screenshots or charts. This makes one additional cloud inference call, without recursive tools. Use explicit model or configured visionModel for non-Codex callers. Reports effective detail and actual dimensions.',
+            parameters: { type: 'object', additionalProperties: false, required: ['prompt', 'images'], properties: {
+                    prompt: { type: 'string', minLength: 1, maxLength: 32000 }, images: imageRefs,
+                    model: { type: 'string' }, detail: { type: 'string', enum: ['auto', 'low', 'high', 'original'] }, reasoning_effort: { type: 'string' },
+                } },
+            output, timeoutMs: 120_000, isConcurrencySafe: () => true,
+            async execute(value, exec) {
+                requireAgent(exec);
+                const args = parseCloudVisionArgs(value);
+                const credential = await deps.client.resolveCredential(exec.signal);
+                const view = await deps.catalog.listWithAuthority?.(exec.signal) ?? { models: await deps.catalog.list(exec.signal) };
+                if (view.authorityHash !== undefined && view.authorityHash !== nativeCodexAuthorityHash(credential.accountId))
+                    throw new Error('Codex account changed before image inspection; retry with the current account');
+                const model = chooseCloudModel({ purpose: 'vision', ...(args.model === undefined ? {} : { requested: args.model }),
+                    ...(config.visionModel === undefined ? {} : { configured: config.visionModel }),
+                    ...exec.agent.options.provider === undefined ? {} : { currentProvider: exec.agent.options.provider },
+                    ...exec.agent.options.model === undefined ? {} : { currentModel: exec.agent.options.model },
+                }, view.models);
+                const images = await resolveImageSources({ images: args.images }, mediaContext(exec));
+                return inspectCloudImages(args, { credential, model, images, signal: exec.signal, transport: deps.transport,
+                    ...(config.visionDetail === undefined ? {} : { defaultDetail: config.visionDetail }) });
+            },
+        });
+}

package/lib/cloud-vision.d.ts

@@ -0,0 +1,34 @@
+import { type TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { NativeCodexCredential, NativeCodexModel } from './catalog.js';
+import { type NativeCodexHttpOptions } from './native-http.js';
+import type { CodexImageDetail } from './responses.js';
+import { type ImageSource } from './cloud-images.js';
+import type { ResolvedCloudImage } from './cloud-media.js';
+export interface CloudVisionArgs {
+    prompt: string;
+    images: ImageSource[];
+    model?: string;
+    detail?: CodexImageDetail;
+    reasoning_effort?: string;
+}
+export declare function parseCloudVisionArgs(value: unknown): CloudVisionArgs;
+export interface CloudVisionDependencies {
+    model: NativeCodexModel;
+    credential: NativeCodexCredential;
+    images: readonly ResolvedCloudImage[];
+    signal: AbortSignal;
+    defaultDetail?: CodexImageDetail;
+    transport: NativeCodexHttpOptions;
+}
+export declare function inspectCloudImages(args: CloudVisionArgs, deps: CloudVisionDependencies): Promise<{
+    images: {
+        requested_detail: CodexImageDetail;
+        effective_detail: string;
+        width: number;
+        height: number;
+        scaled: boolean;
+    }[];
+    usage?: TokenUsage;
+    text: string;
+    model: string;
+}>;

package/lib/cloud-vision.js

@@ -0,0 +1,108 @@
+/** One explicit, tool-free Codex image understanding request. */
+import { randomUUID } from 'node:crypto';
+import { createUserMessage, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { nativeCodexWireReasoningEffort } from './native-adapter.js';
+import { NativeCodexHttpTransport } from './native-http.js';
+import { validateImageSelection } from './cloud-images.js';
+export function parseCloudVisionArgs(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Vision arguments must be an object');
+    const row = value;
+    if (Object.keys(row).some(key => !['prompt', 'images', 'model', 'detail', 'reasoning_effort'].includes(key)))
+        throw new Error('Unknown vision argument');
+    if (typeof row.prompt !== 'string' || !row.prompt.trim() || Buffer.byteLength(row.prompt) > 32_000)
+        throw new Error('Vision prompt must be a nonempty bounded string');
+    const selection = validateImageSelection(row);
+    if (!selection.images)
+        throw new Error('Vision requires explicit images');
+    for (const key of ['model', 'reasoning_effort']) {
+        if (row[key] !== undefined && (typeof row[key] !== 'string' || !row[key].trim() || Buffer.byteLength(row[key]) > 256))
+            throw new Error('Invalid vision ' + key);
+    }
+    if (row.detail !== undefined && !['auto', 'low', 'high', 'original'].includes(row.detail))
+        throw new Error('Invalid vision detail');
+    return { prompt: row.prompt, images: selection.images,
+        ...(row.model === undefined ? {} : { model: row.model }),
+        ...(row.detail === undefined ? {} : { detail: row.detail }),
+        ...(row.reasoning_effort === undefined ? {} : { reasoning_effort: row.reasoning_effort }) };
+}
+export async function inspectCloudImages(args, deps) {
+    const { model } = deps;
+    deps.signal.throwIfAborted();
+    if (!model.inputModalities.includes('image'))
+        throw new LlmError('Select a Codex model with image input', 'VISION_UNSUPPORTED');
+    if (deps.images.length !== args.images.length)
+        throw new Error('Resolved vision images do not match the request');
+    const requested = args.detail ?? deps.defaultDetail ?? 'auto';
+    const effective = model.useResponsesLite ? undefined
+        : requested === 'original' && !model.supportsImageDetailOriginal ? 'high' : requested;
+    const images = deps.images.map(image => {
+        if (!image.width || !image.height)
+            throw new Error('Vision requires verified encoded image dimensions');
+        // Ephemeral references are resolved only by this invocation's reader, never persisted.
+        const ref = { attachmentId: ('vision-' + randomUUID()),
+            mediaType: image.mediaType, bytes: image.data.byteLength, width: image.width, height: image.height };
+        return { image, ref };
+    });
+    const signal = AbortSignal.any([deps.signal, AbortSignal.timeout(120_000)]);
+    let recovered = false;
+    const transport = new NativeCodexHttpTransport({ ...deps.transport, maxTransientRetries: 0,
+        resolveCredential: async (readSignal) => {
+            const current = recovered ? await deps.transport.resolveCredential(readSignal) : deps.credential;
+            if (current.accountId !== deps.credential.accountId)
+                throw new LlmError('Codex account changed during image inspection', 'CODEX_ACCOUNT_CHANGED');
+            return current;
+        },
+        recoverCredential: async (previous, readSignal) => {
+            const ok = await deps.transport.recoverCredential?.(previous, readSignal) ?? false;
+            recovered = ok;
+            return ok;
+        },
+        readImage: async (ref) => {
+            const entry = images.find(image => image.ref.attachmentId === ref.attachmentId);
+            if (!entry)
+                throw new LlmError('Image is outside this inspection request', 'INVALID_ATTACHMENT');
+            return { data: entry.image.data, ...(effective === undefined ? {} : { detail: effective }) };
+        } });
+    const effort = nativeCodexWireReasoningEffort(args.reasoning_effort ?? (model.useResponsesLite ? model.defaultReasoningLevel : undefined), model);
+    const chunks = transport.stream({ provider: 'openai-codex', model: model.slug, signal,
+        system: 'Analyze the provided images and answer the user request. State uncertainty where image details are unclear.',
+        messages: [createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: args.prompt }, ...images.map(({ ref }) => ({ type: 'image', attachment: ref }))] })],
+        tools: [], ...(effort === undefined ? {} : { reasoningEffort: ReasoningEffortId(effort) }) }, { pinnedAccountId: deps.credential.accountId, ...(model.useResponsesLite ? { responsesLite: {
+                ...(model.defaultVerbosity === undefined ? {} : { defaultVerbosity: model.defaultVerbosity }),
+                ...(model.instructionsTemplate === undefined ? {} : { instructionsTemplate: model.instructionsTemplate }),
+            } } : {}) });
+    const texts = new Map();
+    let visibleBytes = 0;
+    let usage;
+    let finished = false;
+    for await (const chunk of chunks) {
+        if (chunk.type === 'tool-call-delta' || (chunk.type === 'block-start' && chunk.blockType === 'tool-call'))
+            throw new LlmError('Image inspection returned an unexpected tool call', 'UNSUPPORTED');
+        if (chunk.type === 'text-delta') {
+            visibleBytes += Buffer.byteLength(chunk.text);
+            if (visibleBytes > 128 * 1024)
+                throw new LlmError('Image inspection output exceeded limit', 'RESPONSE_TOO_LARGE');
+        }
+        if (chunk.type === 'block-end' && chunk.block.type === 'text') {
+            texts.set(chunk.index, chunk.block.text);
+            if ([...texts.values()].reduce((bytes, text) => bytes + Buffer.byteLength(text), 0) > 128 * 1024)
+                throw new LlmError('Image inspection output exceeded limit', 'RESPONSE_TOO_LARGE');
+        }
+        if (chunk.type === 'usage')
+            usage = chunk.usage;
+        if (chunk.type === 'finish') {
+            if (chunk.reason.kind === 'error')
+                throw new LlmError(chunk.reason.failure.message, chunk.reason.failure.code);
+            if (chunk.reason.kind !== 'stop')
+                throw new LlmError('Image inspection did not complete normally', 'INCOMPLETE_RESPONSE');
+            finished = true;
+        }
+    }
+    const text = [...texts.entries()].sort(([a], [b]) => a - b).map(([, value]) => value).join('');
+    if (!finished || !text.trim())
+        throw new LlmError('Image inspection returned no completed text', 'EMPTY_RESPONSE');
+    return { text, model: model.slug, ...(usage === undefined ? {} : { usage }), images: images.map(({ image }) => ({
+            requested_detail: requested, effective_detail: effective ?? 'omitted', width: image.width, height: image.height, scaled: image.scaled,
+        })) };
+}

package/lib/cloud-web-tool.d.ts

@@ -0,0 +1,12 @@
+/** Native codex_web registration. No private host APIs or third-party OAuth requests. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type NativeCodexModelCatalog } from './catalog.js';
+import type { NativeCodexCloudClient } from './cloud-http.js';
+export declare function registerCodexWeb(ctx: Context, deps: {
+    client: NativeCodexCloudClient;
+    catalog: NativeCodexModelCatalog;
+    config: {
+        searchModel?: string;
+        searchMode?: 'live' | 'indexed' | 'cached';
+    };
+}): void;