@deepseek-ai/dsh-client-file-upload 0.1.3-alpha.2

package/lib/typert.remote-client.js

@@ -0,0 +1,65 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+const _deepseek_ai_dsh_client_file_upload_fileUploads_upload_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _deepseek_ai_dsh_client_file_upload_fileUploads_upload_parameter_1$schema = z.object({
+  'data': z.string().readonly(),
+  'name': z.string().readonly().optional(),
+})
+const _deepseek_ai_dsh_client_file_upload_fileUploads_upload_result$schema = z.object({
+  'receiptId': z.intersection(z.string(), z.unknown()).readonly(),
+  'file': z.object({
+  'attachmentId': z.intersection(z.string(), z.unknown()),
+  'name': z.string(),
+  'bytes': z.number(),
+}).readonly(),
+})
+
+export const TYPERT_REMOTE = {
+  package: '@deepseek-ai/dsh-client-file-upload',
+  descriptors: [
+    {
+      id: '@deepseek-ai/dsh-client-file-upload#fileUploads/upload',
+      service: 'fileUploads',
+      namespace: 'fileUploads',
+      method: 'upload',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _deepseek_ai_dsh_client_file_upload_fileUploads_upload_parameter_0$schema,
+          },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-client-file-upload/types#EncodedFileUploadRequest',
+            schema: _deepseek_ai_dsh_client_file_upload_fileUploads_upload_parameter_1$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-client-file-upload/types#FileUploadValue',
+        schema: _deepseek_ai_dsh_client_file_upload_fileUploads_upload_result$schema,
+      },
+      sourceLocation: {"file":"packages/client/file-upload/src/index.ts","line":106,"column":3},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/client/contract.d.ts

@@ -0,0 +1,27 @@
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { FileUploadValue } from '../types.ts';
+/** Browser request body accepted by the background file-upload service. */
+export type FileUploadBody = Blob | ReadableStream<Uint8Array>;
+/** Monotone byte progress reported while a browser body is consumed. */
+export interface FileUploadProgress {
+    readonly loaded: number;
+    readonly total?: number;
+}
+/** Browser upload service addressed by one Session identity. */
+export interface FileUploadService {
+    /** Whether this page has a Host-backed background upload carrier. */
+    readonly available: boolean;
+    /**
+     * Store one file for a Session. Blob and stream bodies use
+     * the background carrier; exact bytes and fixture fallbacks use Remote.
+     * @param sessionId - Session that owns the staged receipt.
+     * @param data - browser Blob, exact bytes, or a one-shot byte stream.
+     * @param name - optional display name.
+     * @param signal - optional cancellation for the active upload.
+     * @param onProgress - optional byte-progress observer for background bodies.
+     * @returns the staged receipt and durable file reference, or a business error.
+     */
+    upload(sessionId: SessionId, data: Blob | Uint8Array | ReadableStream<Uint8Array>, name?: string, signal?: AbortSignal, onProgress?: (progress: FileUploadProgress) => void): Promise<RemoteResult<FileUploadValue>>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,19 @@
+/** Browser background-upload Cordis service. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FileUploadService } from './contract.ts';
+export type { FileUploadProgress, FileUploadService } from './contract.ts';
+export type { FileUploadReceiptId, FileUploadValue } from '../types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Session-addressed browser service for staged file uploads. */
+        fileUpload: FileUploadService;
+    }
+}
+/** The upload service uses the generated Remote fallback. */
+export declare const inject: string[];
+/**
+ * Provide the browser background-upload service.
+ * @param ctx - Client plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.js

@@ -0,0 +1,12 @@
+/** Browser background-upload Cordis service. */
+import { FileUploadRuntime } from "./runtime.js";
+/** The upload service uses the generated Remote fallback. */
+export const inject = ['remote'];
+/**
+ * Provide the browser background-upload service.
+ * @param ctx - Client plugin context.
+ */
+export function apply(ctx) {
+    ctx.plugin(FileUploadRuntime);
+}
+//# sourceMappingURL=index.js.map

package/lib/types/client/runtime.d.ts

@@ -0,0 +1,92 @@
+/** Background browser upload implementation for Blob and byte-stream bodies. */
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { FileUploadValue } from '../types.ts';
+import type { FileUploadBody, FileUploadService } from './contract.ts';
+interface FileUploadRequest {
+    readonly path: string;
+    readonly body: FileUploadBody;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: {
+        readonly loaded: number;
+        readonly total?: number;
+    }) => void;
+}
+interface FileUploadResponse {
+    readonly status: number;
+    readonly body: string;
+}
+interface UploadWorkerStart {
+    readonly url: string;
+    readonly body: FileUploadBody;
+    readonly headers: Readonly<Record<string, string>>;
+}
+type UploadWorkerOutput = {
+    readonly kind: 'progress';
+    readonly loaded: number;
+    readonly total?: number;
+} | {
+    readonly kind: 'complete';
+    readonly status: number;
+    readonly body: string;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+interface UploadWorkerScope {
+    onmessage: ((event: MessageEvent<UploadWorkerStart>) => void) | null;
+    postMessage(message: UploadWorkerOutput): void;
+}
+interface UploadXhr {
+    readonly upload: {
+        onprogress: ((event: ProgressEvent) => void) | null;
+    };
+    status: number;
+    responseText: string;
+    withCredentials: boolean;
+    onload: ((event: ProgressEvent) => void) | null;
+    onerror: ((event: ProgressEvent) => void) | null;
+    open(method: string, url: string): void;
+    setRequestHeader(name: string, value: string): void;
+    send(body: Blob): void;
+}
+type UploadWorkerFetch = (input: string, init: RequestInit & {
+    readonly duplex: 'half';
+}) => Promise<Response>;
+/**
+ * Self-contained Worker body; its string form becomes the Blob Worker source.
+ * @param scope - Worker global used for requests and progress messages.
+ * @param createXhr - XMLHttpRequest factory used for Blob progress.
+ * @param doFetch - Fetch carrier used for one-shot ReadableStream bodies.
+ */
+export declare function fileUploadWorker(scope?: UploadWorkerScope, createXhr?: () => UploadXhr, doFetch?: UploadWorkerFetch): void;
+/** Cordis service that owns one background carrier per upload operation. */
+export declare class FileUploadRuntime extends Service implements FileUploadService {
+    readonly available: boolean;
+    private readonly transport;
+    /** @param ctx - providing Client context. */
+    constructor(ctx: Context);
+    /**
+     * Post one body with the carrier selected before Cordis boot.
+     * @param request - target, body, cancellation, and progress observer.
+     * @returns the response status and text body.
+     */
+    post(request: FileUploadRequest): Promise<FileUploadResponse>;
+    /**
+     * Store one file for a Session.
+     * @param sessionId - Session that owns the staged receipt.
+     * @param data - browser Blob, exact bytes, or a one-shot byte stream.
+     * @param name - optional display name.
+     * @param signal - optional cancellation for the active upload.
+     * @param onProgress - optional byte-progress observer for background bodies.
+     * @returns the staged receipt and durable file reference, or a business error.
+     */
+    upload(sessionId: SessionId, data: Blob | Uint8Array | ReadableStream<Uint8Array>, name?: string, signal?: AbortSignal, onProgress?: (progress: {
+        readonly loaded: number;
+        readonly total?: number;
+    }) => void): Promise<RemoteResult<FileUploadValue>>;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/client/runtime.js

@@ -0,0 +1,270 @@
+/** Background browser upload implementation for Blob and byte-stream bodies. */
+import { Service } from '@deepseek-ai/cordis';
+import { bytesToBase64 } from '@deepseek-ai/dsh-util-crypto';
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+import { FILE_UPLOAD_PATH } from "../protocol.js";
+/**
+ * Self-contained Worker body; its string form becomes the Blob Worker source.
+ * @param scope - Worker global used for requests and progress messages.
+ * @param createXhr - XMLHttpRequest factory used for Blob progress.
+ * @param doFetch - Fetch carrier used for one-shot ReadableStream bodies.
+ */
+export function fileUploadWorker(scope = self, createXhr = () => new XMLHttpRequest(), doFetch = (input, init) => fetch(input, init)) {
+    scope.onmessage = (event) => {
+        const request = event.data;
+        if (request.body instanceof Blob) {
+            const xhr = createXhr();
+            xhr.open('POST', request.url);
+            xhr.withCredentials = true;
+            for (const [name, value] of Object.entries(request.headers))
+                xhr.setRequestHeader(name, value);
+            xhr.upload.onprogress = (progress) => {
+                scope.postMessage({
+                    kind: 'progress',
+                    loaded: progress.loaded,
+                    ...(progress.lengthComputable ? { total: progress.total } : {}),
+                });
+            };
+            xhr.onload = () => {
+                scope.postMessage({ kind: 'complete', status: xhr.status, body: xhr.responseText });
+            };
+            xhr.onerror = () => {
+                scope.postMessage({ kind: 'error', message: 'background upload transport failed' });
+            };
+            xhr.send(request.body);
+            return;
+        }
+        if (!(request.body instanceof ReadableStream)) {
+            scope.postMessage({ kind: 'error', message: 'background upload worker received an invalid body' });
+            return;
+        }
+        const source = request.body;
+        void (async () => {
+            const reader = source.getReader();
+            let loaded = 0;
+            const body = new ReadableStream({
+                async pull(controller) {
+                    const item = await reader.read();
+                    if (item.done) {
+                        controller.close();
+                        return;
+                    }
+                    if (!(item.value instanceof Uint8Array)) {
+                        throw new TypeError('background upload stream produced a non-Uint8Array chunk');
+                    }
+                    loaded += item.value.byteLength;
+                    scope.postMessage({ kind: 'progress', loaded });
+                    controller.enqueue(item.value);
+                },
+                async cancel(reason) {
+                    await reader.cancel(reason);
+                },
+            });
+            const response = await doFetch(request.url, {
+                method: 'POST',
+                headers: request.headers,
+                credentials: 'include',
+                body,
+                duplex: 'half',
+            });
+            scope.postMessage({
+                kind: 'complete',
+                status: response.status,
+                body: await response.text(),
+            });
+        })().catch((error) => {
+            scope.postMessage({
+                kind: 'error',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+    };
+}
+/** Cordis service that owns one background carrier per upload operation. */
+export class FileUploadRuntime extends Service {
+    available;
+    transport;
+    /** @param ctx - providing Client context. */
+    constructor(ctx) {
+        super(ctx, 'fileUpload');
+        const hook = globalThis.__DSH_FILE_UPLOAD__;
+        this.available = hook !== undefined || !isFixturePage();
+        this.transport = hook === undefined ? workerTransport() : customTransport(hook.fetch);
+    }
+    /**
+     * Post one body with the carrier selected before Cordis boot.
+     * @param request - target, body, cancellation, and progress observer.
+     * @returns the response status and text body.
+     */
+    post(request) {
+        if (!this.available)
+            return Promise.reject(new Error('background upload is unavailable in fixture mode'));
+        return this.transport.post(request);
+    }
+    /**
+     * Store one file for a Session.
+     * @param sessionId - Session that owns the staged receipt.
+     * @param data - browser Blob, exact bytes, or a one-shot byte stream.
+     * @param name - optional display name.
+     * @param signal - optional cancellation for the active upload.
+     * @param onProgress - optional byte-progress observer for background bodies.
+     * @returns the staged receipt and durable file reference, or a business error.
+     */
+    async upload(sessionId, data, name, signal, onProgress) {
+        if (!(data instanceof Uint8Array) && this.available) {
+            const query = new URLSearchParams({ sessionId });
+            if (name !== undefined)
+                query.set('name', name);
+            const response = await this.post({
+                path: `${FILE_UPLOAD_PATH}?${query.toString()}`,
+                body: data,
+                headers: { 'content-type': 'application/octet-stream' },
+                ...(signal === undefined ? {} : { signal }),
+                ...(onProgress === undefined ? {} : { onProgress }),
+            });
+            if (response.status !== 200) {
+                throw new Error(`file upload transport failed with HTTP ${String(response.status)}`);
+            }
+            return parseFileUploadResult(response.body);
+        }
+        if (!(data instanceof Uint8Array) && !(data instanceof Blob)) {
+            throw new Error('stream file upload requires a background carrier');
+        }
+        const bytes = data instanceof Uint8Array ? data : new Uint8Array(await data.arrayBuffer());
+        return this.ctx.remote.fileUploads.upload(sessionId, {
+            data: bytesToBase64(bytes),
+            ...(name === undefined ? {} : { name }),
+        }, signal);
+    }
+}
+function customTransport(customFetch) {
+    return {
+        async post(request) {
+            const init = {
+                method: 'POST',
+                ...(request.headers === undefined ? {} : { headers: request.headers }),
+                body: request.body,
+                ...(request.body instanceof ReadableStream ? { duplex: 'half' } : {}),
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            };
+            const response = await customFetch(resolveUrl(request.path), init);
+            return { status: response.status, body: await response.text() };
+        },
+    };
+}
+function workerTransport() {
+    return {
+        post(request) {
+            if (typeof Worker !== 'function') {
+                return Promise.reject(new Error('background upload requires Web Worker support'));
+            }
+            const workerUrl = URL.createObjectURL(new Blob([
+                `(${fileUploadWorker.toString()})()`,
+            ], { type: 'text/javascript' }));
+            const worker = new Worker(workerUrl, { name: 'dsh-file-upload' });
+            URL.revokeObjectURL(workerUrl);
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                const abort = () => {
+                    settled = true;
+                    worker.terminate();
+                    request.signal?.removeEventListener('abort', abort);
+                    reject(new DOMException('The operation was aborted.', 'AbortError'));
+                };
+                const finish = (settle) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    request.signal?.removeEventListener('abort', abort);
+                    worker.terminate();
+                    settle();
+                };
+                worker.onmessage = (event) => {
+                    const output = event.data;
+                    if (output.kind === 'progress') {
+                        request.onProgress?.({
+                            loaded: output.loaded,
+                            ...(output.total === undefined ? {} : { total: output.total }),
+                        });
+                    }
+                    else if (output.kind === 'complete') {
+                        finish(() => { resolve({ status: output.status, body: output.body }); });
+                    }
+                    else {
+                        finish(() => { reject(new Error(output.message)); });
+                    }
+                };
+                worker.onerror = (event) => {
+                    finish(() => { reject(new Error(event.message || 'background upload worker failed')); });
+                };
+                if (request.signal?.aborted === true) {
+                    abort();
+                    return;
+                }
+                request.signal?.addEventListener('abort', abort, { once: true });
+                const message = {
+                    url: resolveUrl(request.path).href,
+                    body: request.body,
+                    headers: request.headers ?? {},
+                };
+                if (request.body instanceof ReadableStream)
+                    worker.postMessage(message, [request.body]);
+                else
+                    worker.postMessage(message);
+            });
+        },
+    };
+}
+function resolveUrl(path) {
+    const pageLocation = Reflect.get(globalThis, 'location');
+    const origin = typeof pageLocation === 'object' && pageLocation !== null
+        && 'origin' in pageLocation && typeof pageLocation.origin === 'string'
+        ? pageLocation.origin
+        : undefined;
+    return new URL(path, origin === undefined || origin === 'null' ? 'http://dsh.internal' : origin);
+}
+function isFixturePage() {
+    const pageLocation = Reflect.get(globalThis, 'location');
+    return typeof pageLocation === 'object' && pageLocation !== null
+        && 'search' in pageLocation && typeof pageLocation.search === 'string'
+        && new URLSearchParams(pageLocation.search).has('fixture');
+}
+function parseFileUploadResult(body) {
+    const value = JSON.parse(body);
+    if (!isRecord(value) || typeof value.ok !== 'boolean') {
+        throw new TypeError('file upload transport returned an invalid result');
+    }
+    if (!value.ok) {
+        const error = value.error;
+        if (!isRecord(error) || typeof error.code !== 'string'
+            || typeof error.message !== 'string' || !isRecord(error.details)) {
+            throw new TypeError('file upload transport returned an invalid failure');
+        }
+        return {
+            ok: false,
+            error: new RemoteError(error.code, error.message, error.details),
+        };
+    }
+    const result = value.value;
+    const file = isRecord(result) ? result.file : undefined;
+    if (!isRecord(result) || typeof result.receiptId !== 'string' || !isRecord(file)
+        || typeof file.attachmentId !== 'string' || typeof file.name !== 'string'
+        || typeof file.bytes !== 'number' || !Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+        throw new TypeError('file upload transport returned an invalid receipt');
+    }
+    return {
+        ok: true,
+        value: {
+            receiptId: result.receiptId,
+            file: {
+                attachmentId: file.attachmentId,
+                name: file.name,
+                bytes: file.bytes,
+            },
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=runtime.js.map

package/lib/types/http-route.d.ts

@@ -0,0 +1,10 @@
+/** Authenticated raw-byte upload route registered on the Connection fetch registry. */
+import type { FileUploads } from './index.ts';
+/**
+ * Handle one authenticated raw-byte upload.
+ * @param service - Host upload service receiving streamed bytes.
+ * @param request - authenticated HTTP request from Connection.
+ * @returns JSON result using HTTP status 200 after request validation.
+ */
+export declare function handleFileUploadHttp(service: FileUploads, request: Request): Promise<Response>;
+//# sourceMappingURL=http-route.d.ts.map

package/lib/types/http-route.js

@@ -0,0 +1,73 @@
+/** Authenticated raw-byte upload route registered on the Connection fetch registry. */
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol';
+/**
+ * Handle one authenticated raw-byte upload.
+ * @param service - Host upload service receiving streamed bytes.
+ * @param request - authenticated HTTP request from Connection.
+ * @returns JSON result using HTTP status 200 after request validation.
+ */
+export async function handleFileUploadHttp(service, request) {
+    if (request.method !== 'POST') {
+        return new Response(null, { status: 405, headers: { allow: 'POST' } });
+    }
+    const mediaType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+    if (mediaType !== 'application/octet-stream') {
+        return new Response('content type must be application/octet-stream', { status: 415 });
+    }
+    const url = new URL(request.url);
+    const sessionId = url.searchParams.get('sessionId');
+    if (sessionId === null || sessionId === '') {
+        return new Response('sessionId is required', { status: 400 });
+    }
+    const name = url.searchParams.get('name') ?? undefined;
+    let result;
+    try {
+        result = {
+            ok: true,
+            value: await service.uploadStream({
+                sessionId: brandString(sessionId),
+                data: requestBodyChunks(request.body),
+                signal: request.signal,
+                ...(name === undefined ? {} : { name }),
+            }),
+        };
+    }
+    catch (error) {
+        const failure = remoteErrorOf(error);
+        result = {
+            ok: false,
+            error: failure !== undefined
+                ? { code: failure.code, message: failure.message, details: failure.details }
+                : {
+                    code: 'gateway/internal',
+                    message: error instanceof Error ? error.message : String(error),
+                    details: {},
+                },
+        };
+    }
+    return new Response(JSON.stringify(result), {
+        status: 200,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+        },
+    });
+}
+async function* requestBodyChunks(body) {
+    if (body === null)
+        return;
+    const reader = body.getReader();
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                return;
+            yield chunk.value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=http-route.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,84 @@
+/** Host file-upload service: streamed intake and Agent-scoped staged receipts. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { EncodedFileUploadRequest, FileUploadReceiptId, FileUploadValue } from './types.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Host storage and staged-receipt service for browser file uploads. */
+        fileUploads: FileUploads;
+    }
+}
+/** Resolve or resume the ordinary Agent that owns one Session identity. */
+export type AgentResolver = (sessionId: SessionId) => Promise<Agent>;
+/** Prompt receipt binding that restores its previous owners unless delivery commits it. */
+export interface PromptFileBinding extends Disposable {
+    /** Keep the receipt bindings until queue or history observation retires them. */
+    commit(): void;
+}
+/** Host service owning upload storage and Agent-scoped staged receipts. */
+export declare class FileUploads extends TypertRemoteService {
+    static inject: string[];
+    private readonly stagedFiles;
+    private agentResolver;
+    /** @param ctx - Host context carrying Agent, attachment, command, and Connection services. */
+    constructor(ctx: Context);
+    /**
+     * Register the ordinary-Session resolver used when a raw upload addresses a cold Session.
+     * @param resolve - resolver that returns the exact live Agent or throws a Remote error.
+     * @returns disposer removing this resolver.
+     */
+    registerAgentResolver(resolve: AgentResolver): () => void;
+    /**
+     * Persist one encoded upload and stage it under the Agent receiver selected by Typert.
+     * @param agent - receiving Agent resolved from the Remote Agent scope.
+     * @param request - canonical base64 bytes and optional display name.
+     * @param signal - caller cancellation before storage begins.
+     * @returns the staged receipt and durable file reference.
+     */
+    upload(agent: Agent, request: EncodedFileUploadRequest, signal: AbortSignal): Promise<FileUploadValue>;
+    /**
+     * Persist raw chunks for one Session without aggregating the upload.
+     * @param request - Session identity, ordered bytes, cancellation, and optional display name.
+     * @returns the staged receipt and durable file reference.
+     */
+    uploadStream(request: {
+        readonly sessionId: SessionId;
+        readonly data: AsyncIterable<Uint8Array>;
+        readonly signal?: AbortSignal;
+        readonly name?: string;
+    }): Promise<FileUploadValue>;
+    /**
+     * Resolve one staged receipt inside its receiving Agent scope.
+     * @param agent - receiving Agent.
+     * @param receiptId - opaque receipt minted for one completed upload.
+     * @returns durable file reference, or `undefined` for an unknown or foreign receipt.
+     */
+    resolve(agent: Agent, receiptId: FileUploadReceiptId): FileAttachmentRef | undefined;
+    /**
+     * Bind receipts while one prompt enters an Agent inbox.
+     * Disposal restores every prior binding unless the caller commits successful delivery.
+     * @param agent - receiving Agent.
+     * @param receiptIds - distinct staged receipts referenced by the prompt.
+     * @param requestId - prompt identity later observed in queue or history.
+     * @returns binding kept after commit until queue or history observation retires its receipts.
+     */
+    bindPrompt(agent: Agent, receiptIds: readonly FileUploadReceiptId[], requestId: string): PromptFileBinding;
+    /**
+     * Retire every receipt accepted by one removed queue occurrence.
+     * @param agent - receiving Agent.
+     * @param requestId - prompt identity carried by the queue occurrence.
+     */
+    retirePrompt(agent: Agent, requestId: string): void;
+    private commit;
+    private resolveAgent;
+    private assertAgentScope;
+    private assertOrdinaryAgent;
+    private observeSessionEvent;
+    private retire;
+}
+export default FileUploads;
+//# sourceMappingURL=index.d.ts.map