@pure01fx/dsh-openai-codex-auth 0.9.0 → 0.10.1

package/lib/cloud-images.d.ts

@@ -0,0 +1,51 @@
+/** Pure image endpoint validation and bounded decoding. */
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment';
+export declare const MAX_IMAGE_BYTES: number;
+export type ImageSource = {
+    attachment_id: string;
+} | {
+    path: string;
+};
+export interface ImageSelection {
+    images?: ImageSource[];
+    num_last_images_to_include?: number;
+}
+export interface ImageGenerateArgs {
+    prompt: string;
+    model: string;
+    quality: 'auto' | 'low' | 'medium' | 'high';
+    background: 'auto' | 'transparent' | 'opaque';
+    size: string;
+    n?: number;
+}
+export type ImageEditArgs = ImageGenerateArgs & ImageSelection;
+export declare function validateImageSelection(value: unknown): ImageSelection;
+export declare function validateImageGenerateArgs(value: unknown, defaultModel?: string): ImageGenerateArgs;
+export declare function validateImageEditArgs(value: unknown, defaultModel?: string): ImageEditArgs;
+export declare function buildImageGenerationRequest(value: unknown, defaultModel?: string): ImageGenerateArgs;
+export declare function buildImageEditRequest(value: unknown, images: readonly {
+    image_url: string;
+}[], defaultModel?: string): {
+    images: {
+        image_url: string;
+    }[];
+    prompt: string;
+    model: string;
+    quality: "auto" | "low" | "medium" | "high";
+    background: "auto" | "transparent" | "opaque";
+    size: string;
+    n?: number;
+};
+export declare function decodeImageBase64(value: unknown, maxBytes?: number): Uint8Array;
+export declare function imageMediaType(data: Uint8Array): ImageMediaType;
+export interface ParsedCloudImage {
+    data: Uint8Array;
+    mediaType: ImageMediaType;
+    generation_id?: string;
+    metadata: Record<string, unknown>;
+}
+export interface ParsedImageResponse {
+    images: ParsedCloudImage[];
+    metadata: Record<string, unknown>;
+}
+export declare function parseImageResponse(value: unknown, requestId?: string): ParsedImageResponse;

package/lib/cloud-images.js

@@ -0,0 +1,122 @@
+export const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+function object(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(label + ' must be an object');
+    return value;
+}
+function text(value, label, max = 32_000) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max)
+        throw new Error(label + ' must be a nonempty bounded string');
+    return value;
+}
+function count(value, label, max) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max)
+        throw new Error(label + ' must be an integer from 1 to ' + max);
+    return value;
+}
+function choice(value, label, values) {
+    if (!values.includes(value))
+        throw new Error('Invalid ' + label);
+    return value;
+}
+export function validateImageSelection(value) {
+    const a = object(value, 'Image selection');
+    if ((a.images !== undefined) === (a.num_last_images_to_include !== undefined))
+        throw new Error('Provide exactly one of images or num_last_images_to_include');
+    if (a.images === undefined)
+        return { num_last_images_to_include: count(a.num_last_images_to_include, 'num_last_images_to_include', 5) };
+    if (!Array.isArray(a.images) || a.images.length < 1 || a.images.length > 5)
+        throw new Error('images must contain 1 to 5 references');
+    return { images: a.images.map((source) => {
+            const s = object(source, 'Image reference');
+            if (Object.keys(s).length !== 1)
+                throw new Error('Image reference must contain only attachment_id or path');
+            if (s.attachment_id !== undefined)
+                return { attachment_id: text(s.attachment_id, 'attachment_id', 512) };
+            return { path: text(s.path, 'path', 4096) };
+        }) };
+}
+export function validateImageGenerateArgs(value, defaultModel = 'gpt-image-2') {
+    const a = object(value, 'Image arguments');
+    const size = text(a.size ?? 'auto', 'size', 64);
+    if (size !== 'auto' && !/^[1-9][0-9]{0,4}x[1-9][0-9]{0,4}$/.test(size))
+        throw new Error('size must be auto or WIDTHxHEIGHT; model support is determined by the service');
+    return {
+        prompt: text(a.prompt, 'prompt'), model: text(a.model ?? defaultModel, 'model', 256),
+        quality: choice(a.quality ?? 'auto', 'quality', ['auto', 'low', 'medium', 'high']),
+        background: choice(a.background ?? 'auto', 'background', ['auto', 'transparent', 'opaque']), size,
+        ...(a.n === undefined ? {} : { n: count(a.n, 'n', 4) }),
+    };
+}
+export function validateImageEditArgs(value, defaultModel) {
+    return { ...validateImageGenerateArgs(value, defaultModel), ...validateImageSelection(value) };
+}
+export function buildImageGenerationRequest(value, defaultModel) {
+    return validateImageGenerateArgs(value, defaultModel);
+}
+export function buildImageEditRequest(value, images, defaultModel) {
+    const args = validateImageEditArgs(value, defaultModel);
+    const expected = args.images?.length ?? args.num_last_images_to_include;
+    if (images.length !== expected)
+        throw new Error('Resolved image count does not match selection');
+    for (const image of images) {
+        const match = /^data:(image[/](?:png|jpeg|webp|gif));base64,(.*)$/.exec(image.image_url);
+        if (!match)
+            throw new Error('Edit images must be inline supported image data');
+        if (imageMediaType(decodeImageBase64(match[2])) !== match[1])
+            throw new Error('Edit image media type does not match bytes');
+    }
+    return { ...validateImageGenerateArgs(value, defaultModel), images: images.map(({ image_url }) => ({ image_url })) };
+}
+export function decodeImageBase64(value, maxBytes = MAX_IMAGE_BYTES) {
+    const cap = Math.min(maxBytes, MAX_IMAGE_BYTES);
+    if (typeof value !== 'string' || !value.length || value.length > 4 * Math.ceil(cap / 3))
+        throw new Error('Image base64 is empty or exceeds byte limit');
+    // Check length before scanning or allocating the decoded payload.
+    if (value.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(value) || !/^[A-Za-z0-9+/]*={0,2}$/.test(value))
+        throw new Error('Invalid image base64');
+    const data = Buffer.from(value, 'base64');
+    if (!data.length || data.length > cap || data.toString('base64') !== value)
+        throw new Error('Invalid image base64 or byte limit exceeded');
+    return data;
+}
+export function imageMediaType(data) {
+    const b = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    if (b.length >= 8 && b.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return 'image/png';
+    if (b.length >= 3 && b[0] === 255 && b[1] === 216 && b[2] === 255)
+        return 'image/jpeg';
+    if (b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    if (b.length >= 6 && ['GIF87a', 'GIF89a'].includes(b.toString('ascii', 0, 6)))
+        return 'image/gif';
+    throw new Error('Unsupported or invalid image bytes');
+}
+export function parseImageResponse(value, requestId) {
+    const response = object(value, 'Image response');
+    if (!Array.isArray(response.data) || !response.data.length || response.data.length > 4)
+        throw new Error('Image response must contain 1 to 4 data entries');
+    // JSON numbers cannot preserve the entire u64 range. Reject lossy timestamps.
+    if (typeof response.created !== 'number' || !Number.isSafeInteger(response.created) || response.created < 0)
+        throw new Error('Image response created must be a lossless nonnegative u64');
+    const metadata = { created: response.created };
+    if (response.background != null)
+        metadata.background = choice(response.background, 'response background', ['auto', 'transparent', 'opaque']);
+    if (response.quality != null)
+        metadata.quality = choice(response.quality, 'response quality', ['auto', 'low', 'medium', 'high']);
+    if (response.size != null)
+        metadata.size = text(response.size, 'response size', 64);
+    if (requestId !== undefined)
+        metadata.request_id = text(requestId, 'request_id', 512);
+    let total = 0;
+    const images = response.data.map((entry) => {
+        const item = object(entry, 'Image response data');
+        const data = decodeImageBase64(item.b64_json, MAX_IMAGE_BYTES - total);
+        total += data.length;
+        const generation_id = item.generation_id == null ? undefined : text(item.generation_id, 'generation_id', 512);
+        // Unknown fields may contain payloads or private service state; never copy them to history.
+        return { data, mediaType: imageMediaType(data), metadata: generation_id === undefined ? {} : { generation_id },
+            ...(generation_id === undefined ? {} : { generation_id }) };
+    });
+    return { images, metadata };
+}

package/lib/cloud-media.d.ts

@@ -0,0 +1,52 @@
+import type { AttachmentStore, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { ShellExecutor } from '@deepseek-ai/dsh-shell';
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+import { type ImageSelection, type ParsedImageResponse } from './cloud-images.js';
+export interface MediaSourceDependencies {
+    fs: Pick<FileSystem, 'resolve' | 'readBytes' | 'processPath'>;
+    attachments: Pick<AttachmentStore, 'readImage' | 'validateImage'>;
+    /** Only verified references visible in the caller session, in chronological order. */
+    visibleImages: readonly ImageAttachmentRef[];
+    workspace: string;
+    signal?: AbortSignal;
+}
+export interface ResolvedCloudImage {
+    image_url: string;
+    data: Uint8Array;
+    mediaType: ImageMediaType;
+    width: number;
+    height: number;
+    scaled: boolean;
+    attachment?: ImageAttachmentRef;
+    path?: string;
+}
+export declare function resolveImageSources(value: ImageSelection, deps: MediaSourceDependencies): Promise<ResolvedCloudImage[]>;
+export interface MediaOutputDependencies {
+    fs: Pick<FileSystem, 'resolve' | 'processPath' | 'contains'>;
+    shell: Pick<ShellExecutor, 'resolve' | 'run' | 'sandboxMode'>;
+    /** Resolve from the calling session with the public sandboxPolicy service. */
+    policy: SandboxExecutionPolicy;
+    attachments: Pick<AttachmentStore, 'validateImage' | 'saveImage'>;
+    workspace: string;
+    signal?: AbortSignal;
+}
+export declare function saveImageOutputs(response: ParsedImageResponse, deps: MediaOutputDependencies): Promise<{
+    images: {
+        attachment: ImageAttachmentRef;
+        preview: {
+            normalized: boolean;
+            scaled: boolean;
+            mediaType: ImageMediaType;
+            bytes: number;
+            width: number;
+            height: number;
+        };
+        width: number;
+        height: number;
+        generation_id?: string;
+        path: string;
+        mediaType: ImageMediaType;
+        bytes: number;
+    }[];
+}>;

package/lib/cloud-media.js

@@ -0,0 +1,112 @@
+/** Caller-scoped image sources and policy-enforced original artifacts. */
+import { randomUUID } from 'node:crypto';
+import { posix, win32 } from 'node:path';
+import { imageSize } from 'image-size';
+import { MAX_IMAGE_BYTES, imageMediaType, validateImageSelection } from './cloud-images.js';
+// Check both process-world grammars without resolving against the plugin host OS.
+function absoluteWorldPath(path) {
+    return !path.includes('\0') && (posix.isAbsolute(path) || (win32.isAbsolute(path) && /^[A-Za-z]:|^\\\\[^\\]+\\[^\\]+/.test(path)));
+}
+function encodedDimensions(data) {
+    const { width, height } = imageSize(data);
+    if (![width, height].every((n) => Number.isSafeInteger(n) && n > 0))
+        throw new Error('Invalid decoded image dimensions');
+    return { width, height };
+}
+export async function resolveImageSources(value, deps) {
+    const selection = validateImageSelection(value);
+    const refs = new Map(deps.visibleImages.map((ref) => [String(ref.attachmentId), ref]));
+    const recent = selection.num_last_images_to_include;
+    if (recent !== undefined && deps.visibleImages.length < recent)
+        throw new Error('Not enough visible images in this session');
+    const sources = selection.images ?? deps.visibleImages.slice(-recent).map((ref) => ({ attachment_id: String(ref.attachmentId) }));
+    // Resolve every attachment id before performing any storage reads.
+    for (const source of sources)
+        if ('attachment_id' in source && !refs.has(source.attachment_id))
+            throw new Error('Image attachment is not visible in this session: ' + source.attachment_id);
+    const result = [];
+    let total = 0;
+    for (const source of sources) {
+        deps.signal?.throwIfAborted();
+        let data;
+        let attachment;
+        let path;
+        if ('attachment_id' in source) {
+            attachment = refs.get(source.attachment_id);
+            if (!Number.isSafeInteger(attachment.bytes) || attachment.bytes <= 0 || attachment.bytes > MAX_IMAGE_BYTES - total)
+                throw new Error('Image inputs exceed byte limit');
+            const stored = await deps.attachments.readImage(attachment, deps.signal);
+            data = stored.data;
+            if (stored.ref.attachmentId !== attachment.attachmentId || stored.ref.bytes !== attachment.bytes ||
+                stored.ref.mediaType !== attachment.mediaType || stored.ref.width !== attachment.width || stored.ref.height !== attachment.height ||
+                data.length !== attachment.bytes)
+                throw new Error('Stored image does not match visible attachment metadata');
+        }
+        else {
+            if (!absoluteWorldPath(source.path))
+                throw new Error('Image path must be absolute');
+            const target = await deps.fs.resolve(source.path, { cwd: deps.workspace, ...(deps.signal ? { signal: deps.signal } : {}) });
+            data = await deps.fs.readBytes(target, deps.signal, MAX_IMAGE_BYTES - total);
+            path = deps.fs.processPath(target);
+        }
+        total += data.length;
+        if (!data.length || total > MAX_IMAGE_BYTES)
+            throw new Error('Image inputs are empty or exceed byte limit');
+        const mediaType = imageMediaType(data);
+        await deps.attachments.validateImage({ data, mediaType });
+        const dimensions = encodedDimensions(data);
+        if (attachment && (attachment.mediaType !== mediaType || attachment.width !== dimensions.width || attachment.height !== dimensions.height))
+            throw new Error('Stored image bytes do not match attachment dimensions or media type');
+        deps.signal?.throwIfAborted();
+        result.push({ ...dimensions, data, mediaType, image_url: 'data:' + mediaType + ';base64,' + Buffer.from(data).toString('base64'),
+            scaled: !!attachment?.originalDimensions,
+            ...(attachment ? { attachment } : {}),
+            ...(path ? { path } : {}) });
+    }
+    return result;
+}
+const extensions = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' };
+function quote(value) { return "'" + value.replaceAll("'", "'" + '"' + "'" + '"' + "'") + "'"; }
+// Bytes travel on stdin, never in command arguments, stdout, or the model history.
+const WRITE_ORIGINAL = "const fs=require('node:fs');const path=require('node:path');let s='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{const p=process.argv[1];fs.mkdirSync(path.dirname(p),{recursive:true});fs.writeFileSync(p,Buffer.from(s,'base64'),{flag:'wx',mode:0o600});});";
+export async function saveImageOutputs(response, deps) {
+    if (!absoluteWorldPath(deps.workspace))
+        throw new Error('Caller workspace must be absolute');
+    if (!deps.policy || !deps.shell.sandboxMode)
+        throw new Error('Original image writes require a policy-enforcing DSH shell');
+    let total = 0;
+    const dimensions = [];
+    for (const image of response.images) {
+        deps.signal?.throwIfAborted();
+        total += image.data.length;
+        if (!image.data.length || total > MAX_IMAGE_BYTES)
+            throw new Error('Image outputs exceed byte limit');
+        if (imageMediaType(image.data) !== image.mediaType)
+            throw new Error('Output media type does not match bytes');
+        await deps.attachments.validateImage({ data: image.data, mediaType: image.mediaType });
+        dimensions.push(encodedDimensions(image.data));
+    }
+    const workspace = await deps.fs.resolve(deps.workspace, { ...(deps.signal ? { signal: deps.signal } : {}) });
+    const images = [];
+    for (const image of response.images) {
+        deps.signal?.throwIfAborted();
+        const name = randomUUID() + '.' + extensions[image.mediaType];
+        const target = await deps.fs.resolve('.dsh/codex-images/' + name, { cwd: deps.workspace, ...(deps.signal ? { signal: deps.signal } : {}) });
+        if (!deps.fs.contains(workspace, target))
+            throw new Error('Original image target escapes caller workspace');
+        const path = deps.fs.processPath(target);
+        const outcome = await deps.shell.run(deps.shell.resolve({
+            command: 'node -e ' + quote(WRITE_ORIGINAL) + ' -- ' + quote(path),
+            stdin: Buffer.from(image.data).toString('base64'), workdir: deps.fs.processPath(workspace),
+            sandboxPolicy: deps.policy, signal: deps.signal, timeoutMs: 30_000, stdoutMaxBytes: 1024,
+        }));
+        if (outcome.sandbox?.denied || outcome.sandbox?.runnerFailed || outcome.exitCode !== 0 || outcome.aborted || outcome.timedOut)
+            throw new Error('Original image write failed under caller filesystem policy');
+        const attachment = await deps.attachments.saveImage({ data: image.data, mediaType: image.mediaType, name });
+        images.push({ ...image.metadata, path, mediaType: image.mediaType, bytes: image.data.length,
+            ...(image.generation_id ? { generation_id: image.generation_id } : {}),
+            ...dimensions[images.length],
+            attachment, preview: { normalized: true, scaled: !!attachment.originalDimensions, mediaType: attachment.mediaType, bytes: attachment.bytes, width: attachment.width, height: attachment.height } });
+    }
+    return { ...response.metadata, images };
+}

package/lib/cloud-search.d.ts

@@ -0,0 +1,31 @@
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface CloudSearchArgs {
+    commands: Record<string, Json>;
+    model?: string;
+    context?: string;
+    mode?: 'cached' | 'indexed' | 'live';
+    search_context_size?: 'low' | 'medium' | 'high';
+    user_location?: Record<string, string>;
+    filters?: Record<string, string[]>;
+    image_settings?: {
+        max_results?: number;
+        caption?: boolean;
+    };
+}
+export declare function parseCloudSearchArgs(value: unknown): CloudSearchArgs;
+/** The caller selects the model and visible context using the same request credential. */
+export declare function buildCloudSearchRequest(args: CloudSearchArgs, context: {
+    sessionId: string;
+    accountId: string;
+    model: string;
+    input?: unknown;
+}): Record<string, unknown>;
+/** Keep whole opaque result entries and identify any omitted data explicitly. */
+export declare function parseCloudSearchResponse(body: unknown): {
+    output: string;
+    results?: unknown[];
+    truncated: boolean;
+};
+export {};

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;