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.

Operator Runs API and console

Workflows 0.5.1 exposes its durable, engine-neutral run plane at /api/workflows/runs. Authenticated operators can page and filter run records, inspect stages, numbered attempts, typed external job correlations, and artifact metadata, apply pause/resume/cancel/retry controls with idempotency and sequence preconditions, and follow one authorized run through a polling-backed SSE stream. Cross-tenant and absent identifiers share the same not-found response, and artifact dereference returns metadata only.

WorkflowsHostFeature also contributes the capability-gated Runs panel to the Console from package-owned JavaScript and CSS. The panel uses authenticated streaming with polling fallback, renders generic SDK fields only, and offers an optional correlation handoff to an installed Observability panel.

An injected workflows.operator_context_resolver remains authoritative for Castle and other multi-tenant deployments. Otherwise Workflows resolves the current host-scoped claws.catalog>=1.3 service for each request and asks its public operator-context resolver to authorize OAuth and other authenticated solo operators. A present Claws service is authoritative: policy denial or an invalid resolver fails closed and cannot fall through to broader local rights. Generic Workflows hosts without a compatible Claws service retain the existing zero-config fallback, which grants access only to the Sovereign API-key caller and requires an injected tenant resolver. A present 1.2 catalog without the 1.3 operator policy is not considered absent and fails closed. The selected resolver is responsible for user, tenant, boundary, capability, action, and expiry policy.

The HTTP and Console surfaces intentionally do not launch runs. Launch remains the feature-owned RunService.launch_run boundary used by installed execution features, where source attribution, target boundaries, capabilities, tenancy, and idempotency are authorized before acceptance. No Talon-, Eye-, Flight-, repository-, command-, or filesystem-specific fields are part of this API.

Development

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

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.