Metadata-Version: 2.5
Name: kestrel-feature-talon
Version: 0.2.0
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.53,>=0.52.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, workflow 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.

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

## Tool and contribution contract

Version 0.2.0 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` |

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

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