@bevel-software/ael 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/ael",
-  "version": "0.1.0",
+  "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": {

package/src/cli/main.ts

@@ -17,6 +17,12 @@ import { OUTCOME_MARKER, readAll, runStep } from './run-step.js';
  *                          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
@@ -50,12 +56,14 @@ export async function main(argv: string[]): Promise<number> {
       process.stdout.write(`${OUTCOME_MARKER}${JSON.stringify(outcome)}\n`);
       return 0;
     }
-    case 'executor': {
+    case 'executor':
+    case 'ci-executor':
+    case 'ci-worker': {
       const { executorMain } = await import('../executor/main.js');
-      return executorMain();
+      return executorMain(command, argv[1]);
     }
     default:
-      process.stderr.write('usage: bevel-agent run <file> [input] | run-step | executor\n');
+      process.stderr.write('usage: bevel-agent run <file> [input] | run-step | executor | ci-executor | ci-worker <run id>\n');
       return 2;
   }
 }

package/src/executor/main.ts

@@ -35,23 +35,55 @@ import { PERSONAL_EXECUTOR_NAME } from '../workflow/definition.js';
  *                           beyond the defaults, such as running a rootless Docker daemon inside a step.
  *                           Split on spaces and nothing else: no quoting, so no value with a space in it
  *
- * An executor inside a CI job, which is the environment already and ends with the work:
- *
  *   EXECUTOR_IN_PLACE       `true`: each step runs as a process of this executor, in a directory per run,
  *                           with no container engine; the engine settings above (bundle, limits, run
  *                           options, deployment) do not apply. One step at once unless EXECUTOR_MAX_STEPS says more
- *   EXECUTOR_EXIT_WHEN_IDLE seconds without a step after which the executor leaves (default: never)
- *   EXECUTOR_RUN            a run id: take that run's steps alone, one after another — a worker started
- *                           for one run, which leaves (EXECUTOR_EXIT_WHEN_IDLE) when the run waits or is over
- *   EXECUTOR_START_WORKER   a shell command: this executor runs no step. It looks for runs with a step
- *                           waiting and runs the command once per run, to start a worker elsewhere (another
- *                           pipeline); the command gets BEVEL_RUN_ID, BEVEL_WORKFLOW, BEVEL_STEP and
- *                           BEVEL_ENVIRONMENT (the workflow's `environment:` as written: the worker job to start)
+ *   EXECUTOR_EXIT_WHEN_IDLE seconds without work after which it leaves (default: never)
  *   EXECUTOR_TOKEN_FILE     a file holding the key, in place of EXECUTOR_TOKEN: read once and removed, so
  *                           a step running beside the executor finds it neither in a variable nor on disk
+ *
+ * In a CI pipeline the executor is two jobs under one name, each its own command, so neither can become
+ * the other through a variable set in the wrong place:
+ *
+ * `bevel-agent ci-executor` runs no step. It looks for runs with a step waiting and starts a worker for each:
+ *
+ *   EXECUTOR_START_WORKER   a shell command (required), run once per run, to start a worker elsewhere (another
+ *                           pipeline); it gets BEVEL_RUN_ID, BEVEL_WORKFLOW, BEVEL_STEP and BEVEL_ENVIRONMENT
+ *                           (the workflow's `environment:` as written: the worker job to start)
+ *   EXECUTOR_EXIT_WHEN_IDLE seconds without a waiting run after which it leaves (default 480)
+ *
+ * `bevel-agent ci-worker <run id>` takes that run's steps alone, one after another, each in place, and leaves
+ * when none comes — the run waits at a gate, or is over:
+ *
+ *   EXECUTOR_EXIT_WHEN_IDLE seconds without a step after which it leaves (default 90)
  */
-export async function executorMain(): Promise<number> {
+export type ExecutorRole = 'executor' | 'ci-executor' | 'ci-worker';
+
+/** A run id as an executor may name one. */
+const RUN_ID = /^[A-Za-z0-9_-]{1,80}$/;
+
+export async function executorMain(role: ExecutorRole = 'executor', runArg?: string): Promise<number> {
   const env = process.env;
+  // The role's own inputs first, before anything is read or removed: each command says what it lacks,
+  // and refuses the other one's settings rather than quietly becoming it.
+  const startWorker = env.EXECUTOR_START_WORKER?.trim();
+  const run = runArg?.trim();
+  if (role === 'executor' && (startWorker || env.EXECUTOR_RUN?.trim())) {
+    process.stderr.write('EXECUTOR_START_WORKER and EXECUTOR_RUN are not settings of `bevel-agent executor`: a CI pipeline runs `bevel-agent ci-executor` (starts workers) and `bevel-agent ci-worker <run id>` (works one run)\n');
+    return 2;
+  }
+  if (role === 'ci-executor' && !startWorker) {
+    process.stderr.write('EXECUTOR_START_WORKER is required for `bevel-agent ci-executor`: the command that starts a worker pipeline for a run (it gets BEVEL_RUN_ID and BEVEL_ENVIRONMENT)\n');
+    return 2;
+  }
+  if (role === 'ci-worker' && startWorker) {
+    process.stderr.write('EXECUTOR_START_WORKER is set on a worker job: a worker that started workers would start pipelines without end. Set it on the `bevel-agent ci-executor` job alone\n');
+    return 2;
+  }
+  if (role === 'ci-worker' && (!run || !RUN_ID.test(run))) {
+    process.stderr.write('usage: bevel-agent ci-worker <run id> — the run this worker was started for (BEVEL_RUN_ID of the command that started it)\n');
+    return 2;
+  }
   const platformUrl = env.PLATFORM_URL?.trim().replace(/\/+$/, '');
   if (!platformUrl) {
     process.stderr.write("PLATFORM_URL is required: the platform's address, which every executor asks for its steps\n");
@@ -92,14 +124,14 @@ export async function executorMain(): Promise<number> {
   const kind = rawKind;
   const log = (line: string) => process.stderr.write(`[executor ${name}] ${line}\n`);
   const idleSeconds = Number(env.EXECUTOR_EXIT_WHEN_IDLE);
-  const exitWhenIdleMs = Number.isFinite(idleSeconds) && idleSeconds > 0 ? idleSeconds * 1000 : undefined;
+  // A CI job ends by itself, set or not: one that stayed would hold a runner until the job's own limit.
+  const idleDefaultMs = role === 'ci-executor' ? 480_000 : role === 'ci-worker' ? 90_000 : undefined;
+  const exitWhenIdleMs = Number.isFinite(idleSeconds) && idleSeconds > 0 ? idleSeconds * 1000 : idleDefaultMs;
   const queueName = kind === 'deployment' ? `executor-${name}` : `personal-${name}`;
   const stop = new AbortController();
   process.once('SIGINT', () => stop.abort());
   process.once('SIGTERM', () => stop.abort());
-  const run = env.EXECUTOR_RUN?.trim() || undefined;
-  const startWorker = env.EXECUTOR_START_WORKER?.trim();
-  if (startWorker) {
+  if (role === 'ci-executor' && startWorker) {
     await runWorkerStarter(
       {
         apiUrl: `${platformUrl}/api`,
@@ -116,7 +148,8 @@ export async function executorMain(): Promise<number> {
     log('stopped');
     return 0;
   }
-  if (/^(1|true|yes)$/i.test(env.EXECUTOR_IN_PLACE?.trim() ?? '')) {
+  // A worker's job is the environment, always: there is no engine in it to ask for a container.
+  if (role === 'ci-worker' || /^(1|true|yes)$/i.test(env.EXECUTOR_IN_PLACE?.trim() ?? '')) {
     const executor = createInPlaceExecutor({
       queueName,
       workspacesDir: path.join(tmpdir(), 'bevel-runs'),
@@ -126,7 +159,7 @@ export async function executorMain(): Promise<number> {
       cancellation: personalExecutorHooks.cancellation,
     });
     log('steps run in place: as processes of this executor, with no container engine');
-    await runPersonalExecutor({ apiUrl: `${platformUrl}/api`, token, name, kind, slots: Number(env.EXECUTOR_MAX_STEPS) || 1, executor, log, exitWhenIdleMs, run }, stop.signal);
+    await runPersonalExecutor({ apiUrl: `${platformUrl}/api`, token, name, kind, slots: Number(env.EXECUTOR_MAX_STEPS) || 1, executor, log, exitWhenIdleMs, ...(role === 'ci-worker' ? { run } : {}) }, stop.signal);
     log('stopped');
     return 0;
   }
@@ -150,7 +183,7 @@ export async function executorMain(): Promise<number> {
     heartbeat: personalExecutorHooks.heartbeat,
     cancellation: personalExecutorHooks.cancellation,
   });
-  await runPersonalExecutor({ apiUrl: `${platformUrl}/api`, token, name, kind, slots: Number(env.EXECUTOR_MAX_STEPS) || 2, executor, log, exitWhenIdleMs, run }, stop.signal);
+  await runPersonalExecutor({ apiUrl: `${platformUrl}/api`, token, name, kind, slots: Number(env.EXECUTOR_MAX_STEPS) || 2, executor, log, exitWhenIdleMs }, stop.signal);
   log('stopped');
   return 0;
 }