Merge pull request #86 from compoundingtech/schickling-assistant/2026-07-30-resource-bindings

feat(agent-spec): add typed Resource bindings

Author: schickling

INVARIANTS.md

@@ -14,7 +14,7 @@ materialization, messaging, DING, or presence must preserve them.
 | **Mutation-only filesystem wakeups** | Supervisor and DING filesystem watchers ignore read/open access events and wake early only for create, modify, rename, or remove events. Their own catalog and inbox reads therefore cannot bypass the bounded timer cadence or form a Linux inotify CPU loop. | `src/watch.rs::only_mutations_wake_watch_loops`; `src/watch.rs::linux_reads_are_silent_but_real_mutations_wake`; `src/ding/mod.rs::idle_ding_does_not_spin_on_its_own_inbox_reads`; `src/run.rs::idle_supervisor_does_not_spin_on_its_own_catalog_reads` |
 | **Bounded DING PTY probe churn** | An unsafe or active composer retains its FIFO notice but deferred delivery retries use a bounded backoff, so each inbox poll cannot spawn another short-lived PTY probe. | `src/ding/mod.rs::deferred_delivery_backoff_bounds_short_lived_pty_attempts` |
 | **Agent-declared presence discipline** | The shipped bus contract requires agents to declare `busy` before executing work, use `available` only while yielding or ready, and reserve `dnd` for an explicit hold. Both native harnesses materialize that contract. Busy remains observable but does not suppress DING; fresh `dnd` is the only delivery gate. | `tests/compile_agent.rs::compile_agent_generates_claude_then_materializes_verbatim_persona`; `tests/compile_agent.rs::compile_agent_generates_codex_then_materializes_composed_agents_md`; `src/ding/mod.rs::pending_delivery_ignores_busy_but_respects_fresh_dnd_archive_and_retry` |
-| **Stable roster JSON** | `st2 agents --json [--enrich]` preserves field names, order, null handling, presence, explicit retirement state, activity, and inbox counts. Human output marks retired declarations without changing active rows. | `src/agents.rs::agents_json_has_stable_wire_shape`; `tests/status_agents.rs::roster_json_and_human_output_distinguish_retirement_from_presence` |
+| **Stable roster JSON** | `st2 agents --json [--enrich]` preserves field names, order, null handling, presence, explicit retirement state, opaque declared Resource descriptors, activity, and inbox counts. Human output marks retired declarations without changing active rows. | `src/agents.rs::agents_json_has_stable_wire_shape`; `src/agents.rs::agents_json_preserves_opaque_declared_resource_descriptors`; `tests/status_agents.rs::roster_json_and_human_output_distinguish_retirement_from_presence` |
 | **Agent-declared presence** | Refresh preserves non-DND declared status and only advances liveness; a missing status starts as `available`, while `dnd` is never refreshed and an unrefreshed declaration ages to `unknown`. | `src/status.rs::refresh_preserves_value_and_bumps_mtime`; `src/status.rs::refresh_leaves_dnd_to_age_out`; `src/status.rs::refresh_missing_writes_available_default`; `src/status.rs::stale_mtime_reads_as_unknown_regardless_of_contents` |
 | **Retirement health** | A retired declaration is healthy only after every declared task ID is absent. Any live or dead declared task record reports incomplete retirement; retired declarations do not require presence. Live declarations retain their existing task and presence checks. | `tests/doctor.rs::retired_declaration_is_healthy_when_tasks_and_presence_are_absent`; `tests/doctor.rs::retired_declaration_is_unhealthy_while_a_declared_task_is_alive`; `tests/doctor.rs::retired_declaration_is_unhealthy_while_a_dead_task_record_remains` |
 | **Crash loops surface** | A task parked by a fail-mode restart policy notifies its supervisor once over the bus. | `tests/run.rs::surface_crash_loop_notifies_the_supervisor_over_the_bus` |

README.md

@@ -106,6 +106,7 @@ The compact declaration shape is:
 agent "<identity>" {
   host "<host>"
   workspace "<workspace>"
+  resource "work" _tag="github-issue" uri="github-issue://example/project/123"
   // Optional metadata:
   // role "worker"
   // supervisor "<supervisor-bus-id>"
@@ -123,6 +124,22 @@ agent "<identity>" {
 }
 ```
 
+`resource` binds an agent-local semantic name to an exact RFC 3986 absolute URI. `_tag` selects a
+concrete resource contract understood by downstream readers; st2 preserves arbitrary non-empty tags
+and URI bytes without normalization. It neither owns their schemas nor resolves their targets.
+Binding order is irrelevant and names must be unique within the agent:
+
+```kdl
+resource "work" _tag="github-issue" uri="github-issue://example/project/123"
+resource "source" _tag="worktree" uri="worktree://github.com/example/project/change"
+resource "delivery" _tag="ding" uri="ding://host/agent"
+```
+
+The envelope is intentionally only `name` + `_tag` + `uri`. It carries no required/optional,
+access, readiness, or lifecycle policy, and URI possession conveys no authority. Resource-only
+declaration edits do not stop, replace, or relaunch a live task. Resource types and resolvers remain
+opaque to st2; catalog readers use the public `agent-spec` crate to inspect the typed bindings.
+
 `argv` launches its first value directly with the remaining values as arguments. It resolves a bare
 program such as `codex` through the task environment's `PATH`, preserves argument boundaries, and
 does not introduce a shell. Use `command #"..."#` instead when the task intentionally needs shell
@@ -254,9 +271,9 @@ st2 context read --full
 ```
 
 The roster includes retired declarations instead of silently conflating them with runtime
-presence. Both JSON shapes contain an additive `retired` boolean; `--enrich` additionally supplies
-`lastActivity` and `inbox`. Human output leaves active rows unchanged and appends `[retired]` to a
-retired row.
+presence. Both JSON shapes contain `retired` and the declaration's ordered `resources` descriptors;
+`--enrich` additionally supplies `lastActivity` and `inbox`. Human output leaves active rows
+unchanged and appends `[retired]` to a retired row.
 
 For a catalog-backed agent, every native bus operation resolves the same agent directory used by
 the roster: presence is `<agent-dir>/status`, while unread messages, archive receipts, context, and

crates/agent-spec/src/kdl_format.rs

@@ -9,7 +9,7 @@
 
 use kdl::{KdlDocument, KdlNode};
 
-use crate::spec::{RawRestart, RawSpec, RawTask};
+use crate::spec::{RawResource, RawRestart, RawSpec, RawTask};
 
 /// Parse a KDL document into zero or more raw specs (one per top-level `agent` node).
 pub(crate) fn parse_kdl(text: &str) -> anyhow::Result<Vec<RawSpec>> {
@@ -84,6 +84,10 @@ fn agent_node_to_raw(node: &KdlNode) -> anyhow::Result<RawSpec> {
             "retired" => raw.retired = arg_bool(child),
             "keep" => raw.keep = arg_bool(child),
             "restart" => raw.restart = Some(restart_node_to_raw(child)),
+            "resource" => {
+                let (name, resource) = resource_node_to_raw(child)?;
+                raw.resource.insert(name, resource)?;
+            }
             "command" => raw.command = arg_string(child),
             "argv" => raw.argv = Some(argv(child)?),
             "ding" => raw.ding = true,
@@ -111,6 +115,60 @@ fn agent_node_to_raw(node: &KdlNode) -> anyhow::Result<RawSpec> {
     Ok(raw)
 }
 
+fn resource_node_to_raw(node: &KdlNode) -> anyhow::Result<(String, RawResource)> {
+    if node.children().is_some() {
+        anyhow::bail!("resource binding cannot have children");
+    }
+
+    let mut name = None;
+    let mut tag = None;
+    let mut uri = None;
+    for entry in node.entries() {
+        let Some(property) = entry.name() else {
+            if name.is_some() {
+                anyhow::bail!("resource binding accepts exactly one positional name");
+            }
+            name = entry.value().as_string().map(String::from);
+            if name.is_none() {
+                anyhow::bail!("resource binding needs a string name");
+            }
+            continue;
+        };
+
+        let property = property.value();
+        let value = entry.value().as_string().map(String::from);
+        match property {
+            "_tag" => {
+                if tag.is_some() {
+                    anyhow::bail!("resource binding has duplicate `_tag`");
+                }
+                tag = value;
+                if tag.is_none() {
+                    anyhow::bail!("resource binding needs string `_tag`");
+                }
+            }
+            "uri" => {
+                if uri.is_some() {
+                    anyhow::bail!("resource binding has duplicate `uri`");
+                }
+                uri = value;
+                if uri.is_none() {
+                    anyhow::bail!("resource binding needs string `uri`");
+                }
+            }
+            other => anyhow::bail!("resource binding has unsupported property `{other}`"),
+        }
+    }
+
+    Ok((
+        name.ok_or_else(|| anyhow::anyhow!("resource binding needs a string name"))?,
+        RawResource {
+            tag: tag.ok_or_else(|| anyhow::anyhow!("resource binding needs string `_tag`"))?,
+            uri: uri.ok_or_else(|| anyhow::anyhow!("resource binding needs string `uri`"))?,
+        },
+    ))
+}
+
 fn restart_node_to_raw(node: &KdlNode) -> RawRestart {
     let mut r = RawRestart::default();
     let Some(children) = node.children() else {

crates/agent-spec/src/lib.rs

@@ -3,7 +3,7 @@
 //! One agent is one declarative file, Nomad-style: the agent is the job and its `pty`/`exec` blocks
 //! are the tasks. This crate owns the two halves any reader of that catalog needs and nothing else:
 //!
-//! - [`spec`] — the runner-normative model a declaration lowers to ([`AgentSpec`], [`Task`], …).
+//! - [`spec`] — the shared model a declaration lowers to ([`AgentSpec`], [`Task`], [`Resource`], …).
 //! - [`discovery`] — the catalog walk: parse every `*.{kdl,toml,json}` that looks like a
 //!   declaration, and resolve each one's `identity`/`host` with the catalog's precedence rule
 //!   (content wins, the path supplies defaults, a mismatch is a warning).
@@ -25,4 +25,6 @@ mod kdl_format;
 pub mod spec;
 
 pub use discovery::{Declared, Discovered, SpecError, discover, parse_declared, path_defaults};
-pub use spec::{AgentSpec, JobType, Restart, RestartMode, Task, TaskKind, parse_duration};
+pub use spec::{
+    AgentSpec, JobType, Resource, Restart, RestartMode, Task, TaskKind, parse_duration,
+};