@polycore/runner 0.1.0

package/src/config.ts

@@ -0,0 +1,289 @@
+import { readFileSync } from "node:fs";
+
+import { z } from "zod";
+
+/**
+ * Firestore credentials for one environment of one project: the GCP project
+ * plus the path to a **read-only** service-account key
+ * (`roles/datastore.viewer`), the Layer-1 credential that the datastore
+ * itself guarantees cannot mutate.
+ */
+export const FirestoreEnvironmentSchema = z.object({
+  /** GCP project id the environment maps to. */
+  projectId: z.string().min(1),
+  /**
+   * Absolute path to the read-only service-account JSON key for this
+   * environment. The key never leaves the runner's host. **Optional**: when
+   * omitted, the connector falls back to Application Default Credentials, the
+   * idiomatic path when the runner runs inside GCP, where the runtime service
+   * account supplies the (read-only) credential and no key file is shipped.
+   */
+  serviceAccountKeyPath: z.string().min(1).optional(),
+});
+
+export type FirestoreEnvironment = z.infer<typeof FirestoreEnvironmentSchema>;
+
+/**
+ * One environment of one project, namespaced per connector family so a
+ * single environment can carry credentials for several backends (Firestore
+ * today; SQL, HTTP APIs like Stripe/RevenueCat, etc. as they land). A
+ * built-in connector is advertised for a project only when at least one of
+ * the project's environments configures its family.
+ */
+export const EnvironmentConfigSchema = z.object({
+  firestore: FirestoreEnvironmentSchema.optional(),
+});
+
+export type EnvironmentConfig = z.infer<typeof EnvironmentConfigSchema>;
+
+/**
+ * One project (product/system) this runner serves, e.g. a company's two
+ * products are two projects. Each project has its own environments and
+ * credentials, its own customer-authored actions, and optionally an
+ * agent-context document (e.g. its database schema) advertised to the
+ * control plane.
+ */
+export const ProjectConfigSchema = z
+  .object({
+    /** Environment name (`dev`, `staging`, `prod`, …) → its credentials. */
+    environments: z
+      .record(z.string(), EnvironmentConfigSchema)
+      .refine((envs) => Object.keys(envs).length > 0, {
+        message: "At least one environment must be configured.",
+      }),
+    /** Local-CLI default for `runner <capability>` runs. The control plane
+     * keeps its own per-project default for front-door asks. */
+    defaultEnvironment: z.string().min(1).optional(),
+    /**
+     * Absolute path to a directory of customer-authored actions for this
+     * project (one folder per action, each with an `action.ts`). Loaded and
+     * served alongside the built-in connectors.
+     */
+    actionsDir: z.string().min(1).optional(),
+    /**
+     * Secret values for this project's actions, keyed by the names actions
+     * declare in `secrets`. Missing keys fall back to the runner-level
+     * `secrets`, then `process.env`.
+     */
+    secrets: z.record(z.string(), z.string()).optional(),
+    /**
+     * Agent grounding for this project (markdown/plain text, e.g. the
+     * product's database schema). Advertised to the control plane at
+     * enrollment and injected into the agent's system prompt when this
+     * project is in scope. Use `contextFile` for anything longer than a line.
+     */
+    context: z.string().optional(),
+    /** Absolute path to a file holding the agent context (wins over `context`). */
+    contextFile: z.string().min(1).optional(),
+  })
+  .refine((p) => p.context === undefined || p.contextFile === undefined, {
+    message: 'Set "context" or "contextFile", not both.',
+  });
+
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+
+/**
+ * How the runner reaches the control plane. Provisioned at enrollment; the
+ * `signingSecret` is shared out-of-band (never sent on the wire) so the
+ * runner can verify dispatch envelopes.
+ */
+export const ControlPlaneConfigSchema = z.object({
+  /** Control-plane WebSocket URL (`ws://…` locally, `wss://…` in prod). */
+  url: z.string().min(1),
+  /** This runner's id (`rnr_...` from the enroll response). */
+  runnerId: z.string().min(1),
+  /** One-time-ish enrollment secret presented on join. */
+  joinToken: z.string().min(1),
+  /** Shared HMAC secret used to verify dispatch envelopes. */
+  signingSecret: z.string().min(1),
+});
+
+export type ControlPlaneConfig = z.infer<typeof ControlPlaneConfigSchema>;
+
+/**
+ * The runner's configuration: which projects it serves (each with its own
+ * environments/credentials/actions), and optionally how to reach the
+ * control plane. One runner serves 1..N projects of ONE organization;
+ * data separation across products is per-project config, not per-process.
+ */
+export const RunnerConfigSchema = z.object({
+  projects: z
+    .record(z.string(), ProjectConfigSchema)
+    .refine((projects) => Object.keys(projects).length > 0, {
+      message: "At least one project must be configured.",
+    }),
+  controlPlane: ControlPlaneConfigSchema.optional(),
+  /**
+   * Runner-level secret fallback for action secrets, shared by every
+   * project. Per-project `secrets` win. Missing keys fall back to
+   * `process.env`. These never reach the control plane.
+   */
+  secrets: z.record(z.string(), z.string()).optional(),
+});
+
+export type RunnerConfig = z.infer<typeof RunnerConfigSchema>;
+
+/** Env var the CLI falls back to when no explicit config path is given. */
+export const RUNNER_CONFIG_ENV = "POLYCORE_RUNNER_CONFIG";
+
+/** Parse and validate a runner config from an already-read string. */
+export function parseRunnerConfig(json: string): RunnerConfig {
+  const data: unknown = JSON.parse(json);
+  return RunnerConfigSchema.parse(data);
+}
+
+/** Read and validate a runner config from a JSON file path. */
+export function loadRunnerConfig(path: string): RunnerConfig {
+  return parseRunnerConfig(readFileSync(path, "utf8"));
+}
+
+/** Env var carrying the projects map (JSON) for env-driven config. */
+export const RUNNER_PROJECTS_ENV = "POLYCORE_PROJECTS";
+
+/**
+ * Whether the environment is set up to build a config without a file, used
+ * by the CLI to choose between the local file path and the container path.
+ */
+export function hasEnvConfig(source: NodeJS.ProcessEnv): boolean {
+  return typeof source[RUNNER_PROJECTS_ENV] === "string";
+}
+
+/**
+ * Build a runner config entirely from environment variables, the production
+ * path when the runner runs in a container. The non-secret structure
+ * (`POLYCORE_PROJECTS`) and the outbound link's secrets
+ * (`POLYCORE_JOIN_TOKEN`, `POLYCORE_SIGNING_SECRET`, injected from a secret
+ * manager) all arrive as env vars, so nothing is written to disk. The
+ * assembled object is validated by the same schema as a file config, so a
+ * missing/invalid field fails loud at startup.
+ *
+ * This is a *pure* function over the passed env map, the CLI entry point is
+ * the only place that reads `process.env` and hands it in.
+ */
+export function buildRunnerConfigFromEnv(
+  source: NodeJS.ProcessEnv,
+): RunnerConfig {
+  const projectsRaw = source[RUNNER_PROJECTS_ENV];
+  if (projectsRaw === undefined) {
+    throw new Error(
+      `${RUNNER_PROJECTS_ENV} is required to build a config from the environment.`,
+    );
+  }
+  // Include the control-plane block only when at least one of its vars is set.
+  // Omitting it entirely keeps `controlPlane` validly optional (so `runner list`
+  // can load actions in a container without enrollment creds), while a *partial*
+  // block stays included so the schema pinpoints the missing field.
+  const cpUrl = source["POLYCORE_CONTROL_PLANE_URL"];
+  const cpRunnerId = source["POLYCORE_RUNNER_ID"];
+  const cpJoinToken = source["POLYCORE_JOIN_TOKEN"];
+  const cpSigningSecret = source["POLYCORE_SIGNING_SECRET"];
+  const hasAnyControlPlane =
+    cpUrl !== undefined ||
+    cpRunnerId !== undefined ||
+    cpJoinToken !== undefined ||
+    cpSigningSecret !== undefined;
+
+  const candidate = {
+    projects: parseJsonEnv(projectsRaw, RUNNER_PROJECTS_ENV),
+    ...(hasAnyControlPlane
+      ? {
+          controlPlane: {
+            url: cpUrl,
+            runnerId: cpRunnerId,
+            joinToken: cpJoinToken,
+            signingSecret: cpSigningSecret,
+          },
+        }
+      : {}),
+    ...(source["POLYCORE_SECRETS"] === undefined
+      ? {}
+      : {
+          secrets: parseJsonEnv(source["POLYCORE_SECRETS"], "POLYCORE_SECRETS"),
+        }),
+  };
+  return RunnerConfigSchema.parse(candidate);
+}
+
+function parseJsonEnv(raw: string, name: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${name} must be valid JSON: ${message}`, { cause: error });
+  }
+}
+
+/**
+ * Resolve the project to run against: an explicit choice, else the only
+ * project if there is exactly one. Throws with the valid names listed so
+ * callers self-correct.
+ */
+export function resolveProject(
+  config: RunnerConfig,
+  requested?: string,
+): { slug: string; project: ProjectConfig } {
+  const slugs = Object.keys(config.projects);
+  const chosen = requested ?? (slugs.length === 1 ? slugs[0] : undefined);
+  if (chosen === undefined) {
+    throw new Error(
+      `No project specified. Available: ${slugs.map((s) => `"${s}"`).join(", ")}.`,
+    );
+  }
+  const project = config.projects[chosen];
+  if (!project) {
+    throw new Error(
+      `Unknown project "${chosen}". Available: ${slugs
+        .map((s) => `"${s}"`)
+        .join(", ")}.`,
+    );
+  }
+  return { slug: chosen, project };
+}
+
+/**
+ * Resolve the environment to run against within a project: an explicit
+ * choice, else the project's default, else the only environment if there is
+ * exactly one. Throws with the valid names listed so callers self-correct.
+ */
+export function resolveEnvironment(
+  project: ProjectConfig,
+  requested?: string,
+): { name: string; env: EnvironmentConfig } {
+  const names = Object.keys(project.environments);
+  const chosen =
+    requested ??
+    project.defaultEnvironment ??
+    (names.length === 1 ? names[0] : undefined);
+
+  if (chosen === undefined) {
+    throw new Error(
+      `No environment specified and no default set. Available: ${names
+        .map((n) => `"${n}"`)
+        .join(", ")}.`,
+    );
+  }
+
+  const env = project.environments[chosen];
+  if (!env) {
+    throw new Error(
+      `Unknown environment "${chosen}". Available: ${names
+        .map((n) => `"${n}"`)
+        .join(", ")}.`,
+    );
+  }
+  return { name: chosen, env };
+}
+
+/**
+ * The agent-context document a project advertises: the inline `context`
+ * string, or the contents of `contextFile`. Read lazily (at enrollment) so
+ * a re-connect picks up edits without a restart.
+ */
+export function resolveProjectContext(
+  project: ProjectConfig,
+): string | undefined {
+  if (project.contextFile !== undefined) {
+    return readFileSync(project.contextFile, "utf8");
+  }
+  return project.context;
+}

package/src/connect.ts

@@ -0,0 +1,363 @@
+import {
+  type ConnectorDescriptor,
+  type ControlToRunner,
+  type DispatchMessage,
+  parseControlToRunner,
+  type ProjectAdvertisement,
+  PROTOCOL_VERSION,
+  type RunnerToControl,
+  serializeMessage,
+  verifyEnvelope,
+} from "@polycore/protocol";
+import WebSocket from "ws";
+import { z } from "zod";
+
+import type { ControlPlaneConfig, RunnerConfig } from "./config.js";
+import { resolveProjectContext } from "./config.js";
+import type { ConnectorRegistry } from "./connector.js";
+
+/** Describe a registry's connectors for enrollment (Zod → JSON Schema). */
+export function describeConnectors(
+  registry: ConnectorRegistry,
+): ConnectorDescriptor[] {
+  return registry.list().map((capability) => ({
+    name: capability.name,
+    description: capability.description,
+    effect: capability.effect,
+    kind: capability.kind,
+    params: z.toJSONSchema(capability.params),
+  }));
+}
+
+/**
+ * Build the per-project advertisement the join message carries: each
+ * project's environments, its capability catalog, and its agent context.
+ */
+export function describeProjects(
+  config: RunnerConfig,
+  registries: ReadonlyMap<string, ConnectorRegistry>,
+): ProjectAdvertisement[] {
+  return Object.entries(config.projects).map(([slug, project]) => {
+    const registry = registries.get(slug);
+    if (!registry) {
+      throw new Error(`No registry built for project "${slug}".`);
+    }
+    const context = resolveProjectContext(project);
+    return {
+      slug,
+      environments: Object.keys(project.environments),
+      connectors: describeConnectors(registry),
+      ...(context === undefined ? {} : { context }),
+    };
+  });
+}
+
+/** Exponential-backoff schedule for re-dialing a dropped control plane. */
+export interface ReconnectOptions {
+  /** Delay before the first reconnect attempt. */
+  readonly initialDelayMs: number;
+  /** Ceiling the backoff is clamped to. */
+  readonly maxDelayMs: number;
+  /** Multiplier applied per consecutive failed attempt. */
+  readonly factor: number;
+}
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+const DEFAULT_PONG_TIMEOUT_MS = 10_000;
+const DEFAULT_RECONNECT: ReconnectOptions = {
+  initialDelayMs: 1_000,
+  maxDelayMs: 30_000,
+  factor: 2,
+};
+
+export interface RunnerClientOptions {
+  readonly controlPlane: ControlPlaneConfig;
+  readonly config: RunnerConfig;
+  /** One registry per project slug (see `buildProjectRegistries`). */
+  readonly registries: ReadonlyMap<string, ConnectorRegistry>;
+  readonly log?: (message: string) => void;
+  /** Interval between heartbeat pings once enrolled (default 30s). */
+  readonly heartbeatIntervalMs?: number;
+  /** How long to wait for a pong before declaring the link dead (default 10s). */
+  readonly pongTimeoutMs?: number;
+  /**
+   * Exponential-backoff reconnect schedule, or `false` to disable reconnect
+   * entirely (used by tests that drive a single connection by hand).
+   */
+  readonly reconnect?: ReconnectOptions | false;
+}
+
+/**
+ * The runner's outbound link to the control plane. It dials *out* (no
+ * inbound ports), enrolls with its join token, then serves signed dispatch
+ * envelopes: verify the signature, run the connector, return the result.
+ *
+ * The link is self-healing: a WebSocket-level ping/pong heartbeat detects a
+ * silently dead control plane, and any drop triggers an exponential-backoff
+ * reconnect that re-enrolls from scratch. `connect()` resolves on the *first*
+ * successful enrollment; the loop keeps the runner online after that until
+ * {@link close} is called or the join is permanently rejected.
+ */
+export class RunnerClient {
+  private socket: WebSocket | undefined;
+  private readonly log: (message: string) => void;
+
+  private readonly heartbeatIntervalMs: number;
+  private readonly pongTimeoutMs: number;
+  private readonly reconnect: ReconnectOptions | false;
+
+  /** Set by {@link close}; suppresses any further reconnect. */
+  private stopped = false;
+  /** A `rejected` join is a config error, never worth retrying. */
+  private terminal = false;
+  private joined = false;
+  private reconnectAttempts = 0;
+
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  private pongTimer: ReturnType<typeof setTimeout> | undefined;
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  private awaitingPong = false;
+
+  private connectPromise: Promise<void> | undefined;
+  private firstConnectResolve: (() => void) | undefined;
+  private firstConnectReject: ((error: Error) => void) | undefined;
+
+  constructor(private readonly opts: RunnerClientOptions) {
+    this.log = opts.log ?? (() => undefined);
+    this.heartbeatIntervalMs =
+      opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.pongTimeoutMs = opts.pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT_MS;
+    this.reconnect = opts.reconnect ?? DEFAULT_RECONNECT;
+  }
+
+  /**
+   * Dial the control plane and enroll. Resolves once enrollment first
+   * succeeds; rejects only on a permanent rejection (bad token / unknown
+   * runner). Transient network failures are retried with backoff, so a
+   * control plane that is merely down at startup is awaited, not failed.
+   */
+  public connect(): Promise<void> {
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = new Promise<void>((resolve, reject) => {
+      this.firstConnectResolve = resolve;
+      this.firstConnectReject = reject;
+    });
+    this.openConnection();
+    return this.connectPromise;
+  }
+
+  public close(): void {
+    this.stopped = true;
+    this.stopHeartbeat();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    this.socket?.close();
+  }
+
+  private openConnection(): void {
+    if (this.stopped || this.terminal) return;
+    const { url } = this.opts.controlPlane;
+    const socket = new WebSocket(url);
+    this.socket = socket;
+    this.joined = false;
+
+    socket.on("open", () => {
+      this.log(`Connected to ${url}; enrolling…`);
+      this.send({
+        type: "join",
+        protocolVersion: PROTOCOL_VERSION,
+        runnerId: this.opts.controlPlane.runnerId,
+        joinToken: this.opts.controlPlane.joinToken,
+        projects: describeProjects(this.opts.config, this.opts.registries),
+      });
+    });
+
+    socket.on("message", (data: WebSocket.RawData) => {
+      this.onMessage(socket, data);
+    });
+
+    socket.on("error", (error) => {
+      // ws always emits `close` after `error`; reconnect is driven there so
+      // we don't double-schedule. Just surface the cause.
+      this.log(`Socket error: ${describe(error)}`);
+    });
+
+    socket.on("close", () => {
+      this.onClose();
+    });
+  }
+
+  private onMessage(socket: WebSocket, data: WebSocket.RawData): void {
+    let message: ControlToRunner;
+    try {
+      message = parseControlToRunner(rawToString(data));
+    } catch (error) {
+      this.log(`Ignoring unparseable message: ${describe(error)}`);
+      return;
+    }
+    if (message.type === "joined") {
+      this.joined = true;
+      this.reconnectAttempts = 0;
+      this.log(`Enrolled (session ${message.sessionId}).`);
+      this.startHeartbeat();
+      this.firstConnectResolve?.();
+      this.firstConnectResolve = undefined;
+      this.firstConnectReject = undefined;
+      return;
+    }
+    if (message.type === "rejected") {
+      this.terminal = true;
+      const error = new Error(`Control plane rejected join: ${message.reason}`);
+      this.firstConnectReject?.(error);
+      this.firstConnectReject = undefined;
+      this.firstConnectResolve = undefined;
+      socket.close();
+      return;
+    }
+    if (message.type === "pong") {
+      this.onPong();
+      return;
+    }
+    void this.handleDispatch(message);
+  }
+
+  private onClose(): void {
+    this.stopHeartbeat();
+    if (this.joined) this.log("Connection closed.");
+    this.joined = false;
+    if (this.stopped || this.terminal) return;
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnect === false) return;
+    const { initialDelayMs, maxDelayMs, factor } = this.reconnect;
+    const delay = Math.min(
+      maxDelayMs,
+      initialDelayMs * factor ** this.reconnectAttempts,
+    );
+    this.reconnectAttempts += 1;
+    this.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})…`);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.openConnection();
+    }, delay);
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      const socket = this.socket;
+      if (socket?.readyState !== WebSocket.OPEN) return;
+      // A still-outstanding ping means the previous pong never came back:
+      // the link is silently dead. Force it closed so reconnect kicks in.
+      if (this.awaitingPong) {
+        this.log("Heartbeat timed out; terminating dead connection.");
+        socket.terminate();
+        return;
+      }
+      this.awaitingPong = true;
+      this.pongTimer = setTimeout(() => {
+        if (!this.awaitingPong) return;
+        this.log("Heartbeat timed out; terminating dead connection.");
+        this.socket?.terminate();
+      }, this.pongTimeoutMs);
+      // Application-level ping (a real message), NOT the WebSocket protocol's
+      // ping frame: a proxy in front of the control plane (Cloud Run) answers
+      // protocol pings itself, masking a dead backend. Only a message the
+      // control plane application must echo proves the link is truly alive.
+      this.send({ type: "ping" });
+    }, this.heartbeatIntervalMs);
+  }
+
+  private onPong(): void {
+    this.awaitingPong = false;
+    if (this.pongTimer) {
+      clearTimeout(this.pongTimer);
+      this.pongTimer = undefined;
+    }
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    if (this.pongTimer) clearTimeout(this.pongTimer);
+    this.heartbeatTimer = undefined;
+    this.pongTimer = undefined;
+    this.awaitingPong = false;
+  }
+
+  private async handleDispatch(message: DispatchMessage): Promise<void> {
+    const { envelope, sig } = message;
+    if (!verifyEnvelope(envelope, sig, this.opts.controlPlane.signingSecret)) {
+      this.log(`Rejected dispatch ${envelope.id}: bad signature.`);
+      this.send({
+        type: "result",
+        id: envelope.id,
+        ok: false,
+        error: { message: "envelope signature verification failed" },
+      });
+      return;
+    }
+    try {
+      const registry = this.opts.registries.get(envelope.project);
+      const project = this.opts.config.projects[envelope.project];
+      if (!registry || !project) {
+        throw new Error(
+          `Unknown project "${envelope.project}". Configured: ${[
+            ...this.opts.registries.keys(),
+          ]
+            .map((s) => `"${s}"`)
+            .join(", ")}.`,
+        );
+      }
+      const env = project.environments[envelope.environment];
+      if (!env) {
+        throw new Error(
+          `Unknown environment "${envelope.environment}" for project "${envelope.project}". ` +
+            `Configured: ${Object.keys(project.environments)
+              .map((n) => `"${n}"`)
+              .join(", ")}.`,
+        );
+      }
+      const dispatched = await registry.dispatch(
+        envelope.capability,
+        envelope.args,
+        {
+          project: envelope.project,
+          environment: envelope.environment,
+          env,
+          log: (m) => this.log(m),
+        },
+      );
+      this.send({
+        type: "result",
+        id: envelope.id,
+        ok: true,
+        result: dispatched.result,
+      });
+    } catch (error) {
+      this.send({
+        type: "result",
+        id: envelope.id,
+        ok: false,
+        error: { message: describe(error) },
+      });
+    }
+  }
+
+  private send(message: RunnerToControl): void {
+    this.socket?.send(serializeMessage(message));
+  }
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function rawToString(data: WebSocket.RawData): string {
+  if (Buffer.isBuffer(data)) return data.toString("utf8");
+  if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
+  return Buffer.from(data).toString("utf8");
+}