@bevel-software/ael 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026 Bevelites GmbH. All rights reserved.
+
+This software and its source code are the property of Bevelites GmbH.
+They are published so that customers of Bevelites GmbH can install and
+run them. This software may be used only by those who have a contract
+with Bevelites GmbH, and only as that contract allows. No other licence
+to copy, modify, distribute or use it is granted.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+BEVELITES GMBH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @bevel-software/ael
+
+The agentic execution layer of the Bevel platform: everything that reads an
+`.agent` or a `.workflow` file and everything that runs a session from them.
+The platform imports it, run containers mount it, and `bevel-agent` is it.
+
+Shipped as TypeScript source (`main` is `src/index.ts`), like the platform's
+core frontend: the platform and the executor image run it with `tsx`.
+
+## What is in it
+
+- `.agent` and `.workflow` parsers (`parseAgentFile`, `parseWorkflowFile`):
+  the one reader of both file kinds.
+- The run contract: `RunInput`, `RunEvent`, `SessionState`, `Harness`.
+- The interpreter and the dispatchers, Temporal workflows the platform's
+  worker bundles from `@bevel-software/ael/workflows`.
+- The pi in-process harness, with the platform's tools over MCP.
+- The executor: `createExecutor` over a `ContainerDriver`, and the Docker
+  command driver.
+- `bevel-agent`: `run <file>` (a workflow file, locally, against a platform),
+  `run-step` (what an executor execs in a run container), `executor`.
+
+## Running a workflow file locally
+
+```
+BEVEL_API_URL=https://kb.example.com/api BEVEL_CONNECTION_KEY=bevel_… \
+  npx bevel-agent run Workflows/nightly.workflow "the input"
+```
+
+Agent steps only, on the happy path, with pi's tools on the working
+directory; the file's `env:` comes from your environment by name. Gates,
+tool chains, choices and work items are the platform's.

package/bin/bevel-agent.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// `bevel-agent` as npm installs it. The command line is TypeScript, which
+// plain Node does not run, so tsx is registered first and the entry loaded
+// through it — the same tsx the executor image and the run containers use.
+import { register } from 'tsx/esm/api';
+
+register();
+const { main } = await import('../src/cli/main.ts');
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exit(1);
+  },
+);

package/executor-entrypoint.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+set -e
+
+# EXECUTOR_ENABLED=false keeps this host out of container steps: the
+# container stays up doing nothing, so the deployment sees a healthy
+# service and nothing restarts it in a loop, and it polls no queue and
+# touches neither the engine nor the harness volume. The platform's own
+# compose file runs an executor beside the platform by default; this is
+# the switch for a host that should run none.
+case "$(printf '%s' "${EXECUTOR_ENABLED:-true}" | tr '[:upper:]' '[:lower:]')" in
+  false|0|no|off)
+    echo "[executor] disabled on this host (EXECUTOR_ENABLED=${EXECUTOR_ENABLED}): container steps run on other executors"
+    exec sleep infinity
+    ;;
+esac
+
+# No connection key yet: the executor beside the platform comes up with it,
+# before anyone could make one there — said once, then idle, instead of
+# exiting into a restart loop. The key (made by hand on the platform by an
+# Infrastructure Engineer, or by the person for their own executor) turns it
+# on at the next start.
+if [ -z "$(printf '%s' "${EXECUTOR_TOKEN:-}" | tr -d '[:space:]')" ]; then
+  echo "[executor] EXECUTOR_TOKEN is not set — this executor is off; make a connection key on the platform, set it as EXECUTOR_TOKEN and restart"
+  exec sleep infinity
+fi
+
+# Fill the harness volume with this image's bundle, then run the executor.
+# The volume is what run containers mount at /harness; refreshing it at every
+# start is how a new executor image reaches the runs.
+BUNDLE_DIR="${HARNESS_BUNDLE_DIR:-/harness}"
+if [ -d "$BUNDLE_DIR" ]; then
+  echo "[executor] refreshing the harness bundle in $BUNDLE_DIR"
+  rm -rf "$BUNDLE_DIR/packages" "$BUNDLE_DIR/node_modules" "$BUNDLE_DIR/package.json" "$BUNDLE_DIR/bin"
+  cp -R /app/packages /app/node_modules /app/package.json "$BUNDLE_DIR/"
+  # This image's own node, so a run image needs none: a glibc image runs the
+  # harness on it; an Alpine one uses its own node (see harnessNodeCommand).
+  mkdir -p "$BUNDLE_DIR/bin"
+  cp "$(command -v node)" "$BUNDLE_DIR/bin/node"
+fi
+
+exec node /app/packages/ael/node_modules/tsx/dist/cli.mjs /app/packages/ael/src/cli/main.ts executor "$@"

package/executor.Dockerfile

@@ -0,0 +1,37 @@
+# The executor: one container per server, polling the platform's Temporal
+# and running workflow steps as containers on this host's engine. Built from
+# the repository root:
+#
+#   docker build -f packages/ael/executor.Dockerfile -t bevel-executor .
+#
+# It carries the harness bundle (this library, its dependencies, tsx) and
+# copies it into the `bevel-harness` volume at start, with this image's own
+# node, which every run container then mounts read-only at /harness — so a
+# glibc run image needs nothing installed (an Alpine one brings its own Node
+# 22). The engine's socket is mounted into THIS container only, never into a
+# run container. With PLATFORM_URL set it is a person's own executor, asking
+# the platform over HTTPS for their steps (docker-compose.personal-executor.yml).
+FROM node:22-slim
+
+RUN corepack enable && corepack prepare pnpm@10.33.3 --activate
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl gnupg \
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc \
+    && chmod a+r /etc/apt/keyrings/docker.asc \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo $VERSION_CODENAME) stable" > /etc/apt/sources.list.d/docker.list \
+    && apt-get update && apt-get install -y --no-install-recommends docker-ce-cli \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
+COPY packages/ael/package.json packages/ael/
+# The backend and frontend are workspace members pnpm must see to resolve the lockfile.
+COPY packages/backend/package.json packages/backend/
+COPY packages/frontend/package.json packages/frontend/
+RUN pnpm install --frozen-lockfile --prod --filter @bevel-software/ael...
+COPY packages/ael/ packages/ael/
+COPY packages/ael/executor-entrypoint.sh /usr/local/bin/executor-entrypoint
+RUN chmod +x /usr/local/bin/executor-entrypoint
+
+ENV HARNESS_BUNDLE_VOLUME=bevel-harness
+ENTRYPOINT ["executor-entrypoint"]

package/package.json

@@ -1,6 +1,61 @@
-{
-  "name": "@bevel-software/ael",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@bevel-software/ael",
+  "version": "0.2.0",
+  "description": "The agentic execution layer of the Bevel platform: the one parser for .agent and .workflow files, the run contract, the harnesses, the interpreter the platform runs on Temporal, the executor, and the bevel-agent command line.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bevel-Software/bevel-platform.git",
+    "directory": "packages/ael"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "bin",
+    "src",
+    "!src/**/__tests__",
+    "executor.Dockerfile",
+    "executor-entrypoint.sh",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./workflows": "./src/interpreter/workflows.ts",
+    "./schedule": "./src/shared/schedule.ts",
+    "./contract": "./src/run/contract.ts",
+    "./cli": "./src/cli/main.ts"
+  },
+  "bin": {
+    "bevel-agent": "./bin/bevel-agent.mjs"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-code": "2.1.319",
+    "@bevel-software/hexis-mcp": "0.37.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@temporalio/activity": "1.25.0",
+    "@temporalio/client": "1.25.0",
+    "@temporalio/common": "1.25.0",
+    "@temporalio/worker": "1.25.0",
+    "@temporalio/workflow": "1.25.0",
+    "tsx": "^4.19.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@temporalio/testing": "1.25.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.1.9",
+    "zod": "^3.24.0"
+  }
+}

package/src/agent/agent-file.ts

@@ -0,0 +1,242 @@
+import { optionalStr, plainObject, yamlDocumentOf } from '../shared/front-matter.js';
+
+/**
+ * The one parser of an `.agent` file: *who* an agent is.
+ *
+ * It replaces three readers that each took the keys their question needed —
+ * the execution layer's (harness, model, tools, env), the platform's `env:`
+ * allowlist reader (agent-defs) and the connect-as reader of the four narrowing
+ * lists (agent-scope). One definition now carries every field; a caller acts
+ * on the part it owns (the platform on `env:` and the narrowing lists, a
+ * harness on the model and the tool surface) and ignores the rest.
+ *
+ * Same document shape as `.workflow` and `.tool`: one `---` fenced YAML block
+ * with the access verbs inside it, prose after the fence.
+ */
+
+export const AGENT_FILE_EXTENSION = '.agent';
+
+/** Where an `env:` entry's value comes from. */
+export type EnvSource = 'params' | 'vault';
+
+export interface AgentEnvVar {
+  name: string;
+  from: EnvSource;
+  /**
+   * `from: params` only: the run parameter to read when it is not spelled like
+   * the variable (`STAGING_URL` reads `stagingUrl`). Defaults to the name.
+   */
+  param?: string;
+  /** `from: vault` only: the label the secrets panel shows for the entry. */
+  label?: string;
+}
+
+/** The harnesses a session may run on. `pi` runs in-process or in a container; `claude-code` in a container. */
+export type HarnessName = 'pi' | 'claude-code';
+
+export interface AgentDefinition {
+  /** Lowercase snake_case id — also the vault namespace its secrets live under. */
+  id: string;
+  /** One line, at most `AGENT_NAME_MAX` characters. */
+  name: string;
+  /** One line, at most `AGENT_DESCRIPTION_MAX` characters; empty when there is none. */
+  description: string;
+  harness: HarnessName;
+  /**
+   * In the harness's own spelling: a Claude model id for `claude-code`;
+   * `provider/id`, optionally `:<thinking>`, for `pi`. Absent means the
+   * deployment's default model on its gateway.
+   */
+  model?: string;
+  /**
+   * `pi` only: pi's `models.json` `providers` map, verbatim, for a provider
+   * pi's catalog does not carry. Keys, never values: `"$NAME"` reads the
+   * session's environment, which is the `env:` block below.
+   */
+  providers?: Record<string, unknown>;
+  systemPrompt?: { skill?: string; extend?: string };
+  /** Skill folders the agent may load (a parent folder means every skill under it). */
+  skills: string[];
+  /** Plugin folders whose tools and MCP servers come along. */
+  plugins: string[];
+  /** `.tool` files and MCP server definitions (a folder means every connector under it). */
+  connectors: string[];
+  /**
+   * Names of the platform's own tools the agent may call; null when the key is
+   * not written (every platform tool), empty when written empty (none).
+   */
+  platformTools: string[] | null;
+  /** Tool names the HARNESS may enable (`tools.allow`, or `harnessTools`). Empty means the harness default. */
+  harnessTools: string[];
+  env: AgentEnvVar[];
+}
+
+/** An `.agent` that cannot be read as a definition. The message never quotes the file's secrets. */
+export class AgentParseError extends Error {}
+
+/** The longest `name` an agent is shown by. */
+export const AGENT_NAME_MAX = 80;
+/** The longest `description` an agent is shown with. */
+export const AGENT_DESCRIPTION_MAX = 300;
+/**
+ * How many `env:` entries one file may declare. Author-written input: a cap
+ * keeps a mistaken paste from turning the secrets panel into a wall.
+ */
+export const MAX_ENV_VARIABLES = 50;
+
+const SUPPORTED_HARNESSES: readonly HarnessName[] = ['pi', 'claude-code'];
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function obj(value: unknown, what: string): Record<string, unknown> {
+  return plainObject(value, what, (message) => new AgentParseError(message));
+}
+
+/** A frontmatter string folded to one trimmed line of at most `max` characters; empty for anything else. */
+function foldLine(value: unknown, max: number): string {
+  if (typeof value !== 'string') return '';
+  return value.replace(/\s+/g, ' ').trim().slice(0, max).trim();
+}
+
+/** A list written as a YAML list or, for one entry, as a plain string. Anything else is an error, never "empty". */
+function entries(root: Record<string, unknown>, key: string): string[] {
+  const value = root[key];
+  if (value === undefined || value === null) return [];
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value) && value.every((v) => typeof v === 'string')) return value as string[];
+  throw new AgentParseError(`\`${key}\` must be a list of names`);
+}
+
+function names(root: Record<string, unknown>, key: string): string[] {
+  return entries(root, key).map((v) => v.trim()).filter(Boolean);
+}
+
+function pathList(root: Record<string, unknown>, key: string): string[] {
+  return entries(root, key).flatMap((raw) => {
+    const normalized = normalizeEntryPath(raw);
+    return normalized === null ? [] : [normalized];
+  });
+}
+
+/**
+ * An entry as a repo-relative path with no leading or trailing slash, or null
+ * when it names nothing that can be matched (empty, or climbing out). A `.`
+ * segment names the folder it is in, so `./Skills/x` is `Skills/x`.
+ */
+export function normalizeEntryPath(raw: string): string | null {
+  const p = raw.trim().replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '').replace(/\/{2,}/g, '/');
+  if (!p) return null;
+  const segments = p.split('/').filter((s) => s !== '.');
+  if (segments.length === 0 || segments.some((s) => s === '..')) return null;
+  return segments.join('/');
+}
+
+/** `delivery-coder` → `delivery_coder`. The vault namespace; must stay injective enough for a listing. */
+export function agentSlug(raw: string): string {
+  const slug = raw.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  if (!slug || /^[0-9]/.test(slug)) return `agent_${slug}`;
+  return slug;
+}
+
+function parseEnv(value: unknown): AgentEnvVar[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new AgentParseError('`env` must be an array');
+  if (value.length > MAX_ENV_VARIABLES) {
+    throw new AgentParseError(`\`env\` declares ${value.length} variables (max ${MAX_ENV_VARIABLES})`);
+  }
+  const seen = new Set<string>();
+  return value.map((raw, i) => {
+    const e = obj(raw, `\`env[${i}]\``);
+    const name = optionalStr(e.name) ?? '';
+    // POSIX environment variable grammar: anything else cannot be exported to a
+    // process reliably, whatever the file says.
+    if (!ENV_NAME.test(name)) throw new AgentParseError(`\`env[${i}].name\` "${name}" must match [A-Za-z_][A-Za-z0-9_]*`);
+    if (seen.has(name)) throw new AgentParseError(`duplicate env variable "${name}"`);
+    seen.add(name);
+    const from = optionalStr(e.from)?.toLowerCase();
+    if (from !== 'params' && from !== 'vault') {
+      throw new AgentParseError(`env variable "${name}" needs \`from: params\` or \`from: vault\``);
+    }
+    const param = optionalStr(e.param);
+    if (param !== undefined && from !== 'params') {
+      throw new AgentParseError(`env variable "${name}": \`param\` only applies to \`from: params\``);
+    }
+    const label = optionalStr(e.label);
+    if (label !== undefined && from !== 'vault') {
+      throw new AgentParseError(`env variable "${name}": \`label\` only applies to \`from: vault\``);
+    }
+    return { name, from, ...(param ? { param } : {}), ...(label ? { label } : {}) };
+  });
+}
+
+/**
+ * Parse an `.agent` file. `path` is the file's repo-relative path; it supplies
+ * the fallback name and id and appears in error messages.
+ */
+export function parseAgentFile(content: string, path: string): AgentDefinition {
+  let document: unknown;
+  try {
+    document = yamlDocumentOf(content);
+  } catch (err) {
+    throw new AgentParseError(`\`.agent\` ${path} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const root = obj(document, `\`.agent\` ${path}`);
+
+  const file = path.slice(path.lastIndexOf('/') + 1);
+  const base = file.endsWith(AGENT_FILE_EXTENSION) ? file.slice(0, -AGENT_FILE_EXTENSION.length) : file;
+  const name = foldLine(root.name, AGENT_NAME_MAX) || foldLine(base, AGENT_NAME_MAX);
+  const id = optionalStr(root.id) ?? agentSlug(name);
+  if (!/^[a-z0-9][a-z0-9_]*$/.test(id)) {
+    throw new AgentParseError(`\`.agent\` ${path}: id "${id}" must be lowercase snake_case`);
+  }
+
+  const harness = (optionalStr(root.harness) ?? 'pi') as HarnessName;
+  if (!SUPPORTED_HARNESSES.includes(harness)) {
+    // Loudly, at load time: a harness nothing can run is a configuration
+    // error, and the first live step is the wrong place to find it.
+    throw new AgentParseError(
+      `\`.agent\` ${path} declares harness "${harness}" (supported: ${SUPPORTED_HARNESSES.join(', ')})`,
+    );
+  }
+
+  const model = optionalStr(root.model);
+  let providers: Record<string, unknown> | undefined;
+  if (root.providers !== undefined) {
+    if (harness !== 'pi') {
+      throw new AgentParseError(`\`.agent\` ${path}: \`providers\` is pi's models.json and applies to harness pi only`);
+    }
+    providers = obj(root.providers, `\`.agent\` ${path} \`providers\``);
+  }
+
+  let systemPrompt: AgentDefinition['systemPrompt'];
+  if (root.systemPrompt !== undefined) {
+    const sp = obj(root.systemPrompt, `\`.agent\` ${path} \`systemPrompt\``);
+    const skill = optionalStr(sp.skill);
+    const extend = optionalStr(sp.extend);
+    systemPrompt = { ...(skill ? { skill } : {}), ...(extend ? { extend } : {}) };
+  }
+
+  // `tools.allow` is the spelling the execution layer used; `harnessTools` the
+  // one the platform's agent guide documents. Both are read, neither required.
+  const tools = root.tools === undefined ? {} : obj(root.tools, `\`.agent\` ${path} \`tools\``);
+  const harnessTools = [...names(tools, 'allow'), ...names(root, 'harnessTools')];
+
+  return {
+    id,
+    name,
+    description: foldLine(root.description, AGENT_DESCRIPTION_MAX),
+    harness,
+    ...(model ? { model } : {}),
+    ...(providers ? { providers } : {}),
+    ...(systemPrompt ? { systemPrompt } : {}),
+    skills: pathList(root, 'skills').map((p) => p.replace(/\/SKILL\.md$/i, '')),
+    plugins: pathList(root, 'plugins'),
+    connectors: pathList(root, 'connectors'),
+    // Only a key that is not written at all means every platform tool. A key
+    // written with no value (`platformTools:`, YAML null) or as `[]` is the
+    // author clearing the list: an agent that meant to offer nothing must
+    // never be read as offering everything.
+    platformTools: Object.prototype.hasOwnProperty.call(root, 'platformTools') ? names(root, 'platformTools') : null,
+    harnessTools,
+    env: parseEnv(root.env),
+  };
+}

package/src/cli/main.ts

@@ -0,0 +1,81 @@
+import { pathToFileURL } from 'node:url';
+import type { ContainerStepInput } from '../interpreter/contract.js';
+import { formatEvent, runLocally } from './run-local.js';
+import { OUTCOME_MARKER, readAll, runStep } from './run-step.js';
+
+/**
+ * `bevel-agent`: the library's command line.
+ *
+ *   bevel-agent run <file> [input]
+ *                          a workflow file run here, against a platform:
+ *                          BEVEL_API_URL (the API root) and BEVEL_CONNECTION_KEY
+ *                          in the environment, BEVEL_GATEWAY_MODEL optional.
+ *                          Agent steps only, on the happy path; the file's
+ *                          `env:` from this environment by name.
+ *   bevel-agent run-step   one container step: the prepared input on stdin,
+ *                          the outcome as the marked last line of stdout.
+ *                          What an executor execs inside a run container.
+ *   bevel-agent executor   an executor on this host: polls the executor
+ *                          queues and runs container steps on its engine.
+ *   bevel-agent ci-executor
+ *                          the executor job of a CI pipeline: runs no step,
+ *                          starts a worker pipeline per run with work.
+ *   bevel-agent ci-worker <run id>
+ *                          a worker job of a CI pipeline: that run's steps,
+ *                          in the job itself, until it waits or is over.
+ *
+ * Two doors in: `bin/bevel-agent.mjs` (what npm installs; registers tsx and
+ * calls `main`), and this file as the script tsx runs directly (the executor
+ * image and the run containers).
+ */
+export async function main(argv: string[]): Promise<number> {
+  const [command] = argv;
+  switch (command) {
+    case 'run': {
+      const file = argv[1];
+      const apiUrl = process.env.BEVEL_API_URL?.trim();
+      const token = process.env.BEVEL_CONNECTION_KEY?.trim();
+      if (!file || !apiUrl || !token) {
+        process.stderr.write('usage: BEVEL_API_URL=<api root> BEVEL_CONNECTION_KEY=<key> bevel-agent run <file.workflow> [input]\n');
+        return 2;
+      }
+      const result = await runLocally(file, {
+        apiUrl,
+        token,
+        gatewayModel: process.env.BEVEL_GATEWAY_MODEL?.trim() || undefined,
+        input: argv.slice(2).join(' ') || undefined,
+        onEvent: (step, event) => process.stderr.write(`${formatEvent(step, event)}\n`),
+      });
+      for (const step of result.steps) process.stdout.write(`${step.name}: ${step.outcome}${step.reason ? ` — ${step.reason}` : ''}\n`);
+      process.stdout.write(`${result.status}\n`);
+      return result.status === 'done' ? 0 : 1;
+    }
+    case 'run-step': {
+      const input = JSON.parse(await readAll(process.stdin)) as ContainerStepInput;
+      const outcome = await runStep(input, { cwd: process.cwd(), log: (line) => process.stderr.write(`[run-step] ${line}\n`) });
+      process.stdout.write(`${OUTCOME_MARKER}${JSON.stringify(outcome)}\n`);
+      return 0;
+    }
+    case 'executor':
+    case 'ci-executor':
+    case 'ci-worker': {
+      const { executorMain } = await import('../executor/main.js');
+      return executorMain(command, argv[1]);
+    }
+    default:
+      process.stderr.write('usage: bevel-agent run <file> [input] | run-step | executor | ci-executor | ci-worker <run id>\n');
+      return 2;
+  }
+}
+
+// Run only when this file IS the script (`tsx main.ts …`); imported by the
+// bin wrapper or a test, it does nothing on its own.
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+      process.exit(1);
+    },
+  );
+}