@theruntime/protocol 0.0.0 → 0.0.1

package/src/operations/heartbeat.ts

@@ -0,0 +1,27 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+
+export interface Heartbeat {
+  readonly operation: "heartbeat";
+  readonly protocol: ProtocolVersion;
+  readonly client: string;
+}
+
+export function parseHeartbeat(value: unknown): Heartbeat {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("a heartbeat is an object");
+  }
+  if (!("operation" in value) || value.operation !== "heartbeat") {
+    throw new Error("a heartbeat names the heartbeat operation");
+  }
+  if (!("protocol" in value) || value.protocol !== PROTOCOL_VERSION) {
+    throw new Error(`a heartbeat carries protocol ${PROTOCOL_VERSION}`);
+  }
+  if (!("client" in value) || typeof value.client !== "string" || value.client.length === 0) {
+    throw new Error("a heartbeat names the client it comes from");
+  }
+  return { operation: "heartbeat", protocol: PROTOCOL_VERSION, client: value.client };
+}
+
+export function serializeHeartbeat(heartbeat: Heartbeat): string {
+  return JSON.stringify(heartbeat);
+}

package/src/operations/identify.ts

@@ -0,0 +1,50 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+
+const NOUN = "an identify input";
+
+export interface IdentifyInput {
+  readonly operation: "identify";
+  readonly protocol: ProtocolVersion;
+  readonly claimedId: string;
+}
+
+export function parseIdentifyInput(value: unknown): IdentifyInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "identify", NOUN);
+  requireProtocol(record, NOUN);
+  const claimedId = requireString(record, "claimedId", NOUN);
+  return { operation: "identify", protocol: PROTOCOL_VERSION, claimedId };
+}
+
+export function serializeIdentifyInput(input: IdentifyInput): string {
+  return JSON.stringify(input);
+}
+
+export const IDENTITY_VIAS = ["observed", "claimed"] as const;
+export type IdentityVia = (typeof IDENTITY_VIAS)[number];
+
+export interface IdentifyResult {
+  readonly claimedId: string;
+  readonly key: string;
+  readonly via: IdentityVia;
+}
+
+function isIdentityVia(value: unknown): value is IdentityVia {
+  const vias: readonly unknown[] = IDENTITY_VIAS;
+  return vias.includes(value);
+}
+
+export function parseIdentifyResult(value: unknown): IdentifyResult {
+  const record = asRecord(value, "an identify result");
+  const claimedId = requireString(record, "claimedId", "an identify result");
+  const key = requireString(record, "key", "an identify result");
+  if (!isIdentityVia(record.via)) {
+    throw new Error("an identify result names its via as observed or claimed");
+  }
+  return { claimedId, key, via: record.via };
+}
+
+export function serializeIdentifyResult(result: IdentifyResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/list-packages.ts

@@ -0,0 +1,72 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { asRecord, requireOperation, requireProtocol, requireString } from "./parse-helpers";
+
+const NOUN = "a listPackages input";
+
+export interface ListPackagesInput {
+  readonly operation: "listPackages";
+  readonly protocol: ProtocolVersion;
+}
+
+export function parseListPackagesInput(value: unknown): ListPackagesInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listPackages", NOUN);
+  requireProtocol(record, NOUN);
+  return { operation: "listPackages", protocol: PROTOCOL_VERSION };
+}
+
+export function serializeListPackagesInput(input: ListPackagesInput): string {
+  return JSON.stringify(input);
+}
+
+// The one shape this operation carries regardless of transport: an array of entries, each
+// naming where it came from and its resolved version, or null when none is known. The previous
+// engine answered this question two ways depending on transport (an object keyed by id over MCP,
+// an array over HTTP); this protocol carries one operation, one result shape, over every
+// transport.
+//
+// runtime is the runtime's own committed manifest. dependency is a package a route serves because
+// something the runtime ships depends on it. user is a session's addPackage call.
+export type PackageSource = "runtime" | "dependency" | "user";
+
+const PACKAGE_SOURCES: readonly PackageSource[] = ["runtime", "dependency", "user"];
+
+export interface PackageSummary {
+  readonly id: string;
+  readonly source: PackageSource;
+  readonly version: string | null;
+}
+
+function parsePackageSource(value: unknown, noun: string): PackageSource {
+  const source = PACKAGE_SOURCES.find((candidate) => candidate === value);
+  if (source === undefined) {
+    throw new Error(`${noun} names a source of "runtime", "dependency", or "user"`);
+  }
+  return source;
+}
+
+function parsePackageSummary(value: unknown): PackageSummary {
+  const record = asRecord(value, "a package summary");
+  const id = requireString(record, "id", "a package summary");
+  const source = parsePackageSource(record.source, "a package summary");
+  if (record.version !== null && typeof record.version !== "string") {
+    throw new Error("a package summary's version is a string or null");
+  }
+  return { id, source, version: record.version };
+}
+
+export interface ListPackagesResult {
+  readonly packages: readonly PackageSummary[];
+}
+
+export function parseListPackagesResult(value: unknown): ListPackagesResult {
+  const record = asRecord(value, "a listPackages result");
+  if (!Array.isArray(record.packages)) {
+    throw new Error("a listPackages result carries an array of packages");
+  }
+  return { packages: record.packages.map(parsePackageSummary) };
+}
+
+export function serializeListPackagesResult(result: ListPackagesResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/list-presence.ts

@@ -0,0 +1,64 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireNonNegativeInteger,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a listPresence input";
+
+export interface ListPresenceInput {
+  readonly operation: "listPresence";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseListPresenceInput(value: unknown): ListPresenceInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listPresence", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "listPresence", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeListPresenceInput(input: ListPresenceInput): string {
+  return JSON.stringify(input);
+}
+
+export interface PresenceBeatSummary {
+  readonly sid: string;
+  readonly shortId: string;
+  readonly lastBeat: number;
+  readonly ageMs: number;
+}
+
+function parsePresenceBeatSummary(value: unknown): PresenceBeatSummary {
+  const record = asRecord(value, "a presence beat");
+  const sid = requireString(record, "sid", "a presence beat");
+  const shortId = requireString(record, "shortId", "a presence beat");
+  const lastBeat = requireNonNegativeInteger(record, "lastBeat", "a presence beat");
+  const ageMs = requireNonNegativeInteger(record, "ageMs", "a presence beat");
+  return { sid, shortId, lastBeat, ageMs };
+}
+
+export interface ListPresenceResult {
+  readonly name: string;
+  readonly now: number;
+  readonly beats: readonly PresenceBeatSummary[];
+}
+
+export function parseListPresenceResult(value: unknown): ListPresenceResult {
+  const record = asRecord(value, "a listPresence result");
+  const name = requireString(record, "name", "a listPresence result");
+  const now = requireNonNegativeInteger(record, "now", "a listPresence result");
+  if (!Array.isArray(record.beats)) {
+    throw new Error("a listPresence result carries an array of beats");
+  }
+  return { name, now, beats: record.beats.map(parsePresenceBeatSummary) };
+}
+
+export function serializeListPresenceResult(result: ListPresenceResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/list-quick-actions.ts

@@ -0,0 +1,60 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  requireOperation,
+  requirePositiveInteger,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a listQuickActions input";
+
+export interface ListQuickActionsInput {
+  readonly operation: "listQuickActions";
+  readonly protocol: ProtocolVersion;
+}
+
+export function parseListQuickActionsInput(value: unknown): ListQuickActionsInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listQuickActions", NOUN);
+  requireProtocol(record, NOUN);
+  return { operation: "listQuickActions", protocol: PROTOCOL_VERSION };
+}
+
+export function serializeListQuickActionsInput(input: ListQuickActionsInput): string {
+  return JSON.stringify(input);
+}
+
+export interface QuickActionSummary {
+  readonly id: number;
+  readonly icon: string;
+  readonly label: string;
+  readonly prompt: string;
+  readonly createdAt: string;
+}
+
+function parseQuickActionSummary(value: unknown): QuickActionSummary {
+  const record = asRecord(value, "a quick-action summary");
+  const id = requirePositiveInteger(record, "id", "a quick-action summary");
+  const icon = requireString(record, "icon", "a quick-action summary");
+  const label = requireString(record, "label", "a quick-action summary");
+  const prompt = requireString(record, "prompt", "a quick-action summary");
+  const createdAt = requireString(record, "createdAt", "a quick-action summary");
+  return { id, icon, label, prompt, createdAt };
+}
+
+export interface ListQuickActionsResult {
+  readonly actions: readonly QuickActionSummary[];
+}
+
+export function parseListQuickActionsResult(value: unknown): ListQuickActionsResult {
+  const record = asRecord(value, "a listQuickActions result");
+  if (!Array.isArray(record.actions)) {
+    throw new Error("a listQuickActions result carries an array of actions");
+  }
+  return { actions: record.actions.map(parseQuickActionSummary) };
+}
+
+export function serializeListQuickActionsResult(result: ListQuickActionsResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/list-records.ts

@@ -0,0 +1,55 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { parseAppRecord, type AppRecord } from "./app-record";
+import {
+  asRecord,
+  optionalPositiveInteger,
+  optionalString,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a listRecords input";
+
+export interface ListRecordsInput {
+  readonly operation: "listRecords";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+  readonly limit?: number;
+  readonly action?: string;
+}
+
+export function parseListRecordsInput(value: unknown): ListRecordsInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listRecords", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  const limit = optionalPositiveInteger(record, "limit", NOUN);
+  const action = optionalString(record, "action", NOUN);
+  return {
+    operation: "listRecords",
+    protocol: PROTOCOL_VERSION,
+    name,
+    ...(limit !== undefined ? { limit } : {}),
+    ...(action !== undefined ? { action } : {}),
+  };
+}
+
+export function serializeListRecordsInput(input: ListRecordsInput): string {
+  return JSON.stringify(input);
+}
+
+export interface ListRecordsResult {
+  readonly records: readonly AppRecord[];
+}
+
+export function parseListRecordsResult(value: unknown): ListRecordsResult {
+  const record = asRecord(value, "a listRecords result");
+  if (!Array.isArray(record.records))
+    throw new Error("a listRecords result carries an array of records");
+  return { records: record.records.map(parseAppRecord) };
+}
+
+export function serializeListRecordsResult(result: ListRecordsResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/list-route-logs.ts

@@ -0,0 +1,98 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import { isLogTag, parseLogLine, serializeLogLine, type LogLine, type LogTag } from "./log-line";
+import {
+  asRecord,
+  optionalPositiveInteger,
+  optionalString,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a listRouteLogs input";
+
+/** How many routes one answer carries, and the ceiling a caller may ask for. A route's log is
+ * read whole to answer, so the bound is what keeps the question cheap on a daemon serving many. */
+export const ROUTE_LOGS_LIMIT = 50;
+export const ROUTE_LOGS_LIMIT_MAX = 200;
+
+export interface ListRouteLogsInput {
+  readonly operation: "listRouteLogs";
+  readonly protocol: ProtocolVersion;
+  /** The tag every answered route's log carries. */
+  readonly tag: LogTag;
+  readonly limit: number;
+  readonly since?: string;
+}
+
+export function parseListRouteLogsInput(value: unknown): ListRouteLogsInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listRouteLogs", NOUN);
+  requireProtocol(record, NOUN);
+  const tag = requireString(record, "tag", NOUN);
+  if (!isLogTag(tag)) throw new Error(`${NOUN}'s tag is one the protocol defines`);
+  const limit = optionalPositiveInteger(record, "limit", NOUN);
+  if (limit !== undefined && limit > ROUTE_LOGS_LIMIT_MAX)
+    throw new Error(`${NOUN}'s limit is at most ${ROUTE_LOGS_LIMIT_MAX}`);
+  const since = optionalString(record, "since", NOUN);
+  if (since !== undefined && Number.isNaN(Date.parse(since)))
+    throw new Error(`${NOUN}'s since is an ISO timestamp`);
+  return {
+    operation: "listRouteLogs",
+    protocol: PROTOCOL_VERSION,
+    tag,
+    limit: limit ?? ROUTE_LOGS_LIMIT,
+    ...(since !== undefined ? { since } : {}),
+  };
+}
+
+export function serializeListRouteLogsInput(input: ListRouteLogsInput): string {
+  return JSON.stringify({
+    operation: input.operation,
+    protocol: input.protocol,
+    tag: input.tag,
+    ...(input.limit !== ROUTE_LOGS_LIMIT ? { limit: input.limit } : {}),
+    ...(input.since !== undefined ? { since: input.since } : {}),
+  });
+}
+
+/** One route that carries the tag, and the newest line it carries it on, whole. */
+export interface RouteLogSummary {
+  readonly name: string;
+  readonly last: LogLine;
+}
+
+export interface ListRouteLogsResult {
+  /** Newest line first, ties broken by route name. */
+  readonly routes: readonly RouteLogSummary[];
+  /** True when the limit cut routes that carry the tag. What was cut carries an older line
+   * than what was returned. */
+  readonly truncated: boolean;
+}
+
+function parseRouteLogSummary(value: unknown): RouteLogSummary {
+  const record = asRecord(value, "a route log summary");
+  return {
+    name: requireString(record, "name", "a route log summary"),
+    last: parseLogLine(record.last),
+  };
+}
+
+export function parseListRouteLogsResult(value: unknown): ListRouteLogsResult {
+  const record = asRecord(value, "a listRouteLogs result");
+  if (!Array.isArray(record.routes))
+    throw new Error("a listRouteLogs result carries an array of routes");
+  if (typeof record.truncated !== "boolean")
+    throw new Error("a listRouteLogs result says whether routes were cut");
+  return { routes: record.routes.map(parseRouteLogSummary), truncated: record.truncated };
+}
+
+export function serializeListRouteLogsResult(result: ListRouteLogsResult): string {
+  return JSON.stringify({
+    routes: result.routes.map((route): unknown => ({
+      name: route.name,
+      last: JSON.parse(serializeLogLine(route.last)),
+    })),
+    truncated: result.truncated,
+  });
+}

package/src/operations/list-routes.ts

@@ -0,0 +1,101 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalBoolean,
+  optionalPositiveInteger,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+import { parseRouteRefusal, type RouteRefusal } from "../payloads/refusal";
+import { parseAppReadiness, type AppReadiness } from "../readiness";
+import { parseDeclaration, type Declaration } from "./declaration";
+
+const NOUN = "a listRoutes input";
+
+export interface ListRoutesInput {
+  readonly operation: "listRoutes";
+  readonly protocol: ProtocolVersion;
+  readonly liveOnly?: boolean;
+  readonly includeArchived?: boolean;
+  readonly limit?: number;
+}
+
+export function parseListRoutesInput(value: unknown): ListRoutesInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listRoutes", NOUN);
+  requireProtocol(record, NOUN);
+  const liveOnly = optionalBoolean(record, "liveOnly", NOUN);
+  const includeArchived = optionalBoolean(record, "includeArchived", NOUN);
+  const limit = optionalPositiveInteger(record, "limit", NOUN);
+  return {
+    operation: "listRoutes",
+    protocol: PROTOCOL_VERSION,
+    ...(liveOnly !== undefined ? { liveOnly } : {}),
+    ...(includeArchived !== undefined ? { includeArchived } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+  };
+}
+
+export function serializeListRoutesInput(input: ListRoutesInput): string {
+  return JSON.stringify(input);
+}
+
+export interface RouteSummary {
+  readonly name: string;
+  readonly dir: string;
+  readonly url: string;
+  /** The supervisor's process truth: a pid this daemon is tracking right now. */
+  readonly live: boolean;
+  readonly archived: boolean;
+  /** What the route's page has reported about its own rendering. A live route whose page never
+   * painted reads live true and readiness silent. */
+  readonly readiness: AppReadiness;
+  /** What the route declares about its setup. Absent for a route that declares nothing, so a
+   * reader sees the difference between an undeclared app and one declared standalone. */
+  readonly declaration?: Declaration;
+  /** Present when the route is not live because the supervisor gave up restarting it. A reboot
+   * clears it. */
+  readonly refusal?: RouteRefusal;
+}
+
+function parseRouteSummary(value: unknown): RouteSummary {
+  const record = asRecord(value, "a route summary");
+  const name = requireString(record, "name", "a route summary");
+  const dir = requireString(record, "dir", "a route summary");
+  const url = requireString(record, "url", "a route summary");
+  if (typeof record.live !== "boolean")
+    throw new Error("a route summary states whether the route is live");
+  if (typeof record.archived !== "boolean")
+    throw new Error("a route summary states whether the route is archived");
+  if (!("readiness" in record)) throw new Error("a route summary carries a readiness");
+  const declared = "declaration" in record && record.declaration !== undefined;
+  const refusal = record.refusal === undefined ? undefined : parseRouteRefusal(record.refusal);
+  return {
+    name,
+    dir,
+    url,
+    live: record.live,
+    archived: record.archived,
+    readiness: parseAppReadiness(record.readiness),
+    ...(declared
+      ? { declaration: parseDeclaration(record.declaration, "a route summary's declaration") }
+      : {}),
+    ...(refusal !== undefined ? { refusal } : {}),
+  };
+}
+
+export interface ListRoutesResult {
+  readonly routes: readonly RouteSummary[];
+}
+
+export function parseListRoutesResult(value: unknown): ListRoutesResult {
+  const record = asRecord(value, "a listRoutes result");
+  if (!Array.isArray(record.routes))
+    throw new Error("a listRoutes result carries an array of routes");
+  return { routes: record.routes.map(parseRouteSummary) };
+}
+
+export function serializeListRoutesResult(result: ListRoutesResult): string {
+  return JSON.stringify(result);
+}

package/src/operations/list-subscribers.ts

@@ -0,0 +1,75 @@
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../version";
+import {
+  asRecord,
+  optionalString,
+  requireNonNegativeInteger,
+  requireOperation,
+  requireProtocol,
+  requireString,
+} from "./parse-helpers";
+
+const NOUN = "a listSubscribers input";
+
+export interface ListSubscribersInput {
+  readonly operation: "listSubscribers";
+  readonly protocol: ProtocolVersion;
+  readonly name: string;
+}
+
+export function parseListSubscribersInput(value: unknown): ListSubscribersInput {
+  const record = asRecord(value, NOUN);
+  requireOperation(record, "listSubscribers", NOUN);
+  requireProtocol(record, NOUN);
+  const name = requireString(record, "name", NOUN);
+  return { operation: "listSubscribers", protocol: PROTOCOL_VERSION, name };
+}
+
+export function serializeListSubscribersInput(input: ListSubscribersInput): string {
+  return JSON.stringify(input);
+}
+
+export interface SubscriberSummary {
+  readonly sid: string;
+  readonly shortId: string;
+  /** The session's self-chosen name (subscribe's `as`, session_names), when it ever set one. */
+  readonly as?: string;
+  /** The directory the session launched from (session_dirs), when the daemon has observed one. */
+  readonly launchDir?: string;
+  readonly updatedAt: string;
+}
+
+function parseSubscriberSummary(value: unknown): SubscriberSummary {
+  const record = asRecord(value, "a subscriber summary");
+  const sid = requireString(record, "sid", "a subscriber summary");
+  const shortId = requireString(record, "shortId", "a subscriber summary");
+  const as = optionalString(record, "as", "a subscriber summary");
+  const launchDir = optionalString(record, "launchDir", "a subscriber summary");
+  const updatedAt = requireString(record, "updatedAt", "a subscriber summary");
+  return {
+    sid,
+    shortId,
+    ...(as !== undefined ? { as } : {}),
+    ...(launchDir !== undefined ? { launchDir } : {}),
+    updatedAt,
+  };
+}
+
+export interface ListSubscribersResult {
+  readonly name: string;
+  readonly count: number;
+  readonly subscribers: readonly SubscriberSummary[];
+}
+
+export function parseListSubscribersResult(value: unknown): ListSubscribersResult {
+  const record = asRecord(value, "a listSubscribers result");
+  const name = requireString(record, "name", "a listSubscribers result");
+  const count = requireNonNegativeInteger(record, "count", "a listSubscribers result");
+  if (!Array.isArray(record.subscribers)) {
+    throw new Error("a listSubscribers result carries an array of subscribers");
+  }
+  return { name, count, subscribers: record.subscribers.map(parseSubscriberSummary) };
+}
+
+export function serializeListSubscribersResult(result: ListSubscribersResult): string {
+  return JSON.stringify(result);
+}