Metadata-Version: 2.5
Name: kestrel-feature-talon
Version: 0.2.2
Summary: Portable Kestrel feature integration for the Talon execution engine
Project-URL: Homepage, https://kestrelsovereign.com
Project-URL: Source, https://github.com/KestrelSovereignAI/kestrel-feature-talon
Project-URL: Issues, https://github.com/KestrelSovereignAI/kestrel-feature-talon/issues
Author: UncleSaurus
Maintainer: UncleSaurus
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,coding-agent,kestrel,talon
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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: fastapi<1,>=0.115
Requires-Dist: kestrel-feature-workflows<0.6,>=0.5
Requires-Dist: kestrel-sovereign-sdk<0.37,>=0.36.0
Requires-Dist: kestrel-sovereign<0.54.0,>=0.53.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

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

| Component | Distribution / command | Owns |
| --- | --- | --- |
| Talon feature | `kestrel-feature-talon` | Kestrel SDK feature discovery, agent tools, permissions, Talon-specific completion/pipeline/fleet-coding sources, the `talon:<job_id>` wait provider, health checks, and setup integration |
| Workflow runtime | `kestrel-feature-workflows` | Public workflow models and execution contracts used by the fleet workflow registered and built by this feature |
| Talon engine | `kestrel-talon` / `kestrel-talon` | Issue processing, coding-agent execution, and its command-line runtime |

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:

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

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

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

```toml
[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 | Command prefix |
| --- | --- |
| `scan_stale_work` | `!talon scan-stale-work` |
| `talon_claim` | `!talon claim` |
| `talon_file_and_claim` | `!talon file-and-claim` |
| `talon_github_write` | `!talon github-write` |
| `talon_get_config` | `!talon config` |
| `talon_set_config` | `!talon set-config` |
| `talon_verify` | `!talon verify` |
| `talon_schedule_work_rescue` | `!talon schedule-rescue` |
| `talon_workspace_status` | `!talon workspace-status` |
| `talon_setup_workspace` | `!talon setup-workspace` |
| `talon_batch` | `!talon batch` |
| `talon_status` | `!talon status` |
| `talon_job_log` | `!talon job-log` |
| `talon_pause` | `!talon pause` |
| `talon_resume` | `!talon resume` |
| `talon_health` | `!talon health` |

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

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