@camox/api-contract 0.54.0 → 0.57.0

package/src/threads.ts

@@ -2,6 +2,8 @@ import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
 import type { AgentEvent, EntryRecord } from "@earendil-works/pi-durable";
 import { z } from "zod";
 
+import type { DraftOutcome } from "./drafts.ts";
+
 // A thread with Camox's agent, as the studio shows it. The thread's Durable Object sends Pi's own
 // agent events over its socket, and this module is the one place that interprets them: the
 // studio and the API's tests fold them with the same code.
@@ -29,6 +31,41 @@ export const BUILD_STATUS_ENTRY = "camox.build-status";
  */
 export const RECONCILE_ENTRY = "camox.reconcile";
 
+/**
+ * The kind of the transcript entry opening a draft's thread a Live thread handed a request off
+ * to: the Brief, which the model reads and editors see as from Camox, ahead of the editor's
+ * messages.
+ */
+export const BRIEF_ENTRY = "camox.brief";
+
+/**
+ * The kind of the transcript entry telling the agent on Live that a draft it started ended,
+ * published or deleted, with the draft's id as data (`{ draftId }`). The model reads
+ * it at the end of the conversation; editors never see it, since the draft's card says so.
+ */
+export const DRAFT_ENDED_ENTRY = "camox.draft-ended";
+
+/**
+ * The agent's tool on Live handing a request off to a draft it starts (ADR 0025). A run whose
+ * call of it went through ends on the draft's card.
+ */
+export const START_DRAFT_TOOL = "startDraft";
+
+/** The draft a `startDraft` call started, as its result's details name it for the card. */
+export const startedDraftCardSchema = z.object({ draftId: z.string(), name: z.string() });
+export type StartedDraftCard = z.infer<typeof startedDraftCardSchema>;
+
+/**
+ * Where a draft a Live thread's card names stands, as the thread looks it up whenever it's shown
+ * (ADR 0025): its current name, or its last once it ended, and how it ended. Never written into
+ * the transcript, so the model's cached prompt keeps up. A name cleared by a rename is null: the
+ * card keeps the name the agent gave it.
+ */
+export type DraftCardState = { name: string | null; ended?: DraftOutcome };
+
+/** The drafts a Live thread's cards name, by id, as the thread last looked them up. */
+export type DraftCardStates = Readonly<Record<string, DraftCardState>>;
+
 export const reconcileDataSchema = z.object({ message: z.string() });
 
 export const buildStatusSchema = z.enum(["building", "fixing"]);
@@ -48,15 +85,19 @@ export type ThreadSender = z.infer<typeof threadSenderSchema>;
 export const isSender = (data: unknown): data is ThreadSender =>
   threadSenderSchema.safeParse(data).success;
 
-/** What an editor's message entry records: who sent it, and the operation id it was sent with. */
+/**
+ * What an editor's message entry records: who sent it, the operation id it was sent with, and for
+ * a message sent on Live as the agent handed the request off, the draft it went to with it.
+ */
 export const editorMessageDataSchema = threadSenderSchema.extend({
   operationId: z.string().optional(),
+  handedOffTo: z.string().optional(),
 });
 
 /**
- * A draft a Live thread started with its first write, becoming its thread, and the operation ids
- * of the messages of the run that made the write: the studio that sent one of them enters the
- * draft with the thread.
+ * A draft the agent on Live started with `startDraft`, and the operation ids of the messages of
+ * the run that started it: the studio that sent one of them enters the draft, if it still shows
+ * Live.
  */
 export const startedDraftSchema = z.object({
   draftId: z.string(),
@@ -119,22 +160,16 @@ export type ThreadMessage =
    */
   | { id: string; from: "failed" }
   /** In place of the agent's message, for a turn an editor stopped: `sender` stopped it. */
-  | { id: string; from: "stopped"; sender: ThreadSender };
-
-/** Where a Live thread's messages went when it started a draft, beside its transcript. */
-type LiveThreadHandoff = {
+  | { id: string; from: "stopped"; sender: ThreadSender }
   /**
-   * The draft this Live thread started with its first write, whose thread it became. The studio
-   * that sent a message of that run enters the draft with the thread; other tabs on Live move to
-   * the editor's fresh Live thread.
+   * In place of the agent's message, for a Live turn handed off to a draft the agent started:
+   * the draft's card, with its current name, which opens it. Once the draft ended, it has its
+   * last name and how it ended, and opens nothing. The turn is finished.
    */
-  startedDraft?: StartedDraft;
-  /** The draft the editor's previous Live thread continued in, for a fresh Live thread. */
-  continuedIn?: StartedDraft;
-};
+  | ({ id: string; from: "draft"; ended?: DraftOutcome } & StartedDraftCard);
 
 /** Everything the studio shows for a thread. */
-export type ThreadView = LiveThreadHandoff & {
+export type ThreadView = {
   messages: readonly ThreadMessage[];
   /** Whether a run is going: the agent is working on a turn, and stopping would end it. */
   running: boolean;
@@ -157,20 +192,28 @@ export const EMPTY_THREAD_VIEW: ThreadView = { messages: [], running: false };
  * and whether a run is going. The studio and the tests fold Pi's events into this, and derive
  * the view from it with `threadViewOf`, so a snapshot and the events that led to it show the same.
  */
-export type ThreadState = LiveThreadHandoff & {
+export type ThreadState = {
   steps: readonly ThreadStep[];
   running: boolean;
   /** The model's calls still running, by call id. A tool's own calls aren't the agent's. */
   toolCalls?: readonly string[];
   /** Whether the model's latest message makes tool calls: it writes them, then they run. */
   callingTools?: boolean;
+  /** The drafts the thread's cards name, as the thread last looked them up. */
+  drafts?: DraftCardStates;
 };
 
 export const EMPTY_THREAD_STATE: ThreadState = { steps: [], running: false };
 
 /** One transcript entry, as far as the studio's view is concerned. */
 type ThreadStep = { id: string } & (
-  | { type: "editor"; sender: ThreadSender; text: string }
+  | {
+      type: "editor";
+      sender: ThreadSender;
+      text: string;
+      /** The draft the message went to, as the agent on Live handed the request off. */
+      handedOffTo?: string;
+    }
   /** Camox starting a turn of its own, saying why. */
   | { type: "camox"; text: string }
   | { type: "answer"; text: string }
@@ -179,6 +222,8 @@ type ThreadStep = { id: string } & (
   /** A model call that ended without an answer: failed, aborted, or cut short. */
   | { type: "unfinished" }
   | { type: "stopped"; sender: ThreadSender }
+  /** A `startDraft` call that went through, which ends the turn on the draft's card. */
+  | ({ type: "draft" } & StartedDraftCard)
   /** Where the build of the turn's code stands, as the turn ends. */
   | { type: "build"; status: BuildStatus }
   /**
@@ -211,13 +256,16 @@ export type ThreadServerMessage =
   | { type: "events"; events: readonly AgentEvent[] }
   /** The thread recorded the message sent with this operation id (once, however often sent). */
   | { type: "accepted"; operationId: string }
-  /** This Live thread started a draft with its first write, and became that draft's thread. */
+  /**
+   * The agent on Live started a draft with `startDraft`: the studio that sent a message of the
+   * run enters it, if it still shows Live. Live only: a snapshot never replays it.
+   */
   | { type: "started-draft"; startedDraft: StartedDraft }
   /**
-   * The editor's previous Live thread continued in this draft: this one is fresh. Sent before
-   * the snapshot.
+   * Where the drafts a Live thread's cards name stand, after each snapshot and whenever one of
+   * them is renamed or ends. It replaces what the studio knew of them.
    */
-  | { type: "continued-in"; continuedIn: StartedDraft }
+  | { type: "drafts"; drafts: DraftCardStates }
   /**
    * A code-mode script that wrote something ended, failed or not: what its successful writes
    * touched. Sent once per such script, live only: a snapshot never replays past touches.
@@ -232,7 +280,8 @@ export type ThreadServerMessage =
  */
 export const THREAD_ENDED_CLOSE_CODE = 4000;
 
-const textOf = (content: Message["content"]) =>
+/** The text of a message's content: its text parts, joined. */
+export const textOf = (content: Message["content"]) =>
   typeof content === "string"
     ? content
     : content
@@ -264,12 +313,24 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
     const build = buildStatusDataSchema.safeParse(entry.data).data;
     return build && { id, type: "build", status: build.status };
   }
+  // Only the model reads it: as a user message, it would otherwise read as Pi continuing a run.
+  if (entry.kind === DRAFT_ENDED_ENTRY) return undefined;
   const message = entry.model?.find((candidate) => candidate.role !== "system");
   if (!message) return undefined;
   if (message.role === "user") {
     if (entry.kind === EDITOR_MESSAGE_ENTRY) {
-      return sender && { id, type: "editor", sender, text: textOf(message.content) };
+      const handedOffTo = editorMessageDataSchema.safeParse(entry.data).data?.handedOffTo;
+      return (
+        sender && {
+          id,
+          type: "editor",
+          sender,
+          text: textOf(message.content),
+          ...(handedOffTo && { handedOffTo }),
+        }
+      );
     }
+    if (entry.kind === BRIEF_ENTRY) return { id, type: "camox", text: textOf(message.content) };
     if (entry.kind === RECONCILE_ENTRY) {
       const reconcile = reconcileDataSchema.safeParse(entry.data).data;
       return reconcile && { id, type: "camox", text: reconcile.message };
@@ -279,15 +340,21 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
     return { id, type: "continued" };
   }
   if (message.role === "assistant") return assistantStep(id, message);
-  if (message.role === "toolResult") return { id, type: "tools" };
+  if (message.role === "toolResult") {
+    const card =
+      message.toolName === START_DRAFT_TOOL && !message.isError
+        ? startedDraftCardSchema.safeParse(message.details).data
+        : undefined;
+    return card ? { id, type: "draft", ...card } : { id, type: "tools" };
+  }
   return undefined;
 }
 
 /**
  * What the studio shows for a thread. A turn starts with an editor's message, or Camox's own
  * when it began the turn itself, and messages sent
- * while it runs join it. It ends with the agent's final message; text written beside tool calls
- * is never shown. A stopped turn shows who stopped it instead, and whatever its run wrote after
+ * while it runs join it. It ends with the agent's final message, or on Live, the card of the
+ * draft it handed the request off to; text written beside tool calls is never shown. A stopped turn shows who stopped it instead, and whatever its run wrote after
  * the stop is left out. A turn that ended without either shows a failed line in its place: its
  * run is over, or a later message started another run after its last model call came back
  * unfinished. While Pi retries a failed call, the run goes on, so the turn shows as working.
@@ -297,7 +364,7 @@ export function threadViewOf({
   running,
   toolCalls = [],
   callingTools = false,
-  ...drafts
+  drafts = {},
 }: ThreadState): ThreadView {
   const messages: ThreadMessage[] = [];
   // The latest editor's message of a turn still waiting for the agent's message.
@@ -322,7 +389,24 @@ export function threadViewOf({
 
   for (const step of steps) {
     switch (step.type) {
-      case "editor":
+      case "editor": {
+        // A message sent as the agent on Live handed the request off went to the draft with it:
+        // it belongs to the turn ending on that draft's card, which it shows just before. Pi
+        // placed it after the card, which leaves the transcript the model read as it was.
+        const card = step.handedOffTo
+          ? messages.findLastIndex(
+              (message) => message.from === "draft" && message.draftId === step.handedOffTo,
+            )
+          : -1;
+        if (card !== -1) {
+          messages.splice(card, 0, {
+            id: step.id,
+            from: "editor",
+            sender: step.sender,
+            text: step.text,
+          });
+          break;
+        }
         // Pi places a steering message only once a model call is settled: after a round of tool
         // calls, or with the answer ending the run. Never between a failed call and its retry, so
         // an editor's message after an unfinished call means that call's turn is over.
@@ -330,6 +414,7 @@ export function threadViewOf({
         messages.push({ id: step.id, from: "editor", sender: step.sender, text: step.text });
         waiting = step.id;
         break;
+      }
       case "camox":
         if (unfinished) fail();
         messages.push({ id: step.id, from: "camox", text: step.text });
@@ -350,6 +435,21 @@ export function threadViewOf({
           answered = before;
         }
         break;
+      case "draft":
+        // The handoff answers the turn: the agent says nothing more.
+        if (waiting === undefined && messages.at(-1)?.from === "stopped") break;
+        {
+          const draft = drafts[step.draftId];
+          messages.push({
+            id: step.id,
+            from: "draft",
+            draftId: step.draftId,
+            name: draft?.name ?? step.name,
+            ...(draft?.ended && { ended: draft.ended }),
+          });
+        }
+        endTurn();
+        break;
       case "continued":
         // The answer before wasn't the turn's last. Once the end of the turn gives up fixing,
         // the agent explains without a status.
@@ -373,7 +473,6 @@ export function threadViewOf({
   if (!running) fail();
   const usingTools = running && (callingTools || toolCalls.length > 0);
   return {
-    ...drafts,
     messages,
     running,
     ...(running && status && { status }),
@@ -439,10 +538,8 @@ export function reduceThreadFrame(state: ThreadState, frame: ThreadServerMessage
   switch (frame.type) {
     case "events":
       return reduceThreadEvents(state, frame.events);
-    case "started-draft":
-      return { ...state, startedDraft: frame.startedDraft };
-    case "continued-in":
-      return { ...state, continuedIn: frame.continuedIn };
+    case "drafts":
+      return { ...state, drafts: frame.drafts };
     default:
       return state;
   }