@camox/api-contract 0.58.1 → 0.60.2

package/src/threads.ts

@@ -10,7 +10,9 @@ import type { DraftOutcome } from "./drafts.ts";
 
 /**
  * The kind of the transcript entry recording an editor's message, with its sender and the
- * operation id the studio sent it with as data (`editorMessageDataSchema`).
+ * operation id the studio sent it with as data (`editorMessageDataSchema`). Its first text part
+ * is what the editor wrote; a second one, which only the model reads, says where they were in the
+ * studio as they sent it (`editorTextOf`).
  */
 export const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
 
@@ -45,12 +47,57 @@ export const BRIEF_ENTRY = "camox.brief";
  */
 export const DRAFT_ENDED_ENTRY = "camox.draft-ended";
 
+/**
+ * The kind of the transcript entry recording a member's push to the draft's code from their own
+ * checkout (ADR 0026), with a `pushDataSchema` as data. The model reads it as context, never
+ * answering it, and editors see who pushed, their commits, and whether they built.
+ */
+export const PUSH_ENTRY = "camox.push";
+
+/** How a pushed head's build ended: built, built with type errors, or built but not previewed. */
+export const pushOutcomeSchema = z.enum(["built", "typeErrors", "notPreviewed"]);
+export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
+
 /**
  * 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 agent's tool building its code changes mid-turn, which the end of a turn also does. */
+export const BUILD_TOOL = "build";
+
+/**
+ * The tools whose calls change a draft: the content tools that write, and the code tools that
+ * write files. The model calls the code tools, and code mode scripts call both. A test in the API
+ * keeps this in step with the tools themselves.
+ */
+export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
+  // Content
+  "addBackToLocale",
+  "addLocale",
+  "createBlock",
+  "createCollectionRecord",
+  "createPage",
+  "deleteBlock",
+  "deleteCollectionRecord",
+  "deletePage",
+  "editBlock",
+  "editCollectionRecord",
+  "moveBlock",
+  "removeLocale",
+  "setPageLayout",
+  "setPageSeo",
+  "updateFile",
+  "updatePage",
+  "uploadFile",
+  // Code
+  "edit",
+  "mv",
+  "rm",
+  "write",
+]);
+
 /** 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>;
@@ -85,6 +132,14 @@ export type ThreadSender = z.infer<typeof threadSenderSchema>;
 export const isSender = (data: unknown): data is ThreadSender =>
   threadSenderSchema.safeParse(data).success;
 
+/** What a push's entry records: who pushed, their commits' subjects, oldest first, and the build. */
+export const pushDataSchema = z.object({
+  pusher: threadSenderSchema,
+  subjects: z.array(z.string()),
+  outcome: pushOutcomeSchema,
+});
+export type PushData = z.infer<typeof pushDataSchema>;
+
 /**
  * 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.
@@ -166,23 +221,39 @@ export type ThreadMessage =
    * 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.
    */
-  | ({ id: string; from: "draft"; ended?: DraftOutcome } & StartedDraftCard);
+  | ({ id: string; from: "draft"; ended?: DraftOutcome } & StartedDraftCard)
+  /**
+   * A member's push to the draft's code from their own checkout: who pushed, their commits'
+   * subjects, oldest first, and how the pushed head built. It's no turn: the agent doesn't
+   * answer it.
+   */
+  | { id: string; from: "push"; sender: ThreadSender; subjects: string[]; outcome: PushOutcome };
+
+/**
+ * What the agent is doing during a run, as editors see it, without the details of how it works:
+ * - `thinking`: the model is called, and hasn't started writing a tool call.
+ * - `exploring`: it uses tools that only read, from writing a call until the model is called again.
+ * - `changing`: a call of that round changes the draft (`CHANGING_TOOLS`), as soon as it's written
+ *   or, in a code mode script, as soon as the script calls one.
+ * - `building`: its `build` call runs, or the end of the turn builds its code changes.
+ * - `fixing`: the end of the turn's build failed, and the agent fixes it.
+ * - `startingDraft`: on Live, its `startDraft` call runs.
+ */
+export type AgentActivity =
+  | "thinking"
+  | "exploring"
+  | "changing"
+  | "building"
+  | "fixing"
+  | "startingDraft";
 
 /** Everything the studio shows for a thread. */
 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;
-  /**
-   * While a run is going, where the build of the code its turn changed stands: the end of the
-   * turn is building it, or it failed and the agent is fixing it.
-   */
-  status?: BuildStatus;
-  /**
-   * While a run is going, whether the agent is using its tools, code mode included, rather than
-   * thinking: from writing a call until the model is called again.
-   */
-  usingTools?: true;
+  /** While a run is going, what the agent is doing. */
+  activity?: AgentActivity;
 };
 
 export const EMPTY_THREAD_VIEW: ThreadView = { messages: [], running: false };
@@ -195,10 +266,15 @@ export const EMPTY_THREAD_VIEW: ThreadView = { messages: [], running: false };
 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[];
+  /** The model's calls still running. A tool's own calls aren't the agent's. */
+  toolCalls?: readonly { callId: string; name: string }[];
   /** Whether the model's latest message makes tool calls: it writes them, then they run. */
   callingTools?: boolean;
+  /**
+   * Whether a call of the latest round changes the draft, the model's or a script's: from writing
+   * or making it until the model is called again.
+   */
+  changing?: boolean;
   /** The drafts the thread's cards name, as the thread last looked them up. */
   drafts?: DraftCardStates;
 };
@@ -226,6 +302,8 @@ type ThreadStep = { id: string } & (
   | ({ type: "draft" } & StartedDraftCard)
   /** Where the build of the turn's code stands, as the turn ends. */
   | { type: "build"; status: BuildStatus }
+  /** A member's push, between turns. */
+  | ({ type: "push" } & PushData)
   /**
    * The end of the turn sent the agent back to work, after its answer: the answer wasn't the
    * turn's last, and what the agent was told is never shown.
@@ -233,13 +311,54 @@ type ThreadStep = { id: string } & (
   | { type: "continued" }
 );
 
+/**
+ * What an editor had selected on the page as they sent a message, unless they cleared it from
+ * the message: its path as the studio names it, from the block down to the selection, with the
+ * ids the agent's tools take. A record is the one the selection shows, a field the selection's
+ * own, of the record when a record is selected.
+ */
+export const editorSelectionSchema = z.object({
+  path: z.array(z.string().max(512)).min(1).max(16),
+  blockId: z.string().max(64).optional(),
+  itemId: z.string().max(64).optional(),
+  recordId: z.string().max(64).optional(),
+  fieldName: z.string().max(256).optional(),
+});
+export type EditorSelection = z.infer<typeof editorSelectionSchema>;
+
+/**
+ * Where an editor was in the studio as they sent a message, in the Locale they viewed: a Page,
+ * by its path after the Locale's prefix and its title, with its id for a curated page and its
+ * Layout's for a layout page, and what they had selected on it, or the Canvas with no page
+ * selected. A hint for the agent, never what the message is about.
+ */
+export const editorWhereSchema = z.discriminatedUnion("on", [
+  z.object({
+    on: z.literal("page"),
+    locale: z.string().max(64),
+    path: z.string().max(2048),
+    title: z.string().max(512),
+    pageId: z.string().max(64).optional(),
+    layoutId: z.string().max(256).optional(),
+    selection: editorSelectionSchema.optional(),
+  }),
+  z.object({ on: z.literal("canvas"), locale: z.string().max(64) }),
+]);
+export type EditorWhere = z.infer<typeof editorWhereSchema>;
+
 /** Studio → thread. */
 export const threadClientMessageSchema = z.discriminatedUnion("type", [
   /**
-   * An editor's message. The operation id is generated by the studio and kept across resends, so
-   * a message resent after a dropped connection is one submission.
+   * An editor's message, and where they were as they sent it. The operation id is generated by
+   * the studio and kept across resends, so a message resent after a dropped connection is one
+   * submission.
    */
-  z.object({ type: z.literal("send"), operationId: z.string().min(1), text: z.string().min(1) }),
+  z.object({
+    type: z.literal("send"),
+    operationId: z.string().min(1),
+    text: z.string().min(1),
+    where: editorWhereSchema.optional(),
+  }),
   /** Stops the run going, if any. What the agent changed before stays. */
   z.object({ type: z.literal("stop") }),
   /** Asks for a fresh snapshot of the thread. */
@@ -275,8 +394,7 @@ export type ThreadServerMessage =
 
 /**
  * The code a thread closes its sockets with once it ended with its draft, and for good: it's
- * deleted, so reconnecting reaches nothing. A development draft, which stays open, gets a new
- * thread the next time the studio connects.
+ * deleted, so reconnecting reaches nothing.
  */
 export const THREAD_ENDED_CLOSE_CODE = 4000;
 
@@ -289,6 +407,15 @@ export const textOf = (content: Message["content"]) =>
         .join("")
         .trim();
 
+/**
+ * What an editor wrote, of their message entry's content: its first text part. The rest, where
+ * they were in the studio, only the model reads.
+ */
+export const editorTextOf = (content: Message["content"]) =>
+  typeof content === "string"
+    ? content
+    : (content.find((part) => part.type === "text")?.text ?? "").trim();
+
 /** What an assistant message is to the thread: a final answer, a tool round, or neither. */
 function assistantStep(id: string, message: AssistantMessage): ThreadStep {
   if (message.content.some((part) => part.type === "toolCall")) return { id, type: "tools" };
@@ -315,6 +442,10 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
   }
   // 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;
+  if (entry.kind === PUSH_ENTRY) {
+    const push = pushDataSchema.safeParse(entry.data).data;
+    return push && { id, type: "push", ...push };
+  }
   const message = entry.model?.find((candidate) => candidate.role !== "system");
   if (!message) return undefined;
   if (message.role === "user") {
@@ -325,7 +456,7 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
           id,
           type: "editor",
           sender,
-          text: textOf(message.content),
+          text: editorTextOf(message.content),
           ...(handedOffTo && { handedOffTo }),
         }
       );
@@ -364,6 +495,7 @@ export function threadViewOf({
   running,
   toolCalls = [],
   callingTools = false,
+  changing = false,
   drafts = {},
 }: ThreadState): ThreadView {
   const messages: ThreadMessage[] = [];
@@ -462,6 +594,16 @@ export function threadViewOf({
       case "build":
         status = step.status;
         break;
+      case "push":
+        // Pushes land between turns: one doesn't end a turn, nor start one.
+        messages.push({
+          id: step.id,
+          from: "push",
+          sender: step.pusher,
+          subjects: step.subjects,
+          outcome: step.outcome,
+        });
+        break;
       case "tools":
         unfinished = false;
         break;
@@ -471,15 +613,44 @@ export function threadViewOf({
     }
   }
   if (!running) fail();
-  const usingTools = running && (callingTools || toolCalls.length > 0);
+  if (!running) return { messages, running };
   return {
     messages,
     running,
-    ...(running && status && { status }),
-    ...(usingTools && { usingTools }),
+    activity: activityOf({ status, toolCalls, callingTools, changing }),
   };
 }
 
+/** What the agent is doing during a run, from where the turn's build stands and its tool calls. */
+function activityOf({
+  status,
+  toolCalls,
+  callingTools,
+  changing,
+}: {
+  status: BuildStatus | undefined;
+  toolCalls: NonNullable<ThreadState["toolCalls"]>;
+  callingTools: boolean;
+  changing: boolean;
+}): AgentActivity {
+  const calling = (name: string) => toolCalls.some((call) => call.name === name);
+  // Fixing a build error takes thinking, reading and writing, which all read as fixing, but its
+  // builds show as building.
+  if (status === "building" || calling(BUILD_TOOL)) return "building";
+  if (status === "fixing") return "fixing";
+  if (calling(START_DRAFT_TOOL)) return "startingDraft";
+  if (changing) return "changing";
+  if (callingTools || toolCalls.length > 0) return "exploring";
+  return "thinking";
+}
+
+/** Whether a tool call changes the draft. */
+const changes = (name: string) => CHANGING_TOOLS.has(name);
+
+/** Whether a block of the model's message is a call of a tool that changes the draft. */
+const callsChangingTool = (block: AssistantMessage["content"][number]) =>
+  block.type === "toolCall" && changes(block.name);
+
 const append = (state: ThreadState, entry: EntryRecord | undefined): ThreadState => {
   const step = entry && threadStepOf(entry);
   if (!step || state.steps.some((known) => known.id === step.id)) return state;
@@ -489,33 +660,71 @@ const append = (state: ThreadState, entry: EntryRecord | undefined): ThreadState
 /** Folds one of Pi's agent events into the thread's state. */
 export function reduceThreadState(state: ThreadState, event: AgentEvent): ThreadState {
   switch (event.type) {
-    case "snapshot":
+    case "snapshot": {
+      const toolCalls = event.tools.flatMap((tool) =>
+        tool.status === "done" ? [] : [{ callId: tool.callId, name: tool.name }],
+      );
+      const generated = event.generation?.message?.content ?? [];
       return {
         ...state,
         steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
         running: event.run !== undefined,
-        toolCalls: event.tools.flatMap((tool) => (tool.status === "done" ? [] : [tool.callId])),
-        callingTools: !!event.generation?.message?.content.some((part) => part.type === "toolCall"),
+        toolCalls,
+        callingTools: generated.some((part) => part.type === "toolCall"),
+        // A script's calls count while the script runs, finished or not.
+        changing:
+          generated.some(callsChangingTool) ||
+          toolCalls.some((call) => changes(call.name)) ||
+          event.nestedTools.some(
+            (nested) =>
+              changes(nested.name) &&
+              toolCalls.some(
+                (call) =>
+                  nested.parentCallId === call.callId ||
+                  nested.parentCallId.startsWith(`${call.callId}/`),
+              ),
+          ),
       };
+    }
     case "run_start":
       return { ...state, running: true };
     case "run_end":
-      return { ...state, running: false, toolCalls: [], callingTools: false };
+      return { ...state, running: false, toolCalls: [], callingTools: false, changing: false };
     case "message_start":
       // The model is called again: it thinks until it writes a tool call.
-      return event.message.role === "assistant" ? { ...state, callingTools: false } : state;
-    case "message_update":
-      return event.changes.some((change) => change.type === "toolcall_start")
-        ? { ...state, callingTools: true }
+      return event.message.role === "assistant"
+        ? { ...state, callingTools: false, changing: false }
         : state;
-    case "tool_execution_start":
-      if (event.parentToolCallId !== undefined) return state;
-      return { ...state, toolCalls: [...(state.toolCalls ?? []), event.toolCallId] };
+    case "message_update": {
+      // A call's name may come with its start, a later change to its block, or the whole message.
+      const calls = event.changes.flatMap((change) =>
+        change.type === "toolcall_start" || change.type === "block"
+          ? [change.block]
+          : change.type === "message"
+            ? change.message.content
+            : [],
+      );
+      if (calls.length === 0) return state;
+      return {
+        ...state,
+        callingTools: state.callingTools || calls.some((block) => block.type === "toolCall"),
+        changing: state.changing || calls.some(callsChangingTool),
+      };
+    }
+    case "tool_execution_start": {
+      const changing = state.changing || changes(event.toolName);
+      if (event.parentToolCallId !== undefined) return { ...state, changing };
+      return {
+        ...state,
+        changing,
+        toolCalls: [...(state.toolCalls ?? []), { callId: event.toolCallId, name: event.toolName }],
+      };
+    }
     case "tool_execution_end":
       return append(
         {
           ...state,
-          toolCalls: state.toolCalls?.filter((callId) => callId !== event.toolCallId),
+          toolCalls: state.toolCalls?.filter((call) => call.callId !== event.toolCallId),
         },
         event.entry,
       );