@polycore/runner 0.1.0

package/README.md

@@ -0,0 +1,261 @@
+# @polycore/runner
+
+The Polycore **runner** executes governed, read-only-constrained connectors
+against a customer's datastores. It runs in the **customer's own
+infrastructure**, holds scoped credentials read from the customer's own secret
+store, and connects **outbound** to the Polycore control plane (a persistent
+WebSocket it dials out; no inbound port).
+
+One runner belongs to **one organization** and serves **one or more projects**
+(the customer's products/systems). Each project carries its own environments,
+credentials, customer-authored actions, and optional agent-context document;
+the runner advertises all of it per project when it joins the control plane.
+Whether a customer runs one runner for all products or one per product is
+purely a deployment choice; the config shape is the same.
+
+It ships the **Firestore read connectors**, loads customer-authored **actions**,
+and can be driven either by the control plane (`runner connect`) or by hand via
+the local CLI harness. See `internal-docs/architecture.md` and
+`internal-docs/mvp-plan.md`.
+
+## Connectors
+
+A connector is a generic, read-only transport: the caller supplies the
+query/path at request time. All connectors are `read` (Lane 1): they exist
+because they are mutation-incapable, which is what lets them run with no
+approval.
+
+| Capability                  | Args                                       | Returns                            |
+| --------------------------- | ------------------------------------------ | ---------------------------------- |
+| `firestore.query`           | `{ collection, where?, orderBy?, limit? }` | array of `{ id, data }`            |
+| `firestore.get`             | `{ collection, id }`                       | `{ id, data }` or `null`           |
+| `firestore.count`           | `{ collection, where? }`                   | `number` (server-side aggregation) |
+| `firestore.listCollections` | `{}`                                       | array of collection ids            |
+
+`where` clauses are `{ field, op, value }` where `op` is a Firestore filter
+operator (`==`, `!=`, `<`, `<=`, `>`, `>=`, `array-contains`,
+`array-contains-any`, `in`, `not-in`).
+
+## Read-only safety (two layers)
+
+- **Layer 1: IAM.** The credential carries `roles/datastore.viewer`; GCP
+  rejects any write at the API boundary. (The Admin SDK bypasses Firestore
+  Security Rules, so the IAM role, not rules, is what enforces read-only.)
+  This is true whether the credential is a downloaded key (dev) or the
+  runtime service account picked up via Application Default Credentials (prod).
+- **Layer 2: this code.** The connectors only ever call read methods.
+
+## Setup: create a read-only service account (per environment)
+
+With one Firebase project per environment, create a read-only SA in each and
+download its key. Example for `dev` (replace `PROJECT_ID` with your own):
+
+```sh
+PROJECT_ID=my-app-dev
+
+gcloud iam service-accounts create polycore-readonly \
+  --project "$PROJECT_ID" \
+  --display-name "Polycore read-only runner"
+
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+  --member "serviceAccount:polycore-readonly@$PROJECT_ID.iam.gserviceaccount.com" \
+  --role "roles/datastore.viewer"
+
+gcloud iam service-accounts keys create ./readonly-dev.json \
+  --project "$PROJECT_ID" \
+  --iam-account "polycore-readonly@$PROJECT_ID.iam.gserviceaccount.com"
+```
+
+> Keep the key file out of git. When the runner later runs inside GCP, prefer
+> workload identity over a downloaded key.
+
+## Config
+
+Create a `runner.config.json` (path passed via `--config` or the
+`POLYCORE_RUNNER_CONFIG` env var). The top level is a **projects map**: one
+entry per product/system this runner serves. Environments are namespaced per
+connector family (`firestore` today; SQL/HTTP families as they land), so one
+environment can carry credentials for several backends:
+
+```json
+{
+  "projects": {
+    "alpha": {
+      "defaultEnvironment": "dev",
+      "environments": {
+        "dev": {
+          "firestore": {
+            "projectId": "alpha-dev",
+            "serviceAccountKeyPath": "/absolute/path/to/alpha-readonly-dev.json"
+          }
+        },
+        "prod": {
+          "firestore": { "projectId": "alpha-prod" }
+        }
+      },
+      "actionsDir": "/absolute/path/to/alpha/polycore-actions",
+      "contextFile": "/absolute/path/to/alpha/schema.md"
+    },
+    "beta": {
+      "environments": {
+        "prod": {
+          "firestore": { "projectId": "beta-prod" }
+        }
+      }
+    }
+  },
+  "controlPlane": {
+    "url": "wss://cp.example.com/runner",
+    "runnerId": "<uuid from enrollment>",
+    "joinToken": "<from enrollment>",
+    "signingSecret": "<from enrollment>"
+  }
+}
+```
+
+Per-project extras:
+
+- `actionsDir`: customer-authored actions for that project, loaded alongside
+  the built-in connectors.
+- `secrets`: per-project action secret values (falls back to the runner-level
+  `secrets` map, then `process.env`). These never reach the control plane.
+- `context` / `contextFile`: an agent-grounding document (e.g. the product's
+  database schema). Advertised at join and injected into the agent's system
+  prompt when this project is in scope. Re-read on every (re)connect.
+
+The `controlPlane` block is optional; without it the local harness still works.
+
+## Run the harness
+
+```sh
+# list available capabilities across all projects
+pnpm --filter @polycore/runner runner list --config ./runner.config.json
+
+# "how many users?" against alpha's dev
+pnpm --filter @polycore/runner runner firestore.count \
+  --project alpha --env dev --args '{"collection":"users"}' \
+  --config ./runner.config.json
+
+# the first five users (sole project → --project can be omitted)
+pnpm --filter @polycore/runner runner firestore.query \
+  --env dev --args '{"collection":"users","limit":5}' \
+  --config ./runner.config.json
+
+# hold the outbound control-plane link (production mode)
+pnpm --filter @polycore/runner runner connect --config ./runner.config.json
+```
+
+Logs go to stderr; the JSON result goes to stdout (pipeable).
+
+> `serviceAccountKeyPath` is **optional**. Omit it to use 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
+> ships. Provide a key path only for local/off-GCP use.
+
+## Deploy to Cloud Run
+
+The runner ships as a container that dials the control plane outbound, so it
+needs **no inbound port**: `min-instances=1` keeps the link warm. The image is
+built from the repo root; config and secrets arrive entirely via env vars, so
+nothing is baked in.
+
+### 1. Build and push the image
+
+Cloud Run runs `linux/amd64`:
+
+```sh
+docker build --platform linux/amd64 \
+  -f packages/runner/Dockerfile \
+  -t REGION-docker.pkg.dev/PROJECT_ID/polycore/runner:latest .
+
+docker push REGION-docker.pkg.dev/PROJECT_ID/polycore/runner:latest
+```
+
+### 2. Give the runtime service account read-only datastore access
+
+In prod there is **no key file**: the runner uses Application Default
+Credentials, i.e. the Cloud Run runtime service account. Grant it the same
+read-only role the key would have carried:
+
+```sh
+gcloud projects add-iam-policy-binding PROJECT_ID \
+  --member "serviceAccount:RUNTIME_SA@PROJECT_ID.iam.gserviceaccount.com" \
+  --role "roles/datastore.viewer"
+```
+
+### 3. Store the outbound-link secrets in Secret Manager
+
+The join token and signing secret are shared at enrollment and must never be
+baked into the image:
+
+```sh
+printf '%s' "$JOIN_TOKEN"     | gcloud secrets create polycore-join-token     --data-file=-
+printf '%s' "$SIGNING_SECRET" | gcloud secrets create polycore-signing-secret --data-file=-
+```
+
+### 4. Deploy
+
+Non-secret config is plain env vars; the two secrets come from Secret Manager.
+`POLYCORE_PROJECTS` is the projects map (same shape as the config file's
+`projects` field). With ADC each environment needs only its `projectId` (no
+`serviceAccountKeyPath`):
+
+```sh
+gcloud run deploy polycore-runner \
+  --image REGION-docker.pkg.dev/PROJECT_ID/polycore/runner:latest \
+  --no-allow-unauthenticated \
+  --min-instances 1 --max-instances 1 --no-cpu-throttling \
+  --service-account RUNTIME_SA@PROJECT_ID.iam.gserviceaccount.com \
+  --set-env-vars 'POLYCORE_CONTROL_PLANE_URL=wss://control.example.com/runner,POLYCORE_RUNNER_ID=<uuid-from-enrollment>' \
+  --set-env-vars 'POLYCORE_PROJECTS={"alpha":{"environments":{"prod":{"firestore":{"projectId":"PROJECT_ID"}}}}}' \
+  --set-secrets 'POLYCORE_JOIN_TOKEN=polycore-join-token:latest,POLYCORE_SIGNING_SECRET=polycore-signing-secret:latest'
+```
+
+> **Cloud Run caveats (learned in prod).**
+>
+> - **The URL needs the `/runner` WS path**: `wss://<host>/runner`, not just the
+>   host. The control plane only upgrades WebSocket connections on that path.
+> - **`--no-cpu-throttling` is mandatory.** The runner is an outbound-only worker
+>   that never serves requests, so by default Cloud Run would throttle its CPU to
+>   ~0 between (non-existent) requests and freeze its heartbeat/reconnect timers.
+>   CPU-always-allocated keeps the link and the self-healing alive. `max-instances 1`
+>   keeps the single WS pinned to one instance.
+> - **A request-driven host needs the container to listen on `$PORT`.** The
+>   `connect` command starts a tiny liveness HTTP server when `PORT` is set (it is
+>   a no-op locally) purely so Cloud Run's startup probe passes; the real work is
+>   still the outbound WS. It opens the port **before** loading/compiling actions,
+>   so a cold boot is healthy in <1s. If the port only opened after the
+>   (esbuild-backed) action load, a slow boot would blow the startup-probe
+>   deadline and Cloud Run would kill + restart the instance in a ~4-minute loop.
+> - **Redeploy ordering: control plane first, then bounce the runner.** A live
+>   runner's long-lived WS pins it to the control-plane instance it dialed, and
+>   that open connection keeps the old (draining) instance alive, so after a
+>   control-plane redeploy the runner keeps talking to the stale instance while
+>   new HTTP traffic hits the fresh revision's empty hub. Roll a new runner
+>   revision (any config change, e.g. bump a nonce env var) after deploying the
+>   control plane so it reconnects to the current revision.
+
+| Env var                      | Required | Notes                                                                     |
+| ---------------------------- | :------: | ------------------------------------------------------------------------- |
+| `POLYCORE_PROJECTS`          |    ✓     | JSON projects map (same shape as the config file's `projects`)            |
+| `POLYCORE_CONTROL_PLANE_URL` |    ✓     | `wss://…` control-plane WebSocket                                         |
+| `POLYCORE_RUNNER_ID`         |    ✓     | This runner's enrolled id (a uuid)                                        |
+| `POLYCORE_JOIN_TOKEN`        |    ✓     | Enrollment secret (Secret Manager)                                        |
+| `POLYCORE_SIGNING_SECRET`    |    ✓     | HMAC secret to verify dispatch envelopes (Secret Manager)                 |
+| `POLYCORE_SECRETS`           |          | JSON map of runner-level action secrets (per-project `secrets` still win) |
+
+When `POLYCORE_PROJECTS` is set and no `--config` file is given, the runner
+builds its config from these vars; a missing/invalid one fails loud at startup.
+Per-project settings that reference local files (`actionsDir`, `contextFile`,
+`serviceAccountKeyPath`) point at paths baked into or mounted on the container.
+
+## Tests
+
+```sh
+pnpm --filter @polycore/runner test
+```
+
+Unit tests cover the registry's validate-then-dispatch path, the read-only
+invariant, and config parsing. Live-Firestore tests are intentionally not part
+of the default run (they require real credentials); use the harness above to
+verify against a live project.

package/bin/polycore-runner.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Launcher for the runner CLI. The runner is shipped as TypeScript source and
+// executed by tsx (it must also load customer-authored `.ts` actions at
+// runtime), so this thin bin re-execs Node with tsx registered as a loader and
+// hands off to `src/cli.ts`. Consumers run `polycore-runner connect` (or drive
+// the local harness, e.g. `polycore-runner list`).
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const cli = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
+
+const child = spawn(
+  process.execPath,
+  ["--import", "tsx", cli, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+
+child.on("exit", (code, signal) => {
+  if (signal !== null) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@polycore/runner",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Polycore runner: executes governed, read-only-constrained connectors against a customer's datastores. Runs in the customer's own infrastructure; holds scoped credentials and connects outbound to the control plane.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "polycore-runner": "./bin/polycore-runner.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "firebase-admin": "^14.0.0",
+    "tsx": "4.21.0",
+    "ws": "8.18.3",
+    "zod": "4.4.3",
+    "@polycore/protocol": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.2",
+    "@types/ws": "8.18.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "runner": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/action.ts

@@ -0,0 +1,68 @@
+import type { z } from "zod";
+
+/**
+ * Blessed **actions** are the second execution lane: durable, customer-authored
+ * operations (e.g. "customer 360", "refund user") that live in the customer's
+ * own repo and are loaded by the runner. Unlike connectors — generic,
+ * read-only transports that ship inside the runner — an action is a named,
+ * parameterized unit of work with its own input/output contract.
+ *
+ * This is the same authoring shape as the desktop SDK's `defineAction`, minus
+ * the UI/page concern: a Slack/agent caller consumes the structured `output`,
+ * not a React page. An action reaches into the customer's own backend (their
+ * Firestore, Stripe, internal APIs) using `secrets` the runner resolves from
+ * its environment — the credential never leaves the runner's host.
+ */
+
+export type ActionEffect = "read" | "mutate";
+
+/** Human-facing progress sink, mirroring the desktop SDK's `ctx.log`. */
+export interface ActionLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+}
+
+export interface ActionRunContext<Input> {
+  /** Caller-supplied, schema-validated input. */
+  readonly input: Input;
+  /** Declared secrets, resolved by the runner from its environment. */
+  readonly secrets: Readonly<Record<string, string>>;
+  /** The environment to run against (e.g. "dev"), from the dispatch. */
+  readonly environment: string;
+  readonly log: ActionLogger;
+}
+
+export interface Action<Input = unknown, Output = unknown> {
+  readonly title: string;
+  readonly description: string;
+  readonly tags?: readonly string[];
+  /**
+   * Hazard class. Defaults to `mutate` — the safe default, since an
+   * unclassified operation must be treated as dangerous and routed through
+   * the approval gate. Declare `read` for idempotent, side-effect-free work.
+   */
+  readonly effect?: ActionEffect;
+  readonly input: z.ZodType<Input>;
+  readonly output: z.ZodType<Output>;
+  /** Secret keys this action needs, mapped to a human description. */
+  readonly secrets?: Readonly<Record<string, string>>;
+  run(ctx: ActionRunContext<Input>): Promise<Output> | Output;
+}
+
+/**
+ * Identity helper that pins an action's I/O types. Authored modules
+ * `export default defineAction({ … })`; the loader injects the folder-path id.
+ */
+export function defineAction<Input, Output>(
+  spec: Action<Input, Output>,
+): Action<Input, Output> {
+  return spec;
+}
+
+/** A loaded action plus the folder-path id the loader derived for it. */
+export interface LoadedAction {
+  readonly id: string;
+  readonly action: Action;
+}

package/src/cli.ts

@@ -0,0 +1,198 @@
+import { createServer } from "node:http";
+import process from "node:process";
+
+import {
+  buildRunnerConfigFromEnv,
+  hasEnvConfig,
+  loadRunnerConfig,
+  resolveEnvironment,
+  resolveProject,
+  RUNNER_CONFIG_ENV,
+  RUNNER_PROJECTS_ENV,
+  type RunnerConfig,
+} from "./config.js";
+import { RunnerClient } from "./connect.js";
+import { buildProjectRegistries } from "./index.js";
+
+/**
+ * Local harness for driving connectors by hand, the dogfood entry point
+ * before the control-plane connection exists. Logs go to stderr; the JSON
+ * result goes to stdout, so output is pipeable.
+ *
+ *   pnpm --filter @polycore/runner runner list --config ./runner.config.json
+ *   pnpm --filter @polycore/runner runner firestore.count \
+ *     --project alpha --env dev --args '{"collection":"users"}' \
+ *     --config ./runner.config.json
+ */
+
+interface ParsedArgs {
+  readonly positional: string[];
+  readonly flags: Map<string, string>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const positional: string[] = [];
+  const flags = new Map<string, string>();
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === undefined) continue;
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+    const eq = token.indexOf("=");
+    if (eq !== -1) {
+      flags.set(token.slice(2, eq), token.slice(eq + 1));
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      flags.set(key, next);
+      i += 1;
+    } else {
+      flags.set(key, "true");
+    }
+  }
+  return { positional, flags };
+}
+
+function printUsage(): void {
+  process.stderr.write(
+    [
+      "polycore runner, local connector harness",
+      "",
+      "Usage:",
+      "  runner list [--config <path>]",
+      "  runner connect [--config <path>]",
+      "  runner <capability> [--project <slug>] [--env <name>] [--args <json>] [--config <path>]",
+      "",
+      "Flags:",
+      "  --project project to run against (default: the sole configured project)",
+      "  --env     environment to run against (default: project default or sole env)",
+      "  --args    JSON object of connector arguments (default: {})",
+      `  --config  path to runner config (default: $${RUNNER_CONFIG_ENV})`,
+      "",
+      "Examples:",
+      '  runner firestore.count --project alpha --env dev --args \'{"collection":"users"}\'',
+      '  runner firestore.query --env dev --args \'{"collection":"users","limit":5}\'',
+      "",
+    ].join("\n"),
+  );
+}
+
+/**
+ * Pick the config source: an explicit file (flag or `POLYCORE_RUNNER_CONFIG`)
+ * for local use, else an env-driven config when the container path is set
+ * (`POLYCORE_PROJECTS` present).
+ */
+function resolveConfig(configFlag: string | undefined): RunnerConfig {
+  const configPath = configFlag ?? process.env[RUNNER_CONFIG_ENV];
+  if (configPath !== undefined) return loadRunnerConfig(configPath);
+  if (hasEnvConfig(process.env)) return buildRunnerConfigFromEnv(process.env);
+  throw new Error(
+    `No runner config. Pass --config <path>, set ${RUNNER_CONFIG_ENV}, ` +
+      `or provide an env-driven config (${RUNNER_PROJECTS_ENV} + control-plane vars).`,
+  );
+}
+
+/**
+ * Request-driven hosts (Cloud Run, etc.) require the container to listen on
+ * `$PORT` and pass a startup probe before routing it traffic. The runner is an
+ * outbound-only WebSocket worker that never serves requests, so we run a tiny
+ * liveness server alongside the connection purely to satisfy the probe. No-op
+ * when `PORT` is unset, local CLI use is unaffected.
+ */
+function maybeStartHealthServer(log: (message: string) => void): void {
+  const port = process.env["PORT"];
+  if (port === undefined || port.length === 0) return;
+  const server = createServer((_req, res) => {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: true, role: "runner" }));
+  });
+  server.listen(Number(port), () => {
+    log(`Liveness server listening on :${port}`);
+  });
+}
+
+async function main(): Promise<void> {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const command = positional[0];
+
+  if (command === undefined || command === "help") {
+    printUsage();
+    return;
+  }
+
+  // For the long-running `connect` worker, open the liveness port *before* the
+  // (potentially slow) action compilation in `buildProjectRegistries`, so a
+  // request-driven host's startup probe passes in <1s regardless of how long
+  // loading takes. Otherwise a cold boot can exceed the probe deadline and get
+  // the instance killed + restarted in a loop.
+  if (command === "connect") {
+    maybeStartHealthServer((message) => process.stderr.write(`${message}\n`));
+  }
+
+  const config = resolveConfig(flags.get("config"));
+  const registries = await buildProjectRegistries(config);
+
+  if (command === "list") {
+    for (const [slug, registry] of registries) {
+      for (const capability of registry.list()) {
+        process.stdout.write(
+          `[${slug}] ${capability.name}  [${capability.kind}/${capability.effect}]  ${capability.description}\n`,
+        );
+      }
+    }
+    return;
+  }
+
+  if (command === "connect") {
+    const { controlPlane } = config;
+    if (controlPlane === undefined) {
+      throw new Error(
+        'No "controlPlane" block in the runner config; cannot connect.',
+      );
+    }
+    const client = new RunnerClient({
+      controlPlane,
+      config,
+      registries,
+      log: (message) => process.stderr.write(`${message}\n`),
+    });
+    await client.connect();
+    process.stderr.write("Awaiting dispatches… (Ctrl+C to stop)\n");
+    await new Promise<never>(() => undefined);
+    return;
+  }
+
+  const { slug, project } = resolveProject(config, flags.get("project"));
+  const registry = registries.get(slug);
+  if (!registry) throw new Error(`No registry for project "${slug}".`);
+  const { name: environment, env } = resolveEnvironment(
+    project,
+    flags.get("env"),
+  );
+
+  const argsJson = flags.get("args");
+  const rawArgs: unknown = argsJson === undefined ? {} : JSON.parse(argsJson);
+
+  const dispatched = await registry.dispatch(command, rawArgs, {
+    project: slug,
+    environment,
+    env,
+    log: (message) => process.stderr.write(`${message}\n`),
+  });
+
+  process.stdout.write(`${JSON.stringify(dispatched.result, null, 2)}\n`);
+}
+
+void (async () => {
+  try {
+    await main();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}\n`);
+    process.exitCode = 1;
+  }
+})();