@frockbot/protocol 0.0.0 → 0.1.1

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@frockbot/protocol",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/protocol"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeExternalAuthorizationUrl,
+  isAgentCommand,
+  isAgentEvent,
+  isPromptRequest,
+} from "./index";
+
+describe("protocol guards", () => {
+  test("accepts a non-empty prompt", () => {
+    expect(isPromptRequest({ runId: "run-1", text: "Hello" })).toBe(true);
+    expect(
+      isAgentCommand({ type: "prompt", runId: "run-1", text: "Hello" }),
+    ).toBe(true);
+  });
+
+  test("rejects empty or malformed prompts", () => {
+    expect(isPromptRequest({ runId: "run-1", text: "  " })).toBe(false);
+    expect(isAgentCommand({ type: "prompt", runId: "", text: "Hello" })).toBe(
+      false,
+    );
+  });
+
+  test("checks streamed event fields", () => {
+    expect(
+      isAgentEvent({ type: "text-delta", runId: "run-1", text: "Hi" }),
+    ).toBe(true);
+    expect(isAgentEvent({ type: "text-delta", runId: "run-1" })).toBe(false);
+  });
+
+  test("admits only bounded HTTPS authorization URLs", () => {
+    expect(
+      decodeExternalAuthorizationUrl("https://connect.example/authorize"),
+    ).toBe("https://connect.example/authorize");
+    for (const value of [
+      "http://connect.example/authorize",
+      "https://user:secret@connect.example/authorize",
+      "https://connect.example/authorize#token",
+      `https://connect.example/${"a".repeat(4_096)}`,
+    ]) {
+      expect(() => decodeExternalAuthorizationUrl(value)).toThrow(
+        "invalid external authorization URL",
+      );
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,154 @@
+export interface PromptRequest {
+  runId: string;
+  text: string;
+}
+
+export type AgentCommand =
+  | { type: "prompt"; runId: string; text: string }
+  | { type: "abort"; runId: string }
+  | { type: "shutdown" };
+
+export interface AgentModelSummary {
+  provider: string;
+  id: string;
+}
+
+export type AgentEvent =
+  | { type: "worker-ready"; model?: AgentModelSummary }
+  | { type: "run-started"; runId: string }
+  | { type: "text-delta"; runId: string; text: string }
+  | {
+      type: "tool-start";
+      runId: string;
+      toolCallId: string;
+      name: string;
+      input: unknown;
+    }
+  | {
+      type: "tool-end";
+      runId: string;
+      toolCallId: string;
+      name: string;
+      text: string;
+      isError: boolean;
+    }
+  | { type: "settled"; runId: string; reason: "completed" | "aborted" }
+  | { type: "error"; runId?: string; phase: "startup" | "run"; message: string }
+  | { type: "worker-exit"; code: number | null };
+
+export interface PromptResponse {
+  accepted: boolean;
+  error?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function isPromptRequest(value: unknown): value is PromptRequest {
+  return (
+    isRecord(value) &&
+    typeof value.runId === "string" &&
+    value.runId.length > 0 &&
+    typeof value.text === "string" &&
+    value.text.trim().length > 0
+  );
+}
+
+export function isAgentCommand(value: unknown): value is AgentCommand {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  if (value.type === "shutdown") return true;
+  if (value.type === "abort")
+    return typeof value.runId === "string" && value.runId.length > 0;
+  return (
+    value.type === "prompt" &&
+    typeof value.runId === "string" &&
+    value.runId.length > 0 &&
+    typeof value.text === "string" &&
+    value.text.trim().length > 0
+  );
+}
+
+export function isAgentEvent(value: unknown): value is AgentEvent {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  switch (value.type) {
+    case "worker-ready":
+      return value.model === undefined || isRecord(value.model);
+    case "worker-exit":
+      return value.code === null || typeof value.code === "number";
+    case "error":
+      return (
+        typeof value.message === "string" &&
+        (value.phase === "startup" || value.phase === "run")
+      );
+    case "run-started":
+      return typeof value.runId === "string";
+    case "text-delta":
+      return typeof value.runId === "string" && typeof value.text === "string";
+    case "tool-start":
+      return (
+        typeof value.runId === "string" &&
+        typeof value.toolCallId === "string" &&
+        typeof value.name === "string"
+      );
+    case "tool-end":
+      return (
+        typeof value.runId === "string" &&
+        typeof value.toolCallId === "string" &&
+        typeof value.name === "string" &&
+        typeof value.text === "string" &&
+        typeof value.isError === "boolean"
+      );
+    case "settled":
+      return (
+        typeof value.runId === "string" &&
+        (value.reason === "completed" || value.reason === "aborted")
+      );
+    default:
+      return false;
+  }
+}
+
+const MAX_EXTERNAL_AUTHORIZATION_URL_BYTES = 4_096;
+const EXTERNAL_AUTHORIZATION_URL_UNSAFE_CHARACTER =
+  /[\u0000-\u0020\u007f-\u009f]|\s/u;
+const HTTPS_AUTHORIZATION_PREFIX = /^https:\/\/[^/?#]/iu;
+const DNS_HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/iu;
+
+function validAuthorizationHostname(hostname: string): boolean {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return true;
+  const normalized = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+  return (
+    normalized.length > 0 &&
+    normalized.length <= 253 &&
+    normalized.split(".").every((label) => DNS_HOST_LABEL.test(label))
+  );
+}
+
+export function decodeExternalAuthorizationUrl(value: unknown): string {
+  if (
+    typeof value !== "string" ||
+    !HTTPS_AUTHORIZATION_PREFIX.test(value) ||
+    EXTERNAL_AUTHORIZATION_URL_UNSAFE_CHARACTER.test(value) ||
+    value.includes("\\") ||
+    value.includes("#") ||
+    new TextEncoder().encode(value).byteLength >
+      MAX_EXTERNAL_AUTHORIZATION_URL_BYTES
+  ) {
+    throw new Error("invalid external authorization URL");
+  }
+  try {
+    const url = new URL(value);
+    if (
+      url.protocol !== "https:" ||
+      url.username ||
+      url.password ||
+      !validAuthorizationHostname(url.hostname)
+    ) {
+      throw new Error();
+    }
+  } catch {
+    throw new Error("invalid external authorization URL");
+  }
+  return value;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/protocol
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.