@canonmsg/agent-sdk 8.4.0 → 8.6.0

package/README.md

@@ -356,8 +356,8 @@ agent.on('message', async ({ messages, media }) => {
 });
 ```
 
-- `media.materialize(message?)` downloads the message's attachments on demand into `~/.canon/media-cache`.
-- `media.uploadFile(path, options?)` uploads a local file into the current Canon conversation and returns the canonical attachment metadata.
+- `media.materialize(message?, options?)` streams attachments on demand into `~/.canon/media-cache`. Automatic materialization is capped at 10 MiB per attachment before and during the download. A runtime that deliberately needs a larger input can pass `maxBytes`, up to 100 MiB. Failed or oversized attachments are reported through optional `onError`; valid siblings are still returned. Cancellation still aborts the complete operation. Cache files are published through an atomic rename. The cache is persistent and currently has no aggregate quota or automatic eviction, so hosted-agent operators should monitor or periodically clear it.
+- `media.uploadFile(path, options?)` streams a local file (up to 100 MiB) through Canon's private resumable-capable upload lane and returns `{ uploadId, url, attachment }`. The attachment carries the same server-issued `uploadId`, allowing a subsequent durable message/card write to retain the temporary upload. File bytes are never base64-buffered in the SDK. The current helper uses one streamed PUT; a failed application-level attempt starts a new Canon session rather than resuming an acknowledged byte range in the old session.
 - `media.replyWithFile(path, text?, options?)` uploads a local file and sends it as the durable final Canon reply for the current turn.
 
 GIFs are regular image attachments. Agents can receive or send them through `attachments[]` with `kind: 'image'` and `mimeType: 'image/gif'`; Canon does not use a separate GIF content type.

package/dist/bounded-file-read.d.ts

@@ -0,0 +1,14 @@
+import type { FileHandle } from 'node:fs/promises';
+export type BoundedFileReadFailure = 'not-file' | 'too-large';
+export declare class BoundedFileReadError extends Error {
+    readonly failure: BoundedFileReadFailure;
+    constructor(failure: BoundedFileReadFailure);
+}
+type ReadableFileHandle = Pick<FileHandle, 'stat' | 'read'>;
+/**
+ * Read a regular file through an already-open handle without ever requesting
+ * more than maxBytes + 1. The extra byte detects a file that grew after stat
+ * without allowing an unbounded path-based read.
+ */
+export declare function readBoundedRegularFileHandle(handle: ReadableFileHandle, maxBytes: number): Promise<Buffer>;
+export {};

package/dist/bounded-file-read.js

@@ -0,0 +1,34 @@
+export class BoundedFileReadError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure);
+        this.failure = failure;
+        this.name = 'BoundedFileReadError';
+    }
+}
+/**
+ * Read a regular file through an already-open handle without ever requesting
+ * more than maxBytes + 1. The extra byte detects a file that grew after stat
+ * without allowing an unbounded path-based read.
+ */
+export async function readBoundedRegularFileHandle(handle, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new Error('maxBytes must be a positive safe integer');
+    }
+    const fileStat = await handle.stat();
+    if (!fileStat.isFile())
+        throw new BoundedFileReadError('not-file');
+    if (fileStat.size > maxBytes)
+        throw new BoundedFileReadError('too-large');
+    const buffer = Buffer.allocUnsafe(maxBytes + 1);
+    let totalBytes = 0;
+    while (totalBytes < buffer.byteLength) {
+        const { bytesRead } = await handle.read(buffer, totalBytes, buffer.byteLength - totalBytes, totalBytes);
+        if (bytesRead === 0)
+            break;
+        totalBytes += bytesRead;
+    }
+    if (totalBytes > maxBytes)
+        throw new BoundedFileReadError('too-large');
+    return buffer.subarray(0, totalBytes);
+}

package/dist/canon-agent.d.ts

@@ -156,9 +156,9 @@ export declare class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId }` — the target requires approval; the
-     *   server created a contact-request (kind: 'group_invite') routed to the
-     *   approver. The actual group join happens when that request is approved
+     * - `{ status: 'pending', requestId, requirements }` — the target needs
+     *   policy approval, owner session setup, or both. The server created one
+     *   `group_invite`; membership activates after every requirement is met
      *   (you can listen for `contact.approved` SSE events to know when).
      *
      * Throws `CanonApiError` for hard failures (block, inactive, owner-only,

package/dist/canon-agent.js

@@ -791,9 +791,9 @@ export class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId }` — the target requires approval; the
-     *   server created a contact-request (kind: 'group_invite') routed to the
-     *   approver. The actual group join happens when that request is approved
+     * - `{ status: 'pending', requestId, requirements }` — the target needs
+     *   policy approval, owner session setup, or both. The server created one
+     *   `group_invite`; membership activates after every requirement is met
      *   (you can listen for `contact.approved` SSE events to know when).
      *
      * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
@@ -2028,7 +2028,10 @@ export class CanonAgent {
                     return result;
                 }
             };
-            const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
+            const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, {
+                ...(options ?? {}),
+                signal: options?.signal ?? abortController.signal,
+            });
             const replyWithFile = async (filePath, text = '', options) => {
                 throwIfAborted();
                 try {
@@ -2057,6 +2060,8 @@ export class CanonAgent {
                         ...(options?.fileName ? { fileName: options.fileName } : {}),
                         ...(options?.mimeType ? { mimeType: options.mimeType } : {}),
                         ...(options?.durationMs != null ? { durationMs: options.durationMs } : {}),
+                        ...(options?.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+                        signal: options?.signal ?? abortController.signal,
                     });
                     durableMessageSequence += 1;
                     await sleep(FINAL_MESSAGE_HANDOFF_MS);
@@ -2108,6 +2113,7 @@ export class CanonAgent {
                             agentId: agent.agentId,
                             conversationId,
                             ...(options ?? {}),
+                            signal: options?.signal ?? abortController.signal,
                         });
                     },
                     uploadFile,

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { CanonAgent } from './canon-agent.js';
 export type { AgentContactsAPI, AgentConversationsAPI, AgentUsersAPI } from './canon-agent.js';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
-export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } from '@canonmsg/core';
+export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
-export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.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, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
+export type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, GroupInviteRequirements, CanonMessage, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
 export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { CanonAgent } from './canon-agent.js';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.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, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';

package/dist/media.d.ts

@@ -1,4 +1,4 @@
-import { CanonClient, type CanonReplyContext, type CanonMessage, type MediaAttachment, type SendMessageOptions } from '@canonmsg/core';
+import { CanonClient, type CanonReplyContext, type CanonMessage, type MediaAttachment, type ResumableMediaUploadResult, type SendMessageOptions } from '@canonmsg/core';
 export interface MaterializeMediaOptions {
     agentId: string;
     conversationId: string;
@@ -6,11 +6,20 @@ export interface MaterializeMediaOptions {
     rootDir?: string;
     fetchImpl?: typeof fetch;
     signal?: AbortSignal;
+    /**
+     * Maximum bytes written to disk per attachment. Automatic materialization
+     * defaults to 10 MiB; runtimes may opt in up to Canon's 100 MiB upload cap.
+     */
+    maxBytes?: number;
+    /** Called for each attachment that could not be materialized. */
+    onError?: (error: unknown, attachment: MediaAttachment, index: number) => void;
 }
 export interface UploadMediaFileOptions {
     fileName?: string;
     mimeType?: string;
     durationMs?: number;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
 }
 export interface ReplyWithFileOptions extends Omit<SendMessageOptions, 'attachments' | 'contentType'>, UploadMediaFileOptions {
 }
@@ -44,7 +53,27 @@ export interface AnthropicImageBlock {
         data: string;
     };
 }
+export interface AnthropicImageBudgetOptions {
+    /** Text content that shares the Anthropic request with the image blocks. */
+    promptText: string;
+    /** Optional lower per-image limit for providers with smaller image caps. */
+    maxImageRawBytes?: number;
+    /** Optional lower total request ceiling. Defaults to Anthropic's 32 MB limit. */
+    maxRequestBytes?: number;
+    /** Bytes reserved for SDK/request framing outside these content blocks. */
+    requestHeadroomBytes?: number;
+}
 export declare const DEFAULT_MEDIA_CACHE_DIR: string;
+export declare const DEFAULT_MEDIA_MATERIALIZATION_BYTES: number;
+export declare const MAX_CANON_MEDIA_BYTES: number;
+/**
+ * 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 declare const MAX_ANTHROPIC_IMAGE_RAW_BYTES: number;
+export declare const MAX_ANTHROPIC_REQUEST_BYTES = 32000000;
+export declare const DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES: number;
 export declare function getMessageAttachments(message: Pick<CanonMessage, 'attachments'>): MediaAttachment[];
 export declare function materializeAttachment(attachment: MediaAttachment, options: MaterializeMediaOptions & {
     index?: number;
@@ -52,10 +81,7 @@ export declare function materializeAttachment(attachment: MediaAttachment, optio
 export declare function materializeMessageMedia(message: Pick<CanonMessage, 'id' | 'attachments'>, options: Omit<MaterializeMediaOptions, 'messageId'>): Promise<MaterializedCanonAttachment[]>;
 export declare function materializeReplyContextMedia(replyContext: CanonReplyContext | null, options: Omit<MaterializeMediaOptions, 'messageId'>): Promise<MaterializedCanonReplyContext>;
 export declare function inferUploadMimeType(filePath: string, overrideMimeType?: string): string;
-export declare function uploadMediaFile(client: CanonClient, conversationId: string, filePath: string, options?: UploadMediaFileOptions): Promise<{
-    url: string;
-    attachment: MediaAttachment;
-}>;
+export declare function uploadMediaFile(client: CanonClient, conversationId: string, filePath: string, options?: UploadMediaFileOptions): Promise<ResumableMediaUploadResult>;
 export declare function sendMediaFileMessage(client: CanonClient, conversationId: string, filePath: string, text?: string, options?: ReplyWithFileOptions): Promise<{
     messageId: string;
 }>;
@@ -75,7 +101,16 @@ export declare function isAnthropicImageAttachment(attachment: MaterializedCanon
  * Callers should first check `isAnthropicImageAttachment`; this function
  * throws if the MIME type is not supported.
  */
-export declare function toAnthropicImageBlock(attachment: MaterializedCanonAttachment): Promise<AnthropicImageBlock>;
+export declare function toAnthropicImageBlock(attachment: MaterializedCanonAttachment, options?: {
+    maxRawBytes?: number;
+}): Promise<AnthropicImageBlock>;
+/**
+ * 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 declare function toAnthropicImageBlocksWithinBudget(attachments: ReadonlyArray<MaterializedCanonAttachment>, options: AnthropicImageBudgetOptions): Promise<AnthropicImageBlock[]>;
 /**
  * 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

package/dist/media.js

@@ -1,6 +1,11 @@
-import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { createReadStream, 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, } from '@canonmsg/core';
+import { BoundedFileReadError, readBoundedRegularFileHandle, } from './bounded-file-read.js';
 const ANTHROPIC_IMAGE_MIME_TYPES = new Set([
     'image/jpeg',
     'image/png',
@@ -8,6 +13,16 @@ const ANTHROPIC_IMAGE_MIME_TYPES = new Set([
     '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',
@@ -100,6 +115,64 @@ async function fileExists(path) {
         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 : [];
 }
@@ -113,7 +186,25 @@ export async function materializeAttachment(attachment, options) {
         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, {
@@ -123,8 +214,33 @@ export async function materializeAttachment(attachment, options) {
             throw new Error(`Failed to download Canon media (${response.status} ${response.statusText})`);
         }
         responseMimeType = response.headers.get('content-type');
-        const body = Buffer.from(await response.arrayBuffer());
-        await writeFile(path, body, { mode: 0o644 });
+        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,
@@ -142,23 +258,32 @@ export async function materializeAttachment(attachment, options) {
 }
 export async function materializeMessageMedia(message, options) {
     const attachments = getMessageAttachments(message);
-    return Promise.all(attachments.map((attachment, index) => materializeAttachment(attachment, {
-        ...options,
-        messageId: message.id,
+    return materializeAvailableAttachments(attachments.map((attachment, index) => ({
+        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 materialized = (await Promise.all(replyContext.attachments.map((attachment, index) => attachment.url
-        ? materializeAttachment(attachment, {
-            ...options,
-            messageId: replyContext.messageId,
-            index,
-        })
-        : Promise.resolve(null)))).filter((attachment) => attachment !== null);
+    const materializable = replyContext.attachments.flatMap((attachment, index) => attachment.url
+        ? [{
+                attachment,
+                index,
+                run: () => materializeAttachment(attachment, {
+                    ...options,
+                    messageId: replyContext.messageId,
+                    index,
+                }),
+            }]
+        : []);
+    const materialized = await materializeAvailableAttachments(materializable, options);
     return {
         replyContext: {
             ...replyContext,
@@ -179,10 +304,77 @@ export function inferUploadMimeType(filePath, overrideMimeType) {
     return MIME_BY_EXTENSION[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
 }
 export async function uploadMediaFile(client, conversationId, filePath, options) {
-    const buffer = await readFile(filePath);
+    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 uploaded = await client.uploadMedia(conversationId, buffer.toString('base64'), mimeType, fileName);
+    const session = await client.createResumableMediaUpload(conversationId, fileStat.size, mimeType, fileName);
+    options?.signal?.throwIfAborted();
+    if (typeof session.uploadId !== 'string' || session.uploadId.length === 0) {
+        throw new Error('Canon returned an invalid resumable upload ID');
+    }
+    if (session.sizeBytes !== fileStat.size) {
+        throw new Error('Canon resumable upload size does not match the local file');
+    }
+    if (typeof session.mimeType !== 'string' || session.mimeType.length === 0) {
+        throw new Error('Canon returned an invalid resumable upload MIME type');
+    }
+    let uploadUrl;
+    try {
+        uploadUrl = new URL(session.uploadUrl);
+    }
+    catch {
+        throw new Error('Canon returned an invalid resumable upload URL');
+    }
+    if (uploadUrl.protocol !== 'https:') {
+        throw new Error('Canon returned a non-HTTPS resumable upload URL');
+    }
+    if (uploadUrl.hostname !== 'storage.googleapis.com'
+        || uploadUrl.username.length > 0
+        || uploadUrl.password.length > 0) {
+        throw new Error('Canon returned an untrusted resumable upload URL');
+    }
+    const fetchImpl = ensureFetch(options?.fetchImpl);
+    const uploadResponse = await fetchImpl(uploadUrl, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': session.mimeType,
+            'Content-Length': String(fileStat.size),
+            'Content-Range': `bytes 0-${fileStat.size - 1}/${fileStat.size}`,
+        },
+        body: createReadStream(filePath),
+        signal: options?.signal,
+        // Node requires this for streaming request bodies. It is intentionally
+        // outside the DOM RequestInit type but supported by the built-in fetch.
+        duplex: 'half',
+    });
+    if (!uploadResponse.ok) {
+        throw new Error(`Failed to upload Canon media (${uploadResponse.status} ${uploadResponse.statusText})`);
+    }
+    options?.signal?.throwIfAborted();
+    const finalized = await client.finalizeResumableMediaUpload(session.uploadId);
+    options?.signal?.throwIfAborted();
+    if (finalized.uploadId !== session.uploadId) {
+        throw new Error('Canon resumable upload result does not match its session');
+    }
+    if (finalized.attachment.uploadId !== undefined
+        && finalized.attachment.uploadId !== session.uploadId) {
+        throw new Error('Canon resumable upload attachment does not match its session');
+    }
+    const uploaded = {
+        ...finalized,
+        attachment: {
+            ...finalized.attachment,
+            uploadId: session.uploadId,
+        },
+    };
     if (uploaded.attachment.kind === 'audio'
         && typeof options?.durationMs === 'number'
         && Number.isFinite(options.durationMs)
@@ -198,12 +390,15 @@ export async function uploadMediaFile(client, conversationId, filePath, options)
     return uploaded;
 }
 export async function sendMediaFileMessage(client, conversationId, filePath, text = '', options) {
-    const { fileName, mimeType, durationMs, ...sendOptions } = options ?? {};
+    const { fileName, mimeType, durationMs, fetchImpl, signal, ...sendOptions } = options ?? {};
     const uploaded = await uploadMediaFile(client, conversationId, filePath, {
         ...(fileName ? { fileName } : {}),
         ...(mimeType ? { mimeType } : {}),
         ...(durationMs != null ? { durationMs } : {}),
+        ...(fetchImpl ? { fetchImpl } : {}),
+        ...(signal ? { signal } : {}),
     });
+    signal?.throwIfAborted();
     return client.sendMessage(conversationId, text, {
         ...sendOptions,
         contentType: uploaded.attachment.kind,
@@ -247,12 +442,39 @@ export function isAnthropicImageAttachment(attachment) {
  * Callers should first check `isAnthropicImageAttachment`; this function
  * throws if the MIME type is not supported.
  */
-export async function toAnthropicImageBlock(attachment) {
+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 readFile(attachment.path);
+    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: {
@@ -262,6 +484,87 @@ export async function toAnthropicImageBlock(attachment) {
         },
     };
 }
+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

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, VerbSessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, VerbSessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+export type { AddMemberResult, GroupInviteRequirements, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, VerbSessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, SendContextualSelfContextInput, VerbSessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -230,10 +230,7 @@ export interface MessageHandlerContext {
     /** Canon-managed local media access for the current conversation. */
     media: {
         materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
-        uploadFile: (filePath: string, options?: UploadMediaFileOptions) => Promise<{
-            url: string;
-            attachment: import('@canonmsg/core').MediaAttachment;
-        }>;
+        uploadFile: (filePath: string, options?: UploadMediaFileOptions) => Promise<ResumableMediaUploadResult>;
         replyWithFile: (filePath: string, text?: string, options?: ReplyWithFileOptions) => Promise<{
             messageId: string;
         }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "8.4.0",
+  "version": "8.6.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^10.2.0"
+    "@canonmsg/core": "^10.4.0"
   },
   "publishConfig": {
     "access": "public"