@polycore/runner 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycore/runner",
-  "version": "0.2.0",
+  "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.2.0"
+    "@polycore/protocol": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "25.6.2",

package/src/config.ts

@@ -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>;

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

@@ -10,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,
@@ -26,6 +35,7 @@ export type {
   ProjectConfig,
   RunnerConfig,
 } from "./config.js";
+export type { SandboxConfig, SandboxLimits } from "./config.js";
 export {
   buildRunnerConfigFromEnv,
   ControlPlaneConfigSchema,
@@ -42,6 +52,8 @@ export {
   RUNNER_CONFIG_ENV,
   RUNNER_PROJECTS_ENV,
   RunnerConfigSchema,
+  SandboxConfigSchema,
+  SandboxLimitsSchema,
 } from "./config.js";
 export type { RunnerClientOptions } from "./connect.js";
 export {
@@ -66,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
@@ -85,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 = {},
@@ -103,6 +156,13 @@ 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;
 }
 
@@ -147,6 +207,15 @@ export async function buildProjectRegistries(
 ): 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 dir =
       actionsBaseDir === undefined
@@ -159,6 +228,7 @@ export async function buildProjectRegistries(
         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;
+}