@camox/api-contract 0.44.0 → 0.46.0

package/src/threads.ts

@@ -0,0 +1,327 @@
+import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
+import type { AgentEvent, EntryRecord } from "@earendil-works/pi-durable";
+import { z } from "zod";
+
+// A thread with Camox's agent, as the studio shows it. The thread's Durable Object sends Pi's own
+// agent events over its socket, and this module is the one place that interprets them: the
+// studio and the API's tests fold them with the same code.
+
+/**
+ * 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`).
+ */
+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";
+
+/** Who sent a message in a thread. */
+export const threadSenderSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  image: z.string().nullable(),
+});
+export type ThreadSender = z.infer<typeof threadSenderSchema>;
+
+/** Whether `data` names a sender. */
+export const isSender = (data: unknown): data is ThreadSender =>
+  threadSenderSchema.safeParse(data).success;
+
+/** 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(),
+});
+
+/**
+ * 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.
+ */
+export const startedDraftSchema = z.object({
+  draftId: z.string(),
+  operationIds: z.array(z.string()),
+});
+export type StartedDraft = z.infer<typeof startedDraftSchema>;
+
+/** How a write touched what it names. */
+export const touchKindSchema = z.enum(["created", "edited", "moved", "deleted", "settings"]);
+export type TouchKind = z.infer<typeof touchKindSchema>;
+
+/**
+ * One thing a script's successful write touched, named so the studio can locate it: a Page (and
+ * its Block, if any), a Synced Block's shared content, by its block definition, or a Layout (and
+ * its Block, if any). `settings` is a Page's settings only (nickname, path, SEO, layout). `locale`
+ * is the Locale the write was in, for a localized tool. Writes to Collection Records, Files and
+ * Locales aren't on the Canvas, so they're left out.
+ */
+const touchBaseSchema = z.object({ kind: touchKindSchema, locale: z.string().optional() });
+
+export const touchSchema = z.discriminatedUnion("entity", [
+  touchBaseSchema.extend({
+    entity: z.literal("page"),
+    pageId: z.string(),
+    blockId: z.string().optional(),
+  }),
+  touchBaseSchema.extend({
+    entity: z.literal("synced-block"),
+    /** The Synced Block's block definition id. */
+    blockType: z.string(),
+  }),
+  touchBaseSchema.extend({
+    entity: z.literal("layout"),
+    layoutId: z.string(),
+    blockId: z.string().optional(),
+  }),
+]);
+export type Touch = z.infer<typeof touchSchema>;
+
+/**
+ * What one code-mode script's successful writes touched, in write order, and the operation ids
+ * of the messages of the run it belongs to: only the studio that sent one of them follows it.
+ */
+export const touchedBatchSchema = z.object({
+  operationIds: z.array(z.string()),
+  touches: z.array(touchSchema),
+});
+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 }
+  /** The agent's final message of a turn, in Markdown. */
+  | { id: string; from: "agent"; text: string }
+  /**
+   * In place of the agent's message, for a turn that ended without one: the model failed (after
+   * Pi's retries), or its answer was cut short. Sending again retries.
+   */
+  | { id: string; from: "failed" }
+  /** In place of the agent's message, for a turn an editor stopped: `sender` stopped it. */
+  | { 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;
+};
+
+/** Everything the studio shows for a thread. */
+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;
+};
+
+export const EMPTY_THREAD_VIEW: ThreadView = { messages: [], running: false };
+
+/**
+ * What a thread's view is folded from: the steps of its transcript that matter to the studio,
+ * 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 & { steps: readonly ThreadStep[]; running: boolean };
+
+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 }
+  | { 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 }
+);
+
+/** 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.
+   */
+  z.object({ type: z.literal("send"), operationId: z.string().min(1), text: z.string().min(1) }),
+  /** 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. */
+  z.object({ type: z.literal("resync") }),
+]);
+export type ThreadClientMessage = z.infer<typeof threadClientMessageSchema>;
+
+/** Thread → studio. */
+export type ThreadServerMessage =
+  /**
+   * Pi's agent events. The first batch after connecting or resyncing starts with a `snapshot`,
+   * which replaces whatever the studio folded before.
+   */
+  | { type: "events"; events: readonly AgentEvent[] }
+  /** The thread recorded the message sent with this operation id (once, however often sent). */
+  | { type: "accepted"; operationId: string }
+  /** This Live thread started a draft with its first write, and became that draft's thread. */
+  | { type: "started-draft"; startedDraft: StartedDraft }
+  /**
+   * The editor's previous Live thread continued in this draft: this one is fresh. Sent before
+   * the snapshot.
+   */
+  | { type: "continued-in"; continuedIn: StartedDraft }
+  /**
+   * A code-mode script that wrote something ended, failed or not: what its successful writes
+   * touched. Sent once per such script, live only: a snapshot never replays past touches.
+   */
+  | { type: "touched"; touched: TouchedBatch }
+  | { type: "error"; operationId?: string; message: string };
+
+/**
+ * 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.
+ */
+export const THREAD_ENDED_CLOSE_CODE = 4000;
+
+const textOf = (content: Message["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: string, message: AssistantMessage): ThreadStep {
+  if (message.content.some((part) => part.type === "toolCall")) return { id, type: "tools" };
+  // Thinking is never shown. An answer cut short by the model's length limit isn't one.
+  const text = message.stopReason === "stop" ? textOf(message.content) : "";
+  return text ? { id, type: "answer", text } : { id, type: "unfinished" };
+}
+
+/** The sender an entry's data names, if any, without other fields it may carry. */
+function senderOf(data: unknown): ThreadSender | undefined {
+  if (!isSender(data)) return undefined;
+  const { id, name, image } = data;
+  return { id, name, image };
+}
+
+/** The step an entry is, if it's one the view depends on. */
+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 };
+  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 === "assistant") return assistantStep(id, message);
+  if (message.role === "toolResult") return { id, type: "tools" };
+  return undefined;
+}
+
+/**
+ * What the studio shows for a thread. A turn starts with an editor's message, 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
+ * 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 function threadViewOf({ steps, running, ...drafts }: ThreadState): ThreadView {
+  const messages: ThreadMessage[] = [];
+  // The latest editor's message of a turn still waiting for the agent's message.
+  let waiting: string | undefined;
+  let unfinished = false;
+  /** Ends the turn waiting for the agent's message, if any. */
+  const endTurn = () => {
+    waiting = undefined;
+    unfinished = false;
+  };
+  /** Ends the turn waiting for the agent's message with a failed line, if any. */
+  const fail = () => {
+    if (waiting !== undefined) messages.push({ id: `${waiting}:failed`, from: "failed" });
+    endTurn();
+  };
+
+  for (const step of steps) {
+    switch (step.type) {
+      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.
+        if (unfinished) fail();
+        messages.push({ id: step.id, from: "editor", sender: step.sender, text: step.text });
+        waiting = step.id;
+        break;
+      case "stopped":
+        if (waiting === undefined) break;
+        messages.push({ id: step.id, from: "stopped", sender: step.sender });
+        endTurn();
+        break;
+      case "answer":
+        // 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();
+        break;
+      case "tools":
+        unfinished = false;
+        break;
+      case "unfinished":
+        unfinished = true;
+        break;
+    }
+  }
+  if (!running) fail();
+  return { ...drafts, messages, running };
+}
+
+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;
+  return { ...state, steps: [...state.steps, step] };
+};
+
+/** 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":
+      return {
+        ...state,
+        steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
+        running: event.run !== undefined,
+      };
+    case "run_start":
+      return { ...state, running: true };
+    case "run_end":
+      return { ...state, running: false };
+    case "message_end":
+    case "entry_appended":
+    case "tool_execution_end":
+      return append(state, event.entry);
+    default:
+      return state;
+  }
+}
+
+/** Folds a batch of Pi's agent events into the thread's state. */
+export const reduceThreadEvents = (
+  state: ThreadState,
+  events: readonly AgentEvent[],
+): ThreadState => events.reduce(reduceThreadState, state);
+
+/** Folds what the thread sent over its socket into the thread's state. */
+export function reduceThreadFrame(state: ThreadState, frame: ThreadServerMessage): ThreadState {
+  switch (frame.type) {
+    case "events":
+      return reduceThreadEvents(state, frame.events);
+    case "started-draft":
+      return { ...state, startedDraft: frame.startedDraft };
+    case "continued-in":
+      return { ...state, continuedIn: frame.continuedIn };
+    default:
+      return state;
+  }
+}

package/dist/icons.d.ts

@@ -1,20 +0,0 @@
-import type { IconifyJSON } from "@iconify/types";
-export declare const ICON_CATALOG_VERSION = "2.2.532";
-export type IconSvgData = {
-    body: string;
-    attributes: Record<string, string>;
-    attribution?: {
-        collection: string;
-        author: string;
-        license: string;
-        url?: string;
-    };
-};
-export declare function loadIconCollection(prefix: string): Promise<IconifyJSON>;
-export declare function iconCollectionIds(data: IconifyJSON): string[];
-export declare function resolveIconSvg(data: IconifyJSON, id: string): IconSvgData;
-export declare function scopeIconSvgIds(body: string, prefix: string): string;
-export declare function validateIconValue(value: unknown, schema: {
-    fieldType?: string;
-    enum?: unknown;
-}): void;

package/dist/icons.js

@@ -1,72 +0,0 @@
-import { getIconData, iconToSVG } from "@iconify/utils";
-// One immutable snapshot for declarations, schemas, picker and SVG resolution.
-export const ICON_CATALOG_VERSION = "2.2.532";
-const collections = new Map();
-export async function loadIconCollection(prefix) {
-    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(prefix))
-        throw new Error("Invalid icon collection");
-    const existing = collections.get(prefix);
-    if (existing)
-        return existing;
-    const pending = (async () => {
-        const response = await fetch(`https://unpkg.com/@iconify/json@${ICON_CATALOG_VERSION}/json/${prefix}.json`, { signal: AbortSignal.timeout(30_000) });
-        if (!response.ok)
-            throw new Error(`Unable to load icon collection ${prefix}`);
-        const data = (await response.json());
-        if (data.prefix !== prefix || !data.icons || !data.info?.license)
-            throw new Error("Invalid icon catalog or missing license");
-        return data;
-    })();
-    collections.set(prefix, pending);
-    // Bound worker memory; failed fetches must be retryable.
-    if (collections.size > 8)
-        collections.delete(collections.keys().next().value);
-    try {
-        return await pending;
-    }
-    catch (error) {
-        collections.delete(prefix);
-        throw error;
-    }
-}
-export function iconCollectionIds(data) {
-    return [...Object.keys(data.icons), ...Object.keys(data.aliases ?? {})]
-        .filter((name) => getIconData(data, name) !== null)
-        .sort()
-        .map((name) => `${data.prefix}:${name}`);
-}
-export function resolveIconSvg(data, id) {
-    const [prefix, name, extra] = id.split(":");
-    if (prefix !== data.prefix || !name || extra !== undefined)
-        throw new Error("Invalid icon ID");
-    const icon = getIconData(data, name);
-    if (!icon)
-        throw new Error(`Unknown icon: ${id}`);
-    const svg = iconToSVG(icon);
-    return {
-        body: svg.body,
-        attributes: svg.attributes,
-        attribution: data.info
-            ? {
-                collection: data.info.name,
-                author: data.info.author.name,
-                license: data.info.license.title,
-                url: data.info.license.url,
-            }
-            : undefined,
-    };
-}
-export function scopeIconSvgIds(body, prefix) {
-    const ids = [...body.matchAll(/\sid="([^\s"]+)"/g)].map((match) => match[1]);
-    if (!ids.length)
-        return body;
-    const pattern = ids.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
-    return body.replace(new RegExp(`([#;"])(${pattern})([")]|\\.[a-z])`, "g"), (_match, before, id, after) => `${before}${prefix}${id}${after}`);
-}
-export function validateIconValue(value, schema) {
-    if (schema.fieldType !== "Icon")
-        return;
-    if (typeof value !== "string" || !Array.isArray(schema.enum) || !schema.enum.includes(value)) {
-        throw new Error(`Invalid icon ID: ${String(value)}`);
-    }
-}

package/src/comments.ts

@@ -1,33 +0,0 @@
-import { z } from "zod";
-
-export const COMMENT_MESSAGE_MAX_LENGTH = 10_000;
-
-const objectId = z.number().int().positive();
-const fieldName = z.string().min(1).max(200);
-
-export const commentTargetSchema = z.discriminatedUnion("kind", [
-  z.strictObject({ kind: z.literal("page") }),
-  z.strictObject({ kind: z.literal("block"), blockId: objectId }),
-  z.strictObject({ kind: z.literal("item"), blockId: objectId, itemId: objectId }),
-  z.strictObject({ kind: z.literal("block-field"), blockId: objectId, fieldName }),
-  z.strictObject({
-    kind: z.literal("item-field"),
-    blockId: objectId,
-    itemId: objectId,
-    fieldName,
-  }),
-]);
-
-export const commentSchema = z.object({
-  id: z.uuid(),
-  pageId: objectId,
-  environmentId: objectId,
-  message: z.string(),
-  resolved: z.boolean(),
-  target: commentTargetSchema.nullable(),
-  author: z.object({ name: z.string(), image: z.string().nullable() }),
-  createdAt: z.number(),
-});
-
-export type CommentTarget = z.infer<typeof commentTargetSchema>;
-export type Comment = z.infer<typeof commentSchema>;