kestrel-feature-workflows

First-class agent workflow orchestration for Kestrel Sovereign.

The package also installs a host-scoped WorkflowsHostFeature that owns the durable, engine-neutral operator run plane. It registers the public SDK RunService at host scope as workflows.runs version 1.0.0, persists accepted launches and their recovery outbox in the host database, and exposes a fenced producer lifecycle for installed execution features. The run plane does not add HTTP routes or engine-specific fields.

Absolute artifact links fail closed unless their exact HTTPS origins are listed in the package-owned KESTREL_WORKFLOWS_ARTIFACT_ORIGINS environment variable as a JSON array, for example ["https://artifacts.example.com","https://cdn.example.com:8443"]. Entries must be exact HTTPS origins: paths, queries, fragments, credentials, and non-HTTPS URLs are rejected. The value is limited to 16 KiB, 100 origins, and 2,048 characters per origin. Canonical /authorized/artifacts/<artifact_id> links remain same-origin and need no allowlist entry.

Alternate hosts may instead provide the existing workflows.artifact_origins context mapping. If both sources are present, their normalized origin sets must be identical or host-feature startup fails; otherwise the environment source is used when set. Malformed values fail startup without logging their contents.

Workflows is orchestration on top of the existing Signal Dispatcher. Stages dispatch signals (ACTION / ARTIFACT / COGNITION); durability, dedupe, locks, causation tracking, retention, and redaction all come from the dispatcher. Workflows adds what the dispatcher lacks: multi-stage sequencing and fan-out, per-stage gates (including an adversarial red_team_clear gate), reverse-order saga compensation, a cancellation barrier, DID-signed versioned workflow definitions, and constitutional-boundary enforcement.

Execution is lease-owned: runnable runs and open stage/compensation attempts are atomically claimed by an executor and heartbeated. Recovery reuses the persisted attempt idempotency key and dispatch linkage; it advances confirmed effects, never reruns completed stages, and fails safely when an external effect cannot be determined. This provides exactly-once workflow transitions and at-most-once effects where downstream idempotency supports it, not a blanket exactly-once guarantee for arbitrary external systems.

Installation

uv pip install kestrel-feature-workflows

The package registers WorkflowsFeature through kestrel_sovereign.features and WorkflowsHostFeature through kestrel_sovereign.host_features.

Development

uv sync --extra test
uv run --extra test pytest -q

Design

See docs/architecture/WORKFLOWS_FEATURE_DESIGN.md (v4.1) and WORKFLOWS_DEVELOPER_GUIDE.md in the kestrel-sovereign repository for the full design and the stage-to-signal reduction.