Crate codewhale_workflow_js 

Dynamic Workflow runtime for CodeWhale.

This crate is the imperative half of Workflow: a sandboxed QuickJS (rquickjs) runtime that executes a model-authored JS program which dispatches fleet-routed subagents via task(), fans out with parallel()/pipeline(), reports progress with log()/phase(), and scales itself to a token pool via the budget global. The static, declarative IR (record/replay, model policy) stays in codewhale-workflow; this crate only speaks to the outside world through the WorkflowDriver seam, so it is fully testable without spawning a real subagent (see testing::FakeDriver).

Script surface

Every script runs inside an async function with these globals:

• args — the invocation input, verbatim.
• await task(opts) — dispatch one subagent; resolves to the full result text, or to a parsed + schema-validated object when opts.responseSchema is set. Throws on rejection, failure, cancellation, budget exhaustion, or once WORKFLOW_LIFETIME_CAP spawn attempts have been made.
• parallel(thunks) — all-settled fan-out; a failed slot becomes null; at most PARALLEL_MAX_ITEMS items.
• pipeline(items, ...stages) — per-item stage chains with no barrier between stages; a stage error drops that item to null; same item cap.
• log(msg) / phase(title) — progress events forwarded to the driver.
• budget.total / budget.spent() / budget.remaining() — live driver snapshots (total is null and remaining() is Infinity when no ceiling is configured).

Date.now(), new Date(), Date.parse/UTC, and Math.random() throw: runs must be deterministic so recorded traces can be replayed.

Ownership boundaries

Token accounting and reservation (design §5.3) belong to the driver; the VM only reads snapshots and fast-fails a spawn when the pool is already exhausted. Fleet roster resolution for profile also happens driver-side; this crate normalizes and token-validates the profile string, nothing more.

Modules

testing

Test support: a scriptable in-memory WorkflowDriver.

Structs

BudgetSnapshot

Live view of the run’s shared token pool, owned by the driver.

SpawnedTask

A successfully admitted spawn: the driver-assigned task id (the engine’s agent_id) plus the oneshot the driver resolves on completion.

TaskRequest

One task() invocation, fully resolved and validated on the VM side.

VmLimits

Resource limits applied to the QuickJS runtime before any script runs.

WorkflowVm

Executes Workflow scripts, one isolated QuickJS runtime per run.

Enums

DriverError

Errors a crate::WorkflowDriver can return from spawn_task.

ProgressEvent

Progress events emitted by the script (log(..) / phase(..)), delivered to the driver synchronously and in script order.

TaskCompletion

Terminal outcome of one spawned task, delivered over the completion oneshot. Everything except Completed becomes a JS throw on the awaiting task() call.

WorkflowJsError

Errors surfaced by crate::WorkflowVm::run_script.

Constants

PARALLEL_MAX_ITEMS

Maximum items per parallel() or pipeline() call (design §4.2).

WORKFLOW_LIFETIME_CAP

Maximum task() spawn attempts per run (design §4.3). Counted in the VM before the driver is consulted, so a runaway loop-until-dry terminates even if the driver would keep admitting work.

Traits

WorkflowDriver

Host-side executor for a Workflow run.

Functions

normalize_profile

Normalize and validate a Fleet profile token: trim, lowercase, then apply the same token rule as crates/workflow’s validate_leaf_profile — non-empty, no whitespace, and none of ", ', `, =.