@camox/api-contract 0.43.0 → 0.45.0

package/dist/index.js

@@ -0,0 +1,70 @@
+import { n as scopeIconSvgIds, r as validateIconValue, t as ICON_CATALOG_VERSION } from "./icons-Bk4igP2j.js";
+import { PAGE_TEXT_LINK_PREFIX, generateUuidv7, projectIdSchema, uuidv7JsonSchema, uuidv7Schema } from "./ids.js";
+
+//#region src/artifact.ts
+/**
+* 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.
+*/
+const UNTITLED_ARTIFACT = "Untitled artifact";
+const entities = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " "
+};
+function decodeEntities(text) {
+	return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, entity) => {
+		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. */
+function artifactSourceTitle(source) {
+	const match = /<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(source);
+	return (match ? decodeEntities(match[1]).replace(/\s+/g, " ").trim() : "") || void 0;
+}
+/** The artifact's name: its source's `<title>`, or "Untitled artifact". */
+function artifactTitle(source) {
+	return artifactSourceTitle(source) ?? "Untitled artifact";
+}
+
+//#endregion
+//#region src/reference-query.ts
+/**
+* Rules for query-backed reference lists, shared by the SDK (builders) and the API (definition
+* sync), so both accept and reject the same queries.
+*/
+/** The most records a query-backed list resolves to, and its default `limit`. */
+const QUERY_LIMIT_CAP = 100;
+const SYSTEM_ORDER_KEYS = ["createdAt", "publishedAt"];
+function isSystemOrderKey(key) {
+	return SYSTEM_ORDER_KEYS.includes(key);
+}
+/** Whether a reference list field is query-backed: code defines its records, nothing is stored. */
+function isQueryBacked(field) {
+	return !!field && field.query !== void 0;
+}
+/**
+* Why a query is invalid, if it is. `fieldTypeOf` gives the collection field type an ordering
+* key names; keys must name a `String` field or system metadata.
+*/
+function referenceQueryProblem(query, fieldTypeOf) {
+	if (!query || typeof query !== "object" || Array.isArray(query)) return "query must be an object";
+	const { orderBy, limit, ...rest } = query;
+	if (Object.keys(rest).length) return "query only supports orderBy and limit";
+	if (limit !== void 0 && !(typeof limit === "number" && Number.isInteger(limit) && limit >= 1 && limit <= 100)) return `limit must be an integer from 1 to ${100}`;
+	if (orderBy === void 0) return;
+	const entries = orderBy && typeof orderBy === "object" && !Array.isArray(orderBy) ? Object.entries(orderBy) : [];
+	if (entries.length !== 1) return "orderBy takes a single key";
+	const [[key, direction]] = entries;
+	if (direction !== "asc" && direction !== "desc") return "order must be \"asc\" or \"desc\"";
+	if (isSystemOrderKey(key)) return;
+	if (fieldTypeOf(key) !== "String") return `cannot order by "${key}"`;
+}
+
+//#endregion
+export { ICON_CATALOG_VERSION, PAGE_TEXT_LINK_PREFIX, QUERY_LIMIT_CAP, SYSTEM_ORDER_KEYS, UNTITLED_ARTIFACT, artifactSourceTitle, artifactTitle, generateUuidv7, isQueryBacked, isSystemOrderKey, projectIdSchema, referenceQueryProblem, scopeIconSvgIds, uuidv7JsonSchema, uuidv7Schema, validateIconValue };

package/dist/projects.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+//#region src/projects.d.ts
+/**
+ * Project Slugs Camox keeps for its own hosts and pages, so no project's `<slug>.camox.site`
+ * looks like one of them.
+ */
+export declare const RESERVED_PROJECT_SLUGS: ReadonlySet<string>;
+/**
+ * A Project Slug: one lowercase DNS label, the only depth Universal SSL covers on `camox.site`,
+ * made of letters, digits and inner hyphens.
+ */
+export declare const projectSlugSchema: z.ZodString;
+/** Why a slug can't be given to a new project. */
+export type UnavailableSlugReason = "invalid" | "reserved" | "taken";
+/** What a member is told when a slug can't be used, by reason. */
+export declare const UNAVAILABLE_SLUG_MESSAGES: Record<UnavailableSlugReason, string>;
+/**
+ * Where a project is in its life: `settingUp` from its creation until its first release
+ * succeeds, then `live`. `setupFailed` when its setup gave up: Camox is told and fixes it.
+ */
+export type ProjectStatus = "settingUp" | "live" | "setupFailed";
+/**
+ * The steps a project's setup goes through before it's live, as its page lists them: copying the
+ * Template into its repo, then its first release building it and serving it from its Worker.
+ */
+export type ProjectSetupStep = "copyTemplate" | "build" | "serve";
+export declare const PROJECT_SETUP_STEPS: readonly ProjectSetupStep[];
+//#endregion

package/dist/projects.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+//#region src/projects.ts
+/**
+* Project Slugs Camox keeps for its own hosts and pages, so no project's `<slug>.camox.site`
+* looks like one of them.
+*/
+const RESERVED_PROJECT_SLUGS = /* @__PURE__ */ new Set([
+	"www",
+	"api",
+	"app",
+	"dashboard",
+	"studio",
+	"sites",
+	"site",
+	"docs",
+	"blog",
+	"help",
+	"support",
+	"status",
+	"admin",
+	"auth",
+	"login",
+	"mail",
+	"email",
+	"cdn",
+	"static",
+	"assets",
+	"files",
+	"camox"
+]);
+/**
+* A Project Slug: one lowercase DNS label, the only depth Universal SSL covers on `camox.site`,
+* made of letters, digits and inner hyphens.
+*/
+const projectSlugSchema = /* @__PURE__ */ z.string().min(1, "Enter a slug").max(63, "Use at most 63 characters").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, digits and hyphens, without a hyphen at either end");
+/** What a member is told when a slug can't be used, by reason. */
+const UNAVAILABLE_SLUG_MESSAGES = {
+	invalid: "Use lowercase letters, digits and hyphens, without a hyphen at either end.",
+	reserved: "This slug is reserved by Camox. Choose another.",
+	taken: "This slug is already taken. Choose another."
+};
+const PROJECT_SETUP_STEPS = [
+	"copyTemplate",
+	"build",
+	"serve"
+];
+
+//#endregion
+export { PROJECT_SETUP_STEPS, RESERVED_PROJECT_SLUGS, UNAVAILABLE_SLUG_MESSAGES, projectSlugSchema };

package/dist/query-keys.d.ts

@@ -1,3 +1,5 @@
+import { EndedDraft } from "./drafts.js";
+//#region src/query-keys.d.ts
 /**
  * Use TypeScript to enforce 'camox' as the first query key to ensure they're all namespaced.
  * This is because the Tanstack Query client on the frontend may be shared with the user's routes,
@@ -5,46 +7,64 @@
  */
 export type QueryKey = [first: "camox", ...rest: Array<string | number>];
 /**
- * Source axis on read query keys. `'live'` reads the page's live published
- * checkpoint snapshot; `'draft'` reads the live editor rows. The two render
- * through the same component — only the cache slot differs, so toggling the
- * source select is instant once both have been seeded.
- *
- * Block / page-read query keys include the source as the trailing key segment.
- * Omitting it on `invalidateQueries` is a prefix invalidation that hits every
- * source — used for navigation events and other source-agnostic invalidations.
- * Edit-time invalidations (which only touch draft data) pass `'draft'`
- * explicitly so the `'live'` cache stays untouched.
+ * The key prefixes the API's realtime invalidations name (ADR 0011). The studio caches each read
+ * under one of them, with the scope appended, so an invalidation reaches every read it should;
+ * the studio's own keys live with its reads, in the SDK.
  */
-export type ReadSource = "draft" | "live";
 export declare const queryKeys: {
-    pages: {
-        list: ["camox", string, string];
-        getByPath: (path: string, source?: ReadSource) => ["camox", string, string, string] | ["camox", string, string, string, ReadSource];
-        getByPathAll: ["camox", string, string];
-        getById: (id: number) => ["camox", string, string, number];
-    };
-    files: {
-        list: ["camox", string, string];
-        get: (id: number) => ["camox", string, string, number];
-    };
-    blocks: {
-        get: (id: number, source?: ReadSource) => ["camox", string, string, number] | ["camox", string, string, number, ReadSource];
-        getUsageCounts: ["camox", string, string];
-        getPageMarkdown: (pageId: number) => ["camox", string, string, number];
-    };
-    repeatableItems: {
-        get: (id: number) => ["camox", string, string, number];
-    };
-    layouts: {
-        all: ["camox", string];
-    };
-    environments: {
-        all: ["camox", string];
-        checkCompatibility: ["camox", string, string];
-    };
+  collections: {
+    record: (projectUuid: string, collectionId: string, id: string) => ["camox", string, string, string, string, string];
+    records: (projectUuid: string, collectionId: string) => ["camox", string, string, string, string];
+  };
+  pages: {
+    list: ["camox", string, string];
+    getByPath: (path: string) => ["camox", string, string, string];
+    getByPathAll: ["camox", string, string];
+    getById: (id: string) => ["camox", string, string, string];
+  };
+  files: {
+    list: ["camox", string, string];
+    get: (id: string) => ["camox", string, string, string];
+  };
+  blocks: {
+    get: (id: string) => ["camox", string, string, string];
+    getUsageCounts: ["camox", string, string];
+    getSyncedContent: (type: string) => ["camox", string, string, string, string];
+    getPageMarkdown: (pageId: string) => ["camox", string, string, string];
+  };
+  layouts: {
+    all: ["camox", string];
+  };
+  drafts: {
+    all: ["camox", string];
+    list: ["camox", string, string];
+    get: ["camox", string, string];
+  };
 };
+/** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */
+export declare const LIVE_KEY_SCOPE = "live";
+/**
+ * A query key read from Live (`draftId` null) or from a draft. The keys above are prefixes naming
+ * what a query reads; the cache holds them with the scope appended, so each draft's queries are
+ * kept and invalidated apart.
+ */
+export declare function inScope(key: QueryKey, draftId: string | null): QueryKey;
+/** The scope a scoped query key ends in: `"live"` or a draft's id. */
+export declare function scopeOfKey(key: readonly unknown[]): unknown;
+/**
+ * Refetch the queries under these prefixes. `draftId` names the draft the change came from, so
+ * only that draft's queries refetch; a Live change (`null`) refetches every draft's too, since
+ * drafts read Live wherever they change nothing.
+ */
 export type InvalidationMessage = {
-    type: "invalidate";
-    targets: QueryKey[];
+  type: "invalidate";
+  draftId: string | null;
+  targets: QueryKey[];
 };
+/** A draft was published or discarded: its viewers go back to Live. */
+export type DraftEndedMessage = {
+  type: "draftEnded";
+} & EndedDraft;
+/** Everything the project room broadcasts. */
+export type ProjectRoomMessage = InvalidationMessage | DraftEndedMessage;
+//#endregion

package/dist/query-keys.js

@@ -1,29 +1,119 @@
-export const queryKeys = {
-    pages: {
-        list: ["camox", "pages", "list"],
-        getByPath: (path, source) => source
-            ? ["camox", "pages", "getByPath", path, source]
-            : ["camox", "pages", "getByPath", path],
-        getByPathAll: ["camox", "pages", "getByPath"],
-        getById: (id) => ["camox", "pages", "getById", id],
-    },
-    files: {
-        list: ["camox", "files", "list"],
-        get: (id) => ["camox", "files", "get", id],
-    },
-    blocks: {
-        get: (id, source) => source ? ["camox", "blocks", "get", id, source] : ["camox", "blocks", "get", id],
-        getUsageCounts: ["camox", "blocks", "getUsageCounts"],
-        getPageMarkdown: (pageId) => ["camox", "blocks", "getPageMarkdown", pageId],
-    },
-    repeatableItems: {
-        get: (id) => ["camox", "repeatableItems", "get", id],
-    },
-    layouts: {
-        all: ["camox", "layouts"],
-    },
-    environments: {
-        all: ["camox", "environments"],
-        checkCompatibility: ["camox", "environments", "checkCompatibility"],
-    },
+//#region src/query-keys.ts
+/**
+* The key prefixes the API's realtime invalidations name (ADR 0011). The studio caches each read
+* under one of them, with the scope appended, so an invalidation reaches every read it should;
+* the studio's own keys live with its reads, in the SDK.
+*/
+const queryKeys = {
+	collections: {
+		record: (projectUuid, collectionId, id) => [
+			"camox",
+			"collections",
+			"record",
+			projectUuid,
+			collectionId,
+			id
+		],
+		records: (projectUuid, collectionId) => [
+			"camox",
+			"collections",
+			"records",
+			projectUuid,
+			collectionId
+		]
+	},
+	pages: {
+		list: [
+			"camox",
+			"pages",
+			"list"
+		],
+		getByPath: (path) => [
+			"camox",
+			"pages",
+			"getByPath",
+			path
+		],
+		getByPathAll: [
+			"camox",
+			"pages",
+			"getByPath"
+		],
+		getById: (id) => [
+			"camox",
+			"pages",
+			"getById",
+			id
+		]
+	},
+	files: {
+		list: [
+			"camox",
+			"files",
+			"list"
+		],
+		get: (id) => [
+			"camox",
+			"files",
+			"get",
+			id
+		]
+	},
+	blocks: {
+		get: (id) => [
+			"camox",
+			"blocks",
+			"get",
+			id
+		],
+		getUsageCounts: [
+			"camox",
+			"blocks",
+			"getUsageCounts"
+		],
+		getSyncedContent: (type) => [
+			"camox",
+			"blocks",
+			"getUsageCounts",
+			"synced",
+			type
+		],
+		getPageMarkdown: (pageId) => [
+			"camox",
+			"blocks",
+			"getPageMarkdown",
+			pageId
+		]
+	},
+	layouts: { all: ["camox", "layouts"] },
+	drafts: {
+		all: ["camox", "drafts"],
+		list: [
+			"camox",
+			"drafts",
+			"list"
+		],
+		get: [
+			"camox",
+			"drafts",
+			"get"
+		]
+	}
 };
+/** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */
+const LIVE_KEY_SCOPE = "live";
+/**
+* A query key read from Live (`draftId` null) or from a draft. The keys above are prefixes naming
+* what a query reads; the cache holds them with the scope appended, so each draft's queries are
+* kept and invalidated apart.
+*/
+function inScope(key, draftId) {
+	return [...key, draftId ?? "live"];
+}
+/** The scope a scoped query key ends in: `"live"` or a draft's id. */
+function scopeOfKey(key) {
+	return key[key.length - 1];
+}
+
+//#endregion
+export { LIVE_KEY_SCOPE, inScope, queryKeys, scopeOfKey };

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 {};