Explore mediated Agent Spec Resource binding mutations

[schickling-assistant]

Problem

Changing one declared Resource binding on an existing Agent Spec currently requires callers to perform the full exact-byte publication protocol: render a complete candidate agent.kdl, validate it, compute its digest, publish it with compare-and-swap, then read it back. st2 resource add|remove manages linked-reference records instead, and st2 agent publish --bundle is oriented toward creating a complete declaration rather than making a small binding change.

This ceremony is safe but makes simple operations such as attaching one existing resource disproportionately difficult. Coordinating creation of resource material with the binding also lacks one mediated operation.

Design direction to explore

Provide a binding-specific command or API for one exact Agent Spec, for example:

st2 agent resource add|update|remove|rename \
  --host <host> --identity <identity> ...

The surface should:

• preserve full-catalog validation, exact-target selection, CAS, and fail-closed concurrent-change behavior;
• define who may mutate each binding and avoid treating URI possession as authority;
• modify only the intended binding while preserving unrelated Agent Spec bytes where possible;
• remain non-disruptive: a binding-only change must not relaunch a healthy agent;
• support add, update, remove, and rename with explicit idempotent outcomes;
• define crash and retry recovery, including an optional bundled resource-material operation without claiming cross-filesystem ACID; and
• return machine-readable publication and readback evidence.

A generic motivating flow should be one command that creates or verifies resource material and binds its URI to an existing agent, while retaining the same safety properties as manual Agent Spec publication.

Relationship to existing work

• Proposal: exact-byte CAS publication for canonical Agent Specs #41 established exact-byte CAS publication for complete Agent Specs.
• Incubate a transactional content-addressed Agent Spec catalog #52 explores catalog-wide transactional desired state and Resource admissions.
• Clarify that st2 resource manages linked references, not agent state #62 distinguishes link records from declared bindings.
• Unify declared Resource bindings and linked records around one typed Resource reference #122 considers a shared typed Resource reference while preserving different mutation authorities.

This issue is specifically about reducing authoring ceremony for small declared-binding mutations; it should not collapse bindings into linked records or weaken publication fencing.

[schickling]

The storage/ownership boundary for this mutation is now tracked in #305, specifically for Agent Specs whose canonical agent.kdl is generated by Nix. Before standardizing the write target here, #305 should settle whether the mediated operation edits a composed runtime layer, reapplies a managed patch, or relies on stable predeclared container Resources.

#122 remains the separate long-term question about unifying the overlapping Resource concepts and CLI surfaces.

[schickling-assistant]

Accepted

Design interview 2026-08-27 adopted this. st2 resource gains mediated write verbs:

st2 resource add <name> --uri <uri> --reason <text>
st2 resource remove <name>
st2 resource rename <old> <new>

Each does read-modify-CAS-publish internally; the caller never renders KDL. Full-catalog validation, exact-target selection, compare-and-swap, fail-closed concurrent-change behavior, and R21 non-disruption are preserved.

This is the fourth caller of an existing pattern, not new machinery. src/agent_author.rs already implements exactly this shape three times: add_stream/remove_stream (st2 agent stream), set_desired_state (st2 agent desired-state), and set_presentation (st2 rename / st2 describe). Bindings are another field of the same declaration mutated by the same protocol.

The motivating evidence is stronger than "ceremony is disproportionate". Measured on a live catalog of 655 declarations: of 241 link records, 45 were not products at all but dependency and reference edges — current-work (duplicating the work binding outright), depends-on-slice-{1,2,5,1-4}, supervises, blocked-design. Agents filed dependency edges into a products store because that was the plane they could write cheaply. The observed misfiling is what write-cost asymmetry looks like from the inside.

The same interview retires the link-record plane (#122 comment has the measurements), which removes that escape hatch. These verbs remove the pressure that produced it, so they land together rather than sequentially.

Limit, unchanged: this does not address a declaration generated read-only by configuration management, where the next activation overwrites the runtime edit (#305). On the catalog measured, declarations are writable regular files carrying meta { managed-by "agent-spec-authoring" } with no /nix/store symlinks, so the mediated write applies there. The generated-declaration case stays open.

Decision: docs/vrs/.decisions/0010-resource-is-a-mediated-write-surface.md. Pending upstream maintainer approval.

Posted on behalf of @schickling

field	value
agent_identity	unknown
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	Claude Code
agent_tool_version	2.1.237
agent_runtime	Claude Code 2.1.237
tooling_profile	dotfiles@11eaf2d-dirty