Metadata-Version: 2.5
Name: kestrel-feature-workflows
Version: 0.4.0
Summary: First-class agent workflow orchestration primitive for Kestrel Sovereign
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: kestrel-sovereign-sdk<1,>=0.36.0
Requires-Dist: kestrel-sovereign<1,>=0.52.0
Provides-Extra: test
Requires-Dist: prometheus-client>=0.20; extra == 'test'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
uv pip install kestrel-feature-workflows
```

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

## Development

```bash
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.
