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

package/lib/cloud-http.js

@@ -0,0 +1,170 @@
+/** Bounded, nonstreaming Codex cloud requests. Never retry ambiguous POST failures. */
+import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm';
+import { nativeCodexEndpoint } from './endpoint.js';
+const fail = (message, code = 'CODEX_CLOUD_FAILED') => new LlmError(message, code);
+function positive(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 2_147_483_647)
+        throw fail('Invalid cloud request limit', 'INVALID_ARGS');
+    return value;
+}
+function credentialCopy(value) {
+    if (!value || typeof value.accessToken !== 'string' || !value.accessToken.trim()
+        || typeof value.accountId !== 'string' || !value.accountId.trim())
+        throw fail('Codex cloud credential unavailable', 'AUTH_REQUIRED');
+    return { accessToken: value.accessToken, accountId: value.accountId };
+}
+/** Race even injected transports/resolvers that do not implement AbortSignal. */
+function cancellable(operation, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(fail('Codex cloud request cancelled or timed out', 'ABORTED'));
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+export class NativeCodexCloudClient {
+    options;
+    endpoint;
+    constructor(options) {
+        this.options = options;
+        try {
+            this.endpoint = nativeCodexEndpoint(options.endpoint ?? 'https://chatgpt.com/backend-api/codex');
+            if (this.endpoint.search)
+                throw new Error();
+        }
+        catch {
+            throw fail('Invalid Codex cloud endpoint', 'INVALID_ARGS');
+        }
+    }
+    async resolveCredential(signal) {
+        if (signal?.aborted)
+            throw fail('Codex cloud request cancelled', 'ABORTED');
+        try {
+            const pending = this.options.resolveCredential(signal);
+            return credentialCopy(await (signal ? cancellable(pending, signal) : pending));
+        }
+        catch {
+            throw fail(signal?.aborted ? 'Codex cloud request cancelled' : 'Codex cloud credential unavailable', signal?.aborted ? 'ABORTED' : 'AUTH_REQUIRED');
+        }
+    }
+    async post(path, body, options) {
+        if (!['alpha/search', 'images/generations', 'images/edits'].includes(path))
+            throw fail('Invalid Codex cloud path', 'INVALID_ARGS');
+        const timeoutMs = positive(options.timeoutMs ?? this.options.requestTimeoutMs, 120_000);
+        const maxBytes = positive(options.maxResponseBytes ?? this.options.maxResponseBytes, 48 * 1024 * 1024);
+        const requestLimit = positive(this.options.maxRequestBodyBytes, 48 * 1024 * 1024);
+        let encoded;
+        try {
+            encoded = JSON.stringify(body);
+        }
+        catch {
+            throw fail('Invalid cloud JSON request', 'INVALID_ARGS');
+        }
+        if (typeof encoded !== 'string' || Buffer.byteLength(encoded) > requestLimit)
+            throw fail('Cloud request exceeds byte limit', 'INVALID_ARGS');
+        let credential = credentialCopy(options.credential);
+        const accountId = credential.accountId;
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        options.signal.addEventListener('abort', abort, { once: true });
+        if (options.signal.aborted)
+            abort();
+        const timer = setTimeout(abort, timeoutMs);
+        const signal = controller.signal;
+        const url = new URL(this.endpoint);
+        url.pathname = (url.pathname.endsWith('/') ? url.pathname.slice(0, -1) : url.pathname) + '/' + path;
+        try {
+            for (let attempt = 0; attempt < 2; attempt++) {
+                if (signal.aborted)
+                    throw fail('Codex cloud request cancelled or timed out', 'ABORTED');
+                let response;
+                try {
+                    const headers = new Headers({ ...attributionHeaders(), ...options.headers });
+                    headers.set('authorization', 'Bearer ' + credential.accessToken);
+                    headers.set('chatgpt-account-id', credential.accountId);
+                    headers.set('originator', 'dsh');
+                    headers.set('content-type', 'application/json');
+                    headers.set('accept', 'application/json');
+                    response = await cancellable((this.options.fetch ?? fetch)(url.toString(), {
+                        method: 'POST', redirect: 'error', headers, body: encoded, signal,
+                    }), signal);
+                }
+                catch {
+                    throw fail(signal.aborted ? 'Codex cloud request cancelled or timed out' : 'Codex cloud request failed; it was not retried', signal.aborted ? 'ABORTED' : 'CODEX_CLOUD_FAILED');
+                }
+                if (!response.ok) {
+                    void response.body?.cancel().catch(() => { });
+                    if (response.status === 401 && attempt === 0 && this.options.recoverCredential) {
+                        let recovered;
+                        try {
+                            recovered = await cancellable(this.options.recoverCredential(credentialCopy(credential), signal), signal);
+                        }
+                        catch {
+                            throw fail(signal.aborted ? 'Codex cloud request cancelled or timed out' : 'Codex cloud credential recovery failed', signal.aborted ? 'ABORTED' : 'AUTH_REQUIRED');
+                        }
+                        if (recovered) {
+                            credential = await this.resolveCredential(signal);
+                            if (credential.accountId !== accountId)
+                                throw fail('Codex account changed during request; start a new call with the active account', 'CODEX_ACCOUNT_CHANGED');
+                            continue;
+                        }
+                    }
+                    throw fail('Codex cloud service returned HTTP ' + response.status, response.status === 401 ? 'AUTH_REQUIRED' : 'CODEX_CLOUD_HTTP_ERROR');
+                }
+                const reader = response.body?.getReader();
+                if (!reader)
+                    throw fail('Codex cloud response is empty');
+                const chunks = [];
+                let size = 0;
+                try {
+                    const declared = response.headers.get('content-length');
+                    if (declared !== null && Number(declared) > maxBytes)
+                        throw fail('Codex cloud response exceeds byte limit');
+                    while (true) {
+                        let part;
+                        try {
+                            part = await cancellable(reader.read(), signal);
+                        }
+                        catch {
+                            throw fail(signal.aborted ? 'Codex cloud request cancelled or timed out' : 'Codex cloud response interrupted; it was not retried', signal.aborted ? 'ABORTED' : 'CODEX_CLOUD_FAILED');
+                        }
+                        if (part.done)
+                            break;
+                        size += part.value.byteLength;
+                        if (size > maxBytes)
+                            throw fail('Codex cloud response exceeds byte limit');
+                        chunks.push(part.value);
+                    }
+                }
+                catch (error) {
+                    void reader.cancel().catch(() => { });
+                    if (error instanceof LlmError)
+                        throw error;
+                    throw fail('Codex cloud response interrupted; it was not retried');
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+                }
+                catch {
+                    throw fail('Codex cloud service returned invalid JSON');
+                }
+                const requestId = path.startsWith('images/')
+                    ? response.headers.get('x-codex-imagegen-request-id') ?? response.headers.get('x-request-id')
+                    : response.headers.get('x-request-id');
+                return { body: parsed, ...(requestId && /^[a-zA-Z0-9_.:-]{1,256}$/.test(requestId) && !requestId.includes(credential.accessToken) ? { requestId } : {}) };
+            }
+            throw fail('Codex cloud authentication failed', 'AUTH_REQUIRED');
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal.removeEventListener('abort', abort);
+        }
+    }
+}

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 {};