@camox/api-contract 0.59.0 → 0.61.0

package/dist/threads.d.ts

@@ -5,7 +5,9 @@ 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
- * 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 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. */
@@ -52,6 +54,14 @@ export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
  * call of it went through ends on the draft's card.
  */
 export declare const START_DRAFT_TOOL = "startDraft";
+/** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
+export declare 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 declare const CHANGING_TOOLS: ReadonlySet<string>;
 /** 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;
@@ -274,21 +284,24 @@ export type ThreadMessage = {
   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 declare const EMPTY_THREAD_VIEW: ThreadView;
 /**
@@ -299,10 +312,18 @@ export declare const EMPTY_THREAD_VIEW: ThreadView;
 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;
 };
@@ -356,11 +377,68 @@ type ThreadStep = {
 {
   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 declare const editorSelectionSchema: z.ZodObject<{
+  path: z.ZodArray<z.ZodString>;
+  blockId: z.ZodOptional<z.ZodString>;
+  itemId: z.ZodOptional<z.ZodString>;
+  recordId: z.ZodOptional<z.ZodString>;
+  fieldName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const editorWhereSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  on: z.ZodLiteral<"page">;
+  locale: z.ZodString;
+  path: z.ZodString;
+  title: z.ZodString;
+  pageId: z.ZodOptional<z.ZodString>;
+  layoutId: z.ZodOptional<z.ZodString>;
+  selection: z.ZodOptional<z.ZodObject<{
+    path: z.ZodArray<z.ZodString>;
+    blockId: z.ZodOptional<z.ZodString>;
+    itemId: z.ZodOptional<z.ZodString>;
+    recordId: z.ZodOptional<z.ZodString>;
+    fieldName: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  on: z.ZodLiteral<"canvas">;
+  locale: z.ZodString;
+}, z.core.$strip>], "on">;
+export type EditorWhere = z.infer<typeof editorWhereSchema>;
 /** Studio → thread. */
 export declare const threadClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   type: z.ZodLiteral<"send">;
   operationId: z.ZodString;
   text: z.ZodString;
+  where: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    on: z.ZodLiteral<"page">;
+    locale: z.ZodString;
+    path: z.ZodString;
+    title: z.ZodString;
+    pageId: z.ZodOptional<z.ZodString>;
+    layoutId: z.ZodOptional<z.ZodString>;
+    selection: z.ZodOptional<z.ZodObject<{
+      path: z.ZodArray<z.ZodString>;
+      blockId: z.ZodOptional<z.ZodString>;
+      itemId: z.ZodOptional<z.ZodString>;
+      recordId: z.ZodOptional<z.ZodString>;
+      fieldName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>, z.ZodObject<{
+    on: z.ZodLiteral<"canvas">;
+    locale: z.ZodString;
+  }, z.core.$strip>], "on">>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodLiteral<"stop">;
 }, z.core.$strip>, z.ZodObject<{
@@ -417,6 +495,11 @@ export type ThreadServerMessage =
 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 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 declare const editorTextOf: (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
@@ -426,7 +509,7 @@ export declare const textOf: (content: Message["content"]) => string;
  * 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, changing, 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

@@ -3,7 +3,9 @@ import { z } from "zod";
 //#region src/threads.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`).
 */
 const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
@@ -49,6 +51,36 @@ const pushOutcomeSchema = z.enum([
 * call of it went through ends on the draft's card.
 */
 const START_DRAFT_TOOL = "startDraft";
+/** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
+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.
+*/
+const CHANGING_TOOLS = /* @__PURE__ */ new Set([
+	"addBackToLocale",
+	"addLocale",
+	"createBlock",
+	"createCollectionRecord",
+	"createPage",
+	"deleteBlock",
+	"deleteCollectionRecord",
+	"deletePage",
+	"editBlock",
+	"editCollectionRecord",
+	"moveBlock",
+	"removeLocale",
+	"setPageLayout",
+	"setPageSeo",
+	"updateFile",
+	"updatePage",
+	"uploadFile",
+	"edit",
+	"mv",
+	"rm",
+	"write"
+]);
 /** The draft a `startDraft` call started, as its result's details name it for the card. */
 const startedDraftCardSchema = z.object({
 	draftId: z.string(),
@@ -140,12 +172,44 @@ const EMPTY_THREAD_STATE = {
 	steps: [],
 	running: false
 };
+/**
+* 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.
+*/
+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()
+});
+/**
+* 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.
+*/
+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)
+})]);
 /** Studio → thread. */
 const threadClientMessageSchema = z.discriminatedUnion("type", [
 	z.object({
 		type: z.literal("send"),
 		operationId: z.string().min(1),
-		text: z.string().min(1)
+		text: z.string().min(1),
+		where: editorWhereSchema.optional()
 	}),
 	z.object({ type: z.literal("stop") }),
 	z.object({ type: z.literal("resync") })
@@ -157,6 +221,11 @@ const threadClientMessageSchema = z.discriminatedUnion("type", [
 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 editor wrote, of their message entry's content: its first text part. The rest, where
+* they were in the studio, only the model reads.
+*/
+const editorTextOf = (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, message) {
 	if (message.content.some((part) => part.type === "toolCall")) return {
@@ -218,7 +287,7 @@ function threadStepOf(entry) {
 				id,
 				type: "editor",
 				sender,
-				text: textOf(message.content),
+				text: editorTextOf(message.content),
 				...handedOffTo && { handedOffTo }
 			};
 		}
@@ -262,7 +331,7 @@ function threadStepOf(entry) {
 * 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, changing = false, drafts = {} }) {
 	const messages = [];
 	let waiting;
 	let unfinished = false;
@@ -378,14 +447,35 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, dr
 		case "unfinished": unfinished = true;
 	}
 	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 }) {
+	const calling = (name) => toolCalls.some((call) => call.name === name);
+	if (status === "building" || calling("build")) return "building";
+	if (status === "fixing") return "fixing";
+	if (calling("startDraft")) 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) => 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) => block.type === "toolCall" && changes(block.name);
 const append = (state, entry) => {
 	const step = entry && threadStepOf(entry);
 	if (!step || state.steps.some((known) => known.id === step.id)) return state;
@@ -397,13 +487,21 @@ const append = (state, entry) => {
 /** Folds one of Pi's agent events into the thread's state. */
 function reduceThreadState(state, event) {
 	switch (event.type) {
-		case "snapshot": return {
-			...state,
-			steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
-			running: event.run !== void 0,
-			toolCalls: event.tools.flatMap((tool) => tool.status === "done" ? [] : [tool.callId]),
-			callingTools: !!event.generation?.message?.content.some((part) => part.type === "toolCall")
-		};
+		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 !== void 0,
+				toolCalls,
+				callingTools: generated.some((part) => part.type === "toolCall"),
+				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
@@ -412,25 +510,41 @@ function reduceThreadState(state, event) {
 			...state,
 			running: false,
 			toolCalls: [],
-			callingTools: false
+			callingTools: false,
+			changing: false
 		};
 		case "message_start": return event.message.role === "assistant" ? {
 			...state,
-			callingTools: false
-		} : state;
-		case "message_update": return event.changes.some((change) => change.type === "toolcall_start") ? {
-			...state,
-			callingTools: true
+			callingTools: false,
+			changing: false
 		} : state;
-		case "tool_execution_start":
-			if (event.parentToolCallId !== void 0) return state;
+		case "message_update": {
+			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,
-				toolCalls: [...state.toolCalls ?? [], event.toolCallId]
+				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 !== void 0) 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);
 		case "message_end":
 		case "entry_appended": return append(state, event.entry);
@@ -452,4 +566,4 @@ function reduceThreadFrame(state, frame) {
 }
 
 //#endregion
-export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, PUSH_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, editorMessageDataSchema, isSender, pushDataSchema, pushOutcomeSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };
+export { BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, PUSH_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, buildStatusDataSchema, buildStatusSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, isSender, pushDataSchema, pushOutcomeSchema, 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.59.0",
+  "version": "0.61.0",
   "license": "MIT",
   "files": [
     "src",

package/src/record-templates.ts

@@ -17,10 +17,13 @@ export function templateFields(template: string): string[] {
  */
 export function nonStringTemplateFields(
   template: string,
-  properties: Readonly<Record<string, object | undefined>>,
+  properties: Readonly<Record<string, unknown>>,
 ): string[] {
-  const isString = (field: object | undefined) =>
-    field !== undefined && "fieldType" in field && field.fieldType === "String";
+  const isString = (field: unknown) =>
+    typeof field === "object" &&
+    field !== null &&
+    "fieldType" in field &&
+    field.fieldType === "String";
   return templateFields(template).filter((name) => !isString(properties[name]));
 }
 

package/src/reference-query.ts

@@ -15,8 +15,10 @@ export function isSystemOrderKey(key: string): key is SystemOrderKey {
 }
 
 /** Whether a reference list field is query-backed: code defines its records, nothing is stored. */
-export function isQueryBacked(field: object | null | undefined) {
-  return !!field && (field as { query?: unknown }).query !== undefined;
+export function isQueryBacked(field: unknown) {
+  return (
+    typeof field === "object" && field !== null && "query" in field && field.query !== undefined
+  );
 }
 
 /**