Metadata-Version: 2.5
Name: kestrel-feature-features
Version: 0.3.0
Summary: FeatureFeature — agents writing their own Kestrel features end-to-end, on top of the workflow primitive
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: jsonschema>=4.20
Requires-Dist: kestrel-feature-workflows<0.7,>=0.6.0
Requires-Dist: kestrel-sovereign-sdk<0.37,>=0.36.0
Requires-Dist: kestrel-sovereign<0.54,>=0.53.4
Requires-Dist: packaging<27,>=24
Provides-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-features

FeatureFeature — agents writing their own Kestrel features end-to-end.

FeatureFeature is the application layer that lets a sovereign agent propose,
build, review, and ship a new tool or feature package. It is built on the
workflow primitive: each proposal runs as a DID-signed, gated workflow
(explore → design → constitutional review → file epic → assign Talon chunks →
implement → tests/lint/CI → boundary scan → red-team → council → publish →
audit anchor).

## Installation

```bash
uv pip install kestrel-feature-features
```

This pulls in `kestrel-feature-workflows` and registers `FeatureFeaturesFeature`
through the `kestrel_sovereign.features` entry point group.

## Isolated feature scaffolds

`feature_scaffold_isolated` creates a deterministic, SDK-only source bundle for
features whose dependencies conflict with the host or are too heavy for its
environment. The bundle contains:

- a lightweight host marker with `[tool.kestrel.feature] runtime =
  "isolated-venv"`;
- a `service` extra that is installed only in the private child environment;
- one distribution whose `service` extra is Core's install target, plus a
  dependency lock input;
- an `IsolatedFeatureService` initialize/config-transition/health/shutdown
  skeleton and contract test;
- least-privilege declarations for network domains, symbolic filesystem mounts,
  secret capability names, declared native code, resources, and platforms.

The feature package performs no filesystem write, dependency resolution,
installation, or process launch itself. The embedding host injects an
`feature_isolated_scaffold_provider` already bound to the authenticated owner
and recipient agent. The tool deliberately accepts no tenant ID, agent DID,
workspace path, environment path, cache root, package index, or secret value.
The provider must evaluate policy and approval before it materializes the
bundle or invokes uv. Materialization must remain under the bound workspace,
reject pre-existing symlink path components, and use no-follow/exclusive writes
so validation cannot be raced into another tenant's tree.
It must call `evaluate_isolated_feature_policy`, then rewrite the generated
`file:///__KESTREL_PROVIDER_REWRITE_REQUIRED__[service]` target to an absolute
`file://` URI for the approved scoped source tree or wheel before building the
host marker. An unresolved placeholder must never be activated.

Core discovery requires the lightweight marker to be installed in the host.
Do not install its `service` extra or service-only dependencies there.
Generated versions are content-derived so source or manifest changes produce a
fresh Core provisioning identity. The SDK dependency remains within the
scaffolded minor-compatible range; regenerate the scaffold when moving to an
incompatible SDK minor.

Likewise, `feature_isolated_status` reads typed telemetry only through an
owner/agent-bound `feature_isolated_status_provider`. Hosts should report actual
download and environment bytes, resolve/provision/start timings, child RSS/CPU,
restart and active/idle process counts, cache hit/miss, last use, cleanup
eligibility, private writable versus shared cache bytes, file descriptors,
active builds, old-healthy retention, and denial/quarantine reasons.

### Cost model

A separate environment has three different costs; there is no useful fixed
"one venv" price:

1. The environment directory and Python launch scaffolding are generally small.
2. Wheels and native libraries dominate disk. Pure-Python HTTP clients may be
   tens of MB; scientific/ML stacks may be hundreds of MB to multiple GB.
3. Every running service adds a Python interpreter and its imported libraries
   to RSS. Idle shutdown can reclaim process memory while keeping the private
   environment for a faster restart.

`IsolatedFeaturePolicy` therefore contains host-configurable optional ceilings,
not universal defaults: counts per agent/host, environment and cache bytes,
concurrent builds, install timeout, idle timeout, package indexes, build
backends, and native-code policy. An immutable uv download/build cache may be
shared, but writable venvs, config, secrets, sockets, processes, and state must
remain private to one owner/agent namespace.

Recommended host lifecycle:

1. Validate the scaffold declaration and estimate artifacts without resolving.
2. Apply owner/agent quotas and source/build/native-code policy.
   `declares_native_code` is only caller input; dependency artifacts remain
   unverified until the host inspects them, and only verified native code may
   be admitted by `allow_verified_native_code`.
3. Obtain explicit approval.
4. Install only the lightweight marker (without its `service` extra) into the
   host so Core can discover and version it. Resolve and lock the `service`
   extra only in a quarantined owner/agent-private candidate environment.
5. Run contract tests, launch, and wait for readiness.
6. Atomically promote the new environment digest; keep the previous healthy
   environment until promotion succeeds.
7. On cancellation/crash, quarantine the incomplete candidate. On idle expiry,
   stop the process; remove an environment only under scoped cleanup custody.

## Development

```bash
uv sync --extra test
uv run --extra test pytest -q
```

## Architecture

FeatureFeature depends on `kestrel-feature-workflows` (a feature→feature
dependency) for the workflow models, schema, and signing it uses to construct
proposal pipelines. It reaches core surfaces — feature discovery, signals,
identity, security, storage — through `kestrel-sovereign`.
