diff --git a/docs/vrs/requirements.md b/docs/vrs/requirements.md index c9ab5bae..c8ab5d83 100644 --- a/docs/vrs/requirements.md +++ b/docs/vrs/requirements.md @@ -122,3 +122,25 @@ accepted. inspection exposes every Resource binding without interpreting its type or URI. Resource-only declaration changes do not alter a task's effective launch definition and do not stop, replace, or relaunch healthy work. +- **R23 Runner-owned stable launch identity:** Before child start, st2 derives + `ST_AGENT=` for every declared task; a matching authored value + is accepted, while a conflicting value is a validation error and is never + silently overwritten ([decision #64](https://github.com/compoundingtech/st2/issues/64)). + The canonical `pty "agent"` additionally receives `role=agent` for + compatibility, `run.role=coding-agent`, and + `agent.actor.path=`; matching authored tags are accepted and + conflicts fail validation ([decision #64](https://github.com/compoundingtech/st2/issues/64), + [current compact-form partial evidence](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/src/spec.rs#L624-L656)). + Compact `command`/`argv` and explicit canonical `pty "agent"` forms have the + same guarantees; sidecars receive `ST_AGENT` but none of the canonical-agent + PTY tags ([decision #64](https://github.com/compoundingtech/st2/issues/64), + [current env parsing](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/src/kdl_format.rs#L68-L105), + [current task lowering](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/src/spec.rs#L682-L715)). + Harness, provider, model, account, and other mutable runtime facts remain + outside stable identity ([decision #64](https://github.com/compoundingtech/st2/issues/64), + [render-agnostic boundary](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/validate.rs#L15-L16)). + An optional display name is mutable presentation metadata outside launch + identity. Changing or clearing it does not change `ST_AGENT`, bus paths, task + IDs, resource anchors, or the running process, and never restarts the agent + ([display-name decision #108](https://github.com/compoundingtech/st2/issues/108), + [current roster projection](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/agents.rs#L21-L47)). diff --git a/docs/vrs/spec.md b/docs/vrs/spec.md index 50498cda..6451ecf4 100644 --- a/docs/vrs/spec.md +++ b/docs/vrs/spec.md @@ -179,6 +179,36 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler closed instead of hanging reconciliation. The deadline is containment, not the mechanism for admitting a larger fleet. +## Stable launch identity (R23) + +The accepted boundary is runner-owned: every declared task starts with +`ST_AGENT=`, while only the canonical agent PTY starts with +`role=agent`, `run.role=coding-agent`, and +`agent.actor.path=`. Matching authored values are allowed; +conflicts fail validation and are never silently overwritten. Compact and +explicit canonical-agent forms are equivalent; sidecars receive `ST_AGENT` but +none of those canonical-agent PTY tags. Mutable harness/provider/model/account +facts remain outside this contract +([decision #64](https://github.com/compoundingtech/st2/issues/64)). + +An optional display name is mutable presentation metadata, not stable routing +or actor identity. Changing or clearing it leaves `ST_AGENT`, bus paths, task +IDs, resource anchors, and the running process unchanged and does not restart +the agent ([decision #108](https://github.com/compoundingtech/st2/issues/108)). +The current roster already projects the adjacent `name` file on each read +([roster source](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/agents.rs#L34-L47)); +#108 owns the explicit authoring surface without widening this identity +contract. + +This is an accepted requirement with an implementation gap, not a description +of current behavior: + +| Surface | Current evidence | Status against R23 | +| --- | --- | --- | +| Task environment | Agent-level authored environment currently cascades into compact and explicit tasks ([parser](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/src/kdl_format.rs#L68-L105), [executable proof](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/tests/discovery.rs#L127-L175)). Reconciliation derives `ST_SUPERVISOR` but otherwise transports authored task environment ([target construction](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/reconcile.rs#L262-L297)). | **Gap:** `ST_AGENT` is preserved when authored, but is not yet runner-derived or conflict-checked. | +| Canonical PTY tags | Compact lowering currently adds only `role=agent`; an explicit `pty "agent"` keeps only authored tags ([compact lowering](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/src/spec.rs#L624-L656), [explicit task lowering](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/crates/agent-spec/src/spec.rs#L682-L715)). | **Gap:** explicit-form parity, `run.role`, `agent.actor.path`, and conflict checks are not implemented. | +| Launch transport | The PTY runner passes resolved tags and environment at initial launch and persists the environment for restart ([PTY launch](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/run.rs#L188-L218), [tag transport](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/run.rs#L227-L264)); the exec runner passes the same task environment before spawn ([exec launch](https://github.com/compoundingtech/st2/blob/c6846f6239329f0803142afc06c15a07b93937c1/src/exec_backend.rs#L59-L121)). Authored `ST_AGENT` restart preservation is executable evidence, not derivation evidence ([#30 receipt](https://github.com/compoundingtech/st2/issues/30#issuecomment-5110670601)). | **Implemented substrate:** no new PTY feature or metadata protocol is required; derivation and validation remain the missing slice. | + ## Message lifecycle ```text