@polycore/protocol 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @polycore/protocol
+
+The wire contract between the Polycore **control plane** and a **runner**: the
+message schemas for the outbound WebSocket (join, dispatch, result, heartbeat,
+and the join accept/reject frames) and the signed-envelope helpers that let a
+runner verify a dispatch came from the control plane.
+
+It is pure: [`zod`](https://zod.dev) schemas plus `node:crypto` for the HMAC
+envelope, with no transport and no I/O. Both sides import it so a protocol
+change is a single source of truth. `PROTOCOL_VERSION` is bumped whenever the
+join/dispatch shape changes; a runner and control plane on different versions
+refuse to connect.
+
+This package is a dependency of [`@polycore/runner`](https://www.npmjs.com/package/@polycore/runner);
+you normally consume it transitively, not directly.
+
+## Exports
+
+- `PROTOCOL_VERSION` and the message schemas + parsers (`parseRunnerToControl`,
+  `parseControlToRunner`, `serializeMessage`).
+- The signed-envelope helpers for signing and verifying dispatch envelopes.
+
+See `internal-docs/architecture.md` in the Polycore repo for how the two halves
+connect.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@polycore/protocol",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Polycore control-plane and runner wire contract: message schemas and signed-envelope helpers. Pure (zod + node:crypto), no transport.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/envelope.ts

@@ -0,0 +1,77 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { z } from "zod";
+
+/**
+ * A unit of work the control plane dispatches to a runner. The control
+ * plane signs it (HMAC-SHA256) with the runner's provisioned signing
+ * secret; the runner verifies the signature before executing. The secret
+ * is shared out-of-band at enrollment and never travels on the wire, so a
+ * compromised channel cannot forge a dispatch.
+ */
+export const dispatchEnvelopeSchema = z.object({
+  /** Correlation id; the runner echoes it back on the result. */
+  id: z.string().min(1),
+  /** Project to run against (keyed into the runner's config). */
+  project: z.string().min(1),
+  /** Connector capability to run, e.g. `firestore.count`. */
+  capability: z.string().min(1),
+  /** Environment to run against (keyed into the project's config). */
+  environment: z.string().min(1),
+  /** Connector arguments (validated again by the connector itself). */
+  args: z.unknown(),
+  /** Issue time (epoch ms) for staleness checks and audit. */
+  issuedAt: z.number().int().nonnegative(),
+});
+
+export type DispatchEnvelope = z.infer<typeof dispatchEnvelopeSchema>;
+
+/**
+ * Deterministic JSON: object keys sorted recursively so both sides produce
+ * byte-identical input to the HMAC regardless of property insertion order.
+ */
+function stableStringify(value: unknown): string {
+  if (value === undefined) return "null";
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const obj = value as Record<string, unknown>;
+  const entries = Object.keys(obj)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`);
+  return `{${entries.join(",")}}`;
+}
+
+function canonical(envelope: DispatchEnvelope): string {
+  return stableStringify({
+    id: envelope.id,
+    project: envelope.project,
+    capability: envelope.capability,
+    environment: envelope.environment,
+    args: envelope.args ?? null,
+    issuedAt: envelope.issuedAt,
+  });
+}
+
+/** Sign an envelope, returning a hex HMAC-SHA256 signature. */
+export function signEnvelope(
+  envelope: DispatchEnvelope,
+  secret: string,
+): string {
+  return createHmac("sha256", secret).update(canonical(envelope)).digest("hex");
+}
+
+/** Constant-time verify an envelope's signature against the shared secret. */
+export function verifyEnvelope(
+  envelope: DispatchEnvelope,
+  signature: string,
+  secret: string,
+): boolean {
+  const expected = Buffer.from(signEnvelope(envelope, secret), "utf8");
+  const actual = Buffer.from(signature, "utf8");
+  if (expected.length !== actual.length) return false;
+  return timingSafeEqual(expected, actual);
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export type { DispatchEnvelope } from "./envelope.js";
+export {
+  dispatchEnvelopeSchema,
+  signEnvelope,
+  verifyEnvelope,
+} from "./envelope.js";
+export type {
+  ConnectorDescriptor,
+  ControlToRunner,
+  DispatchMessage,
+  JoinedMessage,
+  JoinMessage,
+  ProjectAdvertisement,
+  RejectedMessage,
+  ResultMessage,
+  RunnerToControl,
+} from "./messages.js";
+export {
+  connectorDescriptorSchema,
+  controlToRunnerSchema,
+  parseControlToRunner,
+  parseRunnerToControl,
+  projectAdvertisementSchema,
+  PROTOCOL_VERSION,
+  runnerToControlSchema,
+  serializeMessage,
+} from "./messages.js";

package/src/messages.ts

@@ -0,0 +1,150 @@
+import { z } from "zod";
+
+import { dispatchEnvelopeSchema } from "./envelope.js";
+
+/** Bumped on any breaking change to the wire messages. */
+export const PROTOCOL_VERSION = 3;
+
+/**
+ * What a runner advertises about one connector at enrollment, so the
+ * control plane (and the agent) know what's callable and how. `params` is
+ * a JSON Schema object describing the connector's arguments.
+ */
+export const connectorDescriptorSchema = z.object({
+  name: z.string().min(1),
+  description: z.string(),
+  effect: z.string(),
+  /** Whether this is a built-in connector or a customer-authored action. */
+  kind: z.enum(["connector", "action"]).default("connector"),
+  params: z.record(z.string(), z.unknown()),
+});
+
+export type ConnectorDescriptor = z.infer<typeof connectorDescriptorSchema>;
+
+/**
+ * What a runner advertises about one project it serves. A project is one
+ * product/system of the runner's organization; each carries its own
+ * environments, its own capability catalog (built-in connectors whose
+ * credentials are configured for it, plus its customer-authored actions),
+ * and optionally an agent-context document (e.g. the product's database
+ * schema) the control plane injects into the agent's system prompt when the
+ * project is in scope.
+ */
+export const projectAdvertisementSchema = z.object({
+  /** The project's slug, unique within the runner's organization. */
+  slug: z.string().min(1),
+  /** The environments this project can target (e.g. `["dev","prod"]`). */
+  environments: z.array(z.string().min(1)).min(1),
+  /** The capabilities callable on this project. */
+  connectors: z.array(connectorDescriptorSchema),
+  /** Optional agent grounding for this project (markdown/plain text). */
+  context: z.string().optional(),
+});
+
+export type ProjectAdvertisement = z.infer<typeof projectAdvertisementSchema>;
+
+// ---------------------------------------------------------------------------
+// Runner → Control
+// ---------------------------------------------------------------------------
+
+/** First message after the socket opens: the runner enrolls. */
+const joinSchema = z.object({
+  type: z.literal("join"),
+  protocolVersion: z.number().int(),
+  /** The runner's uuid, assigned at enrollment. */
+  runnerId: z.string().min(1),
+  joinToken: z.string().min(1),
+  /** The projects this runner serves, so the control plane can route. */
+  projects: z.array(projectAdvertisementSchema).min(1),
+});
+
+/** The result of a dispatched envelope, keyed by the envelope's id. */
+const resultSchema = z.object({
+  type: z.literal("result"),
+  id: z.string().min(1),
+  ok: z.boolean(),
+  result: z.unknown().optional(),
+  error: z.object({ message: z.string() }).optional(),
+});
+
+/**
+ * Application-level heartbeat. The WebSocket protocol's own ping/pong is
+ * answered by an intermediary proxy (e.g. Cloud Run's frontend) even after the
+ * backend instance is gone, so it can falsely report a dead link as healthy.
+ * This `ping` rides the same message channel as dispatches, so a missing
+ * {@link pongSchema} reply means the *application* path is dead, the only
+ * signal that reliably catches a proxy-masked half-open connection.
+ */
+const pingSchema = z.object({
+  type: z.literal("ping"),
+});
+
+export const runnerToControlSchema = z.discriminatedUnion("type", [
+  joinSchema,
+  resultSchema,
+  pingSchema,
+]);
+
+export type RunnerToControl = z.infer<typeof runnerToControlSchema>;
+export type JoinMessage = z.infer<typeof joinSchema>;
+export type ResultMessage = z.infer<typeof resultSchema>;
+export type PingMessage = z.infer<typeof pingSchema>;
+
+// ---------------------------------------------------------------------------
+// Control → Runner
+// ---------------------------------------------------------------------------
+
+/** Enrollment accepted. */
+const joinedSchema = z.object({
+  type: z.literal("joined"),
+  sessionId: z.string().min(1),
+});
+
+/** Enrollment refused (bad token, unknown runner, version mismatch). */
+const rejectedSchema = z.object({
+  type: z.literal("rejected"),
+  reason: z.string(),
+});
+
+/** A signed unit of work for the runner to execute. */
+const dispatchSchema = z.object({
+  type: z.literal("dispatch"),
+  envelope: dispatchEnvelopeSchema,
+  sig: z.string().min(1),
+});
+
+/** The control plane's reply to a runner {@link pingSchema} heartbeat. */
+const pongSchema = z.object({
+  type: z.literal("pong"),
+});
+
+export const controlToRunnerSchema = z.discriminatedUnion("type", [
+  joinedSchema,
+  rejectedSchema,
+  dispatchSchema,
+  pongSchema,
+]);
+
+export type ControlToRunner = z.infer<typeof controlToRunnerSchema>;
+export type JoinedMessage = z.infer<typeof joinedSchema>;
+export type RejectedMessage = z.infer<typeof rejectedSchema>;
+export type DispatchMessage = z.infer<typeof dispatchSchema>;
+export type PongMessage = z.infer<typeof pongSchema>;
+
+// ---------------------------------------------------------------------------
+// (de)serialization
+// ---------------------------------------------------------------------------
+
+export function serializeMessage(
+  message: RunnerToControl | ControlToRunner,
+): string {
+  return JSON.stringify(message);
+}
+
+export function parseRunnerToControl(raw: string): RunnerToControl {
+  return runnerToControlSchema.parse(JSON.parse(raw));
+}
+
+export function parseControlToRunner(raw: string): ControlToRunner {
+  return controlToRunnerSchema.parse(JSON.parse(raw));
+}