@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/media.js

@@ -1,542 +1,43 @@
-import { createWriteStream } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-import { mkdir, open, rename, stat, unlink } from 'node:fs/promises';
-import { basename, dirname, extname, join } from 'node:path';
-import { Readable, Transform } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { CANON_DIR, renderCanonHostInboundContent, sanitizeDownloadFileName, } from '@canonmsg/core';
-import { BoundedFileReadError, readBoundedRegularFileHandle, } from './bounded-file-read.js';
-const ANTHROPIC_IMAGE_MIME_TYPES = new Set([
-    'image/jpeg',
-    'image/png',
-    'image/gif',
-    'image/webp',
-]);
-export const DEFAULT_MEDIA_CACHE_DIR = join(CANON_DIR, 'media-cache');
-export const DEFAULT_MEDIA_MATERIALIZATION_BYTES = 10 * 1024 * 1024;
-export const MAX_CANON_MEDIA_BYTES = 100 * 1024 * 1024;
-/**
- * Seven MiB expands to just under 10 MB when base64-encoded. This is suitable
- * for the direct Anthropic transport used by the Claude Code host. Providers
- * with smaller encoded-image limits must pass a lower maxImageRawBytes value.
- */
-export const MAX_ANTHROPIC_IMAGE_RAW_BYTES = 7 * 1024 * 1024;
-export const MAX_ANTHROPIC_REQUEST_BYTES = 32_000_000;
-export const DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES = 4 * 1024 * 1024;
-const EXTENSION_BY_MIME = {
-    'application/json': 'json',
-    'application/pdf': 'pdf',
-    'application/zip': 'zip',
-    'audio/mp4': 'm4a',
-    'audio/mpeg': 'mp3',
-    'audio/ogg': 'ogg',
-    'audio/webm': 'webm',
-    'audio/wav': 'wav',
-    'video/mp4': 'mp4',
-    'video/quicktime': 'mov',
-    'video/webm': 'webm',
-    'video/x-m4v': 'm4v',
-    'image/gif': 'gif',
-    'image/jpeg': 'jpg',
-    'image/png': 'png',
-    'image/webp': 'webp',
-    'text/plain': 'txt',
+import {
+  DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
+  DEFAULT_MEDIA_CACHE_DIR,
+  DEFAULT_MEDIA_MATERIALIZATION_BYTES,
+  MAX_ANTHROPIC_IMAGE_RAW_BYTES,
+  MAX_ANTHROPIC_REQUEST_BYTES,
+  MAX_CANON_MEDIA_BYTES,
+  conversationMediaCacheDir,
+  getCodexImagePath,
+  getMessageAttachments,
+  inferUploadMimeType,
+  isAnthropicImageAttachment,
+  materializeAttachment,
+  materializeMessageMedia,
+  materializeReplyContextMedia,
+  resolveAttachmentMimeType,
+  sendMediaFileMessage,
+  toAnthropicImageBlock,
+  toAnthropicImageBlocksWithinBudget,
+  uploadMediaFile
+} from "./chunks/chunk-OLJ7H4E2.js";
+import "./chunks/chunk-FPQFTTND.js";
+export {
+  DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
+  DEFAULT_MEDIA_CACHE_DIR,
+  DEFAULT_MEDIA_MATERIALIZATION_BYTES,
+  MAX_ANTHROPIC_IMAGE_RAW_BYTES,
+  MAX_ANTHROPIC_REQUEST_BYTES,
+  MAX_CANON_MEDIA_BYTES,
+  conversationMediaCacheDir,
+  getCodexImagePath,
+  getMessageAttachments,
+  inferUploadMimeType,
+  isAnthropicImageAttachment,
+  materializeAttachment,
+  materializeMessageMedia,
+  materializeReplyContextMedia,
+  resolveAttachmentMimeType,
+  sendMediaFileMessage,
+  toAnthropicImageBlock,
+  toAnthropicImageBlocksWithinBudget,
+  uploadMediaFile
 };
-const MIME_BY_EXTENSION = {
-    '.gif': 'image/gif',
-    '.jpeg': 'image/jpeg',
-    '.jpg': 'image/jpeg',
-    '.json': 'application/json',
-    '.m4a': 'audio/mp4',
-    '.mp3': 'audio/mpeg',
-    '.ogg': 'audio/ogg',
-    '.pdf': 'application/pdf',
-    '.png': 'image/png',
-    '.txt': 'text/plain',
-    '.wav': 'audio/wav',
-    '.webm': 'audio/webm',
-    '.m4v': 'video/x-m4v',
-    '.mov': 'video/quicktime',
-    '.mp4': 'video/mp4',
-    '.webp': 'image/webp',
-    '.zip': 'application/zip',
-};
-function sanitizeSegment(value, fallback) {
-    const sanitized = value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
-    return sanitized || fallback;
-}
-function inferExtension(input) {
-    const explicitExtension = extname(input.attachment.fileName ?? '').toLowerCase();
-    if (explicitExtension) {
-        return explicitExtension.replace(/[^a-z0-9.]/g, '') || '.bin';
-    }
-    const mimeType = input.responseMimeType ?? input.attachment.mimeType ?? '';
-    const byMime = EXTENSION_BY_MIME[mimeType.toLowerCase()];
-    if (byMime) {
-        return `.${byMime}`;
-    }
-    const urlPath = input.attachment.url.split('?')[0] ?? '';
-    const urlExtension = extname(urlPath).toLowerCase();
-    if (urlExtension) {
-        return urlExtension.replace(/[^a-z0-9.]/g, '') || '.bin';
-    }
-    return '.bin';
-}
-/**
- * The directory every materialized attachment of one conversation lands in
- * (`<root>/<agent>/<conversation>/<message>/…`). A host that runs one native
- * session per conversation can grant its runtime read access to exactly this
- * directory instead of approving each downloaded file.
- */
-export function conversationMediaCacheDir(input) {
-    return join(input.rootDir ?? DEFAULT_MEDIA_CACHE_DIR, sanitizeSegment(input.agentId, 'agent'), sanitizeSegment(input.conversationId, 'conversation'));
-}
-function buildCachePath(input) {
-    const rootDir = input.rootDir ?? DEFAULT_MEDIA_CACHE_DIR;
-    const extension = inferExtension({
-        attachment: input.attachment,
-        responseMimeType: input.responseMimeType,
-    });
-    const fallbackName = `${input.attachment.kind}-${input.index}${extension}`;
-    const preferredName = input.attachment.fileName
-        ? sanitizeDownloadFileName(input.attachment.fileName, fallbackName)
-        : fallbackName;
-    const fileName = extname(preferredName) ? preferredName : `${preferredName}${extension}`;
-    return join(conversationMediaCacheDir({ agentId: input.agentId, conversationId: input.conversationId, rootDir }), sanitizeSegment(input.messageId, 'message'), `${String(input.index).padStart(2, '0')}-${fileName}`);
-}
-function ensureFetch(fetchImpl) {
-    if (fetchImpl)
-        return fetchImpl;
-    if (typeof fetch === 'function')
-        return fetch;
-    throw new Error('Global fetch is unavailable; provide fetchImpl explicitly.');
-}
-async function fileExists(path) {
-    try {
-        const info = await stat(path);
-        return info.isFile();
-    }
-    catch {
-        return false;
-    }
-}
-function resolveMaxBytes(value) {
-    if (value === undefined)
-        return DEFAULT_MEDIA_MATERIALIZATION_BYTES;
-    if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_CANON_MEDIA_BYTES) {
-        throw new Error(`maxBytes must be an integer between 1 and ${MAX_CANON_MEDIA_BYTES}`);
-    }
-    return value;
-}
-function reportMaterializationError(options, error, attachment, index) {
-    try {
-        options.onError?.(error, attachment, index);
-    }
-    catch {
-        // Diagnostics must never turn a recoverable sibling failure into a failed
-        // message materialization.
-    }
-}
-async function materializeAvailableAttachments(inputs, options) {
-    const settled = await Promise.allSettled(inputs.map((input) => input.run()));
-    options.signal?.throwIfAborted();
-    const materialized = [];
-    let firstError;
-    let hasFailure = false;
-    settled.forEach((result, resultIndex) => {
-        if (result.status === 'fulfilled') {
-            materialized.push(result.value);
-            return;
-        }
-        const input = inputs[resultIndex];
-        if (!hasFailure) {
-            firstError = result.reason;
-            hasFailure = true;
-        }
-        reportMaterializationError(options, result.reason, input.attachment, input.index);
-    });
-    // Preserve the strict all-failed behavior so callers still learn when no
-    // bytes were available, while allowing valid siblings through unchanged.
-    if (materialized.length === 0 && hasFailure) {
-        throw firstError;
-    }
-    return materialized;
-}
-function byteLimitTransform(maxBytes) {
-    let total = 0;
-    return {
-        stream: new Transform({
-            transform(chunk, _encoding, callback) {
-                total += chunk.length;
-                if (total > maxBytes) {
-                    callback(new Error(`Canon media exceeds the ${maxBytes}-byte materialization limit`));
-                    return;
-                }
-                callback(null, chunk);
-            },
-        }),
-        bytesRead: () => total,
-    };
-}
-export function getMessageAttachments(message) {
-    return Array.isArray(message.attachments) ? message.attachments : [];
-}
-function isMaterializableAttachment(attachment) {
-    // Missing status is the legacy-ready contract. Processing URLs are reserved
-    // future capabilities and failed videos intentionally have no playable
-    // object, so neither should trigger a network request from an agent runtime.
-    return attachment.kind !== 'video'
-        || attachment.processingStatus === undefined
-        || attachment.processingStatus === 'ready';
-}
-export async function materializeAttachment(attachment, options) {
-    const path = buildCachePath({
-        agentId: options.agentId,
-        conversationId: options.conversationId,
-        messageId: options.messageId,
-        attachment,
-        index: options.index ?? 0,
-        rootDir: options.rootDir,
-    });
-    await mkdir(dirname(path), { recursive: true });
-    const maxBytes = resolveMaxBytes(options.maxBytes);
-    const expectedBytes = typeof attachment.sizeBytes === 'number'
-        && Number.isSafeInteger(attachment.sizeBytes)
-        && attachment.sizeBytes >= 0
-        ? attachment.sizeBytes
-        : null;
-    if (expectedBytes !== null && expectedBytes > maxBytes) {
-        throw new Error(`Canon media exceeds the ${maxBytes}-byte materialization limit`);
-    }
-    let responseMimeType = null;
-    if (await fileExists(path)) {
-        const info = await stat(path);
-        if (info.size > maxBytes) {
-            throw new Error(`Cached Canon media exceeds the ${maxBytes}-byte materialization limit`);
-        }
-        if (expectedBytes !== null && info.size !== expectedBytes) {
-            await unlink(path).catch(() => { });
-        }
-    }
-    if (!(await fileExists(path))) {
-        const fetchImpl = ensureFetch(options.fetchImpl);
-        const response = await fetchImpl(attachment.url, {
-            signal: options.signal,
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to download Canon media (${response.status} ${response.statusText})`);
-        }
-        responseMimeType = response.headers.get('content-type');
-        const contentLength = response.headers.get('content-length');
-        const declaredLength = contentLength === null ? null : Number(contentLength);
-        if (declaredLength !== null && Number.isFinite(declaredLength) && declaredLength > maxBytes) {
-            throw new Error(`Canon media exceeds the ${maxBytes}-byte materialization limit`);
-        }
-        if (expectedBytes !== null
-            && declaredLength !== null
-            && Number.isFinite(declaredLength)
-            && declaredLength !== expectedBytes) {
-            throw new Error('Canon media response length does not match attachment metadata');
-        }
-        if (!response.body) {
-            throw new Error('Canon media response had no body');
-        }
-        const tempPath = `${path}.${process.pid}.${randomUUID()}.part`;
-        const limiter = byteLimitTransform(maxBytes);
-        try {
-            await pipeline(Readable.fromWeb(response.body), limiter.stream, createWriteStream(tempPath, { mode: 0o600, flags: 'wx' }));
-            if (expectedBytes !== null && limiter.bytesRead() !== expectedBytes) {
-                throw new Error('Canon media response length does not match attachment metadata');
-            }
-            await rename(tempPath, path);
-        }
-        catch (error) {
-            await unlink(tempPath).catch(() => { });
-            throw error;
-        }
-    }
-    return {
-        ...attachment,
-        index: options.index ?? 0,
-        path,
-        sourceUrl: attachment.url,
-        conversationId: options.conversationId,
-        messageId: options.messageId,
-        ...(attachment.mimeType
-            ? {}
-            : responseMimeType
-                ? { mimeType: responseMimeType }
-                : {}),
-    };
-}
-export async function materializeMessageMedia(message, options) {
-    const attachments = getMessageAttachments(message);
-    return materializeAvailableAttachments(attachments.flatMap((attachment, index) => (isMaterializableAttachment(attachment)
-        ? [{
-                attachment,
-                index,
-                run: () => materializeAttachment(attachment, {
-                    ...options,
-                    messageId: message.id,
-                    index,
-                }),
-            }]
-        : [])), options);
-}
-export async function materializeReplyContextMedia(replyContext, options) {
-    if (!replyContext?.found || !replyContext.attachments?.length) {
-        return { replyContext, materialized: [] };
-    }
-    const materializable = replyContext.attachments.flatMap((attachment, index) => attachment.url && isMaterializableAttachment(attachment)
-        ? [{
-                attachment,
-                index,
-                run: () => materializeAttachment(attachment, {
-                    ...options,
-                    messageId: replyContext.messageId,
-                    index,
-                }),
-            }]
-        : []);
-    const materialized = await materializeAvailableAttachments(materializable, options);
-    return {
-        replyContext: {
-            ...replyContext,
-            body: renderCanonHostInboundContent({
-                text: replyContext.text,
-                contentType: replyContext.contentType,
-                attachments: replyContext.attachments,
-                contactCard: replyContext.contactCard,
-                senderType: replyContext.senderType ?? undefined,
-            }, materialized),
-        },
-        materialized,
-    };
-}
-export function inferUploadMimeType(filePath, overrideMimeType) {
-    if (overrideMimeType)
-        return overrideMimeType;
-    return MIME_BY_EXTENSION[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
-}
-export async function uploadMediaFile(client, conversationId, filePath, options) {
-    options?.signal?.throwIfAborted();
-    const fileStat = await stat(filePath);
-    if (!fileStat.isFile())
-        throw new Error(`Canon media path is not a file: ${filePath}`);
-    if (fileStat.size <= 0)
-        throw new Error('Canon media file is empty');
-    if (fileStat.size > MAX_CANON_MEDIA_BYTES) {
-        throw new Error(`Canon media exceeds the ${MAX_CANON_MEDIA_BYTES}-byte upload limit`);
-    }
-    const mimeType = inferUploadMimeType(filePath, options?.mimeType);
-    const fileName = options?.fileName ?? basename(filePath);
-    const media = await client.getFileMediaPipeline(options?.fetchImpl);
-    const [attachment] = await media.prepare({ conversationId, attachmentId: options?.attachmentId ?? randomUUID(),
-        files: [{ source: filePath, descriptor: { mimeType, sizeBytes: fileStat.size, fileName,
-                    ...(options?.durationMs !== undefined ? { durationMs: options.durationMs } : {}) } }],
-    }, { signal: options?.signal });
-    if (typeof attachment?.uploadId !== 'string' || typeof attachment.url !== 'string') {
-        throw new Error('Canon returned an invalid prepared attachment');
-    }
-    return { uploadId: attachment.uploadId, url: attachment.url, attachment: attachment };
-}
-export async function sendMediaFileMessage(client, conversationId, filePath, text = '', options) {
-    const { fileName, mimeType, durationMs, fetchImpl, signal, canPublish, attachmentId: _attachmentId, ...sendOptions } = options ?? {};
-    signal?.throwIfAborted();
-    const info = await stat(filePath);
-    if (!info.isFile() || info.size <= 0 || info.size > MAX_CANON_MEDIA_BYTES) {
-        throw new Error('Canon media must be a regular file from 1 byte to 100 MiB');
-    }
-    const effectiveMimeType = inferUploadMimeType(filePath, mimeType);
-    const contentType = effectiveMimeType.startsWith('image/') ? 'image'
-        : effectiveMimeType.startsWith('video/') ? 'video'
-            : effectiveMimeType.startsWith('audio/') ? 'audio' : 'file';
-    // Automatic artifacts keep their audience across upload and every later
-    // receipt retry. A membership change may reduce, but never expand, that audience.
-    const initialRoom = canPublish ? await client.getConversation(conversationId) : null;
-    const originalMembers = new Set(initialRoom?.memberIds ?? []);
-    const beforePublish = canPublish ? async () => {
-        const current = await client.getConversation(conversationId);
-        return !!current && originalMembers.size > 0
-            && current.memberIds.every((id) => originalMembers.has(id)) && canPublish();
-    } : undefined;
-    const messageId = sendOptions.messageId ?? randomUUID();
-    const pipeline = await client.getFileMediaPipeline(fetchImpl);
-    const delivered = await pipeline.send({
-        conversationId, messageId,
-        message: { ...sendOptions, text, contentType },
-        files: [{ source: filePath, descriptor: {
-                    mimeType: effectiveMimeType, sizeBytes: info.size, fileName: fileName ?? basename(filePath),
-                    ...(durationMs != null ? { durationMs } : {}),
-                } }],
-    }, { ...(signal ? { signal } : {}), ...(beforePublish ? { beforePublish } : {}) });
-    return { messageId: delivered };
-}
-/**
- * Resolve the effective MIME type of a materialized attachment, falling back
- * to filename/URL extensions when the server didn't tell us explicitly.
- */
-export function resolveAttachmentMimeType(attachment) {
-    if (attachment.mimeType)
-        return attachment.mimeType.toLowerCase();
-    const pathExt = extname(attachment.path).toLowerCase();
-    const fromPath = MIME_BY_EXTENSION[pathExt];
-    if (fromPath)
-        return fromPath;
-    const fileExt = extname(attachment.fileName ?? '').toLowerCase();
-    const fromFileName = MIME_BY_EXTENSION[fileExt];
-    if (fromFileName)
-        return fromFileName;
-    const urlExt = extname(attachment.sourceUrl.split('?')[0] ?? '').toLowerCase();
-    const fromUrl = MIME_BY_EXTENSION[urlExt];
-    if (fromUrl)
-        return fromUrl;
-    return null;
-}
-/**
- * True when a materialized attachment can be sent to Anthropic as a base64
- * `image` block (jpeg, png, gif, webp). Other images (heic, tiff, svg, …)
- * must be re-encoded before they can be delivered as a vision block.
- */
-export function isAnthropicImageAttachment(attachment) {
-    if (attachment.kind !== 'image')
-        return false;
-    const mime = resolveAttachmentMimeType(attachment);
-    return mime != null && ANTHROPIC_IMAGE_MIME_TYPES.has(mime);
-}
-/**
- * Read the materialized bytes and build an Anthropic `image` content block.
- * Callers should first check `isAnthropicImageAttachment`; this function
- * throws if the MIME type is not supported.
- */
-export async function toAnthropicImageBlock(attachment, options) {
-    if (!isAnthropicImageAttachment(attachment)) {
-        throw new Error(`Canon attachment ${attachment.index} is not a supported Anthropic image (kind=${attachment.kind}, mime=${attachment.mimeType ?? 'unknown'})`);
-    }
-    const maxRawBytes = options?.maxRawBytes ?? MAX_ANTHROPIC_IMAGE_RAW_BYTES;
-    if (!Number.isSafeInteger(maxRawBytes)
-        || maxRawBytes <= 0
-        || maxRawBytes > MAX_ANTHROPIC_IMAGE_RAW_BYTES) {
-        throw new Error(`maxRawBytes must be an integer between 1 and ${MAX_ANTHROPIC_IMAGE_RAW_BYTES}`);
-    }
-    const mediaType = resolveAttachmentMimeType(attachment);
-    const buffer = await readAnthropicImageBytes(attachment, maxRawBytes);
-    return buildAnthropicImageBlock(buffer, mediaType);
-}
-async function readAnthropicImageBytes(attachment, maxRawBytes) {
-    const handle = await open(attachment.path, 'r');
-    try {
-        return await readBoundedRegularFileHandle(handle, maxRawBytes);
-    }
-    catch (error) {
-        if (error instanceof BoundedFileReadError) {
-            if (error.failure === 'not-file') {
-                throw new Error(`Canon attachment ${attachment.index} is not a file`);
-            }
-            throw new Error(`Canon attachment ${attachment.index} exceeds the ${maxRawBytes}-byte Anthropic image limit`);
-        }
-        throw error;
-    }
-    finally {
-        await handle.close();
-    }
-}
-function buildAnthropicImageBlock(buffer, mediaType) {
-    return {
-        type: 'image',
-        source: {
-            type: 'base64',
-            media_type: mediaType,
-            data: buffer.toString('base64'),
-        },
-    };
-}
-function resolveBoundedInteger(input) {
-    const value = input.value ?? input.fallback;
-    const minimum = input.allowZero ? 0 : 1;
-    if (!Number.isSafeInteger(value) || value < minimum || value > input.maximum) {
-        throw new Error(`${input.name} must be an integer between ${minimum} and ${input.maximum}`);
-    }
-    return value;
-}
-function encodedBase64Length(rawBytes) {
-    return Math.ceil(rawBytes / 3) * 4;
-}
-function serializedTextBlockBytes(promptText) {
-    return Buffer.byteLength(JSON.stringify({ type: 'text', text: promptText }), 'utf8');
-}
-function serializedImageBlockBytes(rawBytes, mediaType) {
-    const framingBytes = Buffer.byteLength(JSON.stringify({
-        type: 'image',
-        source: {
-            type: 'base64',
-            media_type: mediaType,
-            data: '',
-        },
-    }), 'utf8');
-    return framingBytes + encodedBase64Length(rawBytes);
-}
-/**
- * Convert only the supported images that fit both the direct-image limit and
- * the aggregate request budget. Skipped images remain represented by the
- * paths already rendered into promptText; one unavailable image never drops
- * valid siblings.
- */
-export async function toAnthropicImageBlocksWithinBudget(attachments, options) {
-    const maxImageRawBytes = resolveBoundedInteger({
-        value: options.maxImageRawBytes,
-        fallback: MAX_ANTHROPIC_IMAGE_RAW_BYTES,
-        maximum: MAX_ANTHROPIC_IMAGE_RAW_BYTES,
-        name: 'maxImageRawBytes',
-    });
-    const maxRequestBytes = resolveBoundedInteger({
-        value: options.maxRequestBytes,
-        fallback: MAX_ANTHROPIC_REQUEST_BYTES,
-        maximum: MAX_ANTHROPIC_REQUEST_BYTES,
-        name: 'maxRequestBytes',
-    });
-    const requestHeadroomBytes = resolveBoundedInteger({
-        value: options.requestHeadroomBytes,
-        fallback: DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
-        maximum: maxRequestBytes,
-        name: 'requestHeadroomBytes',
-        allowZero: true,
-    });
-    const contentBudgetBytes = maxRequestBytes - requestHeadroomBytes;
-    // Exact JSON content-array framing: opening/closing brackets around the
-    // text block, then one comma before every native image block.
-    let usedBytes = 2 + serializedTextBlockBytes(options.promptText);
-    if (usedBytes > contentBudgetBytes)
-        return [];
-    const blocks = [];
-    for (const attachment of attachments) {
-        if (!isAnthropicImageAttachment(attachment))
-            continue;
-        try {
-            const mediaType = resolveAttachmentMimeType(attachment);
-            const buffer = await readAnthropicImageBytes(attachment, maxImageRawBytes);
-            const nextBlockBytes = 1 + serializedImageBlockBytes(buffer.byteLength, mediaType);
-            if (usedBytes + nextBlockBytes > contentBudgetBytes)
-                continue;
-            const block = buildAnthropicImageBlock(buffer, mediaType);
-            const actualBlockBytes = 1 + Buffer.byteLength(JSON.stringify(block), 'utf8');
-            if (usedBytes + actualBlockBytes > contentBudgetBytes)
-                continue;
-            blocks.push(block);
-            usedBytes += actualBlockBytes;
-        }
-        catch {
-            // A missing, changed, or unreadable file stays as its prompt path. Keep
-            // inspecting siblings instead of failing the whole model request.
-        }
-    }
-    return blocks;
-}
-/**
- * Return the local path to pass to Codex via its `-i/--image` flag when the
- * attachment is an image Codex can consume. Codex accepts the same MIME types
- * as Anthropic in practice (jpeg/png/gif/webp), so we reuse the allowlist.
- */
-export function getCodexImagePath(attachment) {
-    return isAnthropicImageAttachment(attachment) ? attachment.path : null;
-}

package/dist/runner/runner.d.ts

@@ -0,0 +1,37 @@
+import { type CanonEndpoint, type CanonRuntimeDescriptor, type CommunicateInput, type CommunicateResult } from '../internal/core/index.js';
+import { type RuntimeDriver } from './types.js';
+export interface RunnerOptions {
+    apiKey: string;
+    environmentId: string;
+    /** CANON_HOME: a private 0700 directory, checked before anything is opened. */
+    home: string;
+    driver: RuntimeDriver;
+    /** Test seam: an injected endpoint engine. Production never sets it. */
+    endpoint?: CanonEndpoint;
+    /** Test seam: HTTP outside the endpoint protocol (health, identity). Production never sets it. */
+    fetch?: typeof fetch;
+    /** Test-only origin overrides (the CLI's CANON_BASE_URL and CANON_STREAM_URL). */
+    baseUrl?: string;
+    streamUrl?: string;
+    /** How long an aborted turn may take to settle before its session is reset (default 10 s). */
+    abortGraceMs?: number;
+    /** A turn with no text or activity for this long fails (default 30 min); the clock waits while an `ask` is pending. */
+    noProgressMs?: number;
+    /** How long an `ask` waits for its answer before it expires (default 1 h; an expired approval is a denial). */
+    askExpiryMs?: number;
+    /** How long running turns may finish on shutdown before they are aborted (default 10 s). */
+    shutdownGraceMs?: number;
+    /** Never receives prompt or reply text. */
+    log?: (line: string) => void;
+}
+export interface Runner {
+    /** Connects and starts taking input; resolves once listening is set up. */
+    start(): Promise<void>;
+    /** Stops intake, releases unsubmitted input, lets running turns finish within the shutdown grace. */
+    stop(): Promise<void>;
+    /** A proactive send outside any turn (cron): the `communicate` tool's handler, under the runner's identity. */
+    communicate(input: CommunicateInput): Promise<CommunicateResult>;
+}
+/** RUN-27: generated once from the driver's declarations; no static capability table. */
+export declare function runtimeDescriptor(driver: RuntimeDriver): CanonRuntimeDescriptor;
+export declare function createRunner(options: RunnerOptions): Promise<Runner>;