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

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

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.