kestrel-feature-talon

Portable Kestrel feature integration and runtime contracts for the external Talon coding-agent engine.

Package boundary

This distribution and the Talon engine have separate ownership:

Runtime health is exposed through the talon_health tool. The feature's synchronous health() method is a direct convenience probe; it is not a registered SDK health hook.

The 0.2 operator API supports launch, observation, pause, resume, and cancel. It deliberately does not support stage retry: Workflows 0.5 cannot pass fresh catalog/launch authority through its generic retry seam, so a generic retry of a failed Talon stage is terminalized without another engine dispatch. Launch a new governed run instead. Result fields for tests, review, demo, and Eye remain unknown/not_reported unless Talon supplies a bounded verified producer contract. Only Talon's bounded final claim-summary contract can populate PR identity today; arbitrary or partial log text is never promoted to evidence.

Installing this feature also installs its compatible workflow runtime dependency. It does not install or bundle the Talon engine. The host must install kestrel-talon separately and either put its executable on PATH or configure its absolute path as described below.

The compatibility ladder is intentional: Talon feature 0.2.0 is the migration bridge for Sovereign 0.52, where the bundled predecessor still exists. Talon feature 0.2.1 is the sole-owner release for Sovereign 0.53 and requires kestrel-sovereign>=0.53.0,<0.54.0; 0.53 supplies the public turn-bound session adapter needed to preserve durable completion wakes without reaching into core lifecycle internals.

Install and enable

Install the feature into the same Python environment as Kestrel Sovereign:

python -m pip install kestrel-feature-talon

Kestrel discovers TalonCoordinatorFeature from the standard Sovereign feature entry-point group. The wheel also publishes a pre-boot setup provider and the fleet_coding_pipeline workflow-to-feature ownership claim required by Sovereign 0.53. Capture the installed package in the host feature manifest so a later uv sync can be repaired, enable the feature if it was disabled, and restart the affected agent after enablement:

kestrel feature sync --capture
kestrel feature enable talon

On a host whose .kestrel-host-features.toml already declares the package, kestrel feature sync installs or restores it; --capture is only needed when first recording the currently installed extensions.

Run the optional Kestrel setup step to collect the engine's GitHub credentials:

kestrel setup talon

The setup step writes GITHUB_TOKEN and optional GITHUB_HUMAN_REVIEWER values to the host project's .env, preserving unrelated values and backing up an existing file before a change. It does not install the engine or choose runtime paths.

Runtime configuration

Paths are explicit and installation-independent. Configure them under [talon.runtime] in a host-selected TOML file, or provide the equivalent values through the host context:

[talon.runtime]
engine_executable = "/opt/kestrel/bin/kestrel-talon"
project_parent = "/srv/kestrel/projects"
running_agent_source_root = "/srv/kestrel/kestrel-sovereign"

The host supplies the TOML filename through the feature's config_path; the package does not select a global configuration file. A host may instead place the runtime mapping directly in the feature configuration or public talon_host_context.

Feature configuration applied through the SDK/HTTP configuration surface is stored atomically as talon_feature_config.toml with mode 0600 beside the stock agent's storage_path. On initialization, an explicit talon_config on the agent or its talon_host_context takes precedence; otherwise the feature loads that package-owned file. The file stores only the feature's config_path and direct runtime mapping—the host-selected TOML remains independently owned. A corrupt persisted file is reported as a configuration error and no runtime paths are inferred in its place.

Agents without a concrete string or pathlib.Path storage_path still accept configuration for the current process, but that configuration is deliberately ephemeral and will not survive restart. Generic os.PathLike objects and test doubles are not treated as state locations.

engine_executable takes precedence. When omitted, the feature performs only a normal PATH lookup for kestrel-talon; it never searches relative to its installed package or assumes sibling checkouts. project_parent and running_agent_source_root never have implicit filesystem defaults.

Talon workspace clones are kept under <project_parent>/.talon-workspaces/<owner>__<repo>. Every dispatch and verification operation rejects a workspace that contains, equals, or sits inside running_agent_source_root.

The package's TalonConfigAdapter reads and atomically updates the selected TOML file while retaining unrelated configuration values. Hosts may attach a talon_host_context mapping or object to the owning agent. In addition to the runtime paths above, the feature recognizes public context values for agent_name, did, storage_path, scheduler, observability_store, wait_registry, current_signal (or get_current_signal()), and origin_session_id (or get_origin_session_id()). This adapter keeps workflow/session correlation and durable job storage independent of private Sovereign agent fields. When that explicit context does not define an origin, Sovereign 0.53's public agent.get_turn_bound_session_id() adapter supplies the live turn's session; no private lifecycle compatibility alias is consulted.

Tool and contribution contract

Version 0.2.1 preserves the 16-tool public contract from Kestrel Sovereign 0.52.0:

Tool names, command prefixes, and parameter schemas remain compatible. The talon_schedule_work_rescue description and behavior are an intentional Sovereign 0.53 disclosure correction: the command now refuses a schedule that cannot perform live Talon discovery instead of claiming a recurring rescue was installed.

The feature also contributes the agent-scoped talon.coordinator service, the talon:<job_id> wait provider, Talon completion/pipeline/fleet-coding workflow sources, conservative permission defaults, and the optional setup step. Generic stalled_work_rescue sources remain host infrastructure; Talon does not register or override them. Sovereign 0.53's generic sweep is echo-only, so talon_schedule_work_rescue refuses to create a recurring no-op and points operators to scan_stale_work for live Talon findings. scan_stale_work is allowed for unattended discovery; every other Talon tool defaults to operator approval.

talon_pause writes a private durable dispatch marker and both the CLI and A2A rails check it before any external effect. The marker survives agent restarts; talon_resume clears it explicitly. These tools do not depend on a retired core scheduler task. talon_file_and_claim treats its audited GitHub issue creation and Talon launch as two explicit boundaries: a pre-existing pause prevents the GitHub write, while a pause requested during approval or issue creation takes effect immediately and blocks the later dispatch. In that race, the tool reports the already-filed issue as a partial outcome for manual review.

The host-scoped TalonHostFeature owns /api/talon, a capability-gated Talon panel, lifecycle workers, and the talon.operator service. Manual claim and approved-batch launches accept only opaque values resolved through claws.catalog>=1.1.0, while durable run state and artifacts are projected through workflows.runs>=1.0.0. Configure the same runtime paths under [talon.runtime]; operator_state_path may additionally select the private checksum-bound intent/evidence root. If omitted, it is placed beneath the explicit project_parent.

Hosts may inject a Castle or Workflows operator_context_resolver; that resolver always takes precedence. Without one, the operator API resolves the authenticated single-tenant policy through claws.catalog>=1.3.0. Missing or incompatible policy services fail closed.

Referenced operator evidence is never evicted behind an active or completed run API. The private store instead enforces a fail-closed retention ceiling of 10,000 run directories and 128 MiB of evidence; once either bound is reached, new artifact finalization is refused until an operator archives the state root or provisions a larger policy in a future release. Expired pre-dispatch intents are pruned off the event loop, while dispatched and linked intents remain recoverable until their external job is finalized.

Development

uv lock --check
uv run --extra test pytest -q
uv build
git diff --check

The wheel and source distribution are built from this repository alone. No sibling checkout or editable/path dependency is part of the package metadata.