How should Nix-managed Agent Specs compose runtime Resource bindings?

[schickling]

Problem

How should a Nix-managed Agent Spec compose static, generated Resource bindings with bindings discovered or created at runtime?

In the downstream setup motivating this question, agent.kdl is generated by Nix and is intentionally read-only desired state. Runtime actions can nevertheless establish useful direct Resource relationships: for example, creating a PTY associated with an agent or first creating an agent-scoped feedback/friction log.

Directly editing the generated agent.kdl is attractive because it preserves one local, inspectable source of truth and lets existing consumers such as Fractal see the relationship. But the next Nix activation can overwrite the runtime edit. Moving runtime membership into an unrelated registry avoids that overwrite while introducing a second authority and requiring every reader to compose both surfaces.

We would appreciate guidance on the smallest portable st2 model for this boundary.

Desired properties

• Nix remains authoritative for static Agent Spec declarations.
• Runtime Resource membership remains agent-local, inspectable, and durable across process restarts and Nix activation.
• Runtime producers use a mediated, idempotent st2 operation rather than editing KDL themselves.
• Readers get one coherent effective view while retaining provenance (static/generated versus runtime).
• Concurrent updates have explicit collision and revision semantics.
• This does not imply that a Resource binding grants authority to access the Resource.

Candidate shapes

1. Compose generated agent.kdl with an agent-local overlay such as agent.dynamic.kdl.
2. Store only runtime Resource bindings in a dedicated fragment and have st2 expose the composed Agent Spec.
3. Keep one mutable agent.kdl, but define split field ownership and apply runtime mutations as a managed patch set after generation.
4. Avoid dynamic binding churn by declaring stable container Resources up front; only their contents change at runtime.

The fourth option seems simplest for stable resources such as a feedback log, but it does not cover genuinely ad hoc resources such as newly created PTY sessions.

Open questions

• Should the portable Agent Spec format support overlays/fragments, or should this remain a catalog implementation concern?
• What owns the effective revision, and what happens when static and runtime bindings use the same local name?
• Should a runtime Resource-binding change advance the Agent Spec declaration revision even when it does not require an agent restart?
• How should CAS publication and recovery work across a Nix activation?
• Can the mediated mutation explored in Explore mediated Agent Spec Resource binding mutations #231 target this runtime-owned plane without each producer knowing how specs are stored?
• Should consumers read a composed spec, or receive the two provenance-labelled layers?

Non-goals

• Adding Nix-specific behavior to the portable st2 core.
• Making Resource bindings an access-control or authority mechanism.
• Defining ownership of the Resource payload itself.
• Requiring agent-process restarts for Resource-only membership changes.

Related

• Explore mediated Agent Spec Resource binding mutations #231 explores mediated Agent Spec Resource-binding mutations.
• Unify declared Resource bindings and linked records around one typed Resource reference #122 tracks the overlap between declared Resource bindings and linked Resource records/CLI surfaces.
• Incubate a transactional content-addressed Agent Spec catalog #52 discusses catalog transactions and the stable mutable agent directory outside immutable desired objects.
• Downstream motivator: schickling/dotfiles#1824.