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

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;

package/lib/cloud-web-tool.js

@@ -0,0 +1,241 @@
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { nativeCodexAuthorityHash } from './catalog.js';
+import { buildCloudSearchRequest, parseCloudSearchArgs, parseCloudSearchResponse } from './cloud-search.js';
+import { chooseCloudModel, recentSearchInput } from './cloud-context.js';
+const str = { type: 'string' };
+const uint = { type: 'integer', description: 'Nonnegative safe integer.' };
+const bool = { type: 'boolean' };
+const enumeration = (...values) => ({ type: 'string', enum: values });
+const array = (items) => ({ type: 'array', items });
+const object = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const query = object({ q: str, recency: uint, domains: array(str) }, ['q']);
+const operations = {
+    search_query: array(query), image_query: array(query),
+    open: array(object({ ref_id: str, lineno: uint }, ['ref_id'])),
+    click: array(object({ ref_id: str, id: uint }, ['ref_id', 'id'])),
+    find: array(object({ ref_id: str, pattern: str }, ['ref_id', 'pattern'])),
+    screenshot: array(object({ ref_id: str, pageno: uint }, ['ref_id', 'pageno'])),
+    finance: array(object({ ticker: str, type: enumeration('equity', 'fund', 'crypto', 'index'), market: str }, ['ticker', 'type'])),
+    weather: array(object({ location: str, start: { ...str, description: 'YYYY-MM-DD' }, duration: uint }, ['location'])),
+    sports: array(object({ tool: enumeration('sports'), fn: enumeration('schedule', 'standings'), league: enumeration('nba', 'wnba', 'nfl', 'nhl', 'mlb', 'epl', 'ncaamb', 'ncaawb', 'ipl'), team: str, opponent: str, date_from: str, date_to: str, num_games: uint, locale: str }, ['fn', 'league'])),
+    time: array(object({ utc_offset: { ...str, description: 'UTC offset such as +08:00.' } }, ['utc_offset'])),
+    response_length: enumeration('short', 'medium', 'long'),
+};
+const parameters = object({
+    commands: { ...object(operations), description: 'One or more nonempty command arrays; at most 100 operations total. Dependent actions require separate calls. screenshot only supports zero-indexed PDF pages.' },
+    model: { ...str, description: 'Explicit Codex catalog model; otherwise cloudTools.searchModel, then current openai-codex model. No guessed fallback.' },
+    context: { ...str, description: 'Optional explicit text. Default includes last two visible human texts and at most 1000 UTF-8 bytes of visible assistant text.' },
+    mode: enumeration('cached', 'indexed', 'live'), search_context_size: enumeration('low', 'medium', 'high'),
+    user_location: object({ country: str, region: str, city: str, timezone: str }),
+    filters: object({ allowed_domains: array(str), blocked_domains: array(str) }),
+    image_settings: object({ max_results: uint, caption: bool }),
+}, ['commands']);
+const imageSchema = object({ attachmentId: str, mediaType: enumeration('image/png', 'image/jpeg', 'image/webp', 'image/gif'), bytes: uint, width: uint, height: uint, name: str, originalDimensions: object({ width: uint, height: uint }, ['width', 'height']) }, ['attachmentId', 'mediaType', 'bytes', 'width', 'height']);
+function record(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function publicUrl(value) {
+    try {
+        const url = new URL(value);
+        return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** Source: pinned protocol/src/models.rs ContentItem / FunctionCallOutputContentItem.
+ * Search DTOs themselves remain opaque. Only exact known content tags are projected;
+ * arbitrary image_url properties and future screenshot DTOs are never guessed. */
+function inputImage(value) {
+    return record(value) && value.type === 'input_image' && typeof value.image_url === 'string'
+        && (value.detail == null || ['auto', 'low', 'high', 'original'].includes(value.detail));
+}
+async function admitSearchImages(body, attachments, signal) {
+    const images = [];
+    const notes = new Set();
+    let seen = 0;
+    let bytes = 0;
+    const visit = async (item, depth) => {
+        signal.throwIfAborted();
+        if (depth > 8)
+            return item;
+        if (inputImage(item)) {
+            if (publicUrl(item.image_url)) {
+                notes.add('Remote image unavailable: the public DSH web boundary has no binary image retrieval. Image and source links are preserved.');
+                return item;
+            }
+            const match = /^data:(image\/(?:png|jpeg|webp|gif));base64,([A-Za-z0-9+/]*={0,2})$/.exec(item.image_url);
+            if (!match)
+                return item;
+            let ref;
+            try {
+                if (!attachments)
+                    throw new Error('Attachment service unavailable');
+                if (++seen > 4 || match[2].length > 12 * 1024 * 1024)
+                    throw new Error('Image count or byte limit');
+                const data = Buffer.from(match[2], 'base64');
+                bytes += data.length;
+                if (!data.length || bytes > 8 * 1024 * 1024 || data.toString('base64') !== match[2])
+                    throw new Error('Invalid or oversized inline image');
+                signal.throwIfAborted();
+                ref = await attachments.saveImage({ data, mediaType: match[1] });
+                signal.throwIfAborted();
+                images.push(ref);
+            }
+            catch {
+                signal.throwIfAborted();
+                notes.add('Inline image unavailable: attachment service missing, image invalid, or image/storage limit reached. Text and source links are preserved.');
+            }
+            // Binary transfer data must not become historical text; unknown fields remain opaque.
+            return { ...item, image_url: ref ? '[DSH attachment ' + ref.attachmentId + ']' : '[inline image unavailable]' };
+        }
+        // Bounded structural walk permits known content blocks nested in evolving result DTOs.
+        if (Array.isArray(item)) {
+            if (item.length > 100)
+                return item; // Unknown large arrays stay opaque for bounded parsing.
+            const result = [];
+            for (const value of item)
+                result.push(await visit(value, depth + 1));
+            return result;
+        }
+        if (record(item) && Array.isArray(item.content) && item.content.length <= 100) {
+            return { ...item, content: await visit(item.content, depth + 1) };
+        }
+        return item;
+    };
+    if (!record(body) || !Array.isArray(body.results))
+        return { body, images, notes };
+    // Leave excess entries for the response parser to mark explicitly as truncated.
+    const results = [];
+    for (let i = 0; i < body.results.length; i++)
+        results.push(i < 100 ? await visit(body.results[i], 0) : body.results[i]);
+    return { body: { ...body, results }, images, notes };
+}
+const markerPrefix = '[codex_web context: ';
+function containsReference(text, ref) {
+    let start = 0;
+    for (;;) {
+        const index = text.indexOf(ref, start);
+        if (index < 0)
+            return false;
+        const before = text[index - 1] ?? '';
+        const after = text[index + ref.length] ?? '';
+        if (!/[A-Za-z0-9_-]/.test(before) && !/[A-Za-z0-9_-]/.test(after))
+            return true;
+        start = index + ref.length;
+    }
+}
+function checkReferences(args, messages, id, recent) {
+    const refs = Object.values(args.commands).flatMap(value => Array.isArray(value) ? value.flatMap(row => record(row) && typeof row.ref_id === 'string' && !publicUrl(row.ref_id) ? [row.ref_id] : []) : []);
+    if (!refs.length)
+        return;
+    const calls = new Map();
+    const outputs = [];
+    for (const message of messages) {
+        if (message.role === 'assistant')
+            for (const block of message.content)
+                if (block.type === 'tool-call')
+                    calls.set(block.id, block.name);
+        if (message.source.kind !== 'tool' || !['codex_web', 'run_code'].includes(calls.get(message.source.callId) ?? ''))
+            continue;
+        for (const block of message.content)
+            if (block.type === 'tool-result' && block.toolCallId === message.source.callId && !block.isError) {
+                outputs.push(block.content.filter(part => part.type === 'text').map(part => part.text).join('\n'));
+            }
+    }
+    outputs.push(...recent);
+    for (const ref of refs) {
+        const previous = outputs.findLast(text => containsReference(text.slice(0, text.lastIndexOf(markerPrefix)), ref) && text.includes(markerPrefix));
+        // Marker is emitted last, overriding any marker-looking upstream prose. It is an
+        // account/session digest, not a credential or an upstream encrypted continuation.
+        if (!previous || previous.slice(previous.lastIndexOf(markerPrefix), previous.lastIndexOf(markerPrefix) + markerPrefix.length + 64) !== markerPrefix + id) {
+            throw new LlmError('Search reference has no visible result in this account/session context. Search again or open its source URL; references can expire or belong to another account.', 'CODEX_SEARCH_REFERENCE_STALE');
+        }
+    }
+}
+function sourceLinks(results) {
+    const links = new Set();
+    const walk = (value, depth) => {
+        if (depth > 8 || links.size >= 100)
+            return;
+        if (typeof value === 'string' && value.length <= 4096 && publicUrl(value))
+            links.add(value);
+        else if (Array.isArray(value))
+            value.slice(0, 100).forEach(item => walk(item, depth + 1));
+        else if (record(value))
+            Object.values(value).slice(0, 100).forEach(item => walk(item, depth + 1));
+    };
+    walk(results, 0);
+    return [...links];
+}
+export function registerCodexWeb(ctx, deps) {
+    if (!ctx.tools)
+        return;
+    // Same-program Code Mode subcalls precede durable parent output. Keep a bounded
+    // session-object cache of already returned visible text, partitioned by context id.
+    const recentOutputs = new WeakMap();
+    const definition = {
+        name: 'codex_web',
+        description: 'Search the web/images, open/click/find results, screenshot PDF pages, and query finance/weather/sports/time through Codex. Preserve returned source URLs and ref IDs for follow-up calls. Non-Codex sessions require explicit model or cloudTools.searchModel. Search references are scoped to the current account/session; expired references require a fresh search.',
+        parameters: { ...parameters },
+        output: {
+            schema: object({ output: str, results: array({}), images: array(imageSchema), model: str, truncated: bool, image_output: bool }, ['output', 'model', 'truncated', 'image_output']),
+            render: (_args, value) => {
+                const result = value;
+                const content = [{ type: 'text', text: result.output }];
+                if (result.image_output)
+                    for (const attachment of result.images ?? [])
+                        content.push({ type: 'image', attachment });
+                return content;
+            },
+        },
+        async execute(value, exec) {
+            const args = parseCloudSearchArgs(value);
+            exec.signal.throwIfAborted();
+            const agent = exec.agent;
+            if (!agent?.session || !agent.ctx)
+                throw new LlmError('codex_web requires a calling DSH agent session', 'CONTEXT_REQUIRED');
+            const messages = agent.session.deriveMessages();
+            const credential = await deps.client.resolveCredential(exec.signal);
+            const view = await deps.catalog.listWithAuthority?.(exec.signal);
+            exec.signal.throwIfAborted();
+            if (!view || view.authorityHash !== nativeCodexAuthorityHash(credential.accountId))
+                throw new LlmError('Codex model catalog authority changed; retry with the current account', 'CODEX_ACCOUNT_CHANGED');
+            const model = chooseCloudModel({ requested: args.model, configured: deps.config.searchModel, currentProvider: agent.options.provider, currentModel: agent.options.model, purpose: 'search' }, view.models);
+            const input = recentSearchInput(messages).map(item => ({ type: 'message', role: item.role, content: [{ type: item.role === 'user' ? 'input_text' : 'output_text', text: item.content }] }));
+            const body = buildCloudSearchRequest({ ...args, mode: args.mode ?? deps.config.searchMode ?? 'live' }, { sessionId: agent.session.id, accountId: credential.accountId, model: model.slug, input });
+            const id = body.id;
+            const cached = recentOutputs.get(agent.session);
+            const recent = cached?.id === id ? cached.texts : [];
+            checkReferences(args, messages, id, recent);
+            const response = await deps.client.post('alpha/search', body, { credential, signal: exec.signal });
+            // Validate the envelope before any attachment write; image bytes are replaced
+            // before the final bounded result projection so large valid images can attach.
+            if (!record(response.body) || typeof response.body.output !== 'string' || (response.body.results != null && !Array.isArray(response.body.results)))
+                throw new LlmError('Invalid Codex search response', 'CODEX_CLOUD_FAILED');
+            const media = await admitSearchImages(response.body, agent.ctx.attachments, exec.signal);
+            const parsed = parseCloudSearchResponse(media.body);
+            let image_output = false;
+            const { provider: callerProvider, model: callerModel } = agent.options;
+            if (media.images.length && callerProvider && callerModel && agent.ctx.llm) {
+                try {
+                    image_output = (await agent.ctx.llm.resolveModelInfo(callerProvider, callerModel, exec.signal)).inputModalities?.includes('image') ?? false;
+                }
+                catch {
+                    exec.signal.throwIfAborted();
+                }
+            }
+            exec.signal.throwIfAborted();
+            let output = parsed.output;
+            if (parsed.results?.length)
+                output += '\nStructured search results:\n' + JSON.stringify(parsed.results);
+            const links = sourceLinks(parsed.results ?? []);
+            if (links.length)
+                output += '\nSources and result links:\n' + links.map(url => '<' + url.replace(/[<>\s]/g, c => encodeURIComponent(c)) + '>').join('\n');
+            if (media.notes.size)
+                output += '\n' + [...media.notes].join('\n');
+            output += '\n' + markerPrefix + id + ']';
+            recentOutputs.set(agent.session, { id, texts: [...recent.slice(-7), output] });
+            return { ...parsed, output, model: model.slug, image_output, ...(media.images.length ? { images: media.images } : {}) };
+        },
+    };
+    ctx.tools.register(definition);
+}

package/lib/index.d.ts

@@ -5,6 +5,7 @@ import { type IncomingMessage } from 'node:http';
 import type { WebServer } from '@deepseek-ai/dsh-host-webserver';
 import { CODEX_PROVIDER } from './native-adapter.js';
 export { CODEX_PROVIDER, NATIVE_CODEX_PROVIDER } from './native-adapter.js';
+import { type CloudToolsConfig } from './cloud-tools.js';
 export { normalizeUsage } from './usage.js';
 export { CODEX_CLIENT_VERSION, TRACKED_CODEX_COMMIT, TRACKED_CODEX_RELEASE, TRACKED_CODEX_REPOSITORY, } from './upstream.js';
 /** Persisted OAuth credential for one ChatGPT account. */
@@ -27,6 +28,8 @@ interface ParsedCredentialDocument {
 }
 /** Plugin configuration. */
 export interface Config {
+    /** Optional ordinary tools backed by the current Codex cloud account. */
+    cloudTools?: CloudToolsConfig;
     path?: string;
     dshHome?: string;
     nativeAdapter?: boolean;

package/lib/index.js

@@ -14,6 +14,9 @@ export { CODEX_PROVIDER, NATIVE_CODEX_PROVIDER } from './native-adapter.js';
 import { NativeCodexCatalog } from './catalog.js';
 import { NativeCodexHttpTransport } from './native-http.js';
 import { NativeCodexWebSocketTransport } from './native-websocket.js';
+import { NativeCodexCloudClient } from './cloud-http.js';
+import { registerCodexImageTools } from './cloud-tools.js';
+import { registerCodexWeb } from './cloud-web-tool.js';
 import { mergeDirectUsage, normalizeUsage } from './usage.js';
 export { normalizeUsage } from './usage.js';
 export { CODEX_CLIENT_VERSION, TRACKED_CODEX_COMMIT, TRACKED_CODEX_RELEASE, TRACKED_CODEX_REPOSITORY, } from './upstream.js';
@@ -698,6 +701,17 @@ export class OpenAICodexAuth extends Service {
         nativeAdapter: z.boolean().default(true),
         nativeCompatibilityRoute: z.boolean().default(false),
         nativeWebSocket: z.boolean().default(true),
+        cloudTools: z.object({
+            enabled: z.boolean().default(true),
+            search: z.boolean().default(true),
+            imageGeneration: z.boolean().default(true),
+            imageEditing: z.boolean().default(true),
+            imageInspection: z.boolean().default(true),
+            searchModel: z.string(), visionModel: z.string(),
+            imageModel: z.string().default('gpt-image-2'),
+            searchMode: z.union([z.const('cached'), z.const('indexed'), z.const('live')]).default('live'),
+            visionDetail: z.union([z.const('auto'), z.const('low'), z.const('high'), z.const('original')]).default('auto'),
+        }),
     });
     static inject = ['credentials', 'webServer', 'webRuntime'];
     filename;
@@ -728,29 +742,29 @@ export class OpenAICodexAuth extends Service {
             nativeCompatibilityRoute: config.nativeCompatibilityRoute ?? false,
             nativeWebSocket: config.nativeWebSocket ?? true,
         };
+        const catalog = new NativeCodexCatalog({
+            resolveCredential: signal => this.resolveNativeCredential(signal),
+            warn: message => { ctx.logger.warn(message); },
+        });
+        const transportOptions = {
+            resolveCredential: signal => this.resolveNativeCredential(signal),
+            recoverCredential: (previous, signal) => this.recoverNativeCredential(previous, signal),
+            readImage: async (attachment, signal) => {
+                const store = ctx.get('attachments');
+                if (store === undefined) {
+                    throw new LlmError('native Codex image input requires the attachment service', 'UNSUPPORTED');
+                }
+                return store.readImage(attachment, signal);
+            },
+            onRateLimits: observation => {
+                this.acceptRateLimits(observation.accountId, observation.updates);
+            },
+            onResponseUsage: observation => {
+                this.acceptResponseUsage(observation);
+            },
+            warn: message => { ctx.logger.warn(message); },
+        };
         if (this.routeConfig.nativeAdapter) {
-            const catalog = new NativeCodexCatalog({
-                resolveCredential: signal => this.resolveNativeCredential(signal),
-                warn: message => { ctx.logger.warn(message); },
-            });
-            const transportOptions = {
-                resolveCredential: signal => this.resolveNativeCredential(signal),
-                recoverCredential: (previous, signal) => this.recoverNativeCredential(previous, signal),
-                readImage: async (attachment, signal) => {
-                    const store = ctx.get('attachments');
-                    if (store === undefined) {
-                        throw new LlmError('native Codex image input requires the attachment service', 'UNSUPPORTED');
-                    }
-                    return store.readImage(attachment, signal);
-                },
-                onRateLimits: observation => {
-                    this.acceptRateLimits(observation.accountId, observation.updates);
-                },
-                onResponseUsage: observation => {
-                    this.acceptResponseUsage(observation);
-                },
-                warn: message => { ctx.logger.warn(message); },
-            };
             const transport = this.routeConfig.nativeWebSocket
                 ? new NativeCodexWebSocketTransport(transportOptions)
                 : new NativeCodexHttpTransport(transportOptions);
@@ -764,6 +778,15 @@ export class OpenAICodexAuth extends Service {
                 ], new NativeCodexAdapter(catalog, transport));
             });
         }
+        if (config.cloudTools?.enabled !== false) {
+            const cloudClient = new NativeCodexCloudClient(transportOptions);
+            ctx.inject(['tools'], toolCtx => {
+                const cloudConfig = config.cloudTools ?? {};
+                if (cloudConfig.search !== false)
+                    registerCodexWeb(toolCtx, { client: cloudClient, catalog, config: cloudConfig });
+                registerCodexImageTools(toolCtx, { client: cloudClient, catalog, transport: transportOptions, config: cloudConfig });
+            });
+        }
         ctx.effect(async () => {
             try {
                 await this.bearerToken();

package/lib/native-http.d.ts

@@ -9,6 +9,8 @@ type ImageBlock = Extract<ContentBlock, {
 }>;
 export interface NativeCodexImageRead {
     data: Uint8Array;
+    /** Internal per-image control used by the explicit vision tool. */
+    detail?: import('./responses.js').CodexImageDetail;
 }
 export interface NativeCodexHttpOptions {
     resolveCredential(signal?: AbortSignal): Promise<NativeCodexCredential>;