@camox/api-contract 0.56.0 → 0.57.0

package/dist/threads.d.ts

@@ -1,5 +1,7 @@
+import { DraftOutcome } from "./drafts.js";
 import { z } from "zod";
 import { AgentEvent } from "@earendil-works/pi-durable";
+import { Message } from "@earendil-works/pi-ai";
 //#region src/threads.d.ts
 /**
  * The kind of the transcript entry recording an editor's message, with its sender and the
@@ -20,6 +22,41 @@ export declare const BUILD_STATUS_ENTRY = "camox.build-status";
  * editors see. The model gets Camox's instructions instead.
  */
 export declare 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 declare 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 declare 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 declare const START_DRAFT_TOOL = "startDraft";
+/** The draft a `startDraft` call started, as its result's details name it for the card. */
+export declare const startedDraftCardSchema: z.ZodObject<{
+  draftId: z.ZodString;
+  name: z.ZodString;
+}, z.core.$strip>;
+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 declare const reconcileDataSchema: z.ZodObject<{
   message: z.ZodString;
 }, z.core.$strip>;
@@ -43,17 +80,21 @@ export declare const threadSenderSchema: z.ZodObject<{
 export type ThreadSender = z.infer<typeof threadSenderSchema>;
 /** Whether `data` names a sender. */
 export declare const isSender: (data: unknown) => data is ThreadSender;
-/** 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 declare const editorMessageDataSchema: z.ZodObject<{
   id: z.ZodString;
   name: z.ZodString;
   image: z.ZodNullable<z.ZodString>;
   operationId: z.ZodOptional<z.ZodString>;
+  handedOffTo: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
- * 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 declare const startedDraftSchema: z.ZodObject<{
   draftId: z.ZodString;
@@ -182,20 +223,19 @@ export type ThreadMessage = {
   id: string;
   from: "stopped";
   sender: ThreadSender;
-};
-/** Where a Live thread's messages went when it started a draft, beside its transcript. */
-type LiveThreadHandoff = {
-  /**
-   * 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.
-   */
-  startedDraft?: StartedDraft;
-  /** The draft the editor's previous Live thread continued in, for a fresh Live thread. */
-  continuedIn?: StartedDraft;
-};
+} |
+/**
+ * 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.
+ */
+({
+  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;
@@ -216,13 +256,15 @@ export declare const EMPTY_THREAD_VIEW: ThreadView;
  * 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 declare const EMPTY_THREAD_STATE: ThreadState;
 /** One transcript entry, as far as the studio's view is concerned. */
@@ -232,6 +274,8 @@ type ThreadStep = {
   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. */
 {
@@ -252,6 +296,10 @@ type ThreadStep = {
   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";
@@ -290,18 +338,21 @@ export type ThreadServerMessage =
   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
@@ -321,16 +372,18 @@ export type ThreadServerMessage =
  * thread the next time the studio connects.
  */
 export declare const THREAD_ENDED_CLOSE_CODE = 4000;
+/** The text of a message's content: its text parts, joined. */
+export declare const textOf: (content: Message["content"]) => string;
 /**
  * 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.
  */
-export declare function threadViewOf({ steps, running, toolCalls, callingTools, ...drafts }: ThreadState): ThreadView;
+export declare function threadViewOf({ steps, running, toolCalls, callingTools, drafts }: ThreadState): ThreadView;
 /** Folds one of Pi's agent events into the thread's state. */
 export declare function reduceThreadState(state: ThreadState, event: AgentEvent): ThreadState;
 /** Folds a batch of Pi's agent events into the thread's state. */

package/dist/threads.js

@@ -20,6 +20,28 @@ const BUILD_STATUS_ENTRY = "camox.build-status";
 * editors see. The model gets Camox's instructions instead.
 */
 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.
+*/
+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.
+*/
+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.
+*/
+const START_DRAFT_TOOL = "startDraft";
+/** The draft a `startDraft` call started, as its result's details name it for the card. */
+const startedDraftCardSchema = z.object({
+	draftId: z.string(),
+	name: z.string()
+});
 const reconcileDataSchema = z.object({ message: z.string() });
 const buildStatusSchema = z.enum(["building", "fixing"]);
 const buildStatusDataSchema = z.object({ status: buildStatusSchema });
@@ -31,12 +53,18 @@ const threadSenderSchema = z.object({
 });
 /** Whether `data` names a sender. */
 const isSender = (data) => threadSenderSchema.safeParse(data).success;
-/** What an editor's message entry records: who sent it, and the operation id it was sent with. */
-const editorMessageDataSchema = threadSenderSchema.extend({ operationId: 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.
+* 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.
+*/
+const editorMessageDataSchema = threadSenderSchema.extend({
+	operationId: z.string().optional(),
+	handedOffTo: z.string().optional()
+});
+/**
+* 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.
 */
 const startedDraftSchema = z.object({
 	draftId: z.string(),
@@ -110,6 +138,7 @@ const threadClientMessageSchema = z.discriminatedUnion("type", [
 * thread the next time the studio connects.
 */
 const THREAD_ENDED_CLOSE_CODE = 4e3;
+/** The text of a message's content: its text parts, joined. */
 const textOf = (content) => typeof content === "string" ? content : content.flatMap((part) => part.type === "text" ? [part.text] : []).join("").trim();
 /** What an assistant message is to the thread: a final answer, a tool round, or neither. */
 function assistantStep(id, message) {
@@ -154,13 +183,23 @@ function threadStepOf(entry) {
 			status: build.status
 		};
 	}
+	if (entry.kind === "camox.draft-ended") return void 0;
 	const message = entry.model?.find((candidate) => candidate.role !== "system");
 	if (!message) return void 0;
 	if (message.role === "user") {
-		if (entry.kind === "camox.editor-message") return sender && {
+		if (entry.kind === "camox.editor-message") {
+			const handedOffTo = editorMessageDataSchema.safeParse(entry.data).data?.handedOffTo;
+			return sender && {
+				id,
+				type: "editor",
+				sender,
+				text: textOf(message.content),
+				...handedOffTo && { handedOffTo }
+			};
+		}
+		if (entry.kind === "camox.brief") return {
 			id,
-			type: "editor",
-			sender,
+			type: "camox",
 			text: textOf(message.content)
 		};
 		if (entry.kind === "camox.reconcile") {
@@ -177,21 +216,28 @@ function threadStepOf(entry) {
 		};
 	}
 	if (message.role === "assistant") return assistantStep(id, message);
-	if (message.role === "toolResult") return {
-		id,
-		type: "tools"
-	};
+	if (message.role === "toolResult") {
+		const card = message.toolName === "startDraft" && !message.isError ? startedDraftCardSchema.safeParse(message.details).data : void 0;
+		return card ? {
+			id,
+			type: "draft",
+			...card
+		} : {
+			id,
+			type: "tools"
+		};
+	}
 }
 /**
 * 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.
 */
-function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ...drafts }) {
+function threadViewOf({ steps, running, toolCalls = [], callingTools = false, drafts = {} }) {
 	const messages = [];
 	let waiting;
 	let unfinished = false;
@@ -213,7 +259,17 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ..
 		endTurn();
 	};
 	for (const step of steps) switch (step.type) {
-		case "editor":
+		case "editor": {
+			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;
+			}
 			if (unfinished) fail();
 			messages.push({
 				id: step.id,
@@ -223,6 +279,7 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ..
 			});
 			waiting = step.id;
 			break;
+		}
 		case "camox":
 			if (unfinished) fail();
 			messages.push({
@@ -257,6 +314,20 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ..
 				answered = before;
 			}
 			break;
+		case "draft":
+			if (waiting === void 0 && 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":
 			if (!answered) break;
 			if (messages.at(-1)?.from === "agent") messages.pop();
@@ -275,7 +346,6 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ..
 	if (!running) fail();
 	const usingTools = running && (callingTools || toolCalls.length > 0);
 	return {
-		...drafts,
 		messages,
 		running,
 		...running && status && { status },
@@ -339,17 +409,13 @@ const reduceThreadEvents = (state, events) => events.reduce(reduceThreadState, s
 function reduceThreadFrame(state, frame) {
 	switch (frame.type) {
 		case "events": return reduceThreadEvents(state, frame.events);
-		case "started-draft": return {
-			...state,
-			startedDraft: frame.startedDraft
-		};
-		case "continued-in": return {
+		case "drafts": return {
 			...state,
-			continuedIn: frame.continuedIn
+			drafts: frame.drafts
 		};
 		default: return state;
 	}
 }
 
 //#endregion
-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 };
+export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, editorMessageDataSchema, isSender, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "license": "MIT",
   "files": [
     "src",
@@ -44,6 +44,10 @@
       "types": "./dist/locales.d.ts",
       "default": "./dist/locales.js"
     },
+    "./patrol": {
+      "types": "./dist/patrol.d.ts",
+      "default": "./dist/patrol.js"
+    },
     "./router": {
       "types": "./dist/router.d.ts",
       "default": "./dist/router.js"

package/src/patrol.ts

@@ -0,0 +1,113 @@
+/**
+ * The Patrol (ADR 0024): every patroller of a project, the work each did as reports, as the
+ * studio shows it at the top of the Agent Sidebar. The API reads it for one scope, a draft or
+ * Live, and names each report's subject, so the studio needs no entity loaded to show it.
+ */
+
+/** A patroller's stable id. The registry in the API lists them all. */
+export type PatrollerId = "translator" | "seoManager";
+
+/**
+ * What a structured report says was done. Each has a failed form, by the report's outcome. A
+ * merge with Live's localization reads as a translation.
+ */
+export type ReportVerb =
+  | "translated"
+  | "mergedWithLive"
+  | "wroteSeo"
+  | "describedFile"
+  | "publishedCatchUp";
+
+/** What a report can be about. */
+export type ReportEntity =
+  | "page"
+  | "block"
+  | "sharedContent"
+  | "repeatableItem"
+  | "record"
+  | "file";
+
+/** A report's subject, named as the Canvas names it, read when the Patrol is. */
+export type ReportSubject = { entity: ReportEntity; id: string; name: string };
+
+/**
+ * What a report says: structured facts the studio turns into a sentence, in the studio's
+ * language, or text an AI wrote, shown as is. `locale` is a locale's tag.
+ */
+export type ReportSummary =
+  | {
+      kind: "structured";
+      verb: ReportVerb;
+      subject: ReportSubject | null;
+      locale: string | null;
+    }
+  | { kind: "text"; text: string };
+
+/** The locale a summary's work was in: a structured summary's, if any. A text summary has none. */
+export const reportLocale = (
+  summary: { kind: "structured"; locale: string | null } | { kind: "text" },
+) => (summary.kind === "structured" ? summary.locale : null);
+
+/** Whether the work was done, or failed. A failure shows in its report only. */
+export type ReportOutcome = "done" | "failed";
+
+/** Whether a report needs a human. Nothing raises one yet. */
+export type AttentionLevel = "none" | "needed";
+
+/**
+ * Where the studio shows a report's subject: a page on the Canvas, with the block and repeatable
+ * item to select on it, a collection record, or a file.
+ */
+export type ReportPlace =
+  | { kind: "page"; pageId: string; blockId: string | null; itemId: string | null }
+  | { kind: "record"; collectionId: string; recordId: string }
+  | { kind: "file"; fileId: string };
+
+export type ReportView = {
+  /** Unique among the patroller's reports in the view. */
+  id: string;
+  summary: ReportSummary;
+  outcome: ReportOutcome;
+  attention: AttentionLevel;
+  /** When the work last settled, in milliseconds since the epoch. */
+  at: number;
+  /** Whether the report is Live's, seen from a draft or from Live. */
+  live: boolean;
+  /**
+   * Where its subject shows, in the report's scope and locale. Null without a subject, or for one
+   * with no single place, such as a synced block's shared content or a layout's block.
+   */
+  place: ReportPlace | null;
+};
+
+/** How many subjects a patroller is on in one locale, a locale's tag. */
+export type LocaleCount = { locale: string; count: number };
+
+/**
+ * What a patroller is on: the one subject when there's one, and how many subjects in each
+ * locale, the most first. A subject in several locales counts in each.
+ */
+export type PatrollerWorking = {
+  subject: ReportSubject | null;
+  locales: LocaleCount[];
+};
+
+export type PatrollerView = {
+  id: PatrollerId;
+  /** Its role, as editors know it: "Translator", "SEO manager". */
+  role: string;
+  /** Null when it isn't working in the scope. */
+  working: PatrollerWorking | null;
+  /** Its latest activity in the scope, or null when it never worked there. */
+  lastActivityAt: number | null;
+  /** Its newest reports, newest first. */
+  reports: ReportView[];
+  /** How many more reports it has than `reports` shows, per locale, the most first. */
+  more: { locale: string | null; count: number }[];
+};
+
+/** Every patroller of the registry, the latest activity first; never-worked ones last. */
+export type PatrolView = { patrollers: PatrollerView[] };
+
+/** How many reports the Patrol shows of each patroller; the rest are counted. */
+export const REPORTS_SHOWN = 5;

package/src/query-keys.ts

@@ -59,6 +59,10 @@ export const queryKeys = {
     // The draft a viewer is in, scoped to it like content.
     get: ["camox", "drafts", "get"],
   },
+  // The Patrol of a scope: its reports and its patrollers' pending work.
+  patrol: {
+    get: ["camox", "patrol"],
+  },
 } satisfies Record<string, QueryKeyGroup>;
 
 /** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */