@frockbot/protocol 0.2.5 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/protocol",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "exports": {

package/src/bot-state-channel.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeBotStateChannelFrameV1,
+  decodeBotStateCursorV1,
+} from "./index.js";
+
+describe("Bot-state channel protocol", () => {
+  test("decodes each exact version 1 frame", () => {
+    expect(
+      decodeBotStateChannelFrameV1(
+        JSON.stringify({
+          schemaVersion: 1,
+          type: "state/event",
+          cursor: "12",
+          topic: "computer",
+        }),
+      ),
+    ).toEqual({
+      schemaVersion: 1,
+      type: "state/event",
+      cursor: "12",
+      topic: "computer",
+    });
+    expect(
+      decodeBotStateChannelFrameV1(
+        JSON.stringify({
+          schemaVersion: 1,
+          type: "state/reset",
+          cursor: "4",
+          reason: "gap",
+        }),
+      ),
+    ).toMatchObject({ type: "state/reset", reason: "gap" });
+    expect(
+      decodeBotStateChannelFrameV1(
+        JSON.stringify({
+          schemaVersion: 1,
+          type: "state/ready",
+          cursor: "0",
+        }),
+      ),
+    ).toMatchObject({ type: "state/ready", cursor: "0" });
+  });
+
+  test("rejects non-canonical cursors and protocol extensions", () => {
+    for (const cursor of ["", "01", "-1", "1.5", "9007199254740992"]) {
+      expect(() => decodeBotStateCursorV1(cursor)).toThrow();
+    }
+    expect(() =>
+      decodeBotStateChannelFrameV1(
+        JSON.stringify({
+          schemaVersion: 1,
+          type: "state/ready",
+          cursor: "0",
+          extra: true,
+        }),
+      ),
+    ).toThrow();
+  });
+});

package/src/index.ts

@@ -3,6 +3,131 @@ export interface PromptRequest {
   text: string;
 }
 
+/**
+ * Version 1 of the Bot-state observer protocol. Frames are invalidations, not
+ * authority: a client that receives one re-reads the owning HTTP projection.
+ */
+export const BOT_STATE_CHANNEL_VERSION = 1 as const;
+
+export type BotStateTopicV1 = "computer";
+
+export type BotStateChannelFrameV1 =
+  | {
+      schemaVersion: 1;
+      type: "state/event";
+      cursor: string;
+      topic: BotStateTopicV1;
+    }
+  | {
+      schemaVersion: 1;
+      type: "state/reset";
+      cursor: string;
+      reason: "initial" | "gap" | "cursor-ahead";
+    }
+  | {
+      schemaVersion: 1;
+      type: "state/ready";
+      cursor: string;
+    };
+
+const BOT_STATE_CURSOR_PATTERN = /^(?:0|[1-9][0-9]{0,15})$/u;
+
+export function decodeBotStateCursorV1(value: unknown): string {
+  if (
+    typeof value !== "string" ||
+    !BOT_STATE_CURSOR_PATTERN.test(value) ||
+    !Number.isSafeInteger(Number(value))
+  ) {
+    throw new Error("invalid Bot-state cursor");
+  }
+  return value;
+}
+
+function exactObject(
+  value: unknown,
+  required: readonly string[],
+): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("invalid Bot-state frame");
+  }
+  const record = value as Record<string, unknown>;
+  const allowed = new Set(required);
+  if (
+    !required.every((key) => Object.hasOwn(record, key)) ||
+    Object.keys(record).some((key) => !allowed.has(key))
+  ) {
+    throw new Error("invalid Bot-state frame");
+  }
+  return record;
+}
+
+export function decodeBotStateChannelFrameV1(
+  value: unknown,
+): BotStateChannelFrameV1 {
+  if (typeof value !== "string" || value.length > 4_096) {
+    throw new Error("invalid Bot-state frame");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("invalid Bot-state frame");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("invalid Bot-state frame");
+  }
+  const type = (parsed as Record<string, unknown>).type;
+  if (type === "state/event") {
+    const frame = exactObject(parsed, [
+      "schemaVersion",
+      "type",
+      "cursor",
+      "topic",
+    ]);
+    if (frame.schemaVersion !== 1 || frame.topic !== "computer") {
+      throw new Error("invalid Bot-state frame");
+    }
+    return {
+      schemaVersion: 1,
+      type,
+      cursor: decodeBotStateCursorV1(frame.cursor),
+      topic: frame.topic,
+    };
+  }
+  if (type === "state/reset") {
+    const frame = exactObject(parsed, [
+      "schemaVersion",
+      "type",
+      "cursor",
+      "reason",
+    ]);
+    if (
+      frame.schemaVersion !== 1 ||
+      (frame.reason !== "initial" &&
+        frame.reason !== "gap" &&
+        frame.reason !== "cursor-ahead")
+    ) {
+      throw new Error("invalid Bot-state frame");
+    }
+    return {
+      schemaVersion: 1,
+      type,
+      cursor: decodeBotStateCursorV1(frame.cursor),
+      reason: frame.reason,
+    };
+  }
+  if (type === "state/ready") {
+    const frame = exactObject(parsed, ["schemaVersion", "type", "cursor"]);
+    if (frame.schemaVersion !== 1) throw new Error("invalid Bot-state frame");
+    return {
+      schemaVersion: 1,
+      type,
+      cursor: decodeBotStateCursorV1(frame.cursor),
+    };
+  }
+  throw new Error("invalid Bot-state frame");
+}
+
 export type AgentCommand =
   | { type: "prompt"; runId: string; text: string }
   | { type: "abort"; runId: string }