Metadata-Version: 2.5
Name: kestrel-feature-workflows
Version: 0.5.1
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`.

## 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

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