@polycore/runner 0.1.1 → 0.3.0

package/README.md

@@ -93,7 +93,6 @@ environment can carry credentials for several backends:
           "firestore": { "projectId": "alpha-prod" }
         }
       },
-      "actionsDir": "/absolute/path/to/alpha/polycore-actions",
       "contextFile": "/absolute/path/to/alpha/schema.md"
     },
     "beta": {
@@ -113,10 +112,16 @@ environment can carry credentials for several backends:
 }
 ```
 
+Actions are discovered by **convention**, not a config field: put a project's
+actions in an `actions/<slug>/` directory beside the config file, or — when the
+runner serves a single project — directly in `actions/`. They are loaded
+alongside the built-in connectors. (There is no `actionsDir` field.)
+
 Per-project extras:
 
-- `actionsDir`: customer-authored actions for that project, loaded alongside
-  the built-in connectors.
+- `defaultEnvironment`: the environment an unqualified ask targets. It is the
+  runner's local-CLI default AND is advertised to the control plane as the
+  front-door default. Must be one of the project's `environments`.
 - `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
@@ -246,8 +251,11 @@ gcloud run deploy polycore-runner \
 
 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`,
+Per-project settings that reference local files (`contextFile`,
 `serviceAccountKeyPath`) point at paths baked into or mounted on the container.
+Actions can only be discovered via the `actions/` convention beside a `--config`
+file, so an env-only config serves just the built-in connectors — prefer a
+committed `polycore.json` (loaded with `--config` / `POLYCORE_RUNNER_CONFIG`).
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycore/runner",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -30,7 +30,7 @@
     "tsx": "4.21.0",
     "ws": "8.18.3",
     "zod": "4.4.3",
-    "@polycore/protocol": "^0.1.0"
+    "@polycore/protocol": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "25.6.2",

package/src/cli.ts

@@ -1,10 +1,12 @@
 import { createServer } from "node:http";
+import { dirname } from "node:path";
 import process from "node:process";
 
 import {
   buildRunnerConfigFromEnv,
   hasEnvConfig,
   loadRunnerConfig,
+  overlayEnvSecrets,
   resolveEnvironment,
   resolveProject,
   RUNNER_CONFIG_ENV,
@@ -19,10 +21,10 @@ import { buildProjectRegistries } from "./index.js";
  * 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 list --config ./polycore.json
  *   pnpm --filter @polycore/runner runner firestore.count \
  *     --project alpha --env dev --args '{"collection":"users"}' \
- *     --config ./runner.config.json
+ *     --config ./polycore.json
  */
 
 interface ParsedArgs {
@@ -82,13 +84,21 @@ function printUsage(): void {
 }
 
 /**
- * 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).
+ * Pick the config source, in priority order:
+ *
+ * 1. An explicit config **file** (flag or `POLYCORE_RUNNER_CONFIG`). This is
+ *    the committed, code-as-source-of-truth path: the file declares the whole
+ *    structural surface (projects, environments, actions, context) with
+ *    portable relative paths, and any deploy-time secrets it omits
+ *    (`controlPlane` creds, runner-level `secrets`) are overlaid from env, so
+ *    the production container bakes in the file and injects only secrets.
+ * 2. Else a fully env-driven config (`POLYCORE_PROJECTS` present), the legacy
+ *    path where the whole structure arrives as env JSON.
  */
-function resolveConfig(configFlag: string | undefined): RunnerConfig {
-  const configPath = configFlag ?? process.env[RUNNER_CONFIG_ENV];
-  if (configPath !== undefined) return loadRunnerConfig(configPath);
+function resolveConfig(configPath: string | undefined): RunnerConfig {
+  if (configPath !== undefined) {
+    return overlayEnvSecrets(loadRunnerConfig(configPath), process.env);
+  }
   if (hasEnvConfig(process.env)) return buildRunnerConfigFromEnv(process.env);
   throw new Error(
     `No runner config. Pass --config <path>, set ${RUNNER_CONFIG_ENV}, ` +
@@ -133,8 +143,14 @@ async function main(): Promise<void> {
     maybeStartHealthServer((message) => process.stderr.write(`${message}\n`));
   }
 
-  const config = resolveConfig(flags.get("config"));
-  const registries = await buildProjectRegistries(config);
+  const configPath = flags.get("config") ?? process.env[RUNNER_CONFIG_ENV];
+  const config = resolveConfig(configPath);
+  // Actions are discovered from the `actions/` convention beside the config
+  // file; an env-driven config (no file) serves only the built-in connectors.
+  const registries = await buildProjectRegistries(
+    config,
+    configPath === undefined ? undefined : dirname(configPath),
+  );
 
   if (command === "list") {
     for (const [slug, registry] of registries) {

package/src/config.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
 
 import { z } from "zod";
 
@@ -51,15 +52,14 @@ export const ProjectConfigSchema = z
       .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.
+     * The environment an unqualified ask targets: the runner's local-CLI
+     * default AND the value advertised to the control plane, which uses it as
+     * the front-door default when a caller names no environment. One source of
+     * truth for "the default env of this project"; must be one of the
+     * `environments` keys to take effect.
      */
-    actionsDir: z.string().min(1).optional(),
+    defaultEnvironment: 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
@@ -82,6 +82,55 @@ export const ProjectConfigSchema = z
 
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 
+/**
+ * Resource caps a delegated workload runs under. Each field is an upper bound
+ * the runner enforces at the container boundary regardless of what the
+ * approved code requests; a workload may ask for less, never more.
+ */
+export const SandboxLimitsSchema = z.object({
+  /** CPU cores (fractional allowed), e.g. `1` or `0.5`. */
+  cpus: z.number().positive().optional(),
+  /** Memory ceiling in MiB. */
+  memoryMb: z.number().int().positive().optional(),
+  /** Wall-clock timeout in seconds; the container is killed past it. */
+  timeoutSeconds: z.number().int().positive().optional(),
+  /** Max process count inside the sandbox (fork-bomb guard). */
+  pids: z.number().int().positive().optional(),
+});
+
+export type SandboxLimits = z.infer<typeof SandboxLimitsSchema>;
+
+/**
+ * Enables the delegated-workload executor (`workload.execute`) on this runner.
+ * When present, the runner advertises a single generic capability that runs
+ * **human-approved** arbitrary code inside a disposable, OS-isolated container
+ * on the runner's own host. The container holds only the credentials the
+ * approved workload requested; it never sees the runner's other secrets.
+ *
+ * Absent means the runner serves only connectors + actions, exactly as before.
+ */
+export const SandboxConfigSchema = z.object({
+  /**
+   * Base container image the workload runs in. Must contain a Node runtime
+   * plus `tsx` on `PATH` (to run `.ts` entrypoints) and a package manager
+   * (`npm`) for workloads that install dependencies.
+   */
+  image: z.string().min(1),
+  /**
+   * OCI runtime that isolates each workload. Defaults to `runsc` (gVisor):
+   * syscall-level isolation that runs on any Linux VM with no nested
+   * virtualization. Set to `runc` only where gVisor is unavailable (weaker,
+   * shared-kernel isolation).
+   */
+  runtime: z.string().min(1).optional(),
+  /** Container CLI to invoke (default `docker`). */
+  cli: z.string().min(1).optional(),
+  /** Default/maximum resource limits applied to every workload. */
+  limits: SandboxLimitsSchema.optional(),
+});
+
+export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
+
 /**
  * How the runner reaches the control plane. Provisioned at enrollment; the
  * `signingSecret` is shared out-of-band (never sent on the wire) so the
@@ -119,6 +168,11 @@ export const RunnerConfigSchema = z.object({
    * `process.env`. These never reach the control plane.
    */
   secrets: z.record(z.string(), z.string()).optional(),
+  /**
+   * Opt-in delegated-workload execution (`workload.execute`). Absent leaves
+   * the runner serving only connectors + actions. See {@link SandboxConfigSchema}.
+   */
+  sandbox: SandboxConfigSchema.optional(),
 });
 
 export type RunnerConfig = z.infer<typeof RunnerConfigSchema>;
@@ -132,9 +186,78 @@ export function parseRunnerConfig(json: string): RunnerConfig {
   return RunnerConfigSchema.parse(data);
 }
 
-/** Read and validate a runner config from a JSON file path. */
+/**
+ * Read and validate a runner config from a JSON file path, then absolute-
+ * resolve its file-referencing fields (`contextFile`, each environment's
+ * `serviceAccountKeyPath`) against the config file's own directory. This is
+ * what lets a committed config use portable, repo-relative paths
+ * (`"./context/app.md"`): the customer's config file is the source of truth and
+ * the runner does the path bookkeeping. Absolute paths (e.g. a mounted secret
+ * at `/secrets/read.json`) pass through unchanged. Actions are discovered by
+ * convention from an `actions/` directory beside the config file (see
+ * `buildProjectRegistries`), not via a config field.
+ */
 export function loadRunnerConfig(path: string): RunnerConfig {
-  return parseRunnerConfig(readFileSync(path, "utf8"));
+  const config = parseRunnerConfig(readFileSync(path, "utf8"));
+  return resolveConfigPaths(config, dirname(path));
+}
+
+/** Absolute-resolve one path field against `baseDir` when it is relative. */
+function resolveConfigPath(value: string, baseDir: string): string {
+  return isAbsolute(value) ? value : resolve(baseDir, value);
+}
+
+/** Absolute-resolve an environment's `serviceAccountKeyPath` against `baseDir`. */
+function resolveEnvironmentPaths(
+  env: EnvironmentConfig,
+  baseDir: string,
+): EnvironmentConfig {
+  const firestore = env.firestore;
+  if (firestore?.serviceAccountKeyPath === undefined) return env;
+  return {
+    ...env,
+    firestore: {
+      ...firestore,
+      serviceAccountKeyPath: resolveConfigPath(
+        firestore.serviceAccountKeyPath,
+        baseDir,
+      ),
+    },
+  };
+}
+
+/** Absolute-resolve one project's file-referencing fields against `baseDir`. */
+function resolveProjectPaths(
+  project: ProjectConfig,
+  baseDir: string,
+): ProjectConfig {
+  const environments = Object.fromEntries(
+    Object.entries(project.environments).map(([name, env]) => [
+      name,
+      resolveEnvironmentPaths(env, baseDir),
+    ]),
+  );
+  return {
+    ...project,
+    environments,
+    ...(project.contextFile === undefined
+      ? {}
+      : { contextFile: resolveConfigPath(project.contextFile, baseDir) }),
+  };
+}
+
+/** Absolute-resolve every project's file-referencing fields against `baseDir`. */
+function resolveConfigPaths(
+  config: RunnerConfig,
+  baseDir: string,
+): RunnerConfig {
+  const projects = Object.fromEntries(
+    Object.entries(config.projects).map(([slug, project]) => [
+      slug,
+      resolveProjectPaths(project, baseDir),
+    ]),
+  );
+  return { ...config, projects };
 }
 
 /** Env var carrying the projects map (JSON) for env-driven config. */
@@ -169,41 +292,80 @@ export function buildRunnerConfigFromEnv(
       `${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 controlPlane = controlPlaneFromEnv(source);
+  const secrets = secretsFromEnv(source);
   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"),
-        }),
+    ...(controlPlane === undefined ? {} : { controlPlane }),
+    ...(secrets === undefined ? {} : { secrets }),
   };
   return RunnerConfigSchema.parse(candidate);
 }
 
+/**
+ * Overlay deploy-time secrets from the environment onto a **file-loaded**
+ * config: the committed config holds only the code-defined structure
+ * (projects, environments, actions, context), while the outbound link's creds
+ * (`controlPlane`) and runner-level action `secrets` arrive as env vars from a
+ * secret manager and are never written to the repo. Env only *fills* what the
+ * file left unset; a value already present in the file always wins.
+ *
+ * This is the counterpart to {@link loadRunnerConfig} for the production path:
+ * bake the structural config into the image, inject secrets as env at runtime.
+ */
+export function overlayEnvSecrets(
+  config: RunnerConfig,
+  source: NodeJS.ProcessEnv,
+): RunnerConfig {
+  const controlPlane = config.controlPlane ?? controlPlaneFromEnv(source);
+  const secrets = config.secrets ?? secretsFromEnv(source);
+  return {
+    ...config,
+    ...(controlPlane === undefined ? {} : { controlPlane }),
+    ...(secrets === undefined ? {} : { secrets }),
+  };
+}
+
+/**
+ * Build the control-plane block from env vars, or `undefined` when none is set
+ * (so `runner list` can load actions in a container without enrollment creds).
+ * A *partial* block is passed through to the schema so it pinpoints exactly
+ * which field is missing rather than silently dropping the block.
+ */
+function controlPlaneFromEnv(
+  source: NodeJS.ProcessEnv,
+): ControlPlaneConfig | undefined {
+  const url = source["POLYCORE_CONTROL_PLANE_URL"];
+  const runnerId = source["POLYCORE_RUNNER_ID"];
+  const joinToken = source["POLYCORE_JOIN_TOKEN"];
+  const signingSecret = source["POLYCORE_SIGNING_SECRET"];
+  if (
+    url === undefined &&
+    runnerId === undefined &&
+    joinToken === undefined &&
+    signingSecret === undefined
+  ) {
+    return undefined;
+  }
+  return ControlPlaneConfigSchema.parse({
+    url,
+    runnerId,
+    joinToken,
+    signingSecret,
+  });
+}
+
+const runnerSecretsSchema = z.record(z.string(), z.string());
+
+/** Runner-level action secrets from `POLYCORE_SECRETS`, or `undefined`. */
+function secretsFromEnv(
+  source: NodeJS.ProcessEnv,
+): Record<string, string> | undefined {
+  const raw = source["POLYCORE_SECRETS"];
+  if (raw === undefined) return undefined;
+  return runnerSecretsSchema.parse(parseJsonEnv(raw, "POLYCORE_SECRETS"));
+}
+
 function parseJsonEnv(raw: string, name: string): unknown {
   try {
     return JSON.parse(raw) as unknown;

package/src/connect.ts

@@ -47,6 +47,9 @@ export function describeProjects(
       slug,
       environments: Object.keys(project.environments),
       connectors: describeConnectors(registry),
+      ...(project.defaultEnvironment === undefined
+        ? {}
+        : { defaultEnvironment: project.defaultEnvironment }),
       ...(context === undefined ? {} : { context }),
     };
   });

package/src/connector.ts

@@ -13,8 +13,11 @@ export type ConnectorEffect = "read";
 /** Hazard class of any capability (connector or action). */
 export type CapabilityEffect = "read" | "mutate";
 
-/** Whether a capability is a built-in connector or a customer-authored action. */
-export type CapabilityKind = "connector" | "action";
+/**
+ * Whether a capability is a built-in connector, a customer-authored action,
+ * or the generic delegated-workload executor (`workload.execute`).
+ */
+export type CapabilityKind = "connector" | "action" | "workload";
 
 /** Everything a connector needs to execute one request. */
 export interface ConnectorContext {
@@ -168,6 +171,16 @@ export class ConnectorRegistry {
     }
   }
 
+  /**
+   * Register a pre-built capability directly. Used for capabilities that are
+   * neither a read-only `Connector` nor a folder-loaded action, e.g. the
+   * `workload.execute` executor, whose `effect` is `mutate` and whose `run`
+   * bridges into a sandbox backend.
+   */
+  public registerCapability(capability: RegisteredCapability): void {
+    this.add(capability);
+  }
+
   /**
    * Register a customer-authored action as a capability. The action's `input`
    * schema becomes the capability params; its declared secrets are resolved

package/src/index.ts

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
 import type { LoadedAction } from "./action.js";
 import type { ProjectConfig, RunnerConfig } from "./config.js";
 import {
@@ -7,6 +10,15 @@ import {
 } from "./connector.js";
 import { firestoreConnectors } from "./connectors/firestore.js";
 import { loadActions } from "./load-actions.js";
+import {
+  createSandboxBackend,
+  createWorkloadCapability,
+} from "./workload/capability.js";
+import { resolveSandboxMaxima } from "./workload/limits.js";
+import type {
+  ResolvedSandboxLimits,
+  SandboxBackend,
+} from "./workload/types.js";
 
 export type {
   Action,
@@ -23,6 +35,7 @@ export type {
   ProjectConfig,
   RunnerConfig,
 } from "./config.js";
+export type { SandboxConfig, SandboxLimits } from "./config.js";
 export {
   buildRunnerConfigFromEnv,
   ControlPlaneConfigSchema,
@@ -30,6 +43,7 @@ export {
   FirestoreEnvironmentSchema,
   hasEnvConfig,
   loadRunnerConfig,
+  overlayEnvSecrets,
   parseRunnerConfig,
   ProjectConfigSchema,
   resolveEnvironment,
@@ -38,6 +52,8 @@ export {
   RUNNER_CONFIG_ENV,
   RUNNER_PROJECTS_ENV,
   RunnerConfigSchema,
+  SandboxConfigSchema,
+  SandboxLimitsSchema,
 } from "./config.js";
 export type { RunnerClientOptions } from "./connect.js";
 export {
@@ -62,6 +78,38 @@ export {
 } from "./connector.js";
 export { firestoreConnectors } from "./connectors/firestore.js";
 export { loadActions } from "./load-actions.js";
+export {
+  createSandboxBackend,
+  createWorkloadCapability,
+  WORKLOAD_CAPABILITY_NAME,
+} from "./workload/capability.js";
+export {
+  assertSafeRelativePath,
+  buildContainerArgs,
+  buildRunScript,
+  ContainerSandboxBackend,
+} from "./workload/container-backend.js";
+export { workloadDigest } from "./workload/digest.js";
+export {
+  clampWorkloadLimits,
+  DEFAULT_SANDBOX_LIMITS,
+  resolveSandboxMaxima,
+} from "./workload/limits.js";
+export type {
+  ResolvedSandboxLimits,
+  SandboxBackend,
+  SandboxRunRequest,
+  SandboxRunResult,
+  WorkloadFile,
+  WorkloadLimits,
+  WorkloadResult,
+  WorkloadSpec,
+} from "./workload/types.js";
+export {
+  workloadFileSchema,
+  workloadLimitsSchema,
+  workloadSpecSchema,
+} from "./workload/types.js";
 // The pinned Zod, re-exported so action authors share the runner's exact
 // instance, schemas must be introspectable by the runner's `z.toJSONSchema`.
 // Authors import `{ defineAction, z }` from "@polycore/runner", never from a
@@ -81,11 +129,20 @@ export interface CreateRegistryOptions {
    * family at least one of the project's environments configures.
    */
   readonly project?: ProjectConfig;
+  /**
+   * When given, the generic `workload.execute` capability is registered,
+   * running approved arbitrary code in `backend` under `maxima` resource caps.
+   */
+  readonly sandbox?: {
+    readonly backend: SandboxBackend;
+    readonly maxima: ResolvedSandboxLimits;
+  };
 }
 
 /**
- * Build a registry with the runner's built-in connectors (Lane 1) plus any
- * customer-authored actions (Lane 2/3).
+ * Build a registry with the runner's built-in connectors (Lane 1), any
+ * customer-authored actions (Lane 2/3), and, when a sandbox is provided, the
+ * delegated-workload executor.
  */
 export function createRegistry(
   options: CreateRegistryOptions = {},
@@ -99,29 +156,79 @@ export function createRegistry(
   for (const loaded of options.actions ?? []) {
     registry.registerAction(loaded, options.secrets ?? {});
   }
+  if (options.sandbox) {
+    registry.registerCapability(
+      createWorkloadCapability(options.sandbox.backend, options.secrets ?? {}, {
+        maxima: options.sandbox.maxima,
+      }),
+    );
+  }
   return registry;
 }
 
+/** The conventional directory customer actions live in, beside the config. */
+export const ACTIONS_DIRNAME = "actions";
+
+/**
+ * Resolve a project's actions directory by convention, relative to the config
+ * file's directory (`baseDir`): a project's actions live in `actions/<slug>/`,
+ * and when the runner serves a single project they may live directly in
+ * `actions/`. Returns `undefined` when neither exists (a project with no
+ * actions, or an env-driven config with no file directory) — the runner then
+ * serves only the built-in connectors. There is no `actionsDir` config field:
+ * the layout is a fixed convention, exactly like the desktop `src/actions/`.
+ */
+export function resolveActionsDir(
+  baseDir: string,
+  slug: string,
+  projectCount: number,
+): string | undefined {
+  const namespaced = join(baseDir, ACTIONS_DIRNAME, slug);
+  if (existsSync(namespaced)) return namespaced;
+  const shared = join(baseDir, ACTIONS_DIRNAME);
+  if (projectCount === 1 && existsSync(shared)) return shared;
+  return undefined;
+}
+
 /**
  * Build one registry per configured project: built-in connectors filtered
  * by what the project's environments configure, plus the project's own
  * actions with its secrets (project secrets win over runner-level secrets;
  * both fall back to `process.env` at dispatch).
+ *
+ * `actionsBaseDir` is the config file's directory; actions are discovered from
+ * the `actions/` convention under it (see {@link resolveActionsDir}). Omit it
+ * for an env-driven config with no file location — the runner then serves only
+ * the built-in connectors.
  */
 export async function buildProjectRegistries(
   config: RunnerConfig,
+  actionsBaseDir?: string,
 ): Promise<Map<string, ConnectorRegistry>> {
   const registries = new Map<string, ConnectorRegistry>();
+  const projectCount = Object.keys(config.projects).length;
+  // Sandbox is a runner-level capability: one backend + maxima shared across
+  // projects, each registered with its own secrets so a workload can only ask
+  // for credentials of the project it targets.
+  const sandbox = config.sandbox
+    ? {
+        backend: createSandboxBackend(config.sandbox),
+        maxima: resolveSandboxMaxima(config.sandbox.limits),
+      }
+    : undefined;
   for (const [slug, project] of Object.entries(config.projects)) {
-    const actions = project.actionsDir
-      ? await loadActions(project.actionsDir)
-      : [];
+    const dir =
+      actionsBaseDir === undefined
+        ? undefined
+        : resolveActionsDir(actionsBaseDir, slug, projectCount);
+    const actions = dir ? await loadActions(dir) : [];
     registries.set(
       slug,
       createRegistry({
         project,
         actions,
         secrets: { ...config.secrets, ...project.secrets },
+        ...(sandbox ? { sandbox } : {}),
       }),
     );
   }

package/src/workload/capability.ts

@@ -0,0 +1,118 @@
+import type { SandboxConfig } from "../config.js";
+import type {
+  ConnectorContext,
+  RegisteredCapability,
+  SecretSource,
+} from "../connector.js";
+import { ContainerSandboxBackend } from "./container-backend.js";
+import { workloadDigest } from "./digest.js";
+import { clampWorkloadLimits } from "./limits.js";
+import type {
+  ResolvedSandboxLimits,
+  SandboxBackend,
+  WorkloadResult,
+} from "./types.js";
+import { workloadSpecSchema } from "./types.js";
+
+/** The single generic capability name for delegated code execution. */
+export const WORKLOAD_CAPABILITY_NAME = "workload.execute";
+
+const WORKLOAD_DESCRIPTION =
+  "Run a short program you author, in an isolated sandbox on the runner host, " +
+  "when no other connector or action covers the task. Use this for arbitrary " +
+  "computation and multi-step work: parsing files, reconciling systems, batch " +
+  "operations, calling an API no connector exposes. Provide `files` (source, " +
+  "at least the entrypoint; include a package.json to use npm libraries), " +
+  "`entrypoint` (the file to run; .ts runs under tsx), `secrets` (keys of the " +
+  "credentials the code needs, injected as env vars), and set `egress: true` " +
+  "to allow network access or dependency installs. It ALWAYS pauses for human " +
+  "review of the exact code before running, so propose the workload directly " +
+  "rather than asking the user for permission first. Read its stdout for the result.";
+
+/** Build the container backend the runner uses to execute workloads. */
+export function createSandboxBackend(config: SandboxConfig): SandboxBackend {
+  return new ContainerSandboxBackend({
+    image: config.image,
+    ...(config.runtime === undefined ? {} : { runtime: config.runtime }),
+    ...(config.cli === undefined ? {} : { cli: config.cli }),
+  });
+}
+
+/** Resolve the requested secret keys to values, failing loud on any missing. */
+function resolveWorkloadSecrets(
+  keys: readonly string[],
+  source: SecretSource,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const key of keys) {
+    const value = source[key] ?? process.env[key];
+    if (value === undefined || value.length === 0) {
+      throw new Error(
+        `Missing secret "${key}" requested by the workload. Provide it in the ` +
+          `runner config's "secrets" or the environment.`,
+      );
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+
+/** A workload installs dependencies when it ships a package.json. */
+function needsInstall(files: readonly { path: string }[]): boolean {
+  return files.some(
+    (f) => f.path === "package.json" || f.path.endsWith("/package.json"),
+  );
+}
+
+export interface WorkloadCapabilityOptions {
+  /** The runner's resource maxima; per-workload requests are clamped to these. */
+  readonly maxima: ResolvedSandboxLimits;
+}
+
+/**
+ * The `workload.execute` capability: validate the spec, resolve exactly the
+ * requested credentials, clamp the limits, and run it in the sandbox backend.
+ * It is `mutate` unconditionally, so the control plane always routes it through
+ * human approval, the trust transition that turns agent-authored code into
+ * trusted-for-one-run code. The full spec (including the source) is the
+ * approved artifact; its digest is returned for audit.
+ */
+export function createWorkloadCapability(
+  backend: SandboxBackend,
+  secrets: SecretSource,
+  options: WorkloadCapabilityOptions,
+): RegisteredCapability {
+  return {
+    name: WORKLOAD_CAPABILITY_NAME,
+    description: WORKLOAD_DESCRIPTION,
+    effect: "mutate",
+    kind: "workload",
+    params: workloadSpecSchema,
+    run: async (rawArgs: unknown, ctx: ConnectorContext) => {
+      const spec = workloadSpecSchema.parse(rawArgs);
+      const egress = spec.egress ?? false;
+      const credentials = resolveWorkloadSecrets(spec.secrets ?? [], secrets);
+      const limits = clampWorkloadLimits(options.maxima, spec.limits);
+      const install = needsInstall(spec.files);
+      const outcome = await backend.run({
+        files: spec.files,
+        entrypoint: spec.entrypoint,
+        credentials,
+        egress,
+        install,
+        limits,
+        log: (m) => ctx.log(m),
+      });
+      const result: WorkloadResult = {
+        digest: workloadDigest(spec),
+        ok: outcome.exitCode === 0 && !outcome.timedOut,
+        exitCode: outcome.exitCode,
+        stdout: outcome.stdout,
+        stderr: outcome.stderr,
+        timedOut: outcome.timedOut,
+        durationMs: outcome.durationMs,
+      };
+      return result;
+    },
+  };
+}

package/src/workload/container-backend.ts

@@ -0,0 +1,257 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import type {
+  ResolvedSandboxLimits,
+  SandboxBackend,
+  SandboxRunRequest,
+  SandboxRunResult,
+} from "./types.js";
+
+const DEFAULT_RUNTIME = "runsc";
+const DEFAULT_CLI = "docker";
+const WORKDIR = "/workload";
+/** Cap captured stream size so a chatty workload can't exhaust runner memory. */
+const MAX_STREAM_BYTES = 1_000_000;
+
+export interface ContainerSandboxOptions {
+  /** Base image (must carry a Node runtime, `tsx`, and `npm`). */
+  readonly image: string;
+  /** OCI runtime; defaults to `runsc` (gVisor). */
+  readonly runtime?: string;
+  /** Container CLI executable; defaults to `docker`. */
+  readonly cli?: string;
+}
+
+/**
+ * Reject a path that could escape the sandbox workdir. Workload paths are
+ * agent-authored, so this is a hard boundary, not a nicety.
+ */
+export function assertSafeRelativePath(path: string): void {
+  const segments = path.split("/");
+  if (
+    path.startsWith("/") ||
+    path.includes("\\") ||
+    path.includes("\0") ||
+    segments.some((s) => s === ".." || s === "")
+  ) {
+    throw new Error(
+      `Unsafe workload path "${path}": paths must be relative with no "..", ` +
+        `absolute, empty, or backslash segments.`,
+    );
+  }
+}
+
+/** Single-quote a token for safe embedding in a `sh -c` script. */
+function shellSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The in-container command. `.ts`/`.tsx` entrypoints run under `tsx`, others
+ * under `node`. When `install` is set, dependencies are installed first (this
+ * requires network egress). `exec` replaces the shell so signals reach the
+ * process directly for prompt timeout kills.
+ */
+export function buildRunScript(entrypoint: string, install: boolean): string {
+  const runner = /\.tsx?$/.test(entrypoint) ? "tsx" : "node";
+  const run = `exec ${runner} ${shellSingleQuote(entrypoint)}`;
+  if (!install) return run;
+  return `npm install --omit=dev --no-audit --no-fund && ${run}`;
+}
+
+export interface ContainerArgsParams {
+  readonly name: string;
+  readonly image: string;
+  readonly runtime: string;
+  readonly hostDir: string;
+  readonly egress: boolean;
+  readonly limits: ResolvedSandboxLimits;
+  readonly secretKeys: readonly string[];
+  readonly script: string;
+}
+
+/**
+ * Build the container CLI arguments (everything after the `docker`/`podman`
+ * executable). Pure and deterministic so the isolation posture is unit-tested:
+ * no host network unless egress is granted, read-only root fs, all capabilities
+ * dropped, no privilege escalation, hard resource caps, and secrets passed by
+ * *key* (`-e KEY`) so their values never appear on the process argv.
+ */
+export function buildContainerArgs(params: ContainerArgsParams): string[] {
+  const { limits } = params;
+  const args = [
+    "run",
+    "--rm",
+    "--name",
+    params.name,
+    "--runtime",
+    params.runtime,
+    "--network",
+    params.egress ? "bridge" : "none",
+    "--cpus",
+    String(limits.cpus),
+    "--memory",
+    `${limits.memoryMb}m`,
+    // Equal memory + swap disables swap, so the memory cap is hard.
+    "--memory-swap",
+    `${limits.memoryMb}m`,
+    "--pids-limit",
+    String(limits.pids),
+    "--read-only",
+    "--tmpfs",
+    `/tmp:rw,size=${limits.memoryMb}m`,
+    "--cap-drop",
+    "ALL",
+    "--security-opt",
+    "no-new-privileges",
+    "-v",
+    `${params.hostDir}:${WORKDIR}`,
+    "-w",
+    WORKDIR,
+  ];
+  for (const key of params.secretKeys) {
+    args.push("-e", key);
+  }
+  args.push(params.image, "sh", "-c", params.script);
+  return args;
+}
+
+/** Append to a capped buffer, dropping bytes past the cap. */
+function appendCapped(current: string, chunk: string): string {
+  if (current.length >= MAX_STREAM_BYTES) return current;
+  return (current + chunk).slice(0, MAX_STREAM_BYTES);
+}
+
+/**
+ * Runs each approved workload in a fresh, OS-isolated container on the runner's
+ * host and destroys it afterward. Isolation (gVisor by default), credential
+ * injection, and resource limits are enforced at the container boundary; the
+ * approved code inside may use any library, SDK, and (when egress is granted)
+ * the open internet, exactly as a human reviewer signed off on.
+ */
+export class ContainerSandboxBackend implements SandboxBackend {
+  private readonly image: string;
+  private readonly runtime: string;
+  private readonly cli: string;
+
+  constructor(options: ContainerSandboxOptions) {
+    this.image = options.image;
+    this.runtime = options.runtime ?? DEFAULT_RUNTIME;
+    this.cli = options.cli ?? DEFAULT_CLI;
+  }
+
+  public async run(request: SandboxRunRequest): Promise<SandboxRunResult> {
+    assertSafeRelativePath(request.entrypoint);
+    if (!request.files.some((f) => f.path === request.entrypoint)) {
+      throw new Error(
+        `Entrypoint "${request.entrypoint}" is not among the workload files.`,
+      );
+    }
+    if (request.install && !request.egress) {
+      throw new Error(
+        "Installing dependencies requires network egress; set egress: true.",
+      );
+    }
+
+    const dir = await mkdtemp(join(tmpdir(), "polycore-wl-"));
+    try {
+      await this.writeFiles(dir, request.files);
+      return await this.spawnContainer(dir, request);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+
+  private async writeFiles(
+    dir: string,
+    files: SandboxRunRequest["files"],
+  ): Promise<void> {
+    for (const file of files) {
+      assertSafeRelativePath(file.path);
+      const full = join(dir, file.path);
+      await mkdir(dirname(full), { recursive: true });
+      await writeFile(full, file.contents, "utf8");
+    }
+  }
+
+  private spawnContainer(
+    hostDir: string,
+    request: SandboxRunRequest,
+  ): Promise<SandboxRunResult> {
+    const name = `polycore-wl-${randomUUID()}`;
+    const secretKeys = Object.keys(request.credentials);
+    const script = buildRunScript(request.entrypoint, request.install);
+    const args = buildContainerArgs({
+      name,
+      image: this.image,
+      runtime: this.runtime,
+      hostDir,
+      egress: request.egress,
+      limits: request.limits,
+      secretKeys,
+      script,
+    });
+
+    request.log(
+      `Running workload in ${this.runtime} sandbox (egress=${request.egress}, ` +
+        `timeout=${request.limits.timeoutSeconds}s)…`,
+    );
+
+    return new Promise<SandboxRunResult>((resolve, reject) => {
+      const startedAt = Date.now();
+      // Secret values ride the child's env so only `-e KEY` forwards them into
+      // the container; they never touch argv. Other host env stays out of the
+      // sandbox (it is not forwarded) but is available to the CLI itself.
+      const child = spawn(this.cli, args, {
+        env: { ...process.env, ...request.credentials },
+      });
+
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let settled = false;
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        // Killing the CLI does not stop the container; kill it by name.
+        spawn(this.cli, ["kill", name]).on("error", () => undefined);
+        child.kill("SIGKILL");
+      }, request.limits.timeoutSeconds * 1000);
+
+      child.stdout.on("data", (d: Buffer) => {
+        stdout = appendCapped(stdout, d.toString("utf8"));
+      });
+      child.stderr.on("data", (d: Buffer) => {
+        stderr = appendCapped(stderr, d.toString("utf8"));
+      });
+
+      child.on("error", (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(
+          new Error(
+            `Failed to launch sandbox via "${this.cli}": ${error.message}`,
+          ),
+        );
+      });
+
+      child.on("close", (code) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({
+          exitCode: code ?? -1,
+          stdout,
+          stderr,
+          durationMs: Date.now() - startedAt,
+          timedOut,
+        });
+      });
+    });
+  }
+}

package/src/workload/digest.ts

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+
+import type { WorkloadSpec } from "./types.js";
+
+/**
+ * A stable sha256 identity for a workload: the exact thing a human approves and
+ * the runner executes. Files are sorted by path and secret keys are sorted, so
+ * the digest depends on *what* the workload is and *what authority it asks
+ * for*, not on incidental ordering. Any change to code, entrypoint, requested
+ * secrets, egress, or limits changes the digest, which is what lets an approval
+ * bind to one immutable artifact: re-review is required the moment it differs.
+ */
+export function workloadDigest(spec: WorkloadSpec): string {
+  const canonical = {
+    files: [...spec.files]
+      .map((f) => ({ path: f.path, contents: f.contents }))
+      .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    entrypoint: spec.entrypoint,
+    secrets: [...(spec.secrets ?? [])].sort(),
+    egress: spec.egress ?? false,
+    limits: spec.limits ?? {},
+  };
+  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}

package/src/workload/limits.ts

@@ -0,0 +1,43 @@
+import type { SandboxLimits } from "../config.js";
+import type { ResolvedSandboxLimits, WorkloadLimits } from "./types.js";
+
+/** Conservative defaults when the runner config sets no explicit maxima. */
+export const DEFAULT_SANDBOX_LIMITS: ResolvedSandboxLimits = {
+  cpus: 1,
+  memoryMb: 512,
+  timeoutSeconds: 120,
+  pids: 256,
+};
+
+/** Resolve the runner's configured maxima, filling any unset field with a default. */
+export function resolveSandboxMaxima(
+  config: SandboxLimits | undefined,
+): ResolvedSandboxLimits {
+  return {
+    cpus: config?.cpus ?? DEFAULT_SANDBOX_LIMITS.cpus,
+    memoryMb: config?.memoryMb ?? DEFAULT_SANDBOX_LIMITS.memoryMb,
+    timeoutSeconds:
+      config?.timeoutSeconds ?? DEFAULT_SANDBOX_LIMITS.timeoutSeconds,
+    pids: config?.pids ?? DEFAULT_SANDBOX_LIMITS.pids,
+  };
+}
+
+/**
+ * Clamp a workload's requested limits to the runner's maxima: a workload may
+ * ask for less than the configured ceiling, never more. Unset requests default
+ * to the maximum.
+ */
+export function clampWorkloadLimits(
+  maxima: ResolvedSandboxLimits,
+  requested: WorkloadLimits | undefined,
+): ResolvedSandboxLimits {
+  return {
+    cpus: Math.min(requested?.cpus ?? maxima.cpus, maxima.cpus),
+    memoryMb: Math.min(requested?.memoryMb ?? maxima.memoryMb, maxima.memoryMb),
+    timeoutSeconds: Math.min(
+      requested?.timeoutSeconds ?? maxima.timeoutSeconds,
+      maxima.timeoutSeconds,
+    ),
+    pids: maxima.pids,
+  };
+}

package/src/workload/types.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+
+/**
+ * Delegated workloads are the universal escape hatch: when no connector or
+ * action covers a task, the agent authors a small program, a human reviews the
+ * exact code + dependencies + requested credentials, and on approval the runner
+ * executes it in a disposable, OS-isolated sandbox on its own host. This is
+ * arbitrary code in the same sense every program is arbitrary: it computes
+ * freely, and the credentials it may touch are exactly the ones the approval
+ * delegated to it, nothing more.
+ */
+
+/** One source file of a workload bundle, at a workspace-relative path. */
+export const workloadFileSchema = z.object({
+  /** POSIX-relative path inside the sandbox workdir, e.g. `main.ts`. */
+  path: z.string().min(1),
+  /** UTF-8 file contents. */
+  contents: z.string(),
+});
+
+export type WorkloadFile = z.infer<typeof workloadFileSchema>;
+
+/** Per-workload resource request; clamped to the runner's configured maxima. */
+export const workloadLimitsSchema = z.object({
+  cpus: z.number().positive().optional(),
+  memoryMb: z.number().int().positive().optional(),
+  timeoutSeconds: z.number().int().positive().optional(),
+});
+
+export type WorkloadLimits = z.infer<typeof workloadLimitsSchema>;
+
+/**
+ * The `workload.execute` arguments the agent supplies. This whole object is
+ * what a human approves: the exact files, the entrypoint, which credentials it
+ * may use, whether it may reach the network, and its resource envelope.
+ */
+export const workloadSpecSchema = z.object({
+  /** Source files of the program (at least the entrypoint). */
+  files: z.array(workloadFileSchema).min(1),
+  /** Which file to run; must be one of `files`, a safe relative path. */
+  entrypoint: z.string().min(1),
+  /**
+   * Secret keys (from the runner's configured secrets) to inject into the
+   * sandbox as environment variables. These are the credentials the approval
+   * delegates to the code; omit for a pure-computation workload.
+   */
+  secrets: z.array(z.string().min(1)).optional(),
+  /**
+   * Whether the sandbox may reach the network. Required to install npm
+   * dependencies or call any external system. Defaults to false (no egress).
+   */
+  egress: z.boolean().optional(),
+  /** Optional per-workload resource caps (clamped to the runner's maxima). */
+  limits: workloadLimitsSchema.optional(),
+});
+
+export type WorkloadSpec = z.infer<typeof workloadSpecSchema>;
+
+/** Resolved, absolute resource caps a single sandbox run executes under. */
+export interface ResolvedSandboxLimits {
+  readonly cpus: number;
+  readonly memoryMb: number;
+  readonly timeoutSeconds: number;
+  readonly pids: number;
+}
+
+/** Everything a sandbox backend needs to execute one approved workload. */
+export interface SandboxRunRequest {
+  readonly files: readonly WorkloadFile[];
+  readonly entrypoint: string;
+  /** Resolved secret values to expose as env vars inside the sandbox. */
+  readonly credentials: Readonly<Record<string, string>>;
+  readonly egress: boolean;
+  /** Whether to install dependencies before running (needs `egress`). */
+  readonly install: boolean;
+  readonly limits: ResolvedSandboxLimits;
+  readonly log: (message: string) => void;
+}
+
+/** The raw outcome of one sandbox run. */
+export interface SandboxRunResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly durationMs: number;
+  /** True when the run hit its wall-clock timeout and was killed. */
+  readonly timedOut: boolean;
+}
+
+/**
+ * Executes an approved workload in isolation. The default implementation runs
+ * an OS-isolated container; the interface exists so a microVM (or a fake, in
+ * tests) can be swapped in without touching the capability or its callers.
+ */
+export interface SandboxBackend {
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+
+/** The `workload.execute` result returned to the control plane and audit. */
+export interface WorkloadResult {
+  /** Deterministic identity of the approved artifact (what was run). */
+  readonly digest: string;
+  /** Convenience flag: exited 0 and did not time out. */
+  readonly ok: boolean;
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut: boolean;
+  readonly durationMs: number;
+}