Module types 

Fundamental types: Role / Verb / RoleVerbGate / CapToken / IDs.

Structs

CapToken

Capability token. max_uses picks between OneTime / Session / Limited.

IdParseError

Error returned when an ID string does not carry the expected prefix.

RoleVerbGate

Role × Verb gate table. Const-style storage.

RunId

Opaque run identifier, e.g. R-<hex>. One RunId names one kick of a TaskId — minted server-side when a task is started, propagated through the engine ctx to every wire frame so steps, workers, and outputs correlate back to the run.

SessionId

Opaque session identifier, e.g. S-<hex>. See StepId for the newtype rationale.

StepId

Opaque per-step identifier, e.g. ST-<hex>. Newtype over String so step, session, and worker ids can’t be swapped by accident at call sites.

TaskId

Opaque work-item identifier, e.g. T-<hex>. One TaskId names one unit of work (“resolve issue #10” + a Blueprint ref + input ctx), persisted in the task store. A task can be kicked N times; each kick is a RunId.

TokenSigner

Server-side machinery for minting and verifying tokens.

WorkerId

Opaque worker identifier, e.g. W-<hex>. See StepId for the newtype rationale.

WorkerPayload

Response body for HTTP /v1/worker/prompt — the shape that lets a SubAgent pull its task input in a single round-trip.

Enums

CapTokenDecodeError

Error returned when CapToken::decode fails.

Role

The four participant roles in the swarm. Every Verb a caller wants to invoke must be allow-listed for its role in a RoleVerbGate.

Verb

Every action a participant can request. Grouped by the Role that typically performs it (see the // operator / // worker / … section comments below); the grouping is documentation only — actual authorization is decided by RoleVerbGate::is_allowed.

Constants

OBSERVER_VERBS

Verbs an Observer may invoke — strictly read-only (event subscription and trace/state reads, no mutation).

OPERATOR_VERBS

Verbs an Operator may invoke — covers task lifecycle, session, and senior interactions.

SENIOR_VERBS

Verbs a Senior may invoke — human/oversight actions: answering queries, overriding verdicts, and pausing/resuming/injecting into the dispatch loop.

WORKER_LEAF_VERBS

The Worker verbs shared across all workers — the minimum a leaf needs, with no sub-task spawning. If we introduce Role::WorkerLeaf in the future, that role gets allowed against this slice.

WORKER_SWARM_VERBS

Worker verbs for recursive swarming: sub-task spawn and observation. When Role::WorkerSwarm splits out in the future, that role gets allowed against WORKER_LEAF_VERBS plus this slice. The safety valves are EngineCfg.max_spawn_depth today, and a task-ownership gate down the line.

Functions

ct_eq

Constant-time byte-slice equality (XOR accumulate). Public so bearer comparisons outside this module (e.g. the operator login token check) can avoid the timing side channel of ==.

default_role_verb_table

The default Role × Verb table.

secure_hex

OS-RNG hex, safe for bearer credentials.

token_fingerprint

Hex SHA-256 of a token nonce / bearer string — the lookup-key shape used by CapToken::fingerprint. Standalone so callers holding only the bearer string (not a decoded token) can derive the same key.

uid_hex

In-process-unique, restart-decorrelated hex id.