@camox/api-contract 0.51.0 → 0.52.1

package/dist/threads.d.ts

@@ -8,6 +8,32 @@ import { AgentEvent } from "@earendil-works/pi-durable";
 export declare const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
 export declare const RUN_STOPPED_ENTRY = "camox.run-stopped";
+/**
+ * The kind of the transcript entry recording where the build of the code a turn changed stands,
+ * as the turn ends, with a `buildStatusDataSchema` as data: it started, or it failed and the
+ * agent is fixing it. The model never sees it.
+ */
+export declare const BUILD_STATUS_ENTRY = "camox.build-status";
+/**
+ * The kind of the transcript entry starting Camox's own turn, which reconciles the draft's code
+ * with Live's when merging it clashed, with a `reconcileDataSchema` as data: the short message
+ * editors see. The model gets Camox's instructions instead.
+ */
+export declare const RECONCILE_ENTRY = "camox.reconcile";
+export declare const reconcileDataSchema: z.ZodObject<{
+  message: z.ZodString;
+}, z.core.$strip>;
+export declare const buildStatusSchema: z.ZodEnum<{
+  building: "building";
+  fixing: "fixing";
+}>;
+export type BuildStatus = z.infer<typeof buildStatusSchema>;
+export declare const buildStatusDataSchema: z.ZodObject<{
+  status: z.ZodEnum<{
+    building: "building";
+    fixing: "fixing";
+  }>;
+}, z.core.$strip>;
 /** Who sent a message in a thread. */
 export declare const threadSenderSchema: z.ZodObject<{
   id: z.ZodString;
@@ -131,6 +157,12 @@ export type ThreadMessage = {
   sender: ThreadSender;
   text: string;
 } |
+/** Camox's own message, starting a turn it began itself: why it did. */
+{
+  id: string;
+  from: "camox";
+  text: string;
+} |
 /** The agent's final message of a turn, in Markdown. */
 {
   id: string;
@@ -167,6 +199,11 @@ export type ThreadView = LiveThreadHandoff & {
   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;
 };
 export declare const EMPTY_THREAD_VIEW: ThreadView;
 /**
@@ -186,6 +223,11 @@ type ThreadStep = {
   type: "editor";
   sender: ThreadSender;
   text: string;
+} |
+/** Camox starting a turn of its own, saying why. */
+{
+  type: "camox";
+  text: string;
 } | {
   type: "answer";
   text: string;
@@ -200,6 +242,18 @@ type ThreadStep = {
 } | {
   type: "stopped";
   sender: ThreadSender;
+} |
+/** Where the build of the turn's code stands, as the turn ends. */
+{
+  type: "build";
+  status: BuildStatus;
+} |
+/**
+ * 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.
+ */
+{
+  type: "continued";
 });
 /** Studio → thread. */
 export declare const threadClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -259,7 +313,8 @@ export type ThreadServerMessage =
  */
 export declare const THREAD_ENDED_CLOSE_CODE = 4000;
 /**
- * What the studio shows for a thread. A turn starts with an editor's message, and messages sent
+ * 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
  * the stop is left out. A turn that ended without either shows a failed line in its place: its

package/dist/threads.js

@@ -8,6 +8,21 @@ import { z } from "zod";
 const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
 const RUN_STOPPED_ENTRY = "camox.run-stopped";
+/**
+* The kind of the transcript entry recording where the build of the code a turn changed stands,
+* as the turn ends, with a `buildStatusDataSchema` as data: it started, or it failed and the
+* agent is fixing it. The model never sees it.
+*/
+const BUILD_STATUS_ENTRY = "camox.build-status";
+/**
+* The kind of the transcript entry starting Camox's own turn, which reconciles the draft's code
+* with Live's when merging it clashed, with a `reconcileDataSchema` as data: the short message
+* editors see. The model gets Camox's instructions instead.
+*/
+const RECONCILE_ENTRY = "camox.reconcile";
+const reconcileDataSchema = z.object({ message: z.string() });
+const buildStatusSchema = z.enum(["building", "fixing"]);
+const buildStatusDataSchema = z.object({ status: buildStatusSchema });
 /** Who sent a message in a thread. */
 const threadSenderSchema = z.object({
 	id: z.string(),
@@ -131,14 +146,36 @@ function threadStepOf(entry) {
 		type: "stopped",
 		sender
 	};
+	if (entry.kind === "camox.build-status") {
+		const build = buildStatusDataSchema.safeParse(entry.data).data;
+		return build && {
+			id,
+			type: "build",
+			status: build.status
+		};
+	}
 	const message = entry.model?.find((candidate) => candidate.role !== "system");
 	if (!message) return void 0;
-	if (entry.kind === "camox.editor-message" && message.role === "user" && sender) return {
-		id,
-		type: "editor",
-		sender,
-		text: textOf(message.content)
-	};
+	if (message.role === "user") {
+		if (entry.kind === "camox.editor-message") return sender && {
+			id,
+			type: "editor",
+			sender,
+			text: textOf(message.content)
+		};
+		if (entry.kind === "camox.reconcile") {
+			const reconcile = reconcileDataSchema.safeParse(entry.data).data;
+			return reconcile && {
+				id,
+				type: "camox",
+				text: reconcile.message
+			};
+		}
+		return {
+			id,
+			type: "continued"
+		};
+	}
 	if (message.role === "assistant") return assistantStep(id, message);
 	if (message.role === "toolResult") return {
 		id,
@@ -146,7 +183,8 @@ function threadStepOf(entry) {
 	};
 }
 /**
-* What the studio shows for a thread. A turn starts with an editor's message, and messages sent
+* 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
 * the stop is left out. A turn that ended without either shows a failed line in its place: its
@@ -157,10 +195,14 @@ function threadViewOf({ steps, running, ...drafts }) {
 	const messages = [];
 	let waiting;
 	let unfinished = false;
+	let status;
+	let answered;
 	/** Ends the turn waiting for the agent's message, if any. */
 	const endTurn = () => {
 		waiting = void 0;
 		unfinished = false;
+		status = void 0;
+		answered = void 0;
 	};
 	/** Ends the turn waiting for the agent's message with a failed line, if any. */
 	const fail = () => {
@@ -181,6 +223,15 @@ function threadViewOf({ steps, running, ...drafts }) {
 			});
 			waiting = step.id;
 			break;
+		case "camox":
+			if (unfinished) fail();
+			messages.push({
+				id: step.id,
+				from: "camox",
+				text: step.text
+			});
+			waiting = step.id;
+			break;
 		case "stopped":
 			if (waiting === void 0) break;
 			messages.push({
@@ -197,7 +248,24 @@ function threadViewOf({ steps, running, ...drafts }) {
 				from: "agent",
 				text: step.text
 			});
-			endTurn();
+			{
+				const before = {
+					waiting,
+					status
+				};
+				endTurn();
+				answered = before;
+			}
+			break;
+		case "continued":
+			if (!answered) break;
+			if (messages.at(-1)?.from === "agent") messages.pop();
+			waiting = answered.waiting;
+			status = answered.status === "fixing" ? "fixing" : void 0;
+			answered = void 0;
+			break;
+		case "build":
+			status = step.status;
 			break;
 		case "tools":
 			unfinished = false;
@@ -208,7 +276,8 @@ function threadViewOf({ steps, running, ...drafts }) {
 	return {
 		...drafts,
 		messages,
-		running
+		running,
+		...running && status && { status }
 	};
 }
 const append = (state, entry) => {
@@ -260,4 +329,4 @@ function reduceThreadFrame(state, frame) {
 }
 
 //#endregion
-export { EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, RUN_STOPPED_ENTRY, THREAD_ENDED_CLOSE_CODE, editorMessageDataSchema, isSender, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftSchema, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };
+export { BUILD_STATUS_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, editorMessageDataSchema, isSender, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftSchema, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.51.0",
+  "version": "0.52.1",
   "license": "MIT",
   "files": [
     "src",

package/src/drafts.ts

@@ -9,6 +9,22 @@ export const DRAFT_HEADER = "x-camox-draft";
  */
 export const LOCALE_HEADER = "x-camox-locale";
 
+/**
+ * Request header the Worker a publish with code uploaded sends on its public reads, naming
+ * the draft it publishes (spec #560, section 13). While that draft is in its publishing state, a
+ * read naming it sees Live overlaid with the draft, with no session, so the new code serves the
+ * content it was previewed with from its first request. Once the draft has ended, or if it isn't
+ * publishing, the read is Live's. A request naming a draft with `DRAFT_HEADER` ignores it.
+ */
+export const PUBLISHING_DRAFT_HEADER = "x-camox-publishing-draft";
+
+/**
+ * The Worker variable carrying the publishing draft's ID, which the publish sets on the Worker it
+ * uploads (apps/api/src/domains/publishes/scripts.ts). The website's Worker sends it as
+ * `PUBLISHING_DRAFT_HEADER`.
+ */
+export const PUBLISHING_DRAFT_VAR = "CAMOX_PUBLISHING_DRAFT";
+
 /**
  * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
  * exist yet. Its value is `"1"`.
@@ -56,6 +72,31 @@ export const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
  */
 export const CONFLICTS_CHANGED_ERROR = "CONFLICTS_CHANGED";
 
+/**
+ * oRPC error code for a publish of a draft with code whose revision isn't the one the review
+ * showed: the agent left a newer one, or the draft is already publishing. The caller reviews
+ * the new preview.
+ */
+export const REVISION_CHANGED_ERROR = "REVISION_CHANGED";
+
+/**
+ * Why a publish with code went back to the review instead of landing: the agent left a revision
+ * after the one the review showed, Live's conflicts changed, the draft got a blocker, Live's code
+ * moved and the draft's merge of it clashed (the "doesn't merge with Live's" blocker, which
+ * Camox's turn fixes), Live's code moved and the draft took too long to merge it, or the publish
+ * failed on Camox's side.
+ */
+export const PUBLISH_ABORT_REASONS = [
+  "revisionChanged",
+  "conflictsChanged",
+  "blocked",
+  "codeDoesNotMerge",
+  "liveCodeMoved",
+  "failed",
+] as const;
+
+export type PublishAbortReason = (typeof PUBLISH_ABORT_REASONS)[number];
+
 /** oRPC error code for a publish refused because the draft still has blockers. */
 export const PUBLISH_BLOCKED_ERROR = "PUBLISH_BLOCKED";
 
@@ -68,12 +109,13 @@ export const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
 /**
  * Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
  * review again, by the error code of each: Live changed since the preview, the draft has blockers,
- * or translations are still running.
+ * translations are still running, or the draft's code changed since the preview.
  */
 export const NOT_PUBLISHED_CODES = {
   conflictsChanged: CONFLICTS_CHANGED_ERROR,
   blocked: PUBLISH_BLOCKED_ERROR,
   translating: TRANSLATIONS_PENDING_ERROR,
+  revisionChanged: REVISION_CHANGED_ERROR,
 } as const;
 
 export type NotPublishedReason = keyof typeof NOT_PUBLISHED_CODES;

package/src/query-keys.ts

@@ -92,5 +92,11 @@ export type InvalidationMessage = {
 /** A draft was published or discarded: its viewers go back to Live. */
 export type DraftEndedMessage = { type: "draftEnded" } & EndedDraft;
 
+/** A draft with code has a new revision, built with Camox's `sdkVersion`. */
+export type RevisionAnnouncement = { draftId: string; revisionId: string; sdkVersion: string };
+
+/** A draft's new revision: its viewers' frames load it. */
+export type RevisionMessage = { type: "revision" } & RevisionAnnouncement;
+
 /** Everything the project room broadcasts. */
-export type ProjectRoomMessage = InvalidationMessage | DraftEndedMessage;
+export type ProjectRoomMessage = InvalidationMessage | DraftEndedMessage | RevisionMessage;

package/src/threads.ts

@@ -15,6 +15,27 @@ export const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
 export const RUN_STOPPED_ENTRY = "camox.run-stopped";
 
+/**
+ * The kind of the transcript entry recording where the build of the code a turn changed stands,
+ * as the turn ends, with a `buildStatusDataSchema` as data: it started, or it failed and the
+ * agent is fixing it. The model never sees it.
+ */
+export const BUILD_STATUS_ENTRY = "camox.build-status";
+
+/**
+ * The kind of the transcript entry starting Camox's own turn, which reconciles the draft's code
+ * with Live's when merging it clashed, with a `reconcileDataSchema` as data: the short message
+ * editors see. The model gets Camox's instructions instead.
+ */
+export const RECONCILE_ENTRY = "camox.reconcile";
+
+export const reconcileDataSchema = z.object({ message: z.string() });
+
+export const buildStatusSchema = z.enum(["building", "fixing"]);
+export type BuildStatus = z.infer<typeof buildStatusSchema>;
+
+export const buildStatusDataSchema = z.object({ status: buildStatusSchema });
+
 /** Who sent a message in a thread. */
 export const threadSenderSchema = z.object({
   id: z.string(),
@@ -88,6 +109,8 @@ export type TouchedBatch = z.infer<typeof touchedBatchSchema>;
 /** A message the studio shows in a thread. */
 export type ThreadMessage =
   | { id: string; from: "editor"; sender: ThreadSender; text: string }
+  /** Camox's own message, starting a turn it began itself: why it did. */
+  | { id: string; from: "camox"; text: string }
   /** The agent's final message of a turn, in Markdown. */
   | { id: string; from: "agent"; text: string }
   /**
@@ -115,6 +138,11 @@ export type ThreadView = LiveThreadHandoff & {
   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;
 };
 
 export const EMPTY_THREAD_VIEW: ThreadView = { messages: [], running: false };
@@ -131,12 +159,21 @@ 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 }
+  /** Camox starting a turn of its own, saying why. */
+  | { type: "camox"; text: string }
   | { type: "answer"; text: string }
   /** A round of tool calls, or their results: the run goes on after it. */
   | { type: "tools" }
   /** A model call that ended without an answer: failed, aborted, or cut short. */
   | { type: "unfinished" }
   | { type: "stopped"; sender: ThreadSender }
+  /** Where the build of the turn's code stands, as the turn ends. */
+  | { type: "build"; status: BuildStatus }
+  /**
+   * 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.
+   */
+  | { type: "continued" }
 );
 
 /** Studio → thread. */
@@ -211,10 +248,23 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
   const id = String(entry.id);
   const sender = senderOf(entry.data);
   if (entry.kind === RUN_STOPPED_ENTRY && sender) return { id, type: "stopped", sender };
+  if (entry.kind === BUILD_STATUS_ENTRY) {
+    const build = buildStatusDataSchema.safeParse(entry.data).data;
+    return build && { id, type: "build", status: build.status };
+  }
   const message = entry.model?.find((candidate) => candidate.role !== "system");
   if (!message) return undefined;
-  if (entry.kind === EDITOR_MESSAGE_ENTRY && message.role === "user" && sender) {
-    return { id, type: "editor", sender, text: textOf(message.content) };
+  if (message.role === "user") {
+    if (entry.kind === EDITOR_MESSAGE_ENTRY) {
+      return sender && { id, type: "editor", sender, text: textOf(message.content) };
+    }
+    if (entry.kind === RECONCILE_ENTRY) {
+      const reconcile = reconcileDataSchema.safeParse(entry.data).data;
+      return reconcile && { id, type: "camox", text: reconcile.message };
+    }
+    // Editors' messages have a kind of their own: a user message without it is Pi continuing a
+    // run as the end of a turn asked.
+    return { id, type: "continued" };
   }
   if (message.role === "assistant") return assistantStep(id, message);
   if (message.role === "toolResult") return { id, type: "tools" };
@@ -222,7 +272,8 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
 }
 
 /**
- * What the studio shows for a thread. A turn starts with an editor's message, and messages sent
+ * 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
  * the stop is left out. A turn that ended without either shows a failed line in its place: its
@@ -234,10 +285,16 @@ export function threadViewOf({ steps, running, ...drafts }: ThreadState): Thread
   // The latest editor's message of a turn still waiting for the agent's message.
   let waiting: string | undefined;
   let unfinished = false;
+  let status: BuildStatus | undefined;
+  // The turn the agent's last answer ended, and the status before it: the end of the turn may
+  // send the agent back to work after it.
+  let answered: { waiting: string | undefined; status: BuildStatus | undefined } | undefined;
   /** Ends the turn waiting for the agent's message, if any. */
   const endTurn = () => {
     waiting = undefined;
     unfinished = false;
+    status = undefined;
+    answered = undefined;
   };
   /** Ends the turn waiting for the agent's message with a failed line, if any. */
   const fail = () => {
@@ -255,6 +312,11 @@ export function threadViewOf({ steps, running, ...drafts }: ThreadState): Thread
         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 });
+        waiting = step.id;
+        break;
       case "stopped":
         if (waiting === undefined) break;
         messages.push({ id: step.id, from: "stopped", sender: step.sender });
@@ -264,7 +326,23 @@ export function threadViewOf({ steps, running, ...drafts }: ThreadState): Thread
         // A stopped turn's run may still answer before it ends.
         if (waiting === undefined && messages.at(-1)?.from === "stopped") break;
         messages.push({ id: step.id, from: "agent", text: step.text });
-        endTurn();
+        {
+          const before = { waiting, status };
+          endTurn();
+          answered = before;
+        }
+        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.
+        if (!answered) break;
+        if (messages.at(-1)?.from === "agent") messages.pop();
+        waiting = answered.waiting;
+        status = answered.status === "fixing" ? "fixing" : undefined;
+        answered = undefined;
+        break;
+      case "build":
+        status = step.status;
         break;
       case "tools":
         unfinished = false;
@@ -275,7 +353,7 @@ export function threadViewOf({ steps, running, ...drafts }: ThreadState): Thread
     }
   }
   if (!running) fail();
-  return { ...drafts, messages, running };
+  return { ...drafts, messages, running, ...(running && status && { status }) };
 }
 
 const append = (state: ThreadState, entry: EntryRecord | undefined): ThreadState => {