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.

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

Tool and contribution contract

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

The feature also contributes the agent-scoped talon.coordinator service, the talon:<job_id> wait provider, Talon completion/pipeline/fleet/rescue workflow sources, conservative permission defaults, and the optional setup step. scan_stale_work is allowed for unattended discovery; every other Talon tool defaults to operator approval.

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.

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.