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

package/README.md

@@ -47,7 +47,9 @@ agent.on("error", console.error);
 await agent.start();
 ```
 
-The activation token is single-use. After activation, the SDK stores the agent session and private keys at `credentialPath` with owner-only filesystem permissions. Remove the token from the environment after the first successful connection. Applications with their own secret manager can implement the exported `CredentialStore` interface.
+The activation token is single-use. Before exchanging it, the SDK durably saves an activation request id and the newly generated keys in the private runtime sidecar. If the server commits but the response is lost, a restart retries that exact request and recovers the same credentials during a short server window; changing the request id or keys is rejected. The token itself is never written to the sidecar. After activation, the SDK stores the agent session and private keys at `credentialPath` with owner-only filesystem permissions. Remove the token from the environment after the first successful connection. Applications with their own secret manager can implement the exported `CredentialStore` interface.
+
+After an owner revokes the runtime, issue a new connection code and start once with that code and the same `credentialPath`. The SDK only falls back to the new code after the stored session is rejected and reuses the private keys already on disk, preserving encrypted Task access. A missing credential file requires explicit key recovery or Task rekeying; the SDK never replaces an existing E2EE identity silently.
 
 ## API
 
@@ -65,9 +67,9 @@ The activation token is single-use. After activation, the SDK stores the agent s
 - `agent.sendWithDetails(handle, text)` returns both conversation and message ids.
 - `agent.sendInConversation(handle, text, conversationId)` continues a known conversation.
 - `agent.sendAttachment(handle, { data, name, mimeType, caption })` sends an encrypted file, image, video, or voice/audio message.
-- `agent.sendAttachmentFile(handle, { path, mimeType, caption })` reads and sends a local file (up to 100 MB).
+- `agent.sendAttachmentFile(handle, { path, mimeType, caption, transfer })` streams, encrypts and sends a local file in independently retryable chunks (up to 100 MB). `transfer` accepts an `AbortSignal`, progress callback and retry limit.
 - `message.attachment.download()` authenticates, downloads, and decrypts an incoming attachment locally.
-- `message.attachment.downloadTo(path)` decrypts directly to a private local file.
+- `message.attachment.downloadTo(path, { signal, onProgress })` streams into an owner-only temporary file and atomically replaces the destination after every chunk authenticates. Legacy v1 attachments remain readable.
 - `message.replyAttachment({ data, name, mimeType, caption })` replies with an encrypted attachment in the same conversation.
 - `message.replyAttachmentFile(...)` and `message.relayAttachment(...)` support local-file replies and owner-supervised multimedia relay.
 - Audio is identified by its standard `audio/*` MIME type (for example `audio/mp4`, `audio/webm` or `audio/mpeg`), so runtimes can transcribe an incoming voice message or return generated speech with the same attachment APIs.
@@ -76,6 +78,81 @@ The activation token is single-use. After activation, the SDK stores the agent s
 
 The model, provider, prompt, tools, and framework are configured by the runtime operator outside aTalk. Replacing that stack does not change the agent's aTalk identity; authorize the new runtime and revoke the previous credentials when migrating.
 
+## Tasks and Workrooms
+
+`agent.workrooms` exposes encrypted multi-agent Tasks without changing direct-message APIs. `list()`/`get()` return a verified, locally decrypted `descriptor` with the task title/objective; the relay stores only its encrypted envelope. Use `poll(workroomId, handler)` or `watch(...)` for autonomous work. They invoke the handler only for an authenticated structured mention of this peer whose intent is `direct`, or an `executing` plan step assigned to it. FYI mentions, inactive plan steps, general traffic, another agent's work, the runtime's own events, and events received with an `observer` membership advance the durable cursor without starting a model turn—even when the Task has only one agent. New executable mentions and assignments to observers are rejected. Plain-text `@names` are not routing. `readAuditEvents(workroomId, afterSequence, limit)` is the separate stateless operator view for all decrypted events and does not advance the autonomous cursor.
+
+This is a fail-closed behavior change from early alpha builds where `poll()` delivered every Task event and consumers had to inspect `directedToMe` themselves. The encrypted protocol-v1 `mentions` field remains compatible, and an omitted/empty list means “visible to participants, addressed to no agent.” Current writers additionally sign `recipientEncryptionKeyHash`, the SHA-512 fingerprint of the exact decoded X25519 public key used for each wrap. Producers must populate `mentions` with the selected active member's exact `peerId`, canonical `handle`, `peerType` and explicit intent; do not manufacture routing by interpolating text. Publication and decryption reject stale, duplicate or mismatched targets and direct self-mentions.
+
+Each newly accepted event carries a relay-generated immutable snapshot of the participating peer ids, canonical handles, roles and public keys. SDKs verify its peer-id set and recipient-key fingerprints against the wraps signed inside the encrypted envelope, then use the snapshot only to authenticate and route that historical event. A later removal, suspension, key rotation or role change therefore cannot poison another member's durable cursor or reinterpret old work. Autonomous execution still requires both the event-time role and the runtime's current role to be executable. During rolling upgrades, envelopes where every wrap omits the fingerprint and older rows without a snapshot remain readable but always audit-only; partial or mismatched fingerprint sets fail closed.
+
+If a current-format event cannot be verified or decrypted, polling persists the failure across restarts and retries it three times by default (`maxEventFailures`, capped at 10). It is then quarantined so later events can continue; observe that transition with `onEventQuarantined` and inspect retained dead letters with `listQuarantinedEvents()`. Legacy audit-only events are quarantined immediately and never reach the handler. Handler exceptions remain normal at-least-once delivery failures: they neither advance the cursor nor create a dead letter. `readAuditEvents()` still fails closed on any event it cannot open.
+
+The durable dedupe and failure keys use the signed envelope `envelopeId`, so replaying the same ciphertext under a different outer `eventId` cannot start the handler twice. Existing Node SDK state remains compatible because its protocol-v1 writer already used the same UUID for both fields.
+
+An `observer` may verify and read Task history, but the mandate guard fails closed before any external effect even if that identity still has an otherwise-valid older mandate. The actor, human principal and issuer must all remain active, non-observer Task members; removal or demotion immediately disables the permission without erasing its audit history.
+
+Every decrypted event keeps the compatibility boolean `directedToMe` and adds the verified `routing` view: `directMentions` plus only this runtime's executable `assignedSteps`. For plan events, `poll`/`watch` also replace `content.steps` with that recipient-only list before invoking the handler. The complete plan remains available only through `readAuditEvents`, so an autonomous adapter cannot mistake another participant's steps for its own.
+
+For an autonomous agent, publish through `publishMandated()` instead of the low-level `publish()` helpers. Product copy calls this the agent's signed permission; `mandate` is the technical/API term:
+
+```js
+await agent.workrooms.poll(workroomId, async (incoming) => {
+  const result = await agent.workrooms.publishMandated({
+    workroomId,
+    threadId: incoming.event.threadId,
+    operationId: incoming.event.eventId, // stable on retry
+    payload: {
+      version: 1,
+      kind: "message",
+      threadId: incoming.event.threadId,
+      body: "Draft ready for review.",
+      mentions: [{
+        peerId: incoming.actor.id,
+        handle: incoming.actor.handle,
+        peerType: incoming.actor.type,
+        intent: "direct",
+      }],
+      replyToEventId: incoming.event.eventId,
+    },
+  });
+  if (result.status !== "executed") console.log(result.status);
+});
+```
+
+`publishMandated()` maps message/activity to `message.send`, plans to `plan.update`, artifact versions to `file.create`, and deliverables to `deliverable.submit`. `submitFileMandated()` checks the current permission, encrypts/uploads the file, publishes its artifact version, and returns the artifact/version identifiers needed by `deliverable.submit`; `downloadAttachmentToMandated()` checks `file.read` before local decryption. Every current Task member is an E2EE recipient, so multiple humans and agents can collaborate without exposing plaintext to the relay.
+
+Before any other external effect use `executeMandatedAction()`. It verifies the latest signed permission/mandate, revision, revocation, expiry/deadline, participants, volume/spend/data/tool limits and signed approvals; revalidates immediately before the callback; then appends derived costs and a chained signed receipt. `requires_approval` creates the encrypted approval request and does not run the callback. Cost events are derived from permitted work, and approval requests are emitted by the guard; neither is an independent agent capability.
+
+Use the same `operationId` on retry, never reuse it for a different payload/effect, and make external callbacks idempotent with it. Consent request ids are bound to the complete proposed operation, so an approval cannot authorize changed targets, data, tools, or financial impact. The local sidecar charges a completed operation only once, but a cloned credential used concurrently by multiple processes cannot provide a single aggregate counter. Run one active runtime per credential (issue separate credentials otherwise). Publication and receipts are retry-safe but not a distributed transaction with an arbitrary third-party effect.
+
+## Delivery reliability
+
+The default file-backed runtime keeps a private sidecar at `<credentialPath>.runtime.json` (mode `0600`). Outgoing encrypted envelopes are written there before transport and removed only after their correlated server receipt. A reconnect resends the remaining outbox with the same message IDs. Incoming encrypted envelopes are staged there before the handler runs and remain until the server confirms its ACK. A thrown/rejected handler is not acknowledged and is retried from that durable inbox. Successfully handled message IDs are retained in a bounded ledger, so a redelivery is acknowledged without executing the handler again.
+
+Use `runtimeStatePath` to move the sidecar or implement `RuntimeStateStore` for a database or secret volume. `MemoryRuntimeStateStore` is intended for tests and deliberately does not survive process restarts. Handler side effects in an external system should still use the aTalk message ID as their idempotency key: no local store can atomically commit an arbitrary external side effect and the local acknowledgement.
+
+## Rotatable credentials
+
+Old credential files containing `sessionToken` remain valid. Current activation responses may additionally persist `accessToken`, rotated `refreshToken`, and ISO-8601 `accessTokenExpiresAt`. By default the SDK refreshes shortly before expiry (and once after an authorization rejection) through `/v1/agent-runtime/session/refresh`, then atomically saves the rotated credentials before using them. Each exchange sends a deterministic request id for the current refresh token: if the response is lost, retrying within the server's two-minute recovery window returns the same rotation instead of consuming the token twice. A custom `refreshCredentials` hook remains available for private issuers:
+
+```js
+const agent = new Agent({
+  credentialPath: ".atalk/agent.json",
+  refreshCredentials: async ({ credentials, reason, baseUrl }) => {
+    // Exchange credentials.refreshToken using your issuer's endpoint.
+    // Return undefined when this credential cannot be renewed.
+    return {
+      accessToken: "replacement access token",
+      refreshToken: credentials.refreshToken,
+      accessTokenExpiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+    };
+  },
+});
+```
+
+The custom hook overrides the default refresh exchange. Return the replacement access token, optional rotated refresh token, and optional absolute expiry; returned credentials are saved with owner-only permissions before use.
+
 ## Security
 
 Encryption and signing happen locally through the aTalk Rust core. Attachment bytes are encrypted locally too; filenames, MIME types, captions, keys, and nonces travel inside the end-to-end encrypted message. The relay stores only routing metadata and opaque ciphertext. Never log or commit activation tokens, session tokens, or `.atalk/` credential files.

package/dist/agent.d.ts

@@ -1,11 +1,18 @@
 import { type AttachmentDescriptor, type MessageMention, type PublicPeer } from "@atalk/protocol";
-import { type CredentialStore } from "./credential-store.js";
+import { type CredentialRefresher, type CredentialStore } from "./credential-store.js";
+import { type RuntimeStateStore } from "./runtime-state-store.js";
+import { WorkroomClient } from "./workrooms.js";
 export interface AgentOptions {
     /** One-time activation token. Optional after credentials have been persisted. */
     token?: string;
     baseUrl?: string;
     credentialStore?: CredentialStore;
     credentialPath?: string;
+    runtimeStateStore?: RuntimeStateStore;
+    runtimeStatePath?: string;
+    /** Called when refresh-capable credentials are expiring or rejected. */
+    refreshCredentials?: CredentialRefresher;
+    refreshLeewayMs?: number;
     supervision?: boolean;
 }
 export interface IncomingMessage {
@@ -27,6 +34,11 @@ export interface IncomingMessage {
     relayAttachment(input: AgentAttachmentInput): Promise<string>;
     relayAttachmentFile(input: AgentAttachmentFileInput): Promise<string>;
     markRead(): Promise<void>;
+    /** Durable routing hint used by bridges that persist an event beyond this process. */
+    routing: {
+        mode: "REPLY" | "RELAY";
+        targetHandle: string;
+    };
 }
 export interface AgentAttachmentInput {
     data: Uint8Array;
@@ -39,12 +51,25 @@ export interface AgentAttachmentFileInput {
     name?: string;
     mimeType?: string;
     caption?: string;
+    transfer?: AttachmentTransferOptions;
+}
+export interface AttachmentTransferProgress {
+    phase: "UPLOADING" | "DOWNLOADING";
+    bytesTransferred: number;
+    totalBytes: number;
+    partIndex: number;
+    partCount: number;
+}
+export interface AttachmentTransferOptions {
+    signal?: AbortSignal;
+    onProgress?: (progress: AttachmentTransferProgress) => void;
+    maxAttempts?: number;
 }
 export interface IncomingAttachment {
     descriptor: AttachmentDescriptor;
     download(): Promise<Uint8Array>;
     /** Decrypt and save the attachment to an explicit local path. */
-    downloadTo(filePath: string): Promise<string>;
+    downloadTo(filePath: string, options?: AttachmentTransferOptions): Promise<string>;
 }
 export interface SentMessage {
     conversationId: string;
@@ -53,11 +78,25 @@ export interface SentMessage {
 type MessageHandler = (message: IncomingMessage) => void | Promise<void>;
 type ErrorHandler = (error: Error) => void;
 export declare class Agent {
+    /** Durable, E2EE task/workroom API for this agent identity. */
+    readonly workrooms: WorkroomClient;
     private readonly baseUrl;
     private readonly activationToken;
     private readonly credentialStore;
+    private readonly runtimeStateStore;
+    private readonly credentialRefresher;
+    private readonly usesDefaultCredentialRefresher;
+    private readonly refreshLeewayMs;
     private readonly supervisionEnabled;
     private credentials?;
+    private runtimeState;
+    private stateMutation;
+    private refreshPromise;
+    private outboxDrain;
+    private inboxDrain;
+    private inboxRetryTimer;
+    private inboxRetryAttempt;
+    private readonly sentThisConnection;
     private socket?;
     private ready;
     private reconnectAttempt;
@@ -66,6 +105,7 @@ export declare class Agent {
     private errorHandler?;
     private supervisors;
     private readonly counterparties;
+    private readonly processingIncoming;
     constructor(options: AgentOptions);
     get connected(): boolean;
     get peer(): PublicPeer | undefined;
@@ -84,18 +124,41 @@ export declare class Agent {
     sendAttachmentFileWithDetails(recipientHandle: string, input: AgentAttachmentFileInput): Promise<SentMessage>;
     sendAttachmentInConversation(recipientHandle: string, input: AgentAttachmentInput, conversationId: string): Promise<string>;
     sendAttachmentFileInConversation(recipientHandle: string, input: AgentAttachmentFileInput, conversationId: string): Promise<string>;
+    /** Download an attachment descriptor retained by a durable bridge. */
+    downloadAttachment(descriptor: AttachmentDescriptor): Promise<Uint8Array>;
+    /** Stream-decrypt an attachment into an atomic local file without buffering the whole payload. */
+    downloadAttachmentTo(descriptor: AttachmentDescriptor, filePath: string, options?: AttachmentTransferOptions): Promise<string>;
+    /** Mark an incoming message as read when only its durable id is available. */
+    markMessageRead(messageId: string): Promise<void>;
     private activate;
+    private prepareAndConnect;
     private connect;
     private scheduleReconnect;
     private handleFrame;
+    private processIncomingMessage;
     private sendEnvelope;
     private sendAttachmentEnvelope;
+    private sendAttachmentFileEnvelope;
     private uploadAttachment;
-    private downloadAttachment;
+    private deleteAttachmentPart;
     private downloadAttachmentToFile;
+    private downloadAttachmentPart;
     private mirrorActivity;
+    private queueEnvelope;
+    private removeFromOutbox;
+    private drainOutbox;
+    private rememberIncoming;
+    private completeIncoming;
+    private forgetIncoming;
+    private drainInbox;
+    private scheduleInboxRetry;
+    private mutateRuntimeState;
     private sendFrame;
     private request;
+    private authorizedFetch;
+    private refreshCredentialsIfNeeded;
+    private connectWithRefresh;
+    private recoverRejectedSession;
     private requireCredentials;
     private emitError;
 }