@atalk/sdk 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/agent.js

@@ -1,16 +1,40 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, resolve } from "node:path";
-import { decodeAttachmentMessage, decodeDirectedMessage, decryptAttachment, attachmentPartDescriptors, encodeAgentActivity, encodeAttachmentMessage, encryptAttachment, joinEncryptedAttachmentParts, serverFrameSchema, splitEncryptedAttachment, } from "@atalk/protocol";
+import { decodeAttachmentMessage, createChunkedAttachmentDescriptor, decryptAttachmentChunk, decodeDirectedMessage, decryptAttachment, attachmentPartDescriptors, encodeAgentActivity, encodeAttachmentMessage, encryptAttachment, encryptAttachmentChunk, joinEncryptedAttachmentParts, serverFrameSchema, splitEncryptedAttachment, } from "@atalk/protocol";
 import WebSocket from "ws";
-import { FileCredentialStore } from "./credential-store.js";
+import { FileCredentialStore, } from "./credential-store.js";
 import { decryptTextNative, encryptTextNative, generateIdentityKeysNative } from "./native-core.js";
+import { emptyRuntimeState, FileRuntimeStateStore, MemoryRuntimeStateStore, } from "./runtime-state-store.js";
+import { WorkroomClient } from "./workrooms.js";
+const MAX_PROCESSED_INCOMING = 10_000;
+const DEFAULT_REFRESH_LEEWAY_MS = 5 * 60_000;
+const FATAL_SESSION_CODES = new Set([
+    "AUTH_REQUIRED",
+    "INVALID_REFRESH_TOKEN",
+    "INVALID_SESSION",
+    "PEER_INACTIVE",
+]);
 export class Agent {
+    /** Durable, E2EE task/workroom API for this agent identity. */
+    workrooms;
     baseUrl;
     activationToken;
     credentialStore;
+    runtimeStateStore;
+    credentialRefresher;
+    usesDefaultCredentialRefresher;
+    refreshLeewayMs;
     supervisionEnabled;
     credentials;
+    runtimeState = emptyRuntimeState();
+    stateMutation = Promise.resolve();
+    refreshPromise;
+    outboxDrain;
+    inboxDrain;
+    inboxRetryTimer;
+    inboxRetryAttempt = 0;
+    sentThisConnection = new Set();
     socket;
     ready = false;
     reconnectAttempt = 0;
@@ -19,11 +43,31 @@ export class Agent {
     errorHandler;
     supervisors = [];
     counterparties = new Map();
+    processingIncoming = new Map();
     constructor(options) {
         this.activationToken = options.token;
         this.baseUrl = (options.baseUrl ?? "http://127.0.0.1:4001").replace(/\/$/u, "");
         this.credentialStore = options.credentialStore ?? new FileCredentialStore(options.token, options.credentialPath);
+        this.runtimeStateStore = options.runtimeStateStore
+            ?? (options.runtimeStatePath
+                ? new FileRuntimeStateStore(options.runtimeStatePath)
+                : this.credentialStore instanceof FileCredentialStore
+                    ? new FileRuntimeStateStore(`${this.credentialStore.path}.runtime.json`)
+                    : new MemoryRuntimeStateStore());
+        this.usesDefaultCredentialRefresher = !options.refreshCredentials;
+        this.credentialRefresher = options.refreshCredentials ?? refreshAtalkCredentials;
+        this.refreshLeewayMs = Math.max(0, options.refreshLeewayMs ?? DEFAULT_REFRESH_LEEWAY_MS);
         this.supervisionEnabled = options.supervision ?? true;
+        this.workrooms = new WorkroomClient({
+            request: (path, init) => this.request(path, init),
+            credentials: () => this.requireCredentials(),
+            runtimeState: () => this.runtimeState,
+            mutateRuntimeState: (mutator) => this.mutateRuntimeState(mutator),
+            uploadPart: (scope, id, bytes, transfer) => this.uploadAttachment(scope, id, bytes, transfer),
+            deletePart: (id) => this.deleteAttachmentPart(id),
+            downloadAttachment: (descriptor) => this.downloadAttachment(descriptor),
+            downloadAttachmentTo: (descriptor, path, transfer) => this.downloadAttachmentTo(descriptor, path, transfer),
+        });
     }
     get connected() {
         return this.ready && this.socket?.readyState === WebSocket.OPEN;
@@ -40,18 +84,37 @@ export class Agent {
     }
     async start() {
         this.stopped = false;
-        this.credentials = (await this.credentialStore.load()) ?? (await this.activate());
-        if (this.supervisionEnabled) {
-            const result = await this.request("/v1/agent-runtime/supervisors");
-            this.supervisors = result.supervisors;
+        this.inboxRetryAttempt = 0;
+        this.runtimeState = (await this.runtimeStateStore.load()) ?? emptyRuntimeState();
+        const persistedCredentials = await this.credentialStore.load();
+        this.credentials = persistedCredentials ?? (await this.activate());
+        this.counterparties.clear();
+        for (const [conversationId, peer] of Object.entries(this.runtimeState.counterparties)) {
+            this.counterparties.set(conversationId, peer);
+        }
+        try {
+            await this.prepareAndConnect();
+        }
+        catch (error) {
+            // A newly issued connection code is also the recovery path after an
+            // owner revoked this runtime's sessions. Reuse the locally persisted
+            // identity keys: silently generating a new pair would strand encrypted
+            // Task history and change the agent's cryptographic identity.
+            if (!persistedCredentials || !this.activationToken || !isSessionError(error))
+                throw error;
+            this.credentials = await this.activate(persistedCredentials.keys);
+            await this.prepareAndConnect();
         }
-        await this.connect();
     }
     async stop() {
         this.stopped = true;
         this.ready = false;
         this.reconnectAttempt = 0;
+        if (this.inboxRetryTimer)
+            clearTimeout(this.inboxRetryTimer);
+        this.inboxRetryTimer = undefined;
         this.socket?.close(1000, "Agent stopped");
+        await this.stateMutation;
     }
     async send(recipientHandle, text) {
         return (await this.sendWithDetails(recipientHandle, text)).conversationId;
@@ -78,31 +141,82 @@ export class Agent {
         return (await this.sendAttachmentFileWithDetails(recipientHandle, input)).conversationId;
     }
     async sendAttachmentFileWithDetails(recipientHandle, input) {
-        return this.sendAttachmentWithDetails(recipientHandle, await attachmentInputFromFile(input));
+        const conversationId = randomUUID();
+        const messageId = await this.sendAttachmentFileEnvelope(recipientHandle, input, conversationId);
+        return { conversationId, messageId };
     }
     async sendAttachmentInConversation(recipientHandle, input, conversationId) {
         return this.sendAttachmentEnvelope(recipientHandle, input, conversationId);
     }
     async sendAttachmentFileInConversation(recipientHandle, input, conversationId) {
-        return this.sendAttachmentInConversation(recipientHandle, await attachmentInputFromFile(input), conversationId);
+        return this.sendAttachmentFileEnvelope(recipientHandle, input, conversationId);
+    }
+    /** Download an attachment descriptor retained by a durable bridge. */
+    async downloadAttachment(descriptor) {
+        const parts = [];
+        for (const part of attachmentPartDescriptors(descriptor)) {
+            const response = await this.authorizedFetch(`${this.baseUrl}/v1/attachments/${part.id}`);
+            if (!response.ok)
+                throw await responseError(response);
+            parts.push(new Uint8Array(await response.arrayBuffer()));
+        }
+        return decryptAttachment(joinEncryptedAttachmentParts(parts, descriptor), descriptor);
     }
-    async activate() {
+    /** Stream-decrypt an attachment into an atomic local file without buffering the whole payload. */
+    async downloadAttachmentTo(descriptor, filePath, options) {
+        return this.downloadAttachmentToFile(descriptor, filePath, options);
+    }
+    /** Mark an incoming message as read when only its durable id is available. */
+    async markMessageRead(messageId) {
+        await this.completeIncoming(messageId, "READ");
+        this.sendFrame({ kind: "ACK", messageId, state: "READ" });
+        this.scheduleInboxRetry();
+    }
+    async activate(existingKeys) {
         if (!this.activationToken) {
             throw new Error("ACTIVATION_REQUIRED: Provide a one-time token because no persisted credentials were found");
         }
-        const keys = generateIdentityKeysNative();
+        const remembered = this.runtimeState.pendingActivation;
+        const pending = remembered && (!existingKeys || sameIdentityKeys(remembered.keys, existingKeys))
+            ? remembered
+            : {
+                requestId: randomUUID(),
+                keys: existingKeys ?? generateIdentityKeysNative(),
+            };
+        if (pending !== remembered) {
+            await this.mutateRuntimeState((state) => { state.pendingActivation = pending; });
+        }
         const response = await this.request("/v1/agents/activate", {
             method: "POST",
             body: JSON.stringify({
                 activationToken: this.activationToken,
-                signingPublicKey: keys.signingPublicKey,
-                encryptionPublicKey: keys.encryptionPublicKey,
+                activationRequestId: pending.requestId,
+                signingPublicKey: pending.keys.signingPublicKey,
+                encryptionPublicKey: pending.keys.encryptionPublicKey,
             }),
         }, false);
-        const credentials = { sessionToken: response.token, peer: response.peer, keys };
+        const access = response.accessToken ?? response.token;
+        const accessTokenExpiresAt = response.accessTokenExpiresAt ?? response.expiresAt;
+        const credentials = {
+            sessionToken: access,
+            accessToken: access,
+            ...(response.refreshToken ? { refreshToken: response.refreshToken } : {}),
+            ...(accessTokenExpiresAt ? { accessTokenExpiresAt } : {}),
+            peer: response.peer,
+            keys: pending.keys,
+        };
         await this.credentialStore.save(credentials);
+        await this.mutateRuntimeState((state) => { delete state.pendingActivation; });
         return credentials;
     }
+    async prepareAndConnect() {
+        await this.refreshCredentialsIfNeeded("EXPIRING");
+        if (this.supervisionEnabled) {
+            const result = await this.request("/v1/agent-runtime/supervisors");
+            this.supervisors = result.supervisors;
+        }
+        await this.connectWithRefresh();
+    }
     async connect() {
         const credentials = this.requireCredentials();
         const websocketUrl = `${this.baseUrl.replace(/^http/u, "ws")}/v1/ws`;
@@ -117,7 +231,7 @@ export class Agent {
                     reject(new Error("aTalk connection timed out"));
                 }
             }, 10_000);
-            socket.on("open", () => socket.send(JSON.stringify({ kind: "AUTH", token: credentials.sessionToken })));
+            socket.on("open", () => socket.send(JSON.stringify({ kind: "AUTH", token: accessToken(credentials) })));
             socket.on("message", (raw) => {
                 const frame = serverFrameSchema.parse(JSON.parse(raw.toString()));
                 void this.handleFrame(frame).then(() => {
@@ -125,8 +239,11 @@ export class Agent {
                         ready = true;
                         this.ready = true;
                         this.reconnectAttempt = 0;
+                        this.sentThisConnection.clear();
                         clearTimeout(timeout);
                         resolve();
+                        void this.drainOutbox().catch((error) => this.emitError(error));
+                        void this.drainInbox();
                     }
                 }).catch((error) => {
                     if (!ready) {
@@ -136,6 +253,7 @@ export class Agent {
                     }
                     else {
                         this.emitError(error);
+                        this.scheduleInboxRetry();
                     }
                 });
             });
@@ -151,15 +269,14 @@ export class Agent {
                 if (this.socket === socket)
                     this.ready = false;
                 if (!ready) {
-                    const error = new Error(code === 4001 || code === 1008 ? "INVALID_SESSION: Agent credentials were revoked" : "aTalk connection closed before authentication");
-                    if (code === 4001 || code === 1008)
-                        this.stopped = true;
+                    const error = code === 4001 || code === 1008
+                        ? new AgentProtocolError("INVALID_SESSION", "Agent credentials were rejected")
+                        : new Error("aTalk connection closed before authentication");
                     reject(error);
                     return;
                 }
                 if (code === 4001 || code === 1008) {
-                    this.stopped = true;
-                    this.emitError(new Error("INVALID_SESSION: Agent credentials were revoked"));
+                    void this.recoverRejectedSession();
                     return;
                 }
                 if (!this.stopped && ready)
@@ -174,7 +291,9 @@ export class Agent {
         setTimeout(() => {
             if (this.stopped)
                 return;
-            void this.connect().catch((error) => {
+            void this.connectWithRefresh().catch((error) => {
+                if (isSessionError(error))
+                    this.stopped = true;
                 this.emitError(error);
                 if (!this.stopped)
                     this.scheduleReconnect();
@@ -182,16 +301,45 @@ export class Agent {
         }, delay);
     }
     async handleFrame(frame) {
-        if (frame.kind === "ERROR")
-            throw new Error(`${frame.code}: ${frame.message}`);
+        if (frame.kind === "ERROR") {
+            throw new AgentProtocolError(frame.code, frame.message);
+        }
         if (frame.kind === "RECEIPT") {
+            await this.removeFromOutbox(frame.messageId);
             this.sendFrame({ kind: "RECEIPT_ACK", messageId: frame.messageId, state: frame.state });
             return;
         }
+        if (frame.kind === "ACK_RECEIVED") {
+            await this.forgetIncoming(frame.messageId);
+            return;
+        }
         if (frame.kind !== "MESSAGE")
             return;
+        const messageId = frame.envelope.message_id;
+        const confirmed = this.runtimeState.processedIncoming[messageId];
+        if (confirmed) {
+            this.sendFrame({ kind: "ACK", messageId, state: confirmed });
+            this.scheduleInboxRetry();
+            return;
+        }
+        await this.rememberIncoming(frame.envelope);
+        const existing = this.processingIncoming.get(messageId);
+        if (existing) {
+            await existing;
+            return;
+        }
+        const processing = this.processIncomingMessage(frame);
+        this.processingIncoming.set(messageId, processing);
+        try {
+            await processing;
+        }
+        finally {
+            this.processingIncoming.delete(messageId);
+        }
+    }
+    async processIncomingMessage(frame) {
         const credentials = this.requireCredentials();
-        const sender = await this.request(`/v1/peers/${frame.envelope.sender_peer_id}/keys`);
+        const sender = await this.request(`/v1/messages/${frame.envelope.message_id}/sender-keys`);
         const text = decryptTextNative({
             envelope: frame.envelope,
             senderSigningPublicKey: sender.signingPublicKey,
@@ -202,61 +350,76 @@ export class Agent {
         const content = directedMessage?.content ?? text;
         const attachmentMessage = decodeAttachmentMessage(content);
         const isSupervisor = this.supervisors.some((supervisor) => supervisor.id === sender.id);
+        const isMentioned = directedMessage?.mentions.some((mention) => mention.peerId === credentials.peer.id) ?? false;
+        const counterparty = isSupervisor ? this.counterparties.get(frame.envelope.conversation_id) : sender;
+        const routing = isSupervisor && !isMentioned
+            ? { mode: "RELAY", targetHandle: counterparty?.handle ?? "" }
+            : { mode: "REPLY", targetHandle: sender.handle };
         if (!isSupervisor) {
             this.counterparties.set(frame.envelope.conversation_id, sender);
-            await this.mirrorActivity("INCOMING", sender, text, frame.envelope.conversation_id, frame.envelope.message_id, frame.envelope.timestamp);
-        }
-        this.sendFrame({ kind: "ACK", messageId: frame.envelope.message_id, state: "DELIVERED" });
-        if (this.messageHandler) {
-            await this.messageHandler({
-                id: frame.envelope.message_id,
-                conversationId: frame.envelope.conversation_id,
-                text: attachmentMessage?.caption ?? (attachmentMessage ? "" : content),
-                ...(attachmentMessage ? { attachment: {
-                        descriptor: attachmentMessage.attachment,
-                        download: () => this.downloadAttachment(attachmentMessage.attachment),
-                        downloadTo: (filePath) => this.downloadAttachmentToFile(attachmentMessage.attachment, filePath),
-                    } } : {}),
-                sender,
-                receivedAt: new Date(frame.envelope.timestamp),
-                isSupervisor,
-                mentions: directedMessage?.mentions ?? [],
-                isMentioned: directedMessage?.mentions.some((mention) => mention.peerId === credentials.peer.id) ?? false,
-                reply: (replyText) => this.sendEnvelope(sender.handle, replyText, frame.envelope.conversation_id),
-                replyAttachment: (input) => this.sendAttachmentEnvelope(sender.handle, input, frame.envelope.conversation_id),
-                replyAttachmentFile: async (input) => this.sendAttachmentEnvelope(sender.handle, await attachmentInputFromFile(input), frame.envelope.conversation_id),
-                relay: async (relayText) => {
-                    if (!isSupervisor)
-                        throw new Error("Only supervisor messages can be relayed");
-                    const counterparty = this.counterparties.get(frame.envelope.conversation_id);
-                    if (!counterparty)
-                        throw new Error("No active counterparty exists for this supervised conversation");
-                    return this.sendEnvelope(counterparty.handle, relayText, frame.envelope.conversation_id);
-                },
-                relayAttachment: async (input) => {
-                    if (!isSupervisor)
-                        throw new Error("Only supervisor messages can be relayed");
-                    const counterparty = this.counterparties.get(frame.envelope.conversation_id);
-                    if (!counterparty)
-                        throw new Error("No active counterparty exists for this supervised conversation");
-                    return this.sendAttachmentEnvelope(counterparty.handle, input, frame.envelope.conversation_id);
-                },
-                relayAttachmentFile: async (input) => {
-                    if (!isSupervisor)
-                        throw new Error("Only supervisor messages can be relayed");
-                    const counterparty = this.counterparties.get(frame.envelope.conversation_id);
-                    if (!counterparty)
-                        throw new Error("No active counterparty exists for this supervised conversation");
-                    return this.sendAttachmentEnvelope(counterparty.handle, await attachmentInputFromFile(input), frame.envelope.conversation_id);
-                },
-                markRead: async () => this.sendFrame({ kind: "ACK", messageId: frame.envelope.message_id, state: "READ" }),
+            await this.mutateRuntimeState((state) => {
+                state.counterparties[frame.envelope.conversation_id] = sender;
             });
+            await this.mirrorActivity("INCOMING", sender, text, frame.envelope.conversation_id, frame.envelope.message_id, frame.envelope.timestamp);
         }
+        if (!this.messageHandler)
+            throw new Error("MESSAGE_HANDLER_NOT_CONFIGURED: Register a message handler before start()");
+        let acknowledgedState = "DELIVERED";
+        let handlerComplete = false;
+        await this.messageHandler({
+            id: frame.envelope.message_id,
+            conversationId: frame.envelope.conversation_id,
+            text: attachmentMessage?.caption ?? (attachmentMessage ? "" : content),
+            ...(attachmentMessage ? { attachment: {
+                    descriptor: attachmentMessage.attachment,
+                    download: () => this.downloadAttachment(attachmentMessage.attachment),
+                    downloadTo: (filePath, options) => this.downloadAttachmentToFile(attachmentMessage.attachment, filePath, options),
+                } } : {}),
+            sender,
+            receivedAt: new Date(frame.envelope.timestamp),
+            isSupervisor,
+            mentions: directedMessage?.mentions ?? [],
+            isMentioned,
+            reply: (replyText) => this.sendEnvelope(sender.handle, replyText, frame.envelope.conversation_id),
+            replyAttachment: (input) => this.sendAttachmentEnvelope(sender.handle, input, frame.envelope.conversation_id),
+            replyAttachmentFile: (input) => this.sendAttachmentFileEnvelope(sender.handle, input, frame.envelope.conversation_id),
+            relay: async (relayText) => {
+                if (!isSupervisor)
+                    throw new Error("Only supervisor messages can be relayed");
+                if (!counterparty)
+                    throw new Error("No active counterparty exists for this supervised conversation");
+                return this.sendEnvelope(counterparty.handle, relayText, frame.envelope.conversation_id);
+            },
+            relayAttachment: async (input) => {
+                if (!isSupervisor)
+                    throw new Error("Only supervisor messages can be relayed");
+                if (!counterparty)
+                    throw new Error("No active counterparty exists for this supervised conversation");
+                return this.sendAttachmentEnvelope(counterparty.handle, input, frame.envelope.conversation_id);
+            },
+            relayAttachmentFile: async (input) => {
+                if (!isSupervisor)
+                    throw new Error("Only supervisor messages can be relayed");
+                if (!counterparty)
+                    throw new Error("No active counterparty exists for this supervised conversation");
+                return this.sendAttachmentFileEnvelope(counterparty.handle, input, frame.envelope.conversation_id);
+            },
+            markRead: async () => {
+                if (!handlerComplete) {
+                    acknowledgedState = "READ";
+                    return;
+                }
+                await this.markMessageRead(frame.envelope.message_id);
+            },
+            routing,
+        });
+        handlerComplete = true;
+        await this.completeIncoming(frame.envelope.message_id, acknowledgedState);
+        this.sendFrame({ kind: "ACK", messageId: frame.envelope.message_id, state: acknowledgedState });
+        this.scheduleInboxRetry();
     }
     async sendEnvelope(recipientHandle, text, conversationId) {
         const credentials = this.requireCredentials();
-        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
-            throw new Error("Agent is not connected");
         const { recipient } = await this.request("/v1/messages/authorize", {
             method: "POST",
             body: JSON.stringify({ recipientHandle }),
@@ -272,18 +435,21 @@ export class Agent {
             senderEncryptionSecretKey: credentials.keys.encryptionSecretKey,
             recipientEncryptionPublicKey: recipient.encryptionPublicKey,
         });
-        this.sendFrame({ kind: "DELIVER", envelope });
         const isSupervisor = this.supervisors.some((supervisor) => supervisor.id === recipient.id);
         if (!isSupervisor) {
             this.counterparties.set(conversationId, recipient);
+            await this.mutateRuntimeState((state) => {
+                state.counterparties[conversationId] = recipient;
+            });
+        }
+        await this.queueEnvelope(envelope);
+        if (!isSupervisor) {
             await this.mirrorActivity("OUTGOING", recipient, text, conversationId, envelope.message_id, envelope.timestamp);
         }
         return envelope.message_id;
     }
     async sendAttachmentEnvelope(recipientHandle, input, conversationId) {
         const credentials = this.requireCredentials();
-        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
-            throw new Error("Agent is not connected");
         const { recipient } = await this.request("/v1/messages/authorize", {
             method: "POST",
             body: JSON.stringify({ recipientHandle }),
@@ -295,7 +461,7 @@ export class Agent {
             mimeType: input.mimeType ?? "application/octet-stream",
         }), randomUUID);
         for (const part of encrypted.parts) {
-            await this.uploadAttachment(recipient.id, part.id, part.ciphertext);
+            await this.uploadAttachment({ recipientPeerId: recipient.id }, part.id, part.ciphertext);
         }
         const caption = input.caption?.trim();
         const plaintext = encodeAttachmentMessage({
@@ -313,43 +479,200 @@ export class Agent {
             senderEncryptionSecretKey: credentials.keys.encryptionSecretKey,
             recipientEncryptionPublicKey: recipient.encryptionPublicKey,
         });
-        this.sendFrame({ kind: "DELIVER", envelope });
         const isSupervisor = this.supervisors.some((supervisor) => supervisor.id === recipient.id);
         if (!isSupervisor) {
             this.counterparties.set(conversationId, recipient);
+            await this.mutateRuntimeState((state) => {
+                state.counterparties[conversationId] = recipient;
+            });
+        }
+        await this.queueEnvelope(envelope);
+        if (!isSupervisor) {
             await this.mirrorActivity("OUTGOING", recipient, plaintext, conversationId, envelope.message_id, envelope.timestamp);
         }
         return envelope.message_id;
     }
-    async uploadAttachment(recipientPeerId, attachmentId, ciphertext) {
-        const response = await fetch(`${this.baseUrl}/v1/attachments/${attachmentId}?recipientPeerId=${encodeURIComponent(recipientPeerId)}`, {
+    async sendAttachmentFileEnvelope(recipientHandle, input, conversationId) {
+        const credentials = this.requireCredentials();
+        const path = resolve(input.path);
+        const metadata = await stat(path);
+        if (!metadata.isFile())
+            throw new Error("ATTACHMENT_NOT_A_FILE");
+        const { recipient } = await this.request("/v1/messages/authorize", {
             method: "POST",
-            headers: {
-                authorization: `Bearer ${this.requireCredentials().sessionToken}`,
-                "content-type": "application/octet-stream",
-            },
-            body: exactArrayBuffer(ciphertext),
+            body: JSON.stringify({ recipientHandle }),
         });
-        if (!response.ok)
-            throw await responseError(response);
+        const descriptor = createChunkedAttachmentDescriptor({
+            id: randomUUID(),
+            size: metadata.size,
+            name: input.name?.trim() || basename(path),
+            mimeType: input.mimeType?.trim() || mimeTypeFromPath(path),
+            nextId: randomUUID,
+        });
+        if (descriptor.version !== 2)
+            throw new Error("ATTACHMENT_VERSION_UNSUPPORTED");
+        const file = await open(path, "r");
+        let transferred = 0;
+        try {
+            for (let index = 0; index < descriptor.chunks.length; index += 1) {
+                throwIfAborted(input.transfer?.signal);
+                const part = descriptor.chunks[index];
+                const plaintext = new Uint8Array(part.plaintextSize);
+                const { bytesRead } = await file.read(plaintext, 0, plaintext.byteLength, transferred);
+                if (bytesRead !== plaintext.byteLength)
+                    throw new Error("ATTACHMENT_SIZE_MISMATCH");
+                await this.uploadAttachment({ recipientPeerId: recipient.id }, part.id, encryptAttachmentChunk(plaintext, descriptor, index), input.transfer);
+                transferred += bytesRead;
+                input.transfer?.onProgress?.({
+                    phase: "UPLOADING",
+                    bytesTransferred: transferred,
+                    totalBytes: descriptor.size,
+                    partIndex: index + 1,
+                    partCount: descriptor.chunks.length,
+                });
+            }
+        }
+        catch (error) {
+            // Delete every id in the unpublished descriptor. This also removes a part
+            // whose POST reached the server but whose response was lost in transit.
+            await Promise.allSettled(descriptor.chunks.map((part) => this.deleteAttachmentPart(part.id)));
+            throw error;
+        }
+        finally {
+            await file.close();
+        }
+        const caption = input.caption?.trim();
+        const plaintext = encodeAttachmentMessage({ attachment: descriptor, ...(caption ? { caption } : {}) });
+        const envelope = encryptTextNative({
+            messageId: randomUUID(),
+            conversationId,
+            senderPeerId: credentials.peer.id,
+            recipientPeerId: recipient.id,
+            timestamp: new Date().toISOString(),
+            plaintext,
+            senderSigningSecretKey: credentials.keys.signingSecretKey,
+            senderEncryptionSecretKey: credentials.keys.encryptionSecretKey,
+            recipientEncryptionPublicKey: recipient.encryptionPublicKey,
+        });
+        const isSupervisor = this.supervisors.some((supervisor) => supervisor.id === recipient.id);
+        if (!isSupervisor) {
+            this.counterparties.set(conversationId, recipient);
+            await this.mutateRuntimeState((state) => { state.counterparties[conversationId] = recipient; });
+        }
+        await this.queueEnvelope(envelope);
+        if (!isSupervisor) {
+            await this.mirrorActivity("OUTGOING", recipient, plaintext, conversationId, envelope.message_id, envelope.timestamp);
+        }
+        return envelope.message_id;
     }
-    async downloadAttachment(descriptor) {
-        const parts = [];
-        for (const part of attachmentPartDescriptors(descriptor)) {
-            const response = await fetch(`${this.baseUrl}/v1/attachments/${part.id}`, {
-                headers: { authorization: `Bearer ${this.requireCredentials().sessionToken}` },
-            });
-            if (!response.ok)
-                throw await responseError(response);
-            parts.push(new Uint8Array(await response.arrayBuffer()));
+    async uploadAttachment(scope, attachmentId, ciphertext, options) {
+        throwIfAborted(options?.signal);
+        const existing = await this.authorizedFetch(`${this.baseUrl}/v1/attachments/${attachmentId}`, {
+            method: "HEAD", ...(options?.signal ? { signal: options.signal } : {}),
+        }).catch(() => undefined);
+        if (existing?.ok)
+            return;
+        const attempts = Math.max(1, Math.min(5, options?.maxAttempts ?? 3));
+        let lastError;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            throwIfAborted(options?.signal);
+            let response;
+            try {
+                response = await this.authorizedFetch(`${this.baseUrl}/v1/attachments/${attachmentId}?${"recipientPeerId" in scope
+                    ? `recipientPeerId=${encodeURIComponent(scope.recipientPeerId)}`
+                    : `workroomId=${encodeURIComponent(scope.workroomId)}`}`, {
+                    method: "POST",
+                    headers: { "content-type": "application/octet-stream" },
+                    body: exactArrayBuffer(ciphertext),
+                    ...(options?.signal ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                if (options?.signal?.aborted)
+                    throw abortError();
+                lastError = error;
+                if (attempt + 1 < attempts)
+                    await abortableDelay(250 * (2 ** attempt), options?.signal);
+                continue;
+            }
+            if (response.ok)
+                return;
+            lastError = await responseError(response);
+            if (response.status < 500 && response.status !== 429)
+                throw lastError;
+            if (attempt + 1 < attempts)
+                await abortableDelay(250 * (2 ** attempt), options?.signal);
         }
-        return decryptAttachment(joinEncryptedAttachmentParts(parts, descriptor), descriptor);
+        throw lastError instanceof Error ? lastError : new Error("ATTACHMENT_UPLOAD_FAILED");
     }
-    async downloadAttachmentToFile(descriptor, filePath) {
+    async deleteAttachmentPart(id) {
+        await this.authorizedFetch(`${this.baseUrl}/v1/attachments/${id}`, { method: "DELETE" }).catch(() => undefined);
+    }
+    async downloadAttachmentToFile(descriptor, filePath, options) {
         const target = resolve(filePath);
         await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, await this.downloadAttachment(descriptor), { mode: 0o600 });
-        return target;
+        if (descriptor.version === 1) {
+            throwIfAborted(options?.signal);
+            await writeFile(target, await this.downloadAttachment(descriptor), { mode: 0o600 });
+            options?.onProgress?.({ phase: "DOWNLOADING", bytesTransferred: descriptor.size, totalBytes: descriptor.size, partIndex: 1, partCount: 1 });
+            return target;
+        }
+        const chunks = descriptor.chunks;
+        const temporary = `${target}.atalk-${randomUUID()}.part`;
+        const file = await open(temporary, "wx", 0o600);
+        let transferred = 0;
+        try {
+            for (let index = 0; index < chunks.length; index += 1) {
+                throwIfAborted(options?.signal);
+                const part = chunks[index];
+                const ciphertext = await this.downloadAttachmentPart(part.id, options);
+                const plaintext = decryptAttachmentChunk(ciphertext, descriptor, index);
+                await file.write(plaintext);
+                transferred += plaintext.byteLength;
+                options?.onProgress?.({
+                    phase: "DOWNLOADING", bytesTransferred: transferred, totalBytes: descriptor.size,
+                    partIndex: index + 1, partCount: chunks.length,
+                });
+            }
+            await file.sync();
+            await file.close();
+            await rename(temporary, target);
+            return target;
+        }
+        catch (error) {
+            await file.close().catch(() => undefined);
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async downloadAttachmentPart(id, options) {
+        const attempts = Math.max(1, Math.min(5, options?.maxAttempts ?? 3));
+        let lastError;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            throwIfAborted(options?.signal);
+            let response;
+            try {
+                response = await this.authorizedFetch(`${this.baseUrl}/v1/attachments/${id}`, {
+                    ...(options?.signal ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                if (options?.signal?.aborted)
+                    throw abortError();
+                lastError = error;
+                if (attempt + 1 < attempts)
+                    await abortableDelay(250 * (2 ** attempt), options?.signal);
+                continue;
+            }
+            if (response.ok)
+                return new Uint8Array(await response.arrayBuffer());
+            lastError = await responseError(response);
+            if (response.status < 500 && response.status !== 429)
+                throw lastError;
+            if (attempt + 1 < attempts)
+                await abortableDelay(250 * (2 ** attempt), options?.signal);
+        }
+        throw lastError instanceof Error ? lastError : new Error("ATTACHMENT_DOWNLOAD_FAILED");
     }
     async mirrorActivity(direction, counterparty, text, conversationId, sourceMessageId, observedAt) {
         if (!this.supervisionEnabled || this.supervisors.length === 0)
@@ -370,7 +693,7 @@ export class Agent {
         });
         for (const supervisor of this.supervisors) {
             const envelope = encryptTextNative({
-                messageId: randomUUID(),
+                messageId: deterministicUuid(`${sourceMessageId}:${supervisor.id}:${direction}:activity`),
                 conversationId,
                 senderPeerId: credentials.peer.id,
                 recipientPeerId: supervisor.id,
@@ -380,28 +703,241 @@ export class Agent {
                 senderEncryptionSecretKey: credentials.keys.encryptionSecretKey,
                 recipientEncryptionPublicKey: supervisor.encryptionPublicKey,
             });
-            this.sendFrame({ kind: "DELIVER", envelope });
+            await this.queueEnvelope(envelope);
+        }
+    }
+    async queueEnvelope(envelope) {
+        await this.mutateRuntimeState((state) => {
+            if (!state.outbox.some((item) => item.message_id === envelope.message_id))
+                state.outbox.push(envelope);
+        });
+        if (this.connected)
+            await this.drainOutbox();
+    }
+    async removeFromOutbox(messageId) {
+        if (!this.runtimeState.outbox.some((item) => item.message_id === messageId))
+            return;
+        await this.mutateRuntimeState((state) => {
+            state.outbox = state.outbox.filter((item) => item.message_id !== messageId);
+        });
+        this.sentThisConnection.delete(messageId);
+    }
+    async drainOutbox() {
+        if (this.outboxDrain)
+            return this.outboxDrain;
+        const drain = (async () => {
+            while (this.connected) {
+                const envelope = this.runtimeState.outbox.find((item) => !this.sentThisConnection.has(item.message_id));
+                if (!envelope)
+                    return;
+                this.sendFrame({ kind: "DELIVER", envelope });
+                this.sentThisConnection.add(envelope.message_id);
+            }
+        })();
+        this.outboxDrain = drain;
+        try {
+            await drain;
+        }
+        finally {
+            if (this.outboxDrain === drain)
+                this.outboxDrain = undefined;
+        }
+    }
+    async rememberIncoming(envelope) {
+        if (this.runtimeState.inbox.some((item) => item.message_id === envelope.message_id))
+            return;
+        await this.mutateRuntimeState((runtime) => {
+            if (!runtime.inbox.some((item) => item.message_id === envelope.message_id))
+                runtime.inbox.push(envelope);
+        });
+    }
+    async completeIncoming(messageId, state) {
+        await this.mutateRuntimeState((runtime) => {
+            runtime.processedIncoming[messageId] = runtime.processedIncoming[messageId] === "READ" ? "READ" : state;
+            const ids = Object.keys(runtime.processedIncoming);
+            for (let index = 0; index < ids.length - MAX_PROCESSED_INCOMING; index += 1) {
+                delete runtime.processedIncoming[ids[index]];
+            }
+        });
+    }
+    async forgetIncoming(messageId) {
+        if (!this.runtimeState.inbox.some((item) => item.message_id === messageId))
+            return;
+        await this.mutateRuntimeState((runtime) => {
+            runtime.inbox = runtime.inbox.filter((item) => item.message_id !== messageId);
+        });
+        if (this.runtimeState.inbox.length === 0 && this.inboxRetryTimer) {
+            clearTimeout(this.inboxRetryTimer);
+            this.inboxRetryTimer = undefined;
+            this.inboxRetryAttempt = 0;
+        }
+    }
+    async drainInbox() {
+        if (this.inboxDrain)
+            return this.inboxDrain;
+        const drain = (async () => {
+            if (!this.connected) {
+                this.scheduleInboxRetry();
+                return;
+            }
+            for (const envelope of [...this.runtimeState.inbox]) {
+                try {
+                    await this.handleFrame({ kind: "MESSAGE", envelope });
+                }
+                catch (error) {
+                    this.emitError(error);
+                    this.scheduleInboxRetry();
+                    return;
+                }
+            }
+            if (this.runtimeState.inbox.length === 0)
+                this.inboxRetryAttempt = 0;
+        })();
+        this.inboxDrain = drain;
+        try {
+            await drain;
+        }
+        finally {
+            if (this.inboxDrain === drain)
+                this.inboxDrain = undefined;
         }
     }
+    scheduleInboxRetry() {
+        if (this.stopped || this.runtimeState.inbox.length === 0 || this.inboxRetryTimer)
+            return;
+        const delay = reconnectDelay(this.inboxRetryAttempt++);
+        this.inboxRetryTimer = setTimeout(() => {
+            this.inboxRetryTimer = undefined;
+            void this.drainInbox();
+        }, delay);
+    }
+    async mutateRuntimeState(mutator) {
+        const operation = this.stateMutation.then(async () => {
+            const next = structuredClone(this.runtimeState);
+            mutator(next);
+            await this.runtimeStateStore.save(next);
+            this.runtimeState = next;
+        });
+        this.stateMutation = operation.catch(() => undefined);
+        return operation;
+    }
     sendFrame(frame) {
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
             throw new Error("Agent is not connected");
         this.socket.send(JSON.stringify(frame));
     }
     async request(path, init = {}, authenticated = true) {
-        const credentials = this.credentials;
-        const response = await fetch(`${this.baseUrl}${path}`, {
+        const headers = { "content-type": "application/json", ...init.headers };
+        const response = authenticated
+            ? await this.authorizedFetch(`${this.baseUrl}${path}`, { ...init, headers })
+            : await fetch(`${this.baseUrl}${path}`, { ...init, headers });
+        const body = await response.json();
+        if (!response.ok)
+            throw new AgentProtocolError(body.error?.code ?? `HTTP_${response.status}`, body.error?.message ?? `HTTP ${response.status}`);
+        return body;
+    }
+    async authorizedFetch(url, init = {}, retry = true) {
+        await this.refreshCredentialsIfNeeded("EXPIRING");
+        const response = await fetch(url, {
             ...init,
             headers: {
-                "content-type": "application/json",
-                ...(authenticated && credentials ? { authorization: `Bearer ${credentials.sessionToken}` } : {}),
+                authorization: `Bearer ${accessToken(this.requireCredentials())}`,
                 ...init.headers,
             },
         });
-        const body = await response.json();
-        if (!response.ok)
-            throw new Error(body.error ? `${body.error.code}: ${body.error.message}` : `HTTP ${response.status}`);
-        return body;
+        if (response.status === 401 && retry && await this.refreshCredentialsIfNeeded("UNAUTHORIZED", true)) {
+            return this.authorizedFetch(url, init, false);
+        }
+        return response;
+    }
+    async refreshCredentialsIfNeeded(reason, force = false) {
+        if (!this.credentialRefresher || !this.credentials)
+            return false;
+        if (reason === "EXPIRING" && !force) {
+            const expiresAt = this.credentials.accessTokenExpiresAt
+                ? Date.parse(this.credentials.accessTokenExpiresAt)
+                : Number.POSITIVE_INFINITY;
+            if (!Number.isFinite(expiresAt) || expiresAt > Date.now() + this.refreshLeewayMs)
+                return false;
+        }
+        if (this.refreshPromise)
+            return this.refreshPromise;
+        const refresh = (async () => {
+            let current = this.requireCredentials();
+            if (this.usesDefaultCredentialRefresher && current.refreshToken && !current.refreshRequestId) {
+                current = { ...current, refreshRequestId: randomUUID() };
+                // Persist intent before sending. If the successful response is lost, a
+                // restart repeats the same server-side operation instead of reusing the
+                // rotated token under a new idempotency key.
+                await this.credentialStore.save(current);
+                this.credentials = current;
+            }
+            let refreshed;
+            try {
+                refreshed = await this.credentialRefresher({ credentials: current, reason, baseUrl: this.baseUrl });
+            }
+            catch (error) {
+                if (this.usesDefaultCredentialRefresher && current.refreshRequestId && isSessionError(error)) {
+                    const { refreshRequestId: _failedRefreshRequest, ...restored } = current;
+                    await this.credentialStore.save(restored);
+                    this.credentials = restored;
+                }
+                throw error;
+            }
+            if (!refreshed)
+                return false;
+            const { accessTokenExpiresAt: _previousExpiry, refreshRequestId: _completedRefreshRequest, ...currentWithoutExpiry } = current;
+            const next = {
+                ...currentWithoutExpiry,
+                sessionToken: refreshed.accessToken,
+                accessToken: refreshed.accessToken,
+                ...(refreshed.refreshToken ?? current.refreshToken
+                    ? { refreshToken: refreshed.refreshToken ?? current.refreshToken }
+                    : {}),
+                ...(refreshed.accessTokenExpiresAt ? { accessTokenExpiresAt: refreshed.accessTokenExpiresAt } : {}),
+            };
+            await this.credentialStore.save(next);
+            this.credentials = next;
+            return true;
+        })();
+        this.refreshPromise = refresh;
+        try {
+            return await refresh;
+        }
+        finally {
+            if (this.refreshPromise === refresh)
+                this.refreshPromise = undefined;
+        }
+    }
+    async connectWithRefresh() {
+        try {
+            await this.connect();
+        }
+        catch (error) {
+            if (isSessionError(error) && await this.refreshCredentialsIfNeeded("UNAUTHORIZED", true)) {
+                await this.connect();
+                return;
+            }
+            throw error;
+        }
+    }
+    async recoverRejectedSession() {
+        try {
+            if (!await this.refreshCredentialsIfNeeded("UNAUTHORIZED", true)) {
+                this.stopped = true;
+                this.emitError(new AgentProtocolError("INVALID_SESSION", "Agent credentials were rejected"));
+                return;
+            }
+            if (!this.stopped)
+                await this.connectWithRefresh();
+        }
+        catch (error) {
+            if (isSessionError(error))
+                this.stopped = true;
+            this.emitError(error);
+            if (!this.stopped)
+                this.scheduleReconnect();
+        }
     }
     requireCredentials() {
         if (!this.credentials)
@@ -419,6 +955,80 @@ export class Agent {
 function exactArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
+function abortError() {
+    const error = new Error("Attachment transfer was cancelled");
+    error.name = "AbortError";
+    return error;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError();
+}
+async function abortableDelay(milliseconds, signal) {
+    throwIfAborted(signal);
+    await new Promise((resolveDelay, rejectDelay) => {
+        const timer = setTimeout(resolveDelay, milliseconds);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            rejectDelay(abortError());
+        }, { once: true });
+    });
+}
+class AgentProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+function accessToken(credentials) {
+    return credentials.accessToken ?? credentials.sessionToken;
+}
+async function refreshAtalkCredentials(context) {
+    const refreshToken = context.credentials.refreshToken;
+    if (!refreshToken)
+        return undefined;
+    const response = await fetch(`${context.baseUrl}/v1/agent-runtime/session/refresh`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            refreshToken,
+            // Deterministic per credential, so a process restart retries the same
+            // idempotency operation if the first response was lost.
+            requestId: context.credentials.refreshRequestId
+                ?? deterministicUuid(`atalk-agent-refresh:${refreshToken}`),
+        }),
+    });
+    if (!response.ok)
+        throw await responseError(response);
+    const body = await response.json();
+    const nextAccessToken = body.accessToken ?? body.token;
+    if (!nextAccessToken)
+        throw new Error("INVALID_REFRESH_RESPONSE: aTalk did not return an access token");
+    return {
+        accessToken: nextAccessToken,
+        ...(body.refreshToken ? { refreshToken: body.refreshToken } : {}),
+        ...(body.accessTokenExpiresAt ?? body.expiresAt
+            ? { accessTokenExpiresAt: body.accessTokenExpiresAt ?? body.expiresAt }
+            : {}),
+    };
+}
+function isSessionError(error) {
+    return error instanceof AgentProtocolError && FATAL_SESSION_CODES.has(error.code);
+}
+function sameIdentityKeys(left, right) {
+    return left.signingPublicKey === right.signingPublicKey
+        && left.signingSecretKey === right.signingSecretKey
+        && left.encryptionPublicKey === right.encryptionPublicKey
+        && left.encryptionSecretKey === right.encryptionSecretKey;
+}
+function deterministicUuid(value) {
+    const bytes = createHash("sha256").update(value).digest().subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 async function attachmentInputFromFile(input) {
     const path = resolve(input.path);
     return {
@@ -442,12 +1052,12 @@ async function responseError(response) {
     try {
         const body = await response.json();
         if (body.error)
-            return new Error(`${body.error.code ?? response.status}: ${body.error.message ?? "request failed"}`);
+            return new AgentProtocolError(body.error.code ?? `HTTP_${response.status}`, body.error.message ?? "request failed");
     }
     catch {
         // Keep the HTTP fallback for non-JSON proxy responses.
     }
-    return new Error(`HTTP ${response.status}`);
+    return new AgentProtocolError(`HTTP_${response.status}`, `HTTP ${response.status}`);
 }
 function reconnectDelay(attempt) {
     const exponential = Math.min(30_000, 500 * (2 ** Math.min(attempt, 6)));