@camox/api-contract 0.44.0 → 0.45.0

package/dist/threads.d.ts

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import { AgentEvent } from "@earendil-works/pi-durable";
+//#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`).
+ */
+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";
+/** Who sent a message in a thread. */
+export declare const threadSenderSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  image: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+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. */
+export declare const editorMessageDataSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  image: z.ZodNullable<z.ZodString>;
+  operationId: 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.
+ */
+export declare const startedDraftSchema: z.ZodObject<{
+  draftId: z.ZodString;
+  operationIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type StartedDraft = z.infer<typeof startedDraftSchema>;
+/** How a write touched what it names. */
+export declare const touchKindSchema: z.ZodEnum<{
+  created: "created";
+  edited: "edited";
+  moved: "moved";
+  deleted: "deleted";
+  settings: "settings";
+}>;
+export type TouchKind = z.infer<typeof touchKindSchema>;
+export declare const touchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodEnum<{
+    created: "created";
+    edited: "edited";
+    moved: "moved";
+    deleted: "deleted";
+    settings: "settings";
+  }>;
+  locale: z.ZodOptional<z.ZodString>;
+  entity: z.ZodLiteral<"page">;
+  pageId: z.ZodString;
+  blockId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodEnum<{
+    created: "created";
+    edited: "edited";
+    moved: "moved";
+    deleted: "deleted";
+    settings: "settings";
+  }>;
+  locale: z.ZodOptional<z.ZodString>;
+  entity: z.ZodLiteral<"synced-block">;
+  blockType: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodEnum<{
+    created: "created";
+    edited: "edited";
+    moved: "moved";
+    deleted: "deleted";
+    settings: "settings";
+  }>;
+  locale: z.ZodOptional<z.ZodString>;
+  entity: z.ZodLiteral<"layout">;
+  layoutId: z.ZodString;
+  blockId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "entity">;
+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 declare const touchedBatchSchema: z.ZodObject<{
+  operationIds: z.ZodArray<z.ZodString>;
+  touches: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodEnum<{
+      created: "created";
+      edited: "edited";
+      moved: "moved";
+      deleted: "deleted";
+      settings: "settings";
+    }>;
+    locale: z.ZodOptional<z.ZodString>;
+    entity: z.ZodLiteral<"page">;
+    pageId: z.ZodString;
+    blockId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodEnum<{
+      created: "created";
+      edited: "edited";
+      moved: "moved";
+      deleted: "deleted";
+      settings: "settings";
+    }>;
+    locale: z.ZodOptional<z.ZodString>;
+    entity: z.ZodLiteral<"synced-block">;
+    blockType: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodEnum<{
+      created: "created";
+      edited: "edited";
+      moved: "moved";
+      deleted: "deleted";
+      settings: "settings";
+    }>;
+    locale: z.ZodOptional<z.ZodString>;
+    entity: z.ZodLiteral<"layout">;
+    layoutId: z.ZodString;
+    blockId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>], "entity">>;
+}, z.core.$strip>;
+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 declare const EMPTY_THREAD_VIEW: ThreadView;
+/**
+ * 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 declare const EMPTY_THREAD_STATE: ThreadState;
+/** 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 declare const threadClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"send">;
+  operationId: z.ZodString;
+  text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"stop">;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"resync">;
+}, z.core.$strip>], "type">;
+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 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
+ * 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 declare function threadViewOf({ steps, running, ...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. */
+export declare const reduceThreadEvents: (state: ThreadState, events: readonly AgentEvent[]) => ThreadState;
+/** Folds what the thread sent over its socket into the thread's state. */
+export declare function reduceThreadFrame(state: ThreadState, frame: ThreadServerMessage): ThreadState;
+//#endregion
+export {};

package/dist/threads.js

@@ -0,0 +1,263 @@
+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`).
+*/
+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";
+/** Who sent a message in a thread. */
+const threadSenderSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	image: z.string().nullable()
+});
+/** 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.
+*/
+const startedDraftSchema = z.object({
+	draftId: z.string(),
+	operationIds: z.array(z.string())
+});
+/** How a write touched what it names. */
+const touchKindSchema = z.enum([
+	"created",
+	"edited",
+	"moved",
+	"deleted",
+	"settings"
+]);
+/**
+* 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()
+});
+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()
+	})
+]);
+/**
+* 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.
+*/
+const touchedBatchSchema = z.object({
+	operationIds: z.array(z.string()),
+	touches: z.array(touchSchema)
+});
+const EMPTY_THREAD_VIEW = {
+	messages: [],
+	running: false
+};
+const EMPTY_THREAD_STATE = {
+	steps: [],
+	running: false
+};
+/** Studio → thread. */
+const threadClientMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("send"),
+		operationId: z.string().min(1),
+		text: z.string().min(1)
+	}),
+	z.object({ type: z.literal("stop") }),
+	z.object({ type: z.literal("resync") })
+]);
+/**
+* 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.
+*/
+const THREAD_ENDED_CLOSE_CODE = 4e3;
+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) {
+	if (message.content.some((part) => part.type === "toolCall")) return {
+		id,
+		type: "tools"
+	};
+	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) {
+	if (!isSender(data)) return void 0;
+	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) {
+	const id = String(entry.id);
+	const sender = senderOf(entry.data);
+	if (entry.kind === "camox.run-stopped" && sender) return {
+		id,
+		type: "stopped",
+		sender
+	};
+	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 === "assistant") return assistantStep(id, message);
+	if (message.role === "toolResult") return {
+		id,
+		type: "tools"
+	};
+}
+/**
+* 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.
+*/
+function threadViewOf({ steps, running, ...drafts }) {
+	const messages = [];
+	let waiting;
+	let unfinished = false;
+	/** Ends the turn waiting for the agent's message, if any. */
+	const endTurn = () => {
+		waiting = void 0;
+		unfinished = false;
+	};
+	/** Ends the turn waiting for the agent's message with a failed line, if any. */
+	const fail = () => {
+		if (waiting !== void 0) messages.push({
+			id: `${waiting}:failed`,
+			from: "failed"
+		});
+		endTurn();
+	};
+	for (const step of steps) switch (step.type) {
+		case "editor":
+			if (unfinished) fail();
+			messages.push({
+				id: step.id,
+				from: "editor",
+				sender: step.sender,
+				text: step.text
+			});
+			waiting = step.id;
+			break;
+		case "stopped":
+			if (waiting === void 0) break;
+			messages.push({
+				id: step.id,
+				from: "stopped",
+				sender: step.sender
+			});
+			endTurn();
+			break;
+		case "answer":
+			if (waiting === void 0 && 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;
+	}
+	if (!running) fail();
+	return {
+		...drafts,
+		messages,
+		running
+	};
+}
+const append = (state, entry) => {
+	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. */
+function reduceThreadState(state, event) {
+	switch (event.type) {
+		case "snapshot": return {
+			...state,
+			steps: event.entries.flatMap((entry) => threadStepOf(entry) ?? []),
+			running: event.run !== void 0
+		};
+		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. */
+const reduceThreadEvents = (state, events) => events.reduce(reduceThreadState, state);
+/** Folds what the thread sent over its socket into the thread's state. */
+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 {
+			...state,
+			continuedIn: frame.continuedIn
+		};
+		default: return state;
+	}
+}
+
+//#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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "license": "MIT",
   "files": [
     "src",
@@ -15,23 +15,70 @@
     "./query-keys": {
       "types": "./dist/query-keys.d.ts",
       "default": "./dist/query-keys.js"
+    },
+    "./ids": {
+      "types": "./dist/ids.d.ts",
+      "default": "./dist/ids.js"
+    },
+    "./drafts": {
+      "types": "./dist/drafts.d.ts",
+      "default": "./dist/drafts.js"
+    },
+    "./icon-catalog": {
+      "types": "./dist/icon-catalog.d.ts",
+      "default": "./dist/icon-catalog.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "default": "./dist/analytics.js"
+    },
+    "./threads": {
+      "types": "./dist/threads.d.ts",
+      "default": "./dist/threads.js"
+    },
+    "./projects": {
+      "types": "./dist/projects.d.ts",
+      "default": "./dist/projects.js"
     }
   },
   "dependencies": {
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.7",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "dts-bundle-generator": "^9.5.1",
-    "esbuild": "^0.25.12"
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-durable": {
+      "optional": true
+    }
   },
   "nx": {
     "tags": [
       "type:pkg"
-    ]
+    ],
+    "targets": {
+      "build": {
+        "inputs": [
+          "production",
+          "^production",
+          "{workspaceRoot}/apps/api/src/**/*",
+          "{workspaceRoot}/packages/ai-tools/src/**/*",
+          "!{workspaceRoot}/**/*.test.ts"
+        ]
+      }
+    }
   },
   "scripts": {
-    "build": "node build.mjs"
+    "build": "vp pack"
   }
 }

package/src/analytics.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+/**
+ * A GA4 measurement ID: `G-` followed by uppercase letters and digits. Shared so the dashboard
+ * checks an ID by the API's own rule before saving it.
+ */
+export const ga4MeasurementIdSchema = /* @__PURE__ */ z
+  .string()
+  .regex(/^G-[A-Z0-9]+$/, "Not a GA4 measurement ID");
+
+/**
+ * A PostHog project API key: `phc_` followed by letters and digits. The prefix tells it apart from
+ * a personal API key, which is secret and must never reach a public page.
+ */
+export const posthogProjectApiKeySchema = /* @__PURE__ */ z
+  .string()
+  .regex(/^phc_[A-Za-z0-9]+$/, "Not a PostHog project API key");
+
+/** The PostHog Cloud region a project lives in. */
+export const posthogRegionSchema = /* @__PURE__ */ z.enum(["us", "eu"]);
+
+export type PosthogRegion = z.output<typeof posthogRegionSchema>;

package/src/artifact.ts

@@ -0,0 +1,38 @@
+/**
+ * Artifact titles, shared by the SDK (frame titles, studio sidebar) and the API (Markdown
+ * Representation, write warnings), so every surface names an artifact the same way.
+ */
+
+export const UNTITLED_ARTIFACT = "Untitled artifact";
+
+const entities: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+
+function decodeEntities(text: string) {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, entity: string) => {
+    if (entity[0] !== "#") return entities[entity.toLowerCase()] ?? match;
+    const code =
+      entity[1] === "x" || entity[1] === "X"
+        ? Number.parseInt(entity.slice(2), 16)
+        : Number(entity.slice(1));
+    return Number.isNaN(code) ? match : String.fromCodePoint(code);
+  });
+}
+
+/** The non-empty `<title>` of an artifact source, if it has one. */
+export function artifactSourceTitle(source: string): string | undefined {
+  const match = /<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(source);
+  const title = match ? decodeEntities(match[1]).replace(/\s+/g, " ").trim() : "";
+  return title || undefined;
+}
+
+/** The artifact's name: its source's `<title>`, or "Untitled artifact". */
+export function artifactTitle(source: string): string {
+  return artifactSourceTitle(source) ?? UNTITLED_ARTIFACT;
+}