@athenaintel/react 0.57.1 → 0.59.0

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

@@ -1,68 +1,48 @@
+import type { StatewireClient } from "statewire";
 import type { ChatOutboxAttachmentCheck } from "./chat-outbox-attachments";
-import type { ChatOutboxAttachment, ChatOutboxEntry, ChatOutboxFailureReason, ChatOutboxFile, ChatOutboxStore } from "./chat-outbox-store";
+import { type ChatOutboxAttachment, type ChatOutboxEntry, type ChatOutboxFile } from "./chat-outbox-entry";
+import { type LegacyChatOutboxReader } from "./chat-outbox-legacy";
+import type { ChatOutboxDirectory } from "./chat-outbox-storage";
+export type { ChatOutboxAttachment, ChatOutboxEntry, ChatOutboxFile } from "./chat-outbox-entry";
 /**
  * The chat outbox: a message typed while Athena can't be reached waits on this device and is sent
- * once Athena answers again, while the app is in front, after a few seconds the person can cancel
- * (decision 5 of the offline plan, `docs/plans/2026-10-27-offline-everywhere-plan.md`).
+ * once Athena answers again, while the app is in front, after a few seconds the person can cancel.
  *
- * - **Held before the conversation's journal, never inside it.** A send made while Athena can't be
- *   reached does not reach statewire at all: statewire would replay it the moment its connection
- *   returns (from a hidden tab too) and has no way to take a journaled statement back. The message
- *   waits here instead, and reaches statewire only when this controller hands it over, under the
- *   id minted when it was typed.
- * - **Sent in front, with a countdown.** Once Athena is reachable and the app is in front (a visible
- *   tab, an active app, a focused desktop window), the waiting messages count down
- *   ({@link CHAT_OUTBOX_COUNTDOWN_MS}) with a Cancel that gives the text back to the composer; then
- *   each is handed over once. Going to the background or losing Athena stops the countdown; it
- *   starts over, in full, when both are back.
+ * It is a view over the thread's statewire outbox (statewire 0.24), which keeps every waiting
+ * message in the thread's session record, orders it, and stamps each entry exactly once across tabs:
+ *
+ * - **Held, never queued, while Athena can't be reached.** {@link ChatOutbox.hold} puts the message
+ *   in the outbox held (`insert({ held: true, localMeta })`): no flush stamps it, in any tab, until
+ *   it is released.
+ * - **Sent in front, after a countdown.** Once Athena is reachable and the app is in front, the
+ *   waiting messages count down ({@link CHAT_OUTBOX_COUNTDOWN_MS}, kept as `localMeta.countdownEndsAt`
+ *   so every tab shows the same one) with a Cancel that gives the text back to the composer; then
+ *   the visible tab releases each, re-anchored against the thread as it is then. A tab that comes
+ *   to the front starts a countdown it did not see begin over, in full. A hidden tab never
+ *   releases, and a hidden tab's flush holds what was queued before it mounted
+ *   (`createChatOutboxFlushPolicy`).
  * - **A day is the limit for sending on its own.** A message that waited more than
- *   {@link CHAT_OUTBOX_ASK_AFTER_MS} asks first (Send / Edit / Discard); the messages behind it wait
- *   for the answer, so nothing is sent out of order.
- * - **Once per message, never a loop.** A message is handed over at most once per return of Athena.
- *   A hand-off that fails before the conversation took it (anything but the conversation going
- *   away) stays as "Couldn't send" with Retry and Discard, kept with the message so no window and
- *   no later mount sends it again on its own. Once the conversation's journal took it, statewire
- *   owns it: it delivers it exactly once, and a refusal lands in the conversation's own failed
- *   lane (Retry / Discard there).
- * - **One sender per message.** A hand-off claims the message in the store first, atomically
- *   across windows ({@link CHAT_OUTBOX_CLAIM_LEASE_MS}), so two windows on the same conversation
- *   never hand the same message twice (a second hand-off of an id whose run is in flight would be
- *   read as an edit of that turn). The gate is checked again once the claim is written: a tab
- *   hidden (or an Athena lost) meanwhile lets the claim go, and the message waits again.
- * - **Nothing overtakes.** Until the conversation's kept messages are read, a new send waits too
- *   (it goes at once if nothing older turns up), and a message the person told to go now still
- *   goes after the older ones in line.
- * - **Kept until it is safe to let go.** The waiting record is removed only once statewire has the
- *   statement durably (`posted`, `applied` or settled), or once the conversation shows the message
- *   (a journal adopted from an earlier page, or the message already on the transcript).
- * - **Its attachments go with it, still valid.** A message keeps the files that had finished
- *   uploading before Athena went out of reach (references to files already in Athena; one picked
- *   while it can't be reached is never attached). Once the message is claimed they are asked about
- *   ({@link ChatOutboxOptions.checkAttachments}): one Athena refuses (deleted, or no longer shared
- *   with the person) keeps the message as "Couldn't send" with Retry, Edit and Discard, and a check
- *   Athena could not answer keeps it the same way as a send error. Nothing goes unchecked, and the
- *   text is never lost.
- * - **Its own send settings, never another's.** A message keeps the per-send settings it was typed
- *   with ({@link ChatOutboxEntry.sendContext}), and the host stages them as it is handed over (its
- *   `handed` event carries them). Every send of a conversation rides one ambient context, so a host
- *   with settings that can differ between messages gives the outbox a send gate
- *   ({@link ChatOutboxOptions.sendGate}): only messages whose settings are the same are handed over
- *   together, and a message whose settings differ from a send the conversation has not taken yet
- *   waits, in line, until it has.
+ *   {@link CHAT_OUTBOX_ASK_AFTER_MS} asks first (Send / Edit / Discard).
+ * - **Nothing overtakes.** Messages never pass a held one (`athenaCanOvertake`), so the messages
+ *   behind one that asks or failed wait for it, and a send typed while messages wait is held too.
+ * - **Failures come back held.** A send the server refused (or that could not be delivered and is
+ *   not re-sent on its own) comes back held with `localMeta.error` (send recovery,
+ *   `statewire-held-sends.ts`), shown as "Couldn't send" with Retry, Edit and Discard.
+ * - **Attachments are asked about before they go** ({@link ChatOutboxOptions.checkAttachments}).
  */
 /** How long the countdown before a waiting message is sent lasts. */
 export declare const CHAT_OUTBOX_COUNTDOWN_MS = 5000;
 /** A message that waited longer than this asks before it is sent. */
 export declare const CHAT_OUTBOX_ASK_AFTER_MS: number;
-/** How long a window's claim on a message holds against another window's hand-off. */
-export declare const CHAT_OUTBOX_CLAIM_LEASE_MS = 30000;
 /** How long the check of a message's attachments may take before it counts as unanswered. */
 export declare const CHAT_OUTBOX_ATTACHMENT_CHECK_TIMEOUT_MS = 15000;
+/** The failure code a held message carries when Athena refused one of its attachments. */
+export declare const CHAT_OUTBOX_ATTACHMENT_REFUSED_CODE = "attachment-unavailable";
+/** The failure code a held message carries when its attachments' check went unanswered. */
+export declare const CHAT_OUTBOX_ATTACHMENT_UNKNOWN_CODE = "attachment-check-failed";
 /**
- * Why a sent message's Edit is not offered while Athena can't be reached (its tooltip, or the hint
- * under it where there are no tooltips). An edit rewinds the conversation and re-runs it: a
- * journaled one would replay the moment the connection returns, from a hidden window too, so an
- * edit never waits the way a new message does.
+ * Why a sent message's Edit is not offered while Athena can't be reached. An edit rewinds the
+ * conversation and re-runs it, so an edit never waits the way a new message does.
  */
 export declare const CHAT_EDIT_UNREACHABLE_LABEL = "Can't edit while Athena can't be reached";
 /** What an edit submitted while Athena can't be reached says: the edit stays where it was typed. */
@@ -76,29 +56,43 @@ export interface ChatOutboxSignal {
     get(): boolean;
     subscribe(listener: () => void): () => void;
 }
-/**
- * Whether a hand-off reaches the conversation now: `ready` (attached, a never-started chat that
- * dials on its first send, or an idle channel that reattaches on demand — in each case what the
- * conversation shows is the server's, so a message missing from it never reached it),
- * `connecting` (reattaching: what it shows may be a remembered snapshot), `refused` (the host
- * refused the conversation: stopped, or parked on an authorization denial).
- */
-export type ChatOutboxThreadReadiness = "ready" | "connecting" | "refused";
-/** The conversation the outbox hands messages to (`chat-outbox-thread.ts` adapts a statewire thread). */
+/** The statewire outbox verbs the chat outbox uses (`StatewireClient.Outbox`, structurally). */
+export interface ChatOutboxStatewireOutbox {
+    readonly entries: readonly StatewireClient.OutboxEntry[];
+    insert(entry: StatewireClient.OutboxInsert): string;
+    update(id: string, fn: (entry: StatewireClient.OutboxEntry) => StatewireClient.OutboxPatch): void;
+    remove(id: string): void;
+}
+/** The thread as the chat outbox reads it when it builds and re-anchors a send. */
+export interface ChatOutboxThreadView {
+    /** The raw wire messages of the loaded window (`extras.state.messages`), when replicated. */
+    wireMessages: readonly unknown[] | null;
+    /** The live run's id, or `null` between runs. */
+    runId: string | null;
+    /** Message ids on the transcript: a waiting message already there was delivered. */
+    messageIds: ReadonlySet<string>;
+}
+/** The conversation the outbox lives in (`chat-outbox-thread.ts` adapts a statewire thread). */
 export interface ChatOutboxThreadPort {
-    readiness(): ChatOutboxThreadReadiness;
+    /** The thread's statewire outbox; `null` while there is none (no session, not mounted yet). */
+    outbox(): ChatOutboxStatewireOutbox | null;
+    view(): ChatOutboxThreadView;
+    subscribe(listener: () => void): () => void;
     /**
-     * Message ids the conversation shows anywhere: its transcript, its queue and steer lanes, the
-     * run being dispatched, its failed lane — this page's journal included (statewire folds a
-     * journaled send into them, one adopted from an earlier page too).
+     * Dials a thread that is not attached and would not dial by itself (a chat that never started,
+     * an idle channel), so a released message goes. statewire 0.24.1+ does this for outbox entries
+     * itself; 0.24.0 dialed only for sends the page made.
      */
-    heldIds(): ReadonlySet<string>;
-    /** Hand the message to the conversation under its own id; settles with the server's verdict. */
-    send(entry: ChatOutboxEntry): Promise<unknown>;
-    subscribe(listener: () => void): () => void;
+    wake?(): void;
 }
+/** Why a waiting message could not be sent. */
+export type ChatOutboxFailureReason = 
+/** The send failed (the server refused it, or it could not be delivered). */
+"error"
+/** Athena refused one of its attachments: gone, or no longer the person's to open. */
+ | "attachment";
 export type ChatOutboxRowState = 
-/** Not sent yet: Athena can't be reached, or the app is not in front. */
+/** Not sent yet: Athena can't be reached, the app is not in front, or one ahead of it waits. */
 {
     kind: "waiting";
 }
@@ -111,11 +105,11 @@ export type ChatOutboxRowState =
  | {
     kind: "ask";
 }
-/** Being handed to the conversation (by this window or another). */
+/** Being sent (its attachments are being checked). */
  | {
     kind: "sending";
 }
-/** The hand-off failed for a reason other than Athena being unreachable. */
+/** It could not be sent: Retry, Edit or Discard. */
  | {
     kind: "failed";
     reason: ChatOutboxFailureReason;
@@ -128,14 +122,10 @@ export interface ChatOutboxRow {
 /** Another conversation of the same person with messages waiting (the tray offers to open it). */
 export interface ChatOutboxElsewhere {
     threadId: string;
-    /** How many messages wait there. */
     count: number;
     /** The oldest of them: its text names the conversation. */
     first: ChatOutboxEntry;
-    /**
-     * Every message waiting there was typed into a chat that had never started, so it opens as the
-     * new chat it still is (one typed after the chat started says it has a session now).
-     */
+    /** Every message waiting there was typed into a chat that had never started. */
     newChat: boolean;
 }
 export interface ChatOutboxSnapshot {
@@ -144,7 +134,7 @@ export interface ChatOutboxSnapshot {
     countdownEndsAt: number | null;
     /** Whether every waiting message is kept on this device (false: only while the page stays open). */
     durable: boolean;
-    /** Whether the thread's kept messages have been read. */
+    /** Whether the thread's outbox is available (its session hydrated). */
     loaded: boolean;
     /** The person's other conversations with messages waiting, oldest first. */
     elsewhere: readonly ChatOutboxElsewhere[];
@@ -157,8 +147,8 @@ export interface ChatOutboxInput {
     /** The draft as an HTML composer holds it (the phone's), given back exactly on Cancel. */
     composerHtml?: string;
     metadata?: Record<string, unknown>;
-    /** The per-send settings the host stages when the message goes ({@link ChatOutboxEntry.sendContext}). */
-    sendContext?: Record<string, unknown>;
+    /** The agents the message names (`message.metadata.addressedAgents`); omitted, it names none of its own. */
+    addressedAgents?: readonly string[];
     files?: ChatOutboxFile[];
     /** Files already in Athena the message carries, asked about before it goes. */
     attachments?: ChatOutboxAttachment[];
@@ -183,13 +173,6 @@ export type ChatOutboxEvent = {
     messageId: string;
     auto: boolean;
     ageMs: number;
-    /** The message's own send settings, raised just before the hand-off so the host stages them. */
-    sendContext?: Record<string, unknown>;
-} | {
-    type: "delivered";
-    threadId: string;
-    messageId: string;
-    status: string;
 } | {
     type: "adopted";
     threadId: string;
@@ -208,54 +191,38 @@ export type ChatOutboxEvent = {
     type: "discarded";
     threadId: string;
     messageId: string;
+} | {
+    type: "migrated";
+    threadId: string;
+    inserted: number;
+    removed: number;
+    kept: number;
 };
-/**
- * A host's say over which waiting messages go together, and when (Olympus: the agents a message
- * names ride the conversation's one ambient context, so a message naming other agents than a send
- * still on its way waits for it). Without one, every message goes as soon as it may.
- */
-export interface ChatOutboxSendGate {
-    /** Consecutive messages with the same key may be handed over together; a different one waits. */
-    keyOf(entry: ChatOutboxEntry): string;
-    /** Whether the message may be handed over now. */
-    mayHandOff(entry: ChatOutboxEntry): boolean;
-    /** Called whenever {@link mayHandOff} may have changed. */
-    subscribe(listener: () => void): () => void;
-}
-/** The command-lifecycle update statewire reports (`onCommandChange`), structurally. */
-export interface ChatOutboxCommandUpdate {
-    status: "queued" | "posted" | "applied" | "settled";
-    params?: readonly unknown[];
-    failure?: {
-        fate: string;
-        cause?: string;
-    } | undefined;
-}
 export interface ChatOutbox {
     readonly threadId: string;
     getSnapshot(): ChatOutboxSnapshot;
     subscribe(listener: () => void): () => void;
     /**
-     * Whether Athena can be reached, as this outbox reads it (the host's model; in the SDK the
-     * conversation's own channel too). An edit of a sent message waits on it as a send does: while it
-     * says no, the Edit action is not offered and a submitted edit is refused
+     * Whether Athena can be reached, as this outbox reads it. An edit of a sent message waits on it:
+     * while it says no, Edit is not offered and a submitted edit is refused
      * ({@link CHAT_EDIT_UNREACHABLE_LABEL}, {@link ChatEditUnreachableError}).
      */
     readonly reachability: ChatOutboxSignal;
     /**
-     * Whether a send made now must wait here: Athena can't be reached, or earlier messages of this
-     * conversation are still waiting (a later message never overtakes them).
+     * Whether a send made now must wait here: Athena can't be reached, or messages of this
+     * conversation are still waiting (a later message never overtakes them). `false` where the
+     * thread keeps no outbox (no session): the send goes as it always did.
      */
     shouldHold(): boolean;
     /** Keep a message typed now; it waits until it can be sent. */
     hold(input: ChatOutboxInput): ChatOutboxEntry;
     /** Cancel (or the ask's Edit): the message leaves the outbox and its text goes back to the composer. */
     cancel(id: string): void;
-    /** The ask's Send, a failed row's Retry: hand it over now (one attempt; waits if Athena is out of reach). */
+    /** The ask's Send, a failed row's Retry: send it now. */
     send(id: string): void;
+    /** A failed or asking row's Edit in place: the message is sent with the new text (same id). */
+    edit(id: string, input: ChatOutboxInput): void;
     discard(id: string): void;
-    /** Feed statewire's command lifecycle (`onCommandChange`). */
-    observeCommand(update: ChatOutboxCommandUpdate): void;
     /** Open another conversation the tray lists as holding waiting messages (`null`: the host cannot). */
     readonly openThread: ((target: {
         threadId: string;
@@ -263,52 +230,53 @@ export interface ChatOutbox {
     }) => void) | null;
     dispose(): void;
 }
-export interface ChatOutboxOptions {
-    threadId: string;
+export interface ChatOutboxLegacyOptions {
+    reader: LegacyChatOutboxReader;
     /**
-     * The conversation has never started (a new chat): what waits reopens with it. Read when a
-     * message is held, so a chat that started since stamps its later messages as started.
+     * Resolves `true` once the entry carrying `messageId` is stored on the device (read back through
+     * `listChatOutboxes`). Omitted: an entry counts as kept once the outbox reports it `durable`.
      */
+    isKept?: (threadId: string, messageId: string) => Promise<boolean>;
+}
+export interface ChatOutboxOptions {
+    threadId: string;
+    /** The conversation has never started (a new chat); read when a message is held. */
     isNewChat: boolean | (() => boolean);
-    /** Where waiting messages are kept for this person; `null` keeps them in memory only. */
-    store: ChatOutboxStore | null;
     reachability: ChatOutboxSignal;
     foreground: ChatOutboxSignal;
     thread: ChatOutboxThreadPort;
     /** Give a cancelled message's text back to the composer. */
     restore: (entry: ChatOutboxEntry) => void;
-    /**
-     * Open another of the person's conversations that holds waiting messages (the tray's Open);
-     * omitted where the host cannot switch conversations (an embedded chat).
-     */
+    /** Open another of the person's conversations holding waiting messages (the tray's Open). */
     openThread?: (target: {
         threadId: string;
         newChat: boolean;
     }) => void;
     onEvent?: (event: ChatOutboxEvent) => void;
-    /**
-     * Asks Athena whether a waiting message's attachments can still be opened, right before it goes
-     * (`createChatOutboxAttachmentCheck`). `refused` keeps the message as "Couldn't send" (Retry,
-     * Edit, Discard); `unknown` too, as a send error. Omitted: attachments go unchecked.
-     */
+    /** Asks Athena whether a waiting message's attachments can still be opened, right before it goes. */
     checkAttachments?: ChatOutboxAttachmentCheck;
-    /**
-     * Which waiting messages go together, and when (a message whose send settings differ from a send
-     * the conversation has not taken yet waits for it). Omitted: every message goes once it may.
-     */
-    sendGate?: ChatOutboxSendGate;
+    /** Every thread's waiting messages (`createChatOutboxDirectory`): the tray's "elsewhere". */
+    directory?: ChatOutboxDirectory;
+    /** The previous store: this thread's records are moved into its outbox once it is available. */
+    legacy?: ChatOutboxLegacyOptions;
     now?: () => number;
     countdownMs?: number;
     askAfterMs?: number;
-    claimLeaseMs?: number;
-    /** How long the attachment check may take before it counts as unanswered. */
     attachmentCheckTimeoutMs?: number;
     newMessageId?: () => string;
     /** Timer seam (tests): schedule `task` after `ms`, returning what cancels it. */
     setTimer?: (task: () => void, ms: number) => () => void;
 }
-/** The message id a run send carries, off a command update's params. */
-export declare function chatOutboxCommandMessageId(params: readonly unknown[] | undefined): string | null;
-/** Whether two snapshots show the same thing (the rows' entries by identity: a listing keeps them). */
+/**
+ * A held run send's params re-anchored against the thread as it is now, keeping its method (so the
+ * re-anchor and the release are one atomic `update`): a send into the live run keeps its statement,
+ * any other goes into the live run, or starts one at the host's tail. An edit re-asserts its
+ * source's parent. `null`: keep the params as they are.
+ */
+export declare function reanchorHeldSendParams(command: {
+    method: string;
+    params: readonly unknown[];
+}, view: Pick<ChatOutboxThreadView, "wireMessages" | "runId">): unknown[] | null;
+/** Whether two snapshots show the same thing (rows' entries by identity: a listing keeps them). */
 export declare function sameChatOutboxSnapshot(a: ChatOutboxSnapshot, b: ChatOutboxSnapshot): boolean;
 export declare function createChatOutbox(options: ChatOutboxOptions): ChatOutbox;