@evandu/super-pi 0.1.84 → 0.1.85

package/dist/server/store.d.ts

@@ -1,7 +1,7 @@
 import type { AppStateRepository } from "./persistence/app-state-repository.js";
 import { defaultJsonStatePath } from "./persistence/json-state-repository.js";
 import type { WorkflowRun } from "./workflow.js";
-import type { AppState, Conversation, Message, MessageImage, ModelSelection, QueuedMessage, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
+import type { AppState, Conversation, Message, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
 /** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
  *
  *  Exported because the ordering demands it and no other arrangement provides it. Pi's copied file's header
@@ -185,7 +185,40 @@ export declare class Store {
      * the Archived group renders the same name.
      */
     renameConversation(conversationId: string, name: string): Promise<Conversation>;
-    addUserMessage(conversationId: string, content: string, images?: MessageImage[], attachments?: import("./types.js").MessageAttachments): Promise<Message>;
+    /**
+     * Writes ONE user message into the transcript - the single place a user utterance comes into being.
+     *
+     * Two callers exist and they differ only in `delivery`, because whether a send starts a turn or waits
+     * for one is decided by the RUN GUARD in `run-service`, not here. This method records the words and,
+     * if they are waiting, records that they are waiting. Deciding anything about turns would put a second,
+     * contradictory answer next to the guard's.
+     *
+     * `clientId` is the browser's own id for the message it has already drawn. When it is well formed and
+     * not already taken, the message IS that id - which is what lets the optimistic bubble and the stored
+     * message be the same object rather than two that have to be matched up by content afterwards. A
+     * collision falls back to a minted id rather than throwing: the browser is asking for its words to be
+     * kept, and refusing the whole send because an id was already in use would lose them.
+     *
+     * `delivery: "waiting"` ALSO SKIPS EVERY SIDE EFFECT BELOW - no `running`, no title, no `updatedAt`,
+     * no clearing of a failure reason. Those all describe a turn, and a message waiting for one has not
+     * started anything. It is why a conversation holding only waiting messages still reads as idle in the
+     * sidebar, and why the title comes from the first message that was actually asked rather than from
+     * whatever was typed into a box that was not listening yet. `openTurnOnMessage` applies them at the
+     * moment a turn genuinely begins.
+     */
+    addUserMessage(conversationId: string, content: string, images?: MessageImage[], attachments?: import("./types.js").MessageAttachments, options?: {
+        clientId?: string;
+        delivery?: Message["delivery"];
+    }): Promise<Message>;
+    /**
+     * Takes the browser's id for its own optimistic message, when it is safe to.
+     *
+     * A client that names an id already in this conversation gets a minted one instead: two messages sharing
+     * an id would break `updateToolCall`, `revertMessage` and every per-message write that follows, so
+     * uniqueness within the conversation is worth more than the client getting its own id back in that case.
+     * The `message_` prefix is required so a folded legacy id (which is `q_`-prefixed) can never be adopted.
+     */
+    private claimClientMessageId;
     /**
      * Appends one background-result message to a conversation, without starting a turn.
      *
@@ -366,100 +399,152 @@ export declare class Store {
     revertMessages(conversationId: string, messageId: string, withdraw?: boolean): Promise<RevertPlan>;
     private requireConversation;
     /**
-     * This conversation's waiting list, oldest first.
+     * This conversation's waiting messages, in the order they will be started.
      *
      * Cloned like every other value this store hands out, because the caller broadcasts it straight to
-     * browsers and the array is mutated in place by the very next enqueue.
+     * browsers and the array is mutated in place by the very next send.
+     */
+    listWaitingMessages(conversationId: string): Message[];
+    /** The same list by reference, for callers that only read a field and must not pay for a clone. */
+    private waitingMessages;
+    private requireWaitingMessage;
+    private persistMessages;
+    /**
+     * Claims one waiting message for delivery to the live Pi process: `waiting` becomes `sending`, and the
+     * message STAYS WHERE IT IS - still on screen, still in the transcript, still at the same index.
+     *
+     * The read and the write are adjacent statements with no `await` between them, which is what makes the
+     * claim atomic here. This store has no mutex and does not need one: JavaScript runs this synchronous
+     * run-to-completion, so a second caller arriving in the same tick observes the write above and cannot
+     * claim the same message.
+     */
+    claimWaitingMessage(conversationId: string, messageId: string): Promise<Message>;
+    /**
+     * Puts ONE `sending` message back to `waiting`, for the one case that proves Pi never took it.
+     *
+     * The one legal use, and it is narrow on purpose: this is called ONLY when we can prove the message
+     * never reached a model - the turn ended while Pi still held it, or the write to Pi's stdin failed
+     * before it left. Pi drains steering before its loop can end and announces the delivery before the turn
+     * settles, so a message still `sending` when the child is gone provably was not delivered, and
+     * returning it is a fact rather than a guess. It is deliberately NOT used for "Pi has not answered yet",
+     * where the outcome is genuinely unknown and the honest state is still `sending`.
      */
-    listQueuedMessages(conversationId: string): QueuedMessage[];
+    releaseWaitingMessage(conversationId: string, messageId: string): Promise<void>;
     /**
-     * Adds one message to the waiting list and returns it.
+     * Returns every `sending` message of this conversation to `waiting`, for the end of a turn.
      *
-     * The id is minted here and is the entry's identity for its whole life. Pi matches its own queue by
-     * message TEXT (`agent-session.ts:1123`), so two identical messages are one entry to Pi and two here;
-     * `cancel` and `steer` name the id, which is the only reason "cancel the second of two identical
-     * messages" is expressible at all. `crypto.randomUUID`, like every other id in this store.
+     * See `releaseWaitingMessage` for why this is a fact and not a guess. Called both when a turn ends and
+     * when the user stops it: in the stop case the child is killed mid-turn and a steer it was still holding
+     * was never delivered either, so putting it back is what lets the user decide what to do with it instead
+     * of silently dropping a message they typed - a message they can still see, because it never left the
+     * transcript in the first place.
      */
-    enqueueMessage(conversationId: string, content: string, images?: MessageImage[], attachments?: import("./types.js").MessageAttachments): Promise<QueuedMessage>;
+    releaseSendingMessages(conversationId: string): Promise<void>;
     /**
-     * Removes one waiting message. Returns it, or `undefined` when it is already gone.
+     * Withdraws one waiting message, by id. Returns it, or `undefined` when it is already gone.
      *
-     * "Already gone" is a no-op rather than an error, and the reason is the same as `SubagentRun.stop`:
-     * the click that sent this was almost always triggered by a dock row the browser has not been told
-     * about yet, so an id that has already been delivered or cancelled is the ordinary case and must not
-     * surface as a failure.
+     * "Already gone" is a no-op rather than an error, and the reason is the same as `SubagentRun.stop`: the
+     * click that sent this was almost always triggered by a bubble the browser has not been told about
+     * yet, so an id that has already been answered or cancelled is the ordinary case and must not surface
+     * as a failure.
      *
-     * A `sending` entry REFUSES, because the text is already in a live Pi child's stdin and Pi has no way
+     * A `sending` message REFUSES, because the text is already in a live Pi child's stdin and Pi has no way
      * to forget one item (its only queue command is `clear_queue`, which clears every one of them,
-     * including follow-ups that have nothing to do with this click). Removing it from this list would not
-     * stop Pi from delivering it - it would make the model act on a message the user believed they had
-     * withdrawn.
+     * including follow-ups that have nothing to do with this click). Removing it here would not stop Pi from
+     * delivering it - it would make the model act on a message the user believed they had withdrawn, while
+     * their own transcript quietly lost the words.
      */
-    cancelQueuedMessage(conversationId: string, queueId: string): Promise<QueuedMessage | undefined>;
+    cancelWaitingMessage(conversationId: string, messageId: string): Promise<Message | undefined>;
     /**
-     * Claims one waiting message for delivery to the live Pi process: `queued` becomes `sending`, and the
-     * entry STAYS in the list until Pi reports it delivered.
+     * Rewrites the words of one waiting message.
      *
-     * The read and the write are adjacent statements with no `await` between them, which is what makes
-     * the claim atomic here. This store has no mutex, and it does not need one: JavaScript runs this
-     * synchronous run-to-completion, so a second caller arriving in the same tick observes the write above
-     * and cannot claim the same entry. Anything that needed to await between reading and writing would
-     * need real serialization instead.
+     * Only legal while nothing has read it. `waiting` means the text is still only in this transcript, so
+     * changing it is changing the whole truth of the message - there is no second copy anywhere that could
+     * fall out of step. `sending` means Pi already holds it, and a message the model is about to answer is
+     * not one the user gets to rewrite after the fact.
+     */
+    editWaitingMessage(conversationId: string, messageId: string, content: string): Promise<Message>;
+    /**
+     * Moves one waiting message to a new position among the waiting messages.
+     *
+     * `toIndex` is counted over the WAITING messages only, so `0` is the next one the agent will start and
+     * the caller never has to know how many answered messages sit above it. Moving to the front and moving
+     * back are the same operation, which is the point: the old arrangement had a `priority` boolean for the
+     * first and no way at all to express the second, so undoing a priority meant cancelling the message and
+     * retyping it.
      *
-     * Throws for an unknown id and for one that is already `sending`, because both mean the caller is
-     * acting on a state the store has already moved past - and the second one means a second steer of the
-     * same message would put the text into Pi twice.
+     * NOTHING CAN GO IN FRONT OF A `sending` MESSAGE. It is already in Pi's stdin and Pi's steering queue
+     * is FIFO, so it will be delivered before anything this server could do about the order. Accepting the
+     * move and then delivering the other one first would be the UI promising an outcome the transport has
+     * already decided, so it is refused instead.
      */
-    claimQueuedMessage(conversationId: string, queueId: string): Promise<QueuedMessage>;
-    /** Keep a priority request at the front even if the current Pi process has already exited. */
-    prioritizeQueuedMessage(conversationId: string, queueId: string): Promise<QueuedMessage>;
+    reorderWaitingMessage(conversationId: string, messageId: string, toIndex: number): Promise<Message>;
     /**
-     * Puts a `sending` entry back into the queue.
+     * Pi has just delivered one steered message: unmark it and open the answer to it, in ONE write.
      *
-     * The one legal use, and it is narrow on purpose: this is called ONLY when we can prove the message
-     * never reached a model - the turn ended while Pi still held it, or the write to Pi's stdin failed
-     * before it left. Pi drains steering before its loop can end and reports the removal before the
-     * delivered message, so a message still `sending` when the child is gone provably was not delivered,
-     * and returning it is a fact rather than a guess. It is deliberately NOT used for "Pi has not answered
-     * yet" (see `steer` in `index.ts`), where the outcome is genuinely unknown and the honest state is
-     * still `sending`.
+     * Oldest rather than matched on text, and that is forced on us by Pi rather than chosen: Pi identifies
+     * its own queued entry by `indexOf` on the message text (`agent-session.ts:1123`), so two identical
+     * steered messages are ONE entry to it and no host-side matching could do better. Position is sufficient
+     * anyway because Pi's steering queue is FIFO and Super Pi only ever steers from the front of the waiting
+     * group.
+     *
+     * ONE WRITE, because the reader must never see the intermediate: a message that has stopped waiting but
+     * has no answer under it yet is the exact broken state this refactor exists to remove, and a browser
+     * that broadcast between the two halves would put it right back on screen.
+     *
+     * WHAT IS DIFFERENT FROM BEFORE, and is the whole point: the message used to be DELETED here. It is now
+     * merely unmarked, with an assistant message spliced in after it. It was on screen the whole time - it
+     * was written into the transcript when the user pressed send, long before Pi ever saw it - and it stays
+     * exactly where it was, now with the agent answering it. Deleting it is what made a steered reply appear
+     * with no question above it.
      */
-    releaseQueuedMessage(queueId: string): Promise<void>;
+    deliverWaitingMessage(conversationId: string, agentIdentity?: Message["agentIdentity"]): Promise<{
+        user: Message;
+        assistant: Message;
+    } | undefined>;
     /**
-     * Removes the OLDEST `count` messages this conversation has in `sending`, and returns them.
+     * Opens a turn on a message that is ALREADY IN THE TRANSCRIPT: clears its delivery state, applies every
+     * side effect that means "a turn started here", and splices the assistant placeholder in DIRECTLY AFTER
+     * IT.
+     *
+     * THE INSERT POSITION IS THE WHOLE DESIGN. `push` was the old behaviour and it is only correct when the
+     * message being answered is the last thing in the conversation. With two messages waiting, answering
+     * the first by appending puts its reply BELOW the second one, so the reader sees the answer to a
+     * question that is still waiting - a transcript lying about its own order. Splicing at
+     * `indexOf(user) + 1` keeps every waiting message below the reply that belongs to the one above it.
      *
-     * Driven by a COUNT rather than by matching text, and that is the whole point. Pi's `queue_update`
-     * reports only the strings it still holds, and Pi itself identifies which of its entries a delivered
-     * message came from with `indexOf` on that text - so with two identical steered messages, "which one
-     * was delivered" is exactly the question Pi cannot answer. It does not need to be answered: Pi's
-     * steering queue is FIFO and Super Pi only ever steers from the front of this list, so a drop in
-     * `steering.length` from N to N-k means Super Pi's oldest k `sending` entries were delivered, in
-     * order, whatever their text was.
+     * The side effects - title, `updatedAt`, `status: "running"`, clearing a stale failure - all describe a
+     * TURN rather than a message, which is why `addUserMessage` skips them for a message that is only
+     * waiting. They belong here, at the moment the turn genuinely begins.
      */
-    dropSendingMessages(conversationId: string, count: number): Promise<QueuedMessage[]>;
+    openTurnOnMessage(conversationId: string, messageId: string, agentIdentity?: Message["agentIdentity"]): Promise<{
+        user: Message;
+        assistant: Message;
+    }>;
     /**
-     * Takes the oldest still-`queued` message of this conversation OUT of the list and returns it, for the
+     * Takes the OLDEST still-`waiting` message of this conversation, clearing its delivery state, for the
      * next turn to send as its prompt.
      *
-     * Removing it here, rather than marking it and removing it after the turn, is what bounds the loop:
-     * every pass through the follow-up loop strictly shrinks the list, so the loop cannot run forever
-     * even if a turn succeeds without consuming anything. And removing it BEFORE the spawn is what makes a
-     * crash honest - a server that dies mid-turn has already taken the message out of the file, and
-     * `open` does not put it back, because it may well have been delivered.
+     * Clearing the state and taking the message are the same write on purpose: it bounds the follow-up loop
+     * (every pass strictly shrinks the set of waiting messages, so the loop cannot run forever even if a turn
+     * succeeds without consuming anything) and it is what makes the crash honest - a server that dies
+     * mid-turn has already taken the message out of the waiting set, so startup does not put it back, because
+     * it may well have been delivered.
      */
-    takeNextQueuedMessage(conversationId: string): Promise<QueuedMessage | undefined>;
-    /** Removes one still-cancellable row by id so an explicit user action can start it as a new turn. */
-    takeQueuedMessage(conversationId: string, queueId: string): Promise<QueuedMessage>;
+    takeNextWaitingMessage(conversationId: string): Promise<Message | undefined>;
+    /** Takes one specific waiting message by id, so an explicit user action can start it as a new turn. */
+    takeWaitingMessage(conversationId: string, messageId: string): Promise<Message>;
     /**
-     * Returns every `sending` message of this conversation to the queue, for the end of a turn.
+     * Opens a turn for a message the user chose to be answered now, when the conversation is idle.
      *
-     * See `releaseQueuedMessage` for why this is a fact and not a guess, and `reconcileQueuedMessages` for
-     * why the same treatment is right after a crash. Called both when a turn ends and when the user stops
-     * it: in the stop case the child is killed mid-turn and a steer it was still holding was never
-     * delivered either, so putting it back is what lets the user decide what to do with it instead of
-     * silently dropping a message they typed.
+     * The one place that both claims a specific message and opens its turn, so there is no window between
+     * "the message stopped waiting" and "the turn began" in which a crash would leave a message that is
+     * neither waiting nor answered.
      */
-    releaseSendingMessages(conversationId: string): Promise<void>;
+    openTurnOnSpecificMessage(conversationId: string, messageId: string, agentIdentity?: Message["agentIdentity"]): Promise<{
+        user: Message;
+        assistant: Message;
+    }>;
     /**
      * Records a sub-agent run as `running`, BEFORE the child is spawned.
      *