@theruntime/protocol 0.0.0 → 0.0.1

package/src/operations/record-status.ts

@@ -0,0 +1,18 @@
+export const RECORD_STATUSES = [
+  "captured",
+  "submitted",
+  "broadcasted",
+  "read",
+  "working",
+  "problem",
+  "resolved",
+  "cancelled",
+] as const;
+
+export type RecordStatus = (typeof RECORD_STATUSES)[number];
+
+export function isRecordStatus(value: unknown): value is RecordStatus {
+  if (typeof value !== "string") return false;
+  const statuses: readonly string[] = RECORD_STATUSES;
+  return statuses.includes(value);
+}

package/src/operations/register-route.ts

@@ -0,0 +1,135 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { optionalDeclarationPatch, type DeclarationPatch } from "./declaration";
+import { parseGuidance, type Guidance } from "./guidance";
+import {
+  asRecord,
+  optionalBoolean,
+  optionalNonNegativeInteger,
+  optionalString,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a registerRoute input";
+
+export interface RegisterRouteInput {
+  readonly operation: "registerRoute";
+  readonly protocol: ProtocolVersion;
+  readonly dir: string;
+  readonly name?: string;
+  /** What the caller claims for itself, the same role subscribe's `sid` plays. Only needed
+   * when the transport carries no observed identity of its own (the local socket, an HTTP
+   * caller) or to name a session explicitly; an MCP caller with a resolvable observed identity
+   * needs neither. */
+  readonly sid?: string;
+  /** Whether this call also subscribes the registering session to the route's events. Default
+   * true. Passing false never unsubscribes a session already subscribed; it only skips a fresh
+   * subscribe. */
+  readonly subscribe?: boolean;
+  /** A host project's root directory, which the app may read through the @host seam. Three
+   * states, so a re-register of a route that already has one never blanks it by omission:
+   * omitted keeps the stored value, "" clears it, a path sets it. */
+  readonly host?: string;
+  /** The template to create the app from, by id. listTemplates names the set. An id outside it
+   * is refused rather than answered with the plain shell. Only read when the directory has no
+   * App.tsx of its own; the scaffold never overwrites a file that is already there. */
+  readonly template?: string;
+  /** What this app's setup is: whether it is host connected, which React copy it runs, and
+   * whose components it uses. Each field has the same three states host does, so a re-register
+   * that names none of them leaves the stored declaration alone. */
+  readonly declaration?: DeclarationPatch;
+}
+
+export function parseRegisterRouteInput(value: unknown): RegisterRouteInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "registerRoute", NOUN);
+  requireProtocol(record, NOUN);
+  const dir = requireString(record, "dir", NOUN);
+  const name = optionalString(record, "name", NOUN);
+  const sid = optionalString(record, "sid", NOUN);
+  const subscribe = optionalBoolean(record, "subscribe", NOUN);
+  const host = optionalString(record, "host", NOUN);
+  const template = optionalString(record, "template", NOUN);
+  const declaration = optionalDeclarationPatch(record, "declaration", NOUN);
+  // Refused rather than dropped: a caller that named a theme and got an app themed by something
+  // else has no way to tell, which is the same reason the theme name it used to carry was
+  // checked against a set.
+  if (record.theme !== undefined) {
+    throw new Error(
+      `${NOUN} carries no theme. The design register above the app decides its theme, through the tokens.css in the app's own directory.`,
+    );
+  }
+  return {
+    operation: "registerRoute",
+    protocol: PROTOCOL_VERSION,
+    dir,
+    ...(name !== undefined ? { name } : {}),
+    ...(sid !== undefined ? { sid } : {}),
+    ...(subscribe !== undefined ? { subscribe } : {}),
+    ...(host !== undefined ? { host } : {}),
+    ...(template !== undefined ? { template } : {}),
+    ...(declaration !== undefined ? { declaration } : {}),
+  };
+}
+
+export function serializeRegisterRouteInput(input: RegisterRouteInput): string {
+  return JSON.stringify(input);
+}
+
+export interface RegisterRouteResult {
+  readonly name: string;
+  readonly dir: string;
+  readonly url: string;
+  readonly reused: boolean;
+  readonly mismatch: boolean;
+  /** Whether the registering session is subscribed to this route's events after this call,
+   * whether this call did the subscribing or it already was. */
+  readonly subscribed: boolean;
+  /** The identity the subscription was filed under. Present iff subscribed is true. */
+  readonly sid?: string;
+  /** The subscription's replay cursor. Present iff subscribed is true. */
+  readonly cursor?: number;
+  /** The template this app was created from. Present on every later register of the same route,
+   * read off the stored row, so provenance survives the call that established it. */
+  readonly template?: string;
+  /** The template's manifest version at the moment the app was created. Present iff template is. */
+  readonly templateVersion?: string;
+  /** What this registration teaches the calling session. */
+  readonly guidance: Guidance;
+}
+
+export function parseRegisterRouteResult(value: unknown): RegisterRouteResult {
+  const record = asRecord(value, "a registerRoute result");
+  const name = requireString(record, "name", "a registerRoute result");
+  const dir = requireString(record, "dir", "a registerRoute result");
+  const url = requireString(record, "url", "a registerRoute result");
+  if (typeof record.reused !== "boolean")
+    throw new Error("a registerRoute result states whether the route was reused");
+  if (typeof record.mismatch !== "boolean")
+    throw new Error("a registerRoute result states whether the requested dir was a mismatch");
+  if (typeof record.subscribed !== "boolean")
+    throw new Error("a registerRoute result states whether the session is subscribed");
+  const sid = optionalString(record, "sid", "a registerRoute result");
+  const cursor = optionalNonNegativeInteger(record, "cursor", "a registerRoute result");
+  const template = optionalString(record, "template", "a registerRoute result");
+  const templateVersion = optionalString(record, "templateVersion", "a registerRoute result");
+  const guidance = parseGuidance(record.guidance);
+  return {
+    name,
+    dir,
+    url,
+    reused: record.reused,
+    mismatch: record.mismatch,
+    subscribed: record.subscribed,
+    ...(sid !== undefined ? { sid } : {}),
+    ...(cursor !== undefined ? { cursor } : {}),
+    ...(template !== undefined ? { template } : {}),
+    ...(templateVersion !== undefined ? { templateVersion } : {}),
+    guidance,
+  };
+}
+
+export function serializeRegisterRouteResult(result: RegisterRouteResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/save-record.ts

@@ -0,0 +1,55 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireOperation,
+  requirePositiveInteger,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a saveRecord input";
+
+export interface SaveRecordInput {
+  readonly operation: "saveRecord";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly action: string;
+  // Payload is JSON, validated at the boundary, same as emitEvent's.
+  readonly payload: unknown;
+}
+
+export function parseSaveRecordInput(value: unknown): SaveRecordInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "saveRecord", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const action = requireString(record, "action", NOUN);
+  if (!("payload" in record)) throw new Error(`${NOUN} carries a payload`);
+  return {
+    operation: "saveRecord",
+    protocol: PROTOCOL_VERSION,
+    name,
+    action,
+    payload: record.payload,
+  };
+}
+
+export function serializeSaveRecordInput(input: SaveRecordInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SaveRecordResult {
+  readonly name: string;
+  readonly id: number;
+}
+
+export function parseSaveRecordResult(value: unknown): SaveRecordResult {
+  const record = asRecord(value, "a saveRecord result");
+  const name = requireString(record, "name", "a saveRecord result");
+  const id = requirePositiveInteger(record, "id", "a saveRecord result");
+  return { name, id };
+}
+
+export function serializeSaveRecordResult(result: SaveRecordResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/set-record-status.ts

@@ -0,0 +1,63 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalString,
+  requireOperation,
+  requirePositiveInteger,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+import { isRecordStatus, RECORD_STATUSES, type RecordStatus } from "./record-status";
+
+const NOUN = "a setRecordStatus input";
+
+export interface SetRecordStatusInput {
+  readonly operation: "setRecordStatus";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly id: number;
+  readonly status: RecordStatus;
+  readonly note?: string;
+}
+
+export function parseSetRecordStatusInput(value: unknown): SetRecordStatusInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "setRecordStatus", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const id = requirePositiveInteger(record, "id", NOUN);
+  if (!isRecordStatus(record.status))
+    throw new Error(`${NOUN} names a status, one of: ${RECORD_STATUSES.join(", ")}`);
+  const note = optionalString(record, "note", NOUN);
+  return {
+    operation: "setRecordStatus",
+    protocol: PROTOCOL_VERSION,
+    name,
+    id,
+    status: record.status,
+    ...(note !== undefined ? { note } : {}),
+  };
+}
+
+export function serializeSetRecordStatusInput(input: SetRecordStatusInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SetRecordStatusResult {
+  readonly name: string;
+  readonly id: number;
+  readonly status: RecordStatus;
+}
+
+export function parseSetRecordStatusResult(value: unknown): SetRecordStatusResult {
+  const record = asRecord(value, "a setRecordStatus result");
+  const name = requireString(record, "name", "a setRecordStatus result");
+  const id = requirePositiveInteger(record, "id", "a setRecordStatus result");
+  if (!isRecordStatus(record.status))
+    throw new Error("a setRecordStatus result names a known status");
+  return { name, id, status: record.status };
+}
+
+export function serializeSetRecordStatusResult(result: SetRecordStatusResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/set-route-visibility.ts

@@ -0,0 +1,48 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+import { isVisibility, type Visibility } from "./visibility";
+
+const NOUN = "a setRouteVisibility input";
+
+export interface SetRouteVisibilityInput {
+  readonly operation: "setRouteVisibility";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  // A free string, not narrowed to Visibility: the daemon refuses a reserved or unrecognized
+  // value with a policy message of its own, which needs to see the value the caller actually
+  // sent rather than have it rejected here as an unparsable shape.
+  readonly visibility: string;
+}
+
+export function parseSetRouteVisibilityInput(value: unknown): SetRouteVisibilityInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "setRouteVisibility", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const visibility = requireString(record, "visibility", NOUN);
+  return { operation: "setRouteVisibility", protocol: PROTOCOL_VERSION, name, visibility };
+}
+
+export function serializeSetRouteVisibilityInput(input: SetRouteVisibilityInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SetRouteVisibilityResult {
+  readonly name: string;
+  readonly visibility: Visibility;
+  readonly changed: boolean;
+}
+
+export function parseSetRouteVisibilityResult(value: unknown): SetRouteVisibilityResult {
+  const record = asRecord(value, "a setRouteVisibility result");
+  const name = requireString(record, "name", "a setRouteVisibility result");
+  if (!isVisibility(record.visibility))
+    throw new Error("a setRouteVisibility result names a known visibility");
+  if (typeof record.changed !== "boolean")
+    throw new Error("a setRouteVisibility result states whether the visibility changed");
+  return { name, visibility: record.visibility, changed: record.changed };
+}
+
+export function serializeSetRouteVisibilityResult(result: SetRouteVisibilityResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/set-selection.ts

@@ -0,0 +1,53 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireNonNegativeInteger,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a setSelection input";
+
+export interface SetSelectionInput {
+  readonly operation: "setSelection";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  // Each element is an opaque JSON capture (selector, tag, identity, …) the SDK's selection
+  // client owns the shape of; the protocol carries it, never inspects it.
+  readonly elements: readonly unknown[];
+}
+
+export function parseSetSelectionInput(value: unknown): SetSelectionInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "setSelection", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  if (!Array.isArray(record.elements)) throw new Error(`${NOUN} carries an array of elements`);
+  return {
+    operation: "setSelection",
+    protocol: PROTOCOL_VERSION,
+    name,
+    elements: record.elements,
+  };
+}
+
+export function serializeSetSelectionInput(input: SetSelectionInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SetSelectionResult {
+  readonly name: string;
+  readonly count: number;
+}
+
+export function parseSetSelectionResult(value: unknown): SetSelectionResult {
+  const record = asRecord(value, "a setSelection result");
+  const name = requireString(record, "name", "a setSelection result");
+  const count = requireNonNegativeInteger(record, "count", "a setSelection result");
+  return { name, count };
+}
+
+export function serializeSetSelectionResult(result: SetSelectionResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/subscribe.ts

@@ -0,0 +1,47 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+import { parseGuidance, type Guidance } from "./guidance";
+
+const NOUN = "a subscribe input";
+
+export interface SubscribeInput {
+  readonly operation: "subscribe";
+  readonly protocol: ProtocolVersion;
+  readonly sid: string;
+  readonly name: string;
+}
+
+export function parseSubscribeInput(value: unknown): SubscribeInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "subscribe", NOUN);
+  requireProtocol(record, NOUN);
+  const sid = requireString(record, "sid", NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "subscribe", protocol: PROTOCOL_VERSION, sid, name };
+}
+
+export function serializeSubscribeInput(input: SubscribeInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SubscribeResult {
+  readonly sid: string;
+  readonly name: string;
+  readonly cursor: number;
+  /** What this subscription teaches the calling session. */
+  readonly guidance: Guidance;
+}
+
+export function parseSubscribeResult(value: unknown): SubscribeResult {
+  const record = asRecord(value, "a subscribe result");
+  const sid = requireString(record, "sid", "a subscribe result");
+  const name = requireString(record, "name", "a subscribe result");
+  if (typeof record.cursor !== "number" || !Number.isInteger(record.cursor)) {
+    throw new Error("a subscribe result names an integer cursor");
+  }
+  return { sid, name, cursor: record.cursor, guidance: parseGuidance(record.guidance) };
+}
+
+export function serializeSubscribeResult(result: SubscribeResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/unregister-route.ts

@@ -0,0 +1,36 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+
+const NOUN = "an unregisterRoute input";
+
+export interface UnregisterRouteInput {
+  readonly operation: "unregisterRoute";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseUnregisterRouteInput(value: unknown): UnregisterRouteInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "unregisterRoute", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "unregisterRoute", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeUnregisterRouteInput(input: UnregisterRouteInput): string {
+  return JSON.stringify(input);
+}
+
+export interface UnregisterRouteResult {
+  readonly name: string;
+}
+
+export function parseUnregisterRouteResult(value: unknown): UnregisterRouteResult {
+  const record = asRecord(value, "an unregisterRoute result");
+  const name = requireString(record, "name", "an unregisterRoute result");
+  return { name };
+}
+
+export function serializeUnregisterRouteResult(result: UnregisterRouteResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/unsubscribe.ts

@@ -0,0 +1,44 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+
+const NOUN = "an unsubscribe input";
+
+export interface UnsubscribeInput {
+  readonly operation: "unsubscribe";
+  readonly protocol: ProtocolVersion;
+  readonly sid: string;
+  readonly name: string;
+}
+
+export function parseUnsubscribeInput(value: unknown): UnsubscribeInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "unsubscribe", NOUN);
+  requireProtocol(record, NOUN);
+  const sid = requireString(record, "sid", NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "unsubscribe", protocol: PROTOCOL_VERSION, sid, name };
+}
+
+export function serializeUnsubscribeInput(input: UnsubscribeInput): string {
+  return JSON.stringify(input);
+}
+
+export interface UnsubscribeResult {
+  readonly sid: string;
+  readonly name: string;
+  readonly removed: boolean;
+}
+
+export function parseUnsubscribeResult(value: unknown): UnsubscribeResult {
+  const record = asRecord(value, "an unsubscribe result");
+  const sid = requireString(record, "sid", "an unsubscribe result");
+  const name = requireString(record, "name", "an unsubscribe result");
+  if (typeof record.removed !== "boolean") {
+    throw new Error("an unsubscribe result states whether a subscription was removed");
+  }
+  return { sid, name, removed: record.removed };
+}
+
+export function serializeUnsubscribeResult(result: UnsubscribeResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/visibility.ts

@@ -0,0 +1,9 @@
+export const VISIBILITIES = ["private", "link"] as const;
+
+export type Visibility = (typeof VISIBILITIES)[number];
+
+export function isVisibility(value: unknown): value is Visibility {
+  if (typeof value !== "string") return false;
+  const visibilities: readonly string[] = VISIBILITIES;
+  return visibilities.includes(value);
+}

package/src/operations.ts

@@ -0,0 +1,39 @@
+// Every operation the protocol defines. Each name's shape lives in its own file under ./operations.
+export const OPERATIONS = [
+  "heartbeat",
+  "identify",
+  "registerRoute",
+  "unregisterRoute",
+  "listRoutes",
+  "describeRoute",
+  "declareRoute",
+  "archiveRoute",
+  "deleteApp",
+  "rebootRoute",
+  "listRecords",
+  "getRecord",
+  "setRecordStatus",
+  "deleteRecord",
+  "subscribe",
+  "unsubscribe",
+  "emitEvent",
+  "addPackage",
+  "addComponent",
+  "captureSnapshot",
+  "getSnapshot",
+  "setRouteVisibility",
+  "saveRecord",
+  "setSelection",
+  "querySelection",
+  "listSubscribers",
+  "listSubscriptions",
+  "listPresence",
+  "listQuickActions",
+  "listPackages",
+  "listTemplates",
+  "readRouteLog",
+  "listRouteLogs",
+  "readDaemonLog",
+] as const;
+
+export type OperationName = (typeof OPERATIONS)[number];

package/src/payloads/app-ready.ts

@@ -0,0 +1,24 @@
+import { asRecord, requireNonNegativeInteger, requireString } from "../operations/parse-helpers";
+
+const NOUN = "an app_ready payload";
+
+/** What a mounted app reports once its first frame has committed and painted. `at` is the app's
+ * own clock; the daemon measures age from its own receipt instead. */
+export interface AppReadyPayload {
+  readonly route: string;
+  readonly at: number;
+  readonly rootChildren: number;
+}
+
+export function parseAppReadyPayload(value: unknown): AppReadyPayload {
+  const record = asRecord(value, NOUN);
+  return {
+    route: requireString(record, "route", NOUN),
+    at: requireNonNegativeInteger(record, "at", NOUN),
+    rootChildren: requireNonNegativeInteger(record, "rootChildren", NOUN),
+  };
+}
+
+export function serializeAppReadyPayload(payload: AppReadyPayload): string {
+  return JSON.stringify(payload);
+}

package/src/payloads/refusal.ts

@@ -0,0 +1,44 @@
+import {
+  asRecord,
+  optionalString,
+  requireNonNegativeInteger,
+  requireString,
+} from "../operations/parse-helpers";
+
+const NOUN = "a route refusal";
+
+/** The action a route-kind event carries when the supervisor stops restarting a route. */
+export const CRASH_REFUSED_ACTION = "crash_refused";
+
+/**
+ * Why a route's process is not running: the sentence a caller of the route is answered with,
+ * how many crashes fell inside the window, the window they fell inside, when the supervisor
+ * gave up, and the last output the process wrote. `stderr` is absent for a process that
+ * crashed silently.
+ *
+ * One shape, carried two ways: it is the payload of the crash_refused event, and it is the
+ * refusal a listRoutes summary carries for the same route.
+ */
+export interface RouteRefusal {
+  readonly reason: string;
+  readonly attempts: number;
+  readonly windowMs: number;
+  readonly at: string;
+  readonly stderr?: string;
+}
+
+export function parseRouteRefusal(value: unknown): RouteRefusal {
+  const record = asRecord(value, NOUN);
+  const stderr = optionalString(record, "stderr", NOUN);
+  return {
+    reason: requireString(record, "reason", NOUN),
+    attempts: requireNonNegativeInteger(record, "attempts", NOUN),
+    windowMs: requireNonNegativeInteger(record, "windowMs", NOUN),
+    at: requireString(record, "at", NOUN),
+    ...(stderr !== undefined ? { stderr } : {}),
+  };
+}
+
+export function serializeRouteRefusal(refusal: RouteRefusal): string {
+  return JSON.stringify(refusal);
+}

package/src/payloads.ts

@@ -0,0 +1,11 @@
+// Every action the protocol defines a payload shape for. Each name's shape lives in its own file
+// under ./payloads. An action an app emits with no shape here is carried as opaque JSON.
+export const APP_ACTIONS = ["app_ready"] as const;
+
+export type AppActionName = (typeof APP_ACTIONS)[number];
+
+export function isAppActionName(value: unknown): value is AppActionName {
+  if (typeof value !== "string") return false;
+  const actions: readonly string[] = APP_ACTIONS;
+  return actions.includes(value);
+}

package/src/quick-actions/index.ts

@@ -0,0 +1,12 @@
+/** The quick action surface, re-exported by the package barrel as one line. */
+export {
+  parseListQuickActionsInput,
+  serializeListQuickActionsInput,
+  parseListQuickActionsResult,
+  serializeListQuickActionsResult,
+} from "../operations/list-quick-actions";
+export type {
+  ListQuickActionsInput,
+  ListQuickActionsResult,
+  QuickActionSummary,
+} from "../operations/list-quick-actions";