@athenaintel/react 0.41.3 → 0.42.1

package/dist/agent-runtime/src/chat-outbox-store.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Where chat messages typed while Athena can't be reached wait until they are sent
+ * (`chat-outbox.ts`): one store per person on this device, sealed with a key of theirs.
+ *
+ * This store can hold the only copy of what someone wrote, so it never deletes as a side effect:
+ * a record goes when its message was handed to the conversation and the conversation's own journal
+ * took it (`remove`), when the person cancels or discards it, or when the person chooses to sign
+ * out (`clear`). A record that does not open (a key that is gone, a newer build's format) is left
+ * where it is.
+ */
+/** An already-uploaded file a waiting message refers to (never a file picked while offline). */
+export interface ChatOutboxFile {
+    /** A server-backed URL (an asset's image route); never a `blob:` or `data:` URL. */
+    url: string;
+    mediaType: string;
+    filename?: string;
+}
+/**
+ * A file already in Athena that a waiting message carries: an upload that finished before Athena
+ * went out of reach (a file picked while it can't be reached is never attached: it can't upload).
+ * Its reference rides the message's text, as a sent message's does; this copy names it so the
+ * outbox can ask Athena, right before the message goes, that the file is still there and still the
+ * person's to open (`ChatOutboxOptions.checkAttachments`).
+ */
+export interface ChatOutboxAttachment {
+    assetId: string;
+    /** Its name, as the composer showed it. */
+    title: string;
+    mediaType?: string;
+}
+export interface ChatOutboxEntry {
+    /**
+     * The message id, minted when the message was typed. The message is sent under it, so a send
+     * whose answer was lost can never post twice: statewire replays the same statement, and the
+     * thread's host refuses an id it already holds (`duplicate-id`) or re-places one still queued.
+     */
+    id: string;
+    threadId: string;
+    /** The text exactly as it will be sent (what the model reads). */
+    text: string;
+    /** The composer draft the text was serialized from, for giving it back exactly as typed. */
+    composerMarkdown?: string;
+    /**
+     * The draft as a composer whose draft is HTML holds it (the phone's: its mention chips
+     * included), given back exactly on Cancel or Edit.
+     */
+    composerHtml?: string;
+    /** The message metadata frozen when it was typed (its composer markdown, …). */
+    metadata?: Record<string, unknown>;
+    /** Already-uploaded files that ride along. */
+    files?: ChatOutboxFile[];
+    /**
+     * The files already in Athena the message carries (uploads that finished before Athena went out
+     * of reach), asked about right before it goes: a refused one keeps it as "Couldn't send".
+     */
+    attachments?: ChatOutboxAttachment[];
+    /** When it was typed (epoch ms): a message that waited more than a day asks before it goes. */
+    queuedAt: number;
+    /** Typed into a chat that had never started: reopening that chat finds it again. */
+    newChat: boolean;
+}
+/** Which window is handing a message to its conversation right now, and since when. */
+export interface ChatOutboxClaim {
+    by: string;
+    at: number;
+}
+/** Why a hand-off failed. */
+export type ChatOutboxFailureReason = 
+/** The conversation refused it: stopped, or parked on an authorization denial. */
+"refused"
+/** The send failed before the conversation's journal took it. */
+ | "error"
+/** It could not be claimed for sending (the store failed). */
+ | "prepare"
+/** Athena refused one of its attachments: gone, or no longer the person's to open. */
+ | "attachment";
+/**
+ * A failed hand-off, kept with the message: every window (and the next mount) shows it as
+ * "Couldn't send", and nothing sends it again until the person says Retry.
+ */
+export interface ChatOutboxFailure {
+    reason: ChatOutboxFailureReason;
+    at: number;
+}
+export interface ChatOutboxRecord {
+    entry: ChatOutboxEntry;
+    claim?: ChatOutboxClaim;
+    failure?: ChatOutboxFailure;
+    /**
+     * Kept only in this store's memory, because this device could not keep it: it waits as long as
+     * the page or the app stays open.
+     */
+    memoryOnly?: true;
+}
+export type ChatOutboxClaimResult = "claimed" | "taken" | "gone";
+/**
+ * A person's waiting messages. A store keeps every message put into it until it is removed: on
+ * the device when it can (`put` resolves `true`), otherwise in its own memory for as long as the
+ * store lives (`false`, listed with `memoryOnly`), so a host keeps one store per person and a
+ * thread switch never loses a message (`withChatOutboxMemoryFallback`).
+ */
+export interface ChatOutboxStore {
+    /** The thread's waiting messages, oldest first. Resolves `[]` when nothing can be read. */
+    list(threadId: string): Promise<ChatOutboxRecord[]>;
+    /** Every waiting message of this person, oldest first (sign-out, reopening a new chat). */
+    listAll(): Promise<ChatOutboxRecord[]>;
+    /**
+     * How many messages wait, counted without opening them, so a record this build cannot read
+     * still counts (a sign-out asks rather than deleting unread work); the ones kept only in memory
+     * count too. Rejects when the device's records cannot be counted at all.
+     */
+    count(): Promise<number>;
+    /** Keep a waiting message. Resolves `false` when it could not be kept on this device. */
+    put(entry: ChatOutboxEntry): Promise<boolean>;
+    remove(threadId: string, id: string): Promise<void>;
+    /**
+     * Claim a message for handing it to its conversation, atomically across windows: `taken` while
+     * another claimant's claim is younger than `leaseMs`, `gone` when the record no longer exists
+     * (cancelled, discarded, or handed by another window).
+     */
+    claim(input: {
+        threadId: string;
+        id: string;
+        claimant: string;
+        now: number;
+        leaseMs: number;
+    }): Promise<ChatOutboxClaimResult>;
+    /** Drop `claimant`'s claim (its hand-off never reached the conversation). */
+    release(input: {
+        threadId: string;
+        id: string;
+        claimant: string;
+    }): Promise<void>;
+    /** Keep the hand-off's failure with the message, dropping `claimant`'s claim. */
+    markFailed(input: {
+        threadId: string;
+        id: string;
+        claimant: string;
+        failure: ChatOutboxFailure;
+    }): Promise<void>;
+    /** The person said Retry: the message may be sent again. */
+    clearFailure(input: {
+        threadId: string;
+        id: string;
+    }): Promise<void>;
+    /** Every waiting message of this person, gone (a sign-out the person chose). */
+    clear(): Promise<void>;
+    /** Called after any change, this window's or another's. */
+    subscribe(listener: () => void): () => void;
+}
+export declare const CHAT_OUTBOX_DATABASE = "athena-chat-outbox:v1";
+/** The sealed record's format; an older build leaves a newer one alone. */
+export declare const CHAT_OUTBOX_FORMAT = 1;
+export declare function readChatOutboxClaim(value: unknown): ChatOutboxClaim | undefined;
+/** A failure read back from storage; an unknown reason reads as a send error (still failed). */
+export declare function readChatOutboxFailure(value: unknown): ChatOutboxFailure | undefined;
+/** A sealed entry read back, or `null` when it is not one. */
+export declare function parseChatOutboxEntry(value: unknown): ChatOutboxEntry | null;
+/** What a store asks the host's key for: opening kept messages, or keeping a new one. */
+export type ChatOutboxKeyPurpose = "read" | "write";
+export interface IndexedDbChatOutboxStoreOptions {
+    /** The person this store belongs to (with the environment, the key's scope). */
+    ownerId: string;
+    /**
+     * The person's AES-GCM key, or `null` when there is none for `purpose`: `read` opens what is
+     * already kept (a key that exists, whatever the deployment's policy now says, so kept messages
+     * always show and drain); `write` keeps a new message (a key only while the deployment lets
+     * devices keep copies). Without a key to write with, `put` resolves `false` and the message
+     * waits in this store's memory.
+     */
+    getKey: (ownerId: string, purpose: ChatOutboxKeyPurpose) => Promise<CryptoKey | null>;
+    /** An `IDBFactory` (the browser's `indexedDB` by default; a fake one in tests). */
+    factory?: object;
+    databaseName?: string;
+}
+/**
+ * The browser's outbox store (Olympus, the desktop app): IndexedDB records sealed with AES-GCM-256
+ * under the person's key, the owner and the thread hashed for the index and bound to each record
+ * as additional data, so the database names no one and a record moved to another owner or thread
+ * fails to open. A message it cannot keep on the device waits in its memory
+ * ({@link withChatOutboxMemoryFallback}).
+ */
+export declare function createIndexedDbChatOutboxStore(options: IndexedDbChatOutboxStoreOptions): ChatOutboxStore;
+/**
+ * The store contract's memory half, around a store that keeps messages on the device: a message
+ * `inner` could not keep (no key, no storage, a failed write) waits in this wrapper's memory,
+ * listed with `memoryOnly` and counted, for as long as the wrapper lives. A host keeps one store
+ * per person, so switching conversations never loses such a message, and a sign-out still asks
+ * about it.
+ */
+export declare function withChatOutboxMemoryFallback(inner: ChatOutboxStore): ChatOutboxStore;
+/**
+ * An outbox store in this process's memory: for tests, and for a host that keeps nothing on the
+ * device (the messages then wait only as long as the page or app stays open). `durable: false`
+ * makes every `put` report that nothing was kept on the device, and lists its messages as
+ * `memoryOnly`.
+ */
+export declare function createMemoryChatOutboxStore({ durable }?: {
+    durable?: boolean;
+}): ChatOutboxStore & {
+    /** The records as stored (tests). */
+    records(): ChatOutboxRecord[];
+};