bunqueue-dashboard 0.0.34 → 0.0.36

package/README.md

@@ -90,12 +90,14 @@ The full dashboard running on sample data, no server needed.
 bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and
 error-prone. This dashboard is a production-oriented operator console: it exposes the verified,
 safe subset of the API, fails closed where
-[v2.8.55](https://github.com/egeominotti/bunqueue/releases/tag/v2.8.55) lacks atomic
+[v2.8.57](https://github.com/egeominotti/bunqueue/releases/tag/v2.8.57) lacks atomic
 flow-safety guarantees, and also manages the
 server *process* through a separate guarded agent.
 
-It talks **only** to bunqueue's public HTTP API (`:6790`) and a small local **control agent**. It
-never imports or modifies bunqueue itself, so it tracks any bunqueue server you point it at.
+It uses Bunqueue's public HTTP API (`:6790`) for ordinary remote observability and a small local
+**control agent** for process, FlowProducer, Workflow Engine, database, and backup operations. The
+agent is pinned to the server it manages and uses the exact installed Bunqueue 2.8.57 client
+contracts; it never patches Bunqueue internals.
 
 ## Features
 
@@ -105,14 +107,17 @@ never imports or modifies bunqueue itself, so it tracks any bunqueue server you
 | **Server** | Control ▸ Server | **Start / stop / restart** the server process, edit its config, tail process logs |
 | **Enqueue** | Control ▸ Add Job | Add jobs (single or bulk) with every option |
 | **Inspect** | Control ▸ Job Inspector | Look up any job; promote / re-prioritize / delay; view data & result |
-| **Queues** | Control ▸ Queue Control | Pause / resume / promote, explicit desired-state limits, stall config & guarded DLQ policy |
+| **Queues** | Control ▸ Queue Control | Pause/resume/promote; desired-state writes plus live SDK limits, deduplication, metrics and journal retention |
 | **Cron** | Control ▸ Cron Manager | Submit acknowledged cron/interval upserts and delete schedules |
+| **Workflow Engine** | Workflow ▸ Overview / Executions / Waiting / Compensation / Archive | Start, recover, signal, inspect, compensate, archive and clean durable executions |
+| **Job Flows** | Workflow ▸ Job Flows | Explore DAGs, run all FlowProducer create modes and operate safe Flow Job methods |
 | **DLQ** | Control ▸ DLQ | Inspect entries, failure history and CSV exports; retry and purge stay unavailable |
 | **Webhooks** | Control ▸ Webhooks | Create / enable / delete job-event webhooks |
 | **Ops** | Control ▸ Diagnostics | Health, ping, storage, memory, connections, totals |
+| **S3 backup** | Management ▸ S3 Backup | Configure, inspect, list, create and guarded-restore official snapshots |
 | **Browse** | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |
 
-> Job actions are gated by the v2.8.55 flow contract. Every DLQ retry and completed-job requeue is
+> Job actions are gated by the v2.8.57 flow contract. Every DLQ retry and completed-job requeue is
 > unavailable: the DLQ GET + POST sequence has no atomic generation/state/topology precondition and
 > can target a job recreated under the same ID, while `retryCompleted` does not rebuild dependency
 > registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail
@@ -130,7 +135,7 @@ agent start one for you from the **Server** page).
 bunx bunqueue-dashboard
 ```
 
-One command, **zero dependencies** (a 543 kB download): serves the prebuilt dashboard on
+One command serves the prebuilt dashboard on
 http://127.0.0.1:8080, proxies `/api/*` to your bunqueue server (`BUNQUEUE_URL`, default
 `http://localhost:6790`), and runs the control agent on `127.0.0.1:6800`. Same env knobs as the
 standalone binaries: `PORT` · `BIND_ADDR` · `BUNQUEUE_URL` · `AGENT_PORT` ·
@@ -271,14 +276,15 @@ Because the deployed build is a static shell, point it at a reachable bunqueue s
 
 ## Testing & quality gate
 
-Three commands must be green before a change is considered done, the same checks CI runs:
+The canonical gate must be green before a change is considered done; CI runs the same command:
 
 ```bash
-bun run build     # tsc --noEmit + vite build
-bun run check     # Biome lint + format (production-grade config)
-bun test          # unit + agent-lifecycle tests
+bun run quality   # architecture, lint/build, size, docs, coverage, real E2E, packed-bin smoke, audit
 ```
 
+The E2E stage starts disposable Bunqueue 2.8.57 processes and exercises the complete FlowProducer,
+Workflow Engine, and Queue SDK operator bridges. Run it alone with `bun run test:e2e`.
+
 CI enforces this on every push and pull request. See [Contributing](#contributing).
 
 ## Project structure
@@ -286,15 +292,16 @@ CI enforces this on every push and pull request. See [Contributing](#contributin
 ```
 bunqueue-dashboard/
 ├── .github/workflows/   # CI, Pages deploy, Docker publish, Release
-├── agent/               # Bun control agent (process lifecycle), server.ts, manager.ts, index.ts
+├── agent/               # guarded process, Flow, Workflow, Queue, database and backup adapters
 ├── docker/              # Caddyfile for the container image
 ├── docs/                # source-verified reference (architecture, pages, API mapping, known issues)
 ├── scripts/dev.ts       # one-command dev launcher (`bun start`)
 ├── src/
 │   ├── lib/             # api.ts, bq.ts, hooks, formatters, job-action gating
 │   ├── components/      # layout shell, UI kit, Zustand stores
+│   ├── features/        # feature slices with domain, application, infrastructure and UI layers
 │   └── pages/           # view pages + Control ▸ * operator pages
-└── test/                # bun test (format, sse, manager, agent lifecycle, s3 store)
+└── test/                # unit, contract, UI race, agent lifecycle and integration tests
 ```
 
 Full walkthrough in [`docs/README.md`](docs/README.md).
@@ -320,7 +327,7 @@ boundary applies only to `scripts/serve.ts`. Host/Origin checks are not user aut
 
 1. Keep it **additive**, prefer new files + minimal glue over rewriting existing ones
    (see [`CLAUDE.md`](CLAUDE.md)).
-2. Make the [gate](#testing--quality-gate) green: `bun run build && bun run check && bun test`.
+2. Make the [gate](#testing--quality-gate) green: `bun run quality`.
 3. Open a PR, the template walks you through the checklist. CI must pass.
 
 ## License

package/agent/backup/processExecutor.ts

@@ -0,0 +1,90 @@
+import { fileURLToPath } from 'node:url';
+import type { BackupOperation } from './runner';
+
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+export async function executeBackupProcess(
+  environment: Record<string, string>,
+  operation: BackupOperation,
+  key: string | undefined,
+  signal: AbortSignal
+): Promise<unknown> {
+  signal.throwIfAborted();
+  const bun = Bun.which('bun');
+  if (!bun) throw new Error('The Bun executable is required to run Bunqueue backup commands');
+  const child = Bun.spawn(
+    [
+      bun,
+      bunqueueCliPath(),
+      '--json',
+      'backup',
+      operation,
+      ...(operation === 'restore' ? [key as string, '--force'] : []),
+    ],
+    { env: environment, stdout: 'pipe', stderr: 'pipe' }
+  );
+  const abort = () => child.kill('SIGKILL');
+  signal.addEventListener('abort', abort, { once: true });
+  try {
+    let stdout: string;
+    let stderr: string;
+    let exitCode: number;
+    try {
+      [stdout, stderr, exitCode] = await Promise.all([
+        readBounded(child.stdout),
+        readBounded(child.stderr),
+        child.exited,
+      ]);
+    } catch (error) {
+      child.kill('SIGKILL');
+      await child.exited;
+      throw error;
+    }
+    if (signal.aborted) throw abortReason(signal);
+    const raw = stdout.trim() || stderr.trim();
+    try {
+      return JSON.parse(raw);
+    } catch {
+      throw new Error(
+        exitCode === 0
+          ? 'Bunqueue backup command returned malformed JSON'
+          : `Bunqueue backup command failed with exit code ${exitCode}`
+      );
+    }
+  } finally {
+    signal.removeEventListener('abort', abort);
+  }
+}
+
+function bunqueueCliPath(): string {
+  const main = import.meta.resolve('bunqueue');
+  return fileURLToPath(new URL('./cli/index.js', main));
+}
+
+async function readBounded(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      total += next.value.byteLength;
+      if (total > MAX_OUTPUT_BYTES) throw new Error('Bunqueue backup command output exceeded 2 MiB');
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const output = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(output);
+}
+
+function abortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error('Backup operation cancelled');
+}

package/agent/backup/resultValidation.ts

@@ -0,0 +1,85 @@
+import type { BackupCommandResult, BackupOperation } from './runner';
+
+const RESULT_KEYS = new Set(['success', 'message', 'data']);
+const STATUS_KEYS = new Set(['enabled', 'bucket', 'endpoint', 'interval', 'retention']);
+const ITEM_KEYS = new Set(['key', 'size', 'date']);
+const MAX_MESSAGE_LENGTH = 16 * 1024;
+const MAX_LIST_ITEMS = 20_000;
+const MAX_LIST_TEXT = 2 * 1024 * 1024;
+
+export function validateBackupResult(
+  value: unknown,
+  operation: BackupOperation
+): BackupCommandResult {
+  const result = exactRecord(value, RESULT_KEYS, 'backup command result');
+  if (typeof result.success !== 'boolean') invalid('backup command result success');
+  const message = text(result.message, 'backup command result message', MAX_MESSAGE_LENGTH);
+  if (!result.success) throw new Error(message);
+  const data = operationData(operation, result.data);
+  return data === undefined ? { success: true, message } : { success: true, message, data };
+}
+
+function operationData(operation: BackupOperation, value: unknown): unknown {
+  if (operation === 'status') return statusData(value);
+  if (operation === 'list') return listData(value);
+  return value;
+}
+
+function statusData(value: unknown): Record<string, string | boolean> {
+  const status = exactRecord(value, STATUS_KEYS, 'backup status data');
+  if (typeof status.enabled !== 'boolean') invalid('backup status enabled');
+  return {
+    enabled: status.enabled,
+    bucket: text(status.bucket, 'backup status bucket', 1_024),
+    endpoint: text(status.endpoint, 'backup status endpoint', 4_096),
+    interval: text(status.interval, 'backup status interval', 128),
+    retention: text(status.retention, 'backup status retention', 128),
+  };
+}
+
+function listData(value: unknown): Array<Record<string, string>> {
+  if (!Array.isArray(value) || value.length > MAX_LIST_ITEMS) invalid('backup list data');
+  let textSize = 0;
+  const keys = new Set<string>();
+  return value.map((entry, index) => {
+    const item = exactRecord(entry, ITEM_KEYS, `backup list item ${index}`);
+    const key = text(item.key, `backup list item ${index} key`, 2_048);
+    const size = text(item.size, `backup list item ${index} size`, 128);
+    const date = text(item.date, `backup list item ${index} date`, 128);
+    textSize += key.length + size.length + date.length;
+    if (textSize > MAX_LIST_TEXT || keys.has(key) || !validIsoDate(date)) {
+      invalid(`backup list item ${index}`);
+    }
+    keys.add(key);
+    return { key, size, date };
+  });
+}
+
+function exactRecord(
+  value: unknown,
+  allowed: ReadonlySet<string>,
+  label: string
+): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) invalid(label);
+  const result = value as Record<string, unknown>;
+  if (Object.keys(result).some((key) => !allowed.has(key))) invalid(label);
+  return result;
+}
+
+function text(value: unknown, label: string, maxLength: number): string {
+  if (typeof value !== 'string' || value.length < 1 || value.length > maxLength) invalid(label);
+  return value;
+}
+
+function validIsoDate(value: string): boolean {
+  const timestamp = Date.parse(value);
+  return (
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) &&
+    Number.isFinite(timestamp) &&
+    new Date(timestamp).toISOString() === value
+  );
+}
+
+function invalid(label: string): never {
+  throw new Error(`Bunqueue ${label} has an invalid 2.8.57 contract`);
+}

package/agent/backup/routes.ts

@@ -0,0 +1,160 @@
+import { assertManagedTarget } from '../managedTarget';
+import type { DbStats, ServerConfig } from '../manager';
+import { readLimitedJsonBody } from '../server/jsonBody';
+import type { BackupRunnerPort } from './runner';
+
+const MAX_BACKUP_BODY_BYTES = 64 * 1024;
+
+export interface BackupRouteResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+export async function routeBackupRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  config: ServerConfig,
+  serverRunning: boolean,
+  database: DbStats,
+  runner: BackupRunnerPort,
+  configure?: (extraEnv: Record<string, string>) => void
+): Promise<BackupRouteResponse | null> {
+  const operation = routeOperation(pathname, method);
+  if (!operation) return null;
+  const query = exactTargetQuery(request.url);
+  assertManagedTarget(query, config);
+  if (operation === 'configure') {
+    if (!configure) throw new Error('Backup configuration is unavailable');
+    const body = await boundedRecord(request, ['environment']);
+    const next = mergeBackupEnvironment(config.extraEnv, body.environment);
+    configure(next);
+    return success({ configured: true, enabled: next.S3_BACKUP_ENABLED === 'true' });
+  }
+  if (operation === 'restore') {
+    if (serverRunning) throw new Error('Stop the managed Bunqueue server before restoring a backup');
+    const body = await boundedRecord(request, ['key', 'database']);
+    const key = backupKey(body.key);
+    assertDatabaseSnapshot(body.database, database);
+    return success(await runner.execute(config, operation, key));
+  }
+  return success(await runner.execute(config, operation));
+}
+
+function routeOperation(pathname: string, method: string) {
+  if (method === 'GET' && pathname === '/backup/status') return 'status' as const;
+  if (method === 'GET' && pathname === '/backup/list') return 'list' as const;
+  if (method === 'POST' && pathname === '/backup/now') return 'now' as const;
+  if (method === 'POST' && pathname === '/backup/restore') return 'restore' as const;
+  if (method === 'POST' && pathname === '/backup/configure') return 'configure' as const;
+  return null;
+}
+
+const BACKUP_ENV_KEYS = new Set([
+  'S3_BACKUP_ENABLED',
+  'S3_ACCESS_KEY_ID',
+  'S3_SECRET_ACCESS_KEY',
+  'S3_SESSION_TOKEN',
+  'S3_BUCKET',
+  'S3_ENDPOINT',
+  'S3_VIRTUAL_HOSTED_STYLE',
+  'S3_REGION',
+  'S3_BACKUP_INTERVAL',
+  'S3_BACKUP_RETENTION',
+  'S3_BACKUP_PREFIX',
+]);
+
+function mergeBackupEnvironment(
+  current: Record<string, string>,
+  value: unknown
+): Record<string, string> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Backup environment must be an object');
+  }
+  const entries = Object.entries(value as Record<string, unknown>);
+  for (const [key, entry] of entries) {
+    if (!BACKUP_ENV_KEYS.has(key)) throw new Error(`Unknown backup environment key: ${key}`);
+    if (typeof entry !== 'string' || entry.length > 4_096) {
+      throw new Error(`Backup environment ${key} must be a string of at most 4096 characters`);
+    }
+  }
+  const enabled = (value as Record<string, unknown>).S3_BACKUP_ENABLED;
+  if (enabled !== 'true' && enabled !== 'false') {
+    throw new Error('S3_BACKUP_ENABLED must be "true" or "false"');
+  }
+  const retained = Object.fromEntries(
+    Object.entries(current).filter(([key]) => !BACKUP_ENV_KEYS.has(key))
+  );
+  return { ...retained, ...(Object.fromEntries(entries) as Record<string, string>) };
+}
+
+function exactTargetQuery(url: string): URLSearchParams {
+  const query = new URL(url).searchParams;
+  for (const key of query.keys()) {
+    if (key !== 'target') throw new Error(`Unknown backup option: ${key}`);
+    if (query.getAll(key).length !== 1) throw new Error(`Duplicate backup option: ${key}`);
+  }
+  return query;
+}
+
+function success(result: unknown): BackupRouteResponse {
+  return { status: 200, body: { ok: true, result } };
+}
+
+function record(value: unknown, allowed: string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Backup restore body must be an object');
+  }
+  const body = value as Record<string, unknown>;
+  const unknown = Object.keys(body).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`Unknown backup body option: ${unknown}`);
+  return body;
+}
+
+async function boundedRecord(
+  request: Request,
+  allowed: string[]
+): Promise<Record<string, unknown>> {
+  const value = await readLimitedJsonBody(request, {
+    scope: 'Backup',
+    maxBytes: MAX_BACKUP_BODY_BYTES,
+    limitLabel: '64 KiB',
+    missingMessage: 'Backup request body must be valid JSON',
+    invalidUtf8Message: 'Backup request body must be valid JSON',
+    invalidJsonMessage: 'Backup request body must be valid JSON',
+  });
+  return record(value, allowed);
+}
+
+function backupKey(value: unknown): string {
+  if (
+    typeof value !== 'string' ||
+    value.length < 1 ||
+    value.length > 2_048 ||
+    /[\u0000-\u001f\u007f]/.test(value)
+  ) {
+    throw new Error('Backup key must contain 1–2048 printable characters');
+  }
+  return value;
+}
+
+function assertDatabaseSnapshot(value: unknown, current: DbStats): void {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('A database snapshot is required to authorize restore');
+  }
+  const expected = value as Record<string, unknown>;
+  const allowed = ['path', 'exists', 'size', 'walSize', 'shmSize', 'totalSize', 'mtimeMs'];
+  const unknown = Object.keys(expected).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`Unknown database snapshot option: ${unknown}`);
+  if (
+    expected.path !== current.path ||
+    expected.exists !== current.exists ||
+    expected.size !== current.size ||
+    expected.walSize !== current.walSize ||
+    expected.shmSize !== current.shmSize ||
+    expected.totalSize !== current.totalSize ||
+    expected.mtimeMs !== current.mtimeMs
+  ) {
+    throw new Error('Database changed after restore confirmation; reload status and confirm again');
+  }
+}

package/agent/backup/runner.ts

@@ -0,0 +1,91 @@
+import type { ServerConfig } from '../manager';
+import { validateBackupResult } from './resultValidation';
+import { executeBackupOperation } from './workerFactory';
+
+export type BackupOperation = 'status' | 'list' | 'now' | 'restore';
+
+export interface BackupCommandResult {
+  success: boolean;
+  message: string;
+  data?: unknown;
+}
+
+export interface BackupRunnerPort {
+  execute(config: ServerConfig, operation: BackupOperation, key?: string): Promise<BackupCommandResult>;
+  close(): Promise<void>;
+}
+
+export type BackupOperationExecutor = (
+  environment: Record<string, string>,
+  operation: BackupOperation,
+  key: string | undefined,
+  signal: AbortSignal
+) => Promise<unknown>;
+
+const COMMAND_TIMEOUT_MS = 120_000;
+
+/** Owns exactly one cancellable local backup operation at a time. */
+export class BunqueueBackupRunner implements BackupRunnerPort {
+  private active: Promise<BackupCommandResult> | null = null;
+  private controller: AbortController | null = null;
+  private closed = false;
+  private closing: Promise<void> | null = null;
+
+  constructor(
+    private readonly timeoutMs = COMMAND_TIMEOUT_MS,
+    private readonly executor: BackupOperationExecutor = executeBackupOperation
+  ) {}
+
+  execute(
+    config: ServerConfig,
+    operation: BackupOperation,
+    key?: string
+  ): Promise<BackupCommandResult> {
+    if (this.closed) return Promise.reject(new Error('Backup runner is closed'));
+    if (this.active) return Promise.reject(new Error('Another backup operation is already running'));
+    if (operation === 'restore' && !key) {
+      return Promise.reject(new Error('Backup key is required for restore'));
+    }
+
+    const controller = new AbortController();
+    this.controller = controller;
+    const timeout = setTimeout(() => {
+      controller.abort(new Error(`Bunqueue backup command timed out after ${this.timeoutMs} ms`));
+    }, this.timeoutMs);
+    const pending = this.executor(
+      backupEnvironment(config),
+      operation,
+      key,
+      controller.signal
+    ).then((value) => validateBackupResult(value, operation));
+    const active = pending.finally(() => {
+      clearTimeout(timeout);
+      if (this.active === active) this.active = null;
+      if (this.controller === controller) this.controller = null;
+    });
+    this.active = active;
+    return active;
+  }
+
+  close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.closed = true;
+    this.controller?.abort(
+      new Error('Bunqueue backup command cancelled because the control agent is closing')
+    );
+    const active = this.active;
+    this.closing = (async () => {
+      await active?.catch(() => undefined);
+    })();
+    return this.closing;
+  }
+}
+
+function backupEnvironment(config: ServerConfig): Record<string, string> {
+  return {
+    ...(process.env as Record<string, string>),
+    ...config.extraEnv,
+    BUNQUEUE_DATA_PATH: config.dataPath,
+    NO_COLOR: '1',
+  };
+}

package/agent/backup/standaloneWorker.ts

@@ -0,0 +1,23 @@
+import { executeBackupCommand } from '../../node_modules/bunqueue/dist/cli/commands/backup.js';
+import type { BackupWorkerReply, BackupWorkerRequest } from './workerProtocol';
+
+declare const self: Worker;
+
+self.onmessage = async ({ data }: MessageEvent<BackupWorkerRequest>) => {
+  let reply: BackupWorkerReply;
+  try {
+    const args = [
+      data.operation,
+      ...(data.operation === 'restore' ? [requiredKey(data.key), '--force'] : []),
+    ];
+    reply = { ok: true, result: await executeBackupCommand(args) };
+  } catch (error) {
+    reply = { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  self.postMessage(reply);
+};
+
+function requiredKey(value: string | undefined): string {
+  if (!value) throw new Error('Backup key is required for restore');
+  return value;
+}

package/agent/backup/workerExecutor.ts

@@ -0,0 +1,40 @@
+import type { BackupOperation } from './runner';
+import type { BackupWorkerReply, BackupWorkerRequest } from './workerProtocol';
+
+export function executeBackupWorker(
+  workerUrl: string,
+  environment: Record<string, string>,
+  operation: BackupOperation,
+  key: string | undefined,
+  signal: AbortSignal
+): Promise<unknown> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(workerUrl, { type: 'module', env: environment });
+    let settled = false;
+    const finish = (operation: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', abort);
+      worker.terminate();
+      operation();
+    };
+    const abort = () =>
+      finish(() =>
+        reject(
+          signal.reason instanceof Error ? signal.reason : new Error('Backup operation cancelled')
+        )
+      );
+    signal.addEventListener('abort', abort, { once: true });
+    worker.onmessage = ({ data }: MessageEvent<BackupWorkerReply>) => {
+      if (data.ok) finish(() => resolve(data.result));
+      else finish(() => reject(new Error(data.error)));
+    };
+    worker.onerror = (event) => {
+      event.preventDefault();
+      finish(() => reject(new Error(event.message || 'Embedded backup worker failed')));
+    };
+    const request: BackupWorkerRequest = { operation, key };
+    worker.postMessage(request);
+  });
+}

package/agent/backup/workerFactory.ts

@@ -0,0 +1,21 @@
+import type { BackupOperationExecutor } from './runner';
+import { executeBackupProcess } from './processExecutor';
+import { executeBackupWorker } from './workerExecutor';
+
+let embeddedWorkerUrl: string | null = null;
+
+export const executeBackupOperation: BackupOperationExecutor = (
+  environment,
+  operation,
+  key,
+  signal
+) => {
+  if (embeddedWorkerUrl) {
+    return executeBackupWorker(embeddedWorkerUrl, environment, operation, key, signal);
+  }
+  return executeBackupProcess(environment, operation, key, signal);
+};
+
+export function setBackupWorkerUrl(url: string | null): void {
+  embeddedWorkerUrl = url;
+}

package/agent/backup/workerProtocol.ts

@@ -0,0 +1,10 @@
+import type { BackupCommandResult, BackupOperation } from './runner';
+
+export interface BackupWorkerRequest {
+  operation: BackupOperation;
+  key?: string;
+}
+
+export type BackupWorkerReply =
+  | { ok: true; result: BackupCommandResult }
+  | { ok: false; error: string };