@camox/api-contract 0.63.0 → 0.66.0

package/src/threads.ts

@@ -45,7 +45,8 @@ 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.
+ * messages. In a draft Camox opened, such as its Patrol Draft, Camox's own messages are Briefs
+ * too, with their `operationId` as data, and start the agent's run, which acts for Camox.
  */
 export const BRIEF_ENTRY = "camox.brief";
 
@@ -56,6 +57,14 @@ export const BRIEF_ENTRY = "camox.brief";
  */
 export const DRAFT_ENDED_ENTRY = "camox.draft-ended";
 
+/**
+ * The kind of the transcript entry a Live thread starts afresh from once its agent handed a
+ * request off to a draft (ADR 0036): a reset of Pi's context, with a `startedDraftCardSchema` as
+ * data. Editors see it as the draft's card, alone, and the model reads a note naming the draft.
+ * Everything before it is left out of both.
+ */
+export const DRAFT_CARD_ENTRY = "camox.draft-card";
+
 /**
  * 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
@@ -76,6 +85,29 @@ 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 agent's tool rendering the draft in a browser and returning screenshots to the model. */
+export const LOOK_TOOL = "look";
+
+/**
+ * The agent's tool handing an artifact's source to its Artifact Agent, which writes and changes
+ * it in a conversation of its own and answers the agent (ADR 0035).
+ */
+export const ARTIFACT_TOOL = "artifact";
+
+/**
+ * The kind of the entry recording a request the agent sent an Artifact Agent, in the Artifact
+ * Agent's own conversation, which editors never see: who the run acts for and the operation ids
+ * of its messages, as data (`artifactRequestDataSchema`).
+ */
+export const ARTIFACT_REQUEST_ENTRY = "camox.artifact-request";
+
+/** What an Artifact Agent's request records: the member the run acts for, and its messages. */
+export const artifactRequestDataSchema = z.object({
+  member: z.string(),
+  operationIds: z.array(z.string()),
+});
+export type ArtifactRequestData = z.infer<typeof artifactRequestDataSchema>;
+
 /**
  * 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
@@ -85,6 +117,7 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   // Content
   "addBackToLocale",
   "addLocale",
+  "applyFindingFix",
   "createBlock",
   "createCollectionRecord",
   "createPage",
@@ -167,13 +200,9 @@ export const pushDataSchema = z.object({
 });
 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.
- */
+/** What an editor's message entry records: who sent it, and the operation id it was sent with. */
 export const editorMessageDataSchema = threadSenderSchema.extend({
   operationId: z.string().optional(),
-  handedOffTo: z.string().optional(),
 });
 
 /**
@@ -274,16 +303,33 @@ export type ThreadMessage =
  * - `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.
+ * - `checking`: it looks at what it designed, from writing a `look` call until the model is
+ *   called again.
  * - `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";
+export const agentActivitySchema = z.enum([
+  "thinking",
+  "exploring",
+  "changing",
+  "building",
+  "checking",
+  "fixing",
+  "startingDraft",
+]);
+export type AgentActivity = z.infer<typeof agentActivitySchema>;
+
+/**
+ * What an `artifact` call's result carries for the studio: the Artifact Agent's answer, whether
+ * it's the agent's answer to the turn too, which then ends on it, and while it works, what the
+ * Artifact Agent is doing.
+ */
+export const artifactDetailsSchema = z.object({
+  answer: z.string().optional(),
+  final: z.boolean().optional(),
+  activity: agentActivitySchema.optional(),
+});
+export type ArtifactDetails = z.infer<typeof artifactDetailsSchema>;
 
 /** Everything the studio shows for a thread. */
 export type ThreadView = {
@@ -313,6 +359,10 @@ export type ThreadState = {
    * or making it until the model is called again.
    */
   changing?: boolean;
+  /** Whether the model's latest round calls `look`: from writing the call until it's called again. */
+  checking?: boolean;
+  /** What the Artifact Agent the running `artifact` call waits for is doing, as it last said. */
+  artifactActivity?: AgentActivity;
   /** The drafts the thread's cards name, as the thread last looked them up. */
   drafts?: DraftCardStates;
 };
@@ -321,13 +371,7 @@ 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;
-      /** The draft the message went to, as the agent on Live handed the request off. */
-      handedOffTo?: string;
-    }
+  | { type: "editor"; sender: ThreadSender; text: string }
   | { type: "connectedAgent"; member: ThreadSender; client: ConnectedAgentClient; text: string }
   /** Camox starting a turn of its own, saying why. */
   | { type: "camox"; text: string }
@@ -485,20 +529,16 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
     const push = pushDataSchema.safeParse(entry.data).data;
     return push && { id, type: "push", ...push };
   }
+  // The model reads a note: editors see the card it starts the Live thread afresh with.
+  if (entry.kind === DRAFT_CARD_ENTRY) {
+    const card = startedDraftCardSchema.safeParse(entry.data).data;
+    return card && { id, type: "draft", ...card };
+  }
   const message = entry.model?.find((candidate) => candidate.role !== "system");
   if (!message) return undefined;
   if (message.role === "user") {
     if (entry.kind === EDITOR_MESSAGE_ENTRY) {
-      const handedOffTo = editorMessageDataSchema.safeParse(entry.data).data?.handedOffTo;
-      return (
-        sender && {
-          id,
-          type: "editor",
-          sender,
-          text: editorTextOf(message.content),
-          ...(handedOffTo && { handedOffTo }),
-        }
-      );
+      return sender && { id, type: "editor", sender, text: editorTextOf(message.content) };
     }
     if (entry.kind === CONNECTED_AGENT_MESSAGE_ENTRY) {
       const data = connectedAgentMessageDataSchema.safeParse(entry.data).data;
@@ -523,6 +563,11 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
   }
   if (message.role === "assistant") return assistantStep(id, message);
   if (message.role === "toolResult") {
+    // An Artifact Agent's answer that ends the turn is the agent's: editors never see it apart.
+    if (message.toolName === ARTIFACT_TOOL && !message.isError) {
+      const details = artifactDetailsSchema.safeParse(message.details).data;
+      if (details?.final && details.answer) return { id, type: "answer", text: details.answer };
+    }
     const card =
       message.toolName === START_DRAFT_TOOL && !message.isError
         ? startedDraftCardSchema.safeParse(message.details).data
@@ -547,6 +592,8 @@ export function threadViewOf({
   toolCalls = [],
   callingTools = false,
   changing = false,
+  checking = false,
+  artifactActivity,
   drafts = {},
 }: ThreadState): ThreadView {
   const messages: ThreadMessage[] = [];
@@ -572,24 +619,7 @@ export function threadViewOf({
 
   for (const step of steps) {
     switch (step.type) {
-      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;
-        }
+      case "editor":
         // 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.
@@ -597,7 +627,6 @@ export function threadViewOf({
         messages.push({ id: step.id, from: "editor", sender: step.sender, text: step.text });
         waiting = step.id;
         break;
-      }
       case "connectedAgent":
         // Like an editor's message: it starts a turn, or steers the one going.
         if (unfinished) fail();
@@ -680,7 +709,7 @@ export function threadViewOf({
   return {
     messages,
     running,
-    activity: activityOf({ status, toolCalls, callingTools, changing }),
+    activity: activityOf({ status, toolCalls, callingTools, changing, checking, artifactActivity }),
   };
 }
 
@@ -690,16 +719,23 @@ function activityOf({
   toolCalls,
   callingTools,
   changing,
+  checking,
+  artifactActivity,
 }: {
   status: BuildStatus | undefined;
   toolCalls: NonNullable<ThreadState["toolCalls"]>;
   callingTools: boolean;
   changing: boolean;
+  checking: boolean;
+  artifactActivity: AgentActivity | undefined;
 }): 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";
+  // An Artifact Agent works on the agent's behalf: editors see what it does as the agent's.
+  if (calling(ARTIFACT_TOOL)) return artifactActivity ?? "changing";
+  if (checking) return "checking";
   if (status === "fixing") return "fixing";
   if (calling(START_DRAFT_TOOL)) return "startingDraft";
   if (changing) return "changing";
@@ -714,8 +750,25 @@ const changes = (name: string) => CHANGING_TOOLS.has(name);
 const callsChangingTool = (block: AssistantMessage["content"][number]) =>
   block.type === "toolCall" && changes(block.name);
 
+/** Whether a block of the model's message is a call of `look`. */
+const callsLook = (block: AssistantMessage["content"][number]) =>
+  block.type === "toolCall" && block.name === LOOK_TOOL;
+
+/**
+ * Adds an entry to the thread's state as Pi places it. An entry heading a new context, such as
+ * the card a Live thread starts afresh from, leaves out every step before its head, as Pi's
+ * snapshots do.
+ */
 const append = (state: ThreadState, entry: EntryRecord | undefined): ThreadState => {
-  const step = entry && threadStepOf(entry);
+  if (!entry) return state;
+  const step = threadStepOf(entry);
+  if (entry.head !== undefined) {
+    const head = Number(entry.head);
+    const kept = state.steps.filter(
+      (known) => Number(known.id) >= head && known.id !== String(entry.id),
+    );
+    return { ...state, steps: step ? [step, ...kept] : kept };
+  }
   if (!step || state.steps.some((known) => known.id === step.id)) return state;
   return { ...state, steps: [...state.steps, step] };
 };
@@ -728,12 +781,17 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
         tool.status === "done" ? [] : [{ callId: tool.callId, name: tool.name }],
       );
       const generated = event.generation?.message?.content ?? [];
+      const artifact = event.tools.find(
+        (tool) => tool.name === ARTIFACT_TOOL && tool.status !== "done",
+      );
       return {
         ...state,
         steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
+        artifactActivity: artifactDetailsSchema.safeParse(artifact?.details).data?.activity,
         running: event.run !== undefined,
         toolCalls,
         callingTools: generated.some((part) => part.type === "toolCall"),
+        checking: generated.some(callsLook) || toolCalls.some((call) => call.name === LOOK_TOOL),
         // A script's calls count while the script runs, finished or not.
         changing:
           generated.some(callsChangingTool) ||
@@ -752,11 +810,19 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
     case "run_start":
       return { ...state, running: true };
     case "run_end":
-      return { ...state, running: false, toolCalls: [], callingTools: false, changing: false };
+      return {
+        ...state,
+        running: false,
+        toolCalls: [],
+        callingTools: false,
+        changing: false,
+        checking: false,
+        artifactActivity: undefined,
+      };
     case "message_start":
       // The model is called again: it thinks until it writes a tool call.
       return event.message.role === "assistant"
-        ? { ...state, callingTools: false, changing: false }
+        ? { ...state, callingTools: false, changing: false, checking: false }
         : state;
     case "message_update": {
       // A call's name may come with its start, a later change to its block, or the whole message.
@@ -772,6 +838,7 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
         ...state,
         callingTools: state.callingTools || calls.some((block) => block.type === "toolCall"),
         changing: state.changing || calls.some(callsChangingTool),
+        checking: state.checking || calls.some(callsLook),
       };
     }
     case "tool_execution_start": {
@@ -780,14 +847,22 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
       return {
         ...state,
         changing,
+        checking: state.checking || event.toolName === LOOK_TOOL,
         toolCalls: [...(state.toolCalls ?? []), { callId: event.toolCallId, name: event.toolName }],
       };
     }
+    case "tool_execution_update": {
+      if (event.toolName !== ARTIFACT_TOOL || event.parentToolCallId !== undefined) return state;
+      const activity = artifactDetailsSchema.safeParse(event.details).data?.activity;
+      return activity ? { ...state, artifactActivity: activity } : state;
+    }
     case "tool_execution_end":
       return append(
         {
           ...state,
           toolCalls: state.toolCalls?.filter((call) => call.callId !== event.toolCallId),
+          ...(event.toolName === ARTIFACT_TOOL &&
+            event.parentToolCallId === undefined && { artifactActivity: undefined }),
         },
         event.entry,
       );