@bevel-software/ael 0.0.0-stage → 0.2.0

package/src/cli/run-local.ts

@@ -0,0 +1,224 @@
+import { constants } from 'node:fs';
+import { open, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { parseAgentFile, type AgentDefinition } from '../agent/agent-file.js';
+import { PiInProcessHarness } from '../harness/pi-in-process.js';
+import type { Harness, RunEvent } from '../run/contract.js';
+import { parseWorkflowFile } from '../workflow/workflow-file.js';
+import { interpolate, nextAfter, stripReservedKeys, type StepDef, type WorkflowDefinition } from '../workflow/definition.js';
+import { INTERPRETER_STATE_KEYS, MAX_RUN_STEPS } from '../interpreter/contract.js';
+import { outcomeFromResult } from '../run/outcome.js';
+import { SkillNotReadable, composeSystemPrompt } from '../run/system-prompt.js';
+import { Redactor } from '../shared/redact.js';
+
+/**
+ * `bevel-agent run <file>`: a workflow file run here, on this machine,
+ * against a platform — the way to try a file before a trigger does.
+ *
+ * What runs locally is the happy path of a workflow whose steps are all
+ * agent steps: each step's session runs with pi, its tools on this working
+ * directory and the platform's tools over MCP as the connection key's
+ * person, in order, stopping at the first step that does not pass. Gates,
+ * tool chains, choices, retries and work items are the platform's — a
+ * workflow with any of them is refused here with the step named, since a
+ * local run that silently skipped them would say nothing true about it.
+ *
+ * The configuration's `env:` comes from this process's environment by
+ * variable name (vault entries included: a local run has no vault).
+ */
+export interface LocalRunOptions {
+  /** The platform's API root, e.g. `https://kb.example.com/api`. */
+  apiUrl: string;
+  /** A connection key of the person the run acts as. */
+  token: string;
+  gatewayModel?: string;
+  /** The input the first step starts with. */
+  input?: string;
+  cwd?: string;
+  /** This process's environment, where `env:` values come from. */
+  env?: Record<string, string | undefined>;
+  harness?: Harness;
+  /** Reads a repo-relative path (an `.agent` the workflow names) from the knowledge base checkout at `cwd`. */
+  readFile?: (repoPath: string) => Promise<string>;
+  onEvent?: (step: string, event: RunEvent) => void;
+}
+
+export interface LocalRunResult {
+  status: 'done' | 'failed' | 'blocked';
+  steps: Array<{ name: string; outcome: string; reason: string | null }>;
+}
+
+const DEFAULT_AGENT: AgentDefinition = { id: 'default', name: 'Default', description: '', harness: 'pi', skills: [], plugins: [], connectors: [], platformTools: null, harnessTools: [], env: [] };
+
+/**
+ * The reason a workflow cannot run locally, or null when it can. What runs
+ * here is exactly what the file says and nothing the platform would add:
+ * a step that routes on its verdict, a retry, a catch or an entry budget is
+ * refused rather than silently ignored.
+ */
+export function unrunnableLocally(def: WorkflowDefinition): string | null {
+  if (def.environment.kind !== 'none') return `the workflow runs in a container (environment: ${def.environment.kind === 'image' ? def.environment.ref : def.environment.path}), which only an executor runs; this machine runs \`environment: none\``;
+  for (const step of def.steps) {
+    if (step.kind !== 'agent') return `step "${step.name}" is a ${step.kind} step, which only the platform runs`;
+    if (step.then !== undefined && typeof step.then !== 'string') return `step "${step.name}" routes on its verdict (\`then:\` is a map), which only the platform runs`;
+    if ((step.retry?.length ?? 0) > 0 || (step.catch?.length ?? 0) > 0 || step.entries) return `step "${step.name}" has a retry, catch or entries policy, which only the platform runs`;
+  }
+  if (def.defaults.retry.length > 0 || def.defaults.catch.length > 0) return 'the workflow has a retry or catch policy, which only the platform runs';
+  if (def.parameters.require.length > 0) return `the workflow requires parameters (${def.parameters.require.map((r) => r.name).join(', ')}), which come from a work item`;
+  return null;
+}
+
+/** The ways a configuration narrows the platform's tools, named; null when it does not. */
+function narrowing(agent: AgentDefinition): string | null {
+  const ways = [agent.skills.length > 0 && 'skills', agent.plugins.length > 0 && 'plugins', agent.connectors.length > 0 && 'connectors', agent.platformTools !== null && 'platformTools'].filter((w): w is string => typeof w === 'string');
+  return ways.length > 0 ? ways.join(', ') : null;
+}
+
+export async function runLocally(workflowPath: string, options: LocalRunOptions): Promise<LocalRunResult> {
+  const cwd = options.cwd ?? process.cwd();
+  // Contained to the checkout: the paths read here come from file content (a
+  // step's `agent:`, a configuration's skill), and a file must not make a
+  // local run read `~/.ssh/id_rsa` into a system prompt. The check is made
+  // on what would really be opened — the real path, symlinks followed,
+  // against the checkout's real path — so a link inside the checkout that
+  // points out of it is refused like a `../` is. It fails closed: a path
+  // whose real location cannot be told is not read. And the open itself
+  // refuses a link at the final component (`O_NOFOLLOW`), so a link put in
+  // place between the check and the open is not followed either.
+  const read =
+    options.readFile ??
+    (async (repoPath: string) => {
+      const root = await realpath(cwd);
+      const asked = path.resolve(root, repoPath);
+      let target: string;
+      try {
+        target = await realpath(asked);
+      } catch (err) {
+        throw new Error(`${repoPath} is not readable in the checkout at ${cwd} (${(err as NodeJS.ErrnoException).code ?? 'unknown'})`);
+      }
+      const rel = path.relative(root, target);
+      if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error(`${repoPath} is outside the checkout at ${cwd}`);
+      const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      try {
+        return await handle.readFile('utf8');
+      } finally {
+        await handle.close();
+      }
+    });
+  const def = parseWorkflowFile(await readFile(path.resolve(cwd, workflowPath), 'utf8'), workflowPath);
+  const refusal = unrunnableLocally(def);
+  if (refusal) throw new Error(`${workflowPath} cannot run locally: ${refusal}`);
+  const harness = options.harness ?? new PiInProcessHarness({ builtinTools: true });
+  const processEnv = options.env ?? process.env;
+  const platform = { mcpUrl: `${options.apiUrl.replace(/\/$/, '')}/mcp`, gatewayUrl: `${options.apiUrl.replace(/\/$/, '')}/llm/v1`, gatewayModel: options.gatewayModel ?? 'default' };
+
+  const steps: LocalRunResult['steps'] = [];
+  const state: Record<string, unknown> = {};
+  const reserved = [...INTERPRETER_STATE_KEYS, ...def.reservedStateKeys];
+  // The checkout's files, or null: a path that is not there reads as unreadable, the way the platform reads one the actor may not see.
+  const readOrNull = (repoPath: string) => read(repoPath).then((c) => c, () => null);
+  // Where the platform starts: the happy path's first step, not the first one listed (that may be off-path).
+  let current: StepDef | undefined = def.steps.find((s) => s.name === def.happyPath[0]);
+  // Bounded as the platform bounds a run: a `then: <earlier step>` that every
+  // step passes through would otherwise start model sessions without end.
+  let executed = 0;
+  while (current) {
+    const step: StepDef = current;
+    if (++executed > MAX_RUN_STEPS) {
+      steps.push({ name: step.name, outcome: 'blocked', reason: `the run exceeded ${MAX_RUN_STEPS} steps; the file's routing loops` });
+      return { status: 'blocked', steps };
+    }
+    const agent = step.agent ? parseAgentFile(await read(step.agent), step.agent) : DEFAULT_AGENT;
+    // What runs here is pi; a configuration asking for another harness is refused, as the platform refuses it.
+    if (agent.harness !== 'pi') {
+      steps.push({ name: step.name, outcome: 'blocked', reason: `configuration "${agent.id}" asks for the ${agent.harness} harness, which this runner does not have; only pi runs` });
+      return { status: 'blocked', steps };
+    }
+    // The key given here is the person's, not one the platform scoped to the
+    // configuration: a configuration that narrows the platform's tools (its
+    // skills, plugins, connectors or tool list) would run wider than written.
+    const narrows = narrowing(agent);
+    if (narrows) {
+      steps.push({ name: step.name, outcome: 'blocked', reason: `configuration "${agent.id}" narrows the platform's tools (${narrows}), which only a key the platform scopes to it honours; run it on the platform` });
+      return { status: 'blocked', steps };
+    }
+    const env: Record<string, string> = {};
+    const missing: string[] = [];
+    for (const entry of agent.env) {
+      const value = processEnv[entry.param ?? entry.name];
+      if (value) env[entry.name] = value;
+      else missing.push(entry.name);
+    }
+    if (missing.length > 0) {
+      steps.push({ name: step.name, outcome: 'blocked', reason: `configuration "${agent.id}" needs ${missing.join(', ')} in the environment` });
+      return { status: 'blocked', steps };
+    }
+    let systemPrompt: string;
+    try {
+      systemPrompt = await composeSystemPrompt(agent, step, readOrNull);
+    } catch (err) {
+      if (!(err instanceof SkillNotReadable)) throw err;
+      steps.push({ name: step.name, outcome: 'blocked', reason: `skill ${err.skill} is not in the checkout at ${cwd}` });
+      return { status: 'blocked', steps };
+    }
+    // Redacted from every event and outcome this run reports: the configuration's env values and the connection key the session runs on — as the platform redacts a step's run key.
+    const redactor = new Redactor([...Object.values(env), options.token]);
+    const message = [interpolate(step.instructions, state), '', 'Current STATE:', '```json', JSON.stringify(state, null, 2), '```', ...(step.verdict ? ['', `End your final message with exactly one of: ${step.verdict}.`] : []), ...(step.index === 1 && options.input ? ['', 'Input:', options.input] : [])].join('\n');
+    const result = await harness.run({
+      input: { text: message },
+      systemPrompt,
+      agent,
+      actorKey: { token: options.token },
+      platform,
+      env,
+      cwd,
+      expectVerdict: !!step.verdict,
+      onEvent: (event) => options.onEvent?.(step.name, redactor.json(event)),
+    });
+    const outcome = outcomeFromResult(result, { threadId: step.name, expectVerdict: !!step.verdict, redactor });
+    const reason = 'reason' in outcome ? outcome.reason : null;
+    steps.push({ name: step.name, outcome: outcome.kind === 'verdict' ? outcome.verdict : outcome.kind, reason });
+    if (outcome.kind === 'verdict' && outcome.outputs) {
+      // The interpreter's rule: a step's outputs never write the run's own STATE keys, nor the file's reserved ones.
+      Object.assign(state, stripReservedKeys(outcome.outputs, reserved, (key) => options.onEvent?.(step.name, { type: 'error', at: new Date().toISOString(), message: `output "${key}" is a reserved STATE key — dropped` })));
+    }
+    if (outcome.kind !== 'verdict' || outcome.verdict !== 'PASS') {
+      return { status: outcome.kind === 'verdict' && outcome.verdict === 'BLOCKED' ? 'blocked' : 'failed', steps };
+    }
+    // Where the file says to go on a pass: the next step, a named step, or an end — done, failed or blocked, as the file says.
+    const then = (step.then ?? 'continue') as string; // a map was refused by `unrunnableLocally`
+    if (then === 'done') break;
+    if (then === 'failed' || then === 'blocked') return { status: then, steps };
+    const next: string | null = then === 'continue' ? nextAfter(def, step.name) : then;
+    current = next ? def.steps.find((s) => s.name === next) : undefined;
+  }
+  return { status: 'done', steps };
+}
+
+/** One line per event, for a terminal. */
+export function formatEvent(step: string, event: RunEvent): string {
+  switch (event.type) {
+    case 'session_started':
+      return `[${step}] session started (${event.harness}${event.model ? `, ${event.model}` : ''})`;
+    case 'user':
+      return `[${step}] > ${event.text.split('\n')[0]}`;
+    case 'assistant':
+      return `[${step}] ${event.text}`;
+    case 'reasoning':
+      return `[${step}] (weighed) ${event.text.split('\n')[0]}`;
+    case 'tool_call':
+      return `[${step}] → ${event.name}`;
+    case 'tool_result':
+      return `[${step}] ← ${event.name}${event.isError ? ' (error)' : ''}`;
+    case 'verdict':
+      return `[${step}] verdict ${event.verdict}`;
+    case 'outputs':
+      return `[${step}] outputs ${JSON.stringify(event.values)}`;
+    case 'error':
+      return `[${step}] error: ${event.message}`;
+    case 'session_ended':
+      return `[${step}] session ended${event.ok ? '' : ' with an error'}`;
+    case 'transition':
+      return `[${step}] ${event.log}`;
+  }
+}

package/src/cli/run-step.ts

@@ -0,0 +1,147 @@
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { PiInProcessHarness } from '../harness/pi-in-process.js';
+import { ClaudeCodeHarness } from '../harness/claude-code.js';
+import type { AgentStepOutcome, ContainerStepInput } from '../interpreter/contract.js';
+import type { Harness, LocalMcpServer } from '../run/contract.js';
+import { outcomeFromResult } from '../run/outcome.js';
+import { PlatformRunReporter, type FetchLike } from '../run/reporter.js';
+import { Redactor } from '../shared/redact.js';
+
+/**
+ * One step inside a run container: what the executor execs with the harness
+ * bundle mounted. The prepared input arrives on stdin; the session runs with
+ * the harness's own tools on the workspace and the knowledge base's tools
+ * through the local Hexis MCP server as the actor (local tools such as `git`
+ * run here, in the container); every event and every turn's state go to the platform with the run
+ * key; the outcome is the last line of stdout, marked, for the executor to
+ * read back.
+ */
+
+export const OUTCOME_MARKER = '__BEVEL_OUTCOME__ ';
+
+export interface RunStepDeps {
+  /** The harness to run with; pi with its built-in tools when absent. */
+  harness?: Harness;
+  fetch?: FetchLike;
+  log?: (line: string) => void;
+  /** The workspace directory. */
+  cwd?: string;
+  /** The local MCP server for this step; the bundle's hexis-mcp when absent. */
+  localMcp?: (input: ContainerStepInput) => LocalMcpServer;
+}
+
+/**
+ * The local Hexis MCP server, as the execution layer always ran it: the one
+ * the harness bundle carries, on the node running this, signed in as the
+ * actor with the run key. The key travels in its environment (argv is
+ * readable by every process in the container); its materialized local
+ * tools live in the container's own temp, outside the workspace a step
+ * commits from.
+ */
+export function localHexisMcp(input: ContainerStepInput): LocalMcpServer {
+  const require = createRequire(import.meta.url);
+  const manifest = require.resolve('@bevel-software/hexis-mcp/package.json');
+  const bin = (require(manifest) as { bin: Record<string, string> }).bin['hexis-mcp']!;
+  return {
+    command: process.execPath,
+    args: [path.join(path.dirname(manifest), bin)],
+    env: {
+      // The deployment's base address: hexis-mcp finds the endpoint it advertises from there.
+      HEXIS_URL: input.platform.apiUrl.replace(/\/+$/, '').replace(/\/api$/, ''),
+      HEXIS_CONNECTION_KEY: input.actorKey.token,
+      HEXIS_HOME: path.join(tmpdir(), 'hexis'),
+    },
+  };
+}
+
+const FRESH_WORKSPACE_NOTE = 'Note: this step runs in a fresh workspace on another host. Whatever an earlier step left on disk is gone; start from the repository or the knowledge base again where you need it.';
+
+export async function runStep(input: ContainerStepInput, deps: RunStepDeps = {}): Promise<AgentStepOutcome> {
+  // Redacted from everything reported: the configuration's env values and the
+  // run key itself — a session that echoes its own credential would otherwise
+  // put it in the stored transcript.
+  const redactor = new Redactor([...Object.values(input.env), input.actorKey.token]);
+  const reporter = new PlatformRunReporter({
+    apiUrl: input.platform.apiUrl,
+    threadId: input.threadId,
+    token: input.actorKey.token,
+    fetch: deps.fetch,
+    log: deps.log,
+  });
+  const harness = harnessFor(input.agent.harness) && (deps.harness ?? harnessFor(input.agent.harness));
+  const text = input.freshWorkspace ? `${input.message}\n\n${FRESH_WORKSPACE_NOTE}` : input.message;
+  // A configuration asking for a harness the container does not run is never run on another one in its place.
+  if (!harness) {
+    const reason = `configuration ${input.agent.id} asks for the ${input.agent.harness} harness, which this executor does not run; it runs pi and claude-code`;
+    reporter.onEvent({ type: 'error', at: new Date().toISOString(), message: reason });
+    // A harness error whatever the report's fate: the note is for the person, the outcome is the same.
+    await reporter.flush().catch(() => undefined);
+    return { kind: 'harness-error', threadId: input.threadId, reason };
+  }
+  let outcome: AgentStepOutcome;
+  try {
+    const result = await harness.run({
+      input: { text, images: input.step.input.images },
+      systemPrompt: input.systemPrompt,
+      agent: input.agent,
+      actorKey: input.actorKey,
+      platform: { ...input.platform, localMcp: (deps.localMcp ?? localHexisMcp)(input) },
+      env: input.env,
+      cwd: deps.cwd,
+      state: input.state ?? undefined,
+      timeoutMs: input.timeoutMs,
+      expectVerdict: input.expectVerdict,
+      onEvent: (event) => reporter.onEvent(redactor.json(event)),
+      // The state is the session itself — tool calls and results included —
+      // and it is stored: a secret the session echoed would be in it.
+      onState: (state) => reporter.onState(redactor.json(state)),
+    });
+    outcome = outcomeFromResult(result, { threadId: input.threadId, expectVerdict: input.expectVerdict, redactor });
+  } catch (err) {
+    const reason = redactor.text(err instanceof Error ? err.message : String(err));
+    reporter.onEvent({ type: 'error', at: new Date().toISOString(), message: reason });
+    outcome = { kind: 'harness-error', threadId: input.threadId, reason };
+  }
+  // The thread is the record: the platform reads the step's answer and the
+  // state a retry resumes from out of what was reported. A report that was
+  // lost makes the step a harness error for the file's policy, as it does
+  // for a step on the platform's own worker, never a finished step with its
+  // answer gone.
+  try {
+    await reporter.flush();
+  } catch (err) {
+    return { kind: 'harness-error', threadId: input.threadId, reason: `the step's transcript could not be reported: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  return outcome;
+}
+
+/** The harness a configuration names, as a container runs it; null for one it does not run. Cheap: building one starts nothing. */
+function harnessFor(name: string): Harness | null {
+  if (name === 'pi') return new PiInProcessHarness({ builtinTools: true });
+  if (name === 'claude-code') return new ClaudeCodeHarness();
+  return null;
+}
+
+/** The outcome a `run-step` process printed, from its stdout; null when it printed none (it died first). */
+export function parseOutcomeLine(stdout: string): AgentStepOutcome | null {
+  const lines = stdout.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!.trim();
+    if (!line.startsWith(OUTCOME_MARKER)) continue;
+    try {
+      return JSON.parse(line.slice(OUTCOME_MARKER.length)) as AgentStepOutcome;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** Read the whole of a stream as text. */
+export async function readAll(stream: NodeJS.ReadableStream): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}

package/src/executor/activities.ts

@@ -0,0 +1,295 @@
+import { createHash } from 'node:crypto';
+import { ApplicationFailure, Context, heartbeat as temporalHeartbeat } from '@temporalio/activity';
+import { parseOutcomeLine } from '../cli/run-step.js';
+import type { AgentStepOutcome, ContainerStepInput, ExecutorActivities } from '../interpreter/contract.js';
+import { Redactor } from '../shared/redact.js';
+import type { ContainerDriver, ContainerLimits } from './driver.js';
+
+/**
+ * An executor's half of the contract: one container per step on this host.
+ * The image is pulled once, or the workflow's Dockerfile built and tagged by
+ * its content hash (rebuilt only when the text changes); the harness bundle
+ * is mounted read-only and `bevel-agent run-step` exec'd inside; the run's
+ * workspace is a volume that lives while the run is pinned here; the limits
+ * are this executor's, the same for every run; the session inside reports
+ * to the platform itself, and the outcome comes back on stdout. A provider
+ * refusing the ACCOUNT pauses this executor until the reset time, so the
+ * item is left alone and nothing else is claimed meanwhile.
+ */
+
+export interface ExecutorOptions {
+  driver: ContainerDriver;
+  /** This executor's own task queue, the one runs are pinned to. */
+  queueName: string;
+  /**
+   * The harness bundle — the library, its dependencies and tsx — as the
+   * engine mounts it into a run container: a path on the host, or a named
+   * volume the executor filled (the executor's own container is not the
+   * host, so a path inside it means nothing to the engine).
+   */
+  harnessBundle: { kind: 'bind' | 'volume'; source: string };
+  /**
+   * The deployment this executor serves (its compose project, as the engine
+   * names it). Workspace volumes are labelled with it, and the sweep judges
+   * only its own: several deployments on one engine each ask their own
+   * Temporal, which knows none of the others' runs. Unknown, the sweep of a
+   * deployment's executor is off rather than guessing.
+   */
+  deployment?: string | null;
+  limits: ContainerLimits;
+  /** `uid:gid` run containers run as. */
+  user?: string;
+  /** How long to pause when a provider refuses the account and names no reset time. */
+  defaultPauseMs?: number;
+  log?: (line: string) => void;
+  now?: () => number;
+  /** The activity heartbeat; Temporal's when absent. */
+  heartbeat?: (details?: unknown) => void;
+  /** The activity's cancellation, as a signal the container is stopped on; Temporal's when absent. */
+  cancellation?: () => AbortSignal | undefined;
+}
+
+/** How often a running step says it is alive without output, so a cancel reaches it. */
+const ALIVE_HEARTBEAT_MS = 30_000;
+
+export const VOLUME_LABEL = 'software.bevel.run';
+/** The person whose run a workspace volume belongs to: what a person's own executor sweeps by. */
+export const OWNER_LABEL = 'software.bevel.owner';
+/** The deployment whose executor made a workspace volume: the only one whose sweep may judge it. */
+export const DEPLOYMENT_LABEL = 'software.bevel.deployment';
+export const IMAGE_TAG_PREFIX = 'bevel-workflow';
+const HARNESS_MOUNT = '/harness';
+const WORKSPACE_MOUNT = '/workspace';
+
+/**
+ * The command that runs `args` on node inside a run container: the node the
+ * executor ships in the harness bundle (`bin/node`, copied from its own
+ * image) when the image is glibc-based, so an image needs no node of its own
+ * (`python:3.12`, `ubuntu`); the image's own `node` otherwise — an image on
+ * musl (Alpine), where the shipped glibc build cannot start, brings its own,
+ * and so does a bundle without one (a checkout mounted for a test). Needs
+ * `sh`, as the workspace hand-over already does.
+ */
+export function harnessNodeCommand(args: string[], harness = HARNESS_MOUNT): string[] {
+  return [
+    'sh',
+    '-c',
+    `if [ -x "${harness}/bin/node" ] && ! ls /lib/ld-musl-* >/dev/null 2>&1; then exec "${harness}/bin/node" "$@"; fi; exec node "$@"`,
+    'node',
+    ...args,
+  ];
+}
+/**
+ * Left in a fresh workspace by the hand-over below. The engine mounts an
+ * EMPTY volume by copying the image path's ownership over it — root, in an
+ * image without the directory — on every mount, so a bare chown would be
+ * undone by the step's own mount. A volume with a file in it is left alone.
+ */
+const WORKSPACE_MARKER = '.bevel-workspace';
+const STDERR_TAIL = 2_000;
+
+/** The image a Dockerfile's text builds to: one tag per content, so an unchanged file is never rebuilt. */
+export function imageTagFor(dockerfile: string): string {
+  return `${IMAGE_TAG_PREFIX}:${createHash('sha256').update(dockerfile).digest('hex').slice(0, 16)}`;
+}
+
+export function volumeNameFor(runId: string): string {
+  return `bevel-run-${runId}`;
+}
+
+export interface Executor extends ExecutorActivities {
+  /** Until when this executor refuses steps, or null. */
+  pausedUntil(): number | null;
+  /**
+   * Remove the workspace volumes of runs that are no longer open — the
+   * ones whose `releaseRun` never reached this executor (it was down when
+   * the run ended). `runIsOpen` asks the platform's Temporal. Returns the
+   * names removed.
+   */
+  /**
+   * Only volumes this executor's deployment made (see `deployment`), and
+   * nothing at all when the deployment is unknown and no `owner` narrows it.
+   * `owner`: a person's own executor sweeps only the volumes of that person's
+   * runs (labelled when made), and nothing while it does not know the person
+   * yet (`null`).
+   */
+  sweepVolumes(runIsOpen: (runId: string) => Promise<boolean>, owner?: string | null): Promise<string[]>;
+}
+
+export function createExecutor(options: ExecutorOptions): Executor {
+  const { driver, queueName } = options;
+  const log = options.log ?? (() => undefined);
+  const now = options.now ?? (() => Date.now());
+  const heartbeat = options.heartbeat ?? ((details?: unknown) => temporalHeartbeat(details));
+  // Outside an activity (a test, a dry run) there is no context and no signal.
+  const cancellation =
+    options.cancellation ??
+    (() => {
+      try {
+        return Context.current().cancellationSignal;
+      } catch {
+        return undefined;
+      }
+    });
+  const defaultPauseMs = options.defaultPauseMs ?? 30 * 60_000;
+  let pausedUntil: number | null = null;
+
+  async function imageFor(input: ContainerStepInput): Promise<string> {
+    if (input.dockerfile !== null) {
+      const tag = imageTagFor(input.dockerfile);
+      if (!(await driver.hasImage(tag))) {
+        log(`building ${tag} for ${input.step.workflowPath}`);
+        heartbeat('build');
+        await driver.buildImage(tag, input.dockerfile);
+      }
+      return tag;
+    }
+    const ref = input.image ?? 'node:22';
+    if (!(await driver.hasImage(ref))) {
+      log(`pulling ${ref}`);
+      heartbeat('pull');
+      await driver.pullImage(ref);
+    }
+    return ref;
+  }
+
+  return {
+    pausedUntil: () => (pausedUntil !== null && pausedUntil > now() ? pausedUntil : null),
+
+    async runContainerStep(input: ContainerStepInput): Promise<AgentStepOutcome> {
+      const until = pausedUntil !== null && pausedUntil > now() ? pausedUntil : null;
+      if (until !== null) {
+        // Retryable: the task comes back later, here or on another executor
+        // of the shared queue; the item is not charged.
+        // The reset time travels as the failure's detail: the run reads it
+        // and waits until then, as it does for a limit hit mid-step.
+        throw ApplicationFailure.retryable(`executor ${queueName} is paused until ${new Date(until).toISOString()}`, 'ExecutorPaused', until);
+      }
+
+      // Every outcome a step reaches once its workspace exists carries the
+      // pin: a limit hit on the first step would otherwise send the retry to
+      // any host. An environment that could not be made has no workspace to
+      // pin to, and stays unpinned on purpose.
+      const pin = (outcome: AgentStepOutcome): AgentStepOutcome =>
+        outcome.kind === 'verdict' || outcome.kind === 'no-verdict' || outcome.kind === 'timeout' || outcome.kind === 'account-limit' || outcome.kind === 'harness-error' ? { ...outcome, executorQueue: queueName } : outcome;
+      // What a container printed on stderr becomes a reason the platform
+      // stores, logs and mails: the secrets this executor handed the step (its
+      // `env:` and the run key) are scrubbed from it first, as `run-step`
+      // scrubs its own events. A crash that echoes the environment must not
+      // copy a vault value into a work item.
+      const redactor = new Redactor([...Object.values(input.env), input.actorKey.token]);
+      // Redacted whole, then cut: a secret straddling the cut would otherwise leave its suffix in the tail.
+      const stderrTail = (stderr: string): string => redactor.text(stderr).trim().slice(-STDERR_TAIL);
+
+      // Alive from the first moment to the last, the pull, the build and the workspace hand-over included:
+      // a cold build takes minutes, and a step silent that long is given up (a cancel is delivered on a heartbeat too).
+      const alive = setInterval(() => heartbeat('alive'), ALIVE_HEARTBEAT_MS);
+      alive.unref?.();
+      try {
+        return await runPrepared();
+      } finally {
+        clearInterval(alive);
+      }
+
+      async function runPrepared(): Promise<AgentStepOutcome> {
+      let image: string;
+      try {
+        image = await imageFor(input);
+      } catch (err) {
+        return { kind: 'harness-error', threadId: input.threadId, reason: `the environment could not be made: ${err instanceof Error ? err.message : String(err)}` };
+      }
+      const volume = volumeNameFor(input.step.runId);
+      const user = options.user ?? '1000:1000';
+      const labels = { [VOLUME_LABEL]: input.step.runId, 'software.bevel.thread': input.threadId };
+      const workspaceMount = { kind: 'volume' as const, source: volume, target: WORKSPACE_MOUNT, readonly: false };
+      if (await driver.ensureVolume(volume, { [VOLUME_LABEL]: input.step.runId, [OWNER_LABEL]: input.step.actor.userId, ...(options.deployment ? { [DEPLOYMENT_LABEL]: options.deployment } : {}) })) {
+        // A new volume is owned by root; the run user could not write it.
+        // One command as root, once, over the mount alone, hands it over —
+        // the only time anything runs as root here. The marker file keeps
+        // the volume from being empty (see WORKSPACE_MARKER).
+        const prepared = await driver.run({
+          name: `bevel-init-${input.step.runId}`,
+          image,
+          command: ['sh', '-c', 'touch "$2/$3" && chown -R "$1" "$2"', 'prepare', user, WORKSPACE_MOUNT, WORKSPACE_MARKER],
+          stdin: '',
+          env: {},
+          mounts: [workspaceMount],
+          workdir: '/',
+          user: '0:0',
+          limits: options.limits,
+          labels,
+          timeoutMs: 60_000,
+        });
+        if (prepared.exitCode !== 0) {
+          return pin({ kind: 'harness-error', threadId: input.threadId, reason: `the workspace could not be prepared (${prepared.exitCode ?? 'killed'}): ${stderrTail(prepared.stderr)}` });
+        }
+      }
+
+      // Cancelled while the image was pulled or built: the step never starts. (The pull or build itself runs to its end.)
+      if (cancellation()?.aborted) return { kind: 'harness-error', threadId: input.threadId, reason: 'the run was cancelled before the step started' };
+      const result = await driver.run({
+        name: `bevel-step-${input.threadId}-${input.step.attempt}`,
+        image,
+        operatorOptions: true,
+        command: harnessNodeCommand([`${HARNESS_MOUNT}/packages/ael/node_modules/tsx/dist/cli.mjs`, `${HARNESS_MOUNT}/packages/ael/src/cli/main.ts`, 'run-step']),
+        stdin: JSON.stringify(input),
+        env: { ...input.env, HOME: WORKSPACE_MOUNT },
+        mounts: [{ kind: options.harnessBundle.kind, source: options.harnessBundle.source, target: HARNESS_MOUNT, readonly: true }, workspaceMount],
+        workdir: WORKSPACE_MOUNT,
+        user,
+        limits: options.limits,
+        labels,
+        timeoutMs: input.timeoutMs,
+        // A cancelled run stops its container; the signal is the activity's own.
+        signal: cancellation(),
+        onAlive: () => heartbeat('alive'),
+      });
+
+      if (result.timedOut) {
+        return pin({ kind: 'timeout', threadId: input.threadId, reason: `the step exceeded its budget of ${Math.round(input.timeoutMs / 60_000)} minutes` });
+      }
+      const outcome = parseOutcomeLine(result.stdout);
+      if (!outcome) {
+        const tail = stderrTail(result.stderr);
+        return pin({ kind: 'harness-error', threadId: input.threadId, reason: `the container ended (${result.exitCode ?? 'killed'}) without an outcome${tail ? `: ${tail}` : ''}` });
+      }
+      if (outcome.kind === 'account-limit') {
+        pausedUntil = outcome.resetAt ?? now() + defaultPauseMs;
+        log(`paused until ${new Date(pausedUntil).toISOString()}: ${outcome.text}`);
+      }
+      return pin(outcome);
+      }
+    },
+
+    // The run is over, whatever its outcome: nothing reads the workspace
+    // again (the transcript is on the thread, the work is on the branch),
+    // so the volume goes now rather than after a grace period.
+    async releaseRun(input: { runId: string }): Promise<void> {
+      await driver.removeVolume(volumeNameFor(input.runId));
+      log(`released the workspace of run ${input.runId}`);
+    },
+
+    async sweepVolumes(runIsOpen: (runId: string) => Promise<boolean>, owner?: string | null): Promise<string[]> {
+      const removed: string[] = [];
+      // A person's own executor knows only that person's runs: another person's volume on the same engine is never its to judge.
+      if (owner === null) return removed;
+      // Another deployment's volume on the same engine belongs to runs our Temporal has never heard of: never ours to judge.
+      const deployment = options.deployment || null;
+      if (!deployment && owner === undefined) {
+        log('workspace sweep off: this executor does not know its deployment (set EXECUTOR_DEPLOYMENT)');
+        return removed;
+      }
+      for (const v of await driver.listVolumes(VOLUME_LABEL)) {
+        const runId = v.labels[VOLUME_LABEL];
+        if (deployment && v.labels[DEPLOYMENT_LABEL] !== deployment) continue;
+        if (owner !== undefined && v.labels[OWNER_LABEL] !== owner) continue;
+        // Age says nothing: a run parked on a gate keeps its workspace for weeks.
+        if (!runId || (await runIsOpen(runId))) continue;
+        await driver.removeVolume(v.name);
+        removed.push(v.name);
+      }
+      if (removed.length > 0) log(`removed ${removed.length} workspace volume${removed.length === 1 ? '' : 's'} of runs that are over`);
+      return removed;
+    },
+  };
+}