feat(agent-spec): add typed resource bindings

Define a minimal named Resource envelope with exact URI identity, opaque type tags, strict uniqueness and shape validation, and no runtime lifecycle semantics.

agent-session-id: dev3.dotfiles-cos-misc-st2-resource-design
agent-tool: Codex
agent-tool-version: 0.145.0
agent-model: gpt-5.6-sol
agent-runtime-profile: /home/schickling/.local/state/agent-session-recovery/2026-07-29-pty-st2-cutover/runtime-profile/profile-without-null-opencode.json
agent-skills-manifest: /nix/store/kx5j47nghj1yps2v693ryb6wnf1c2xhb-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@16a22c6

Author: schickling-assistant

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 absolute URI. `_tag` selects a concrete
+resource contract understood by downstream readers; st2 preserves arbitrary non-empty tags without
+owning their schemas or resolving their URIs. 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

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).
@@ -14,7 +14,8 @@
 //!
 //! st2 consumes this crate, which is what keeps it a reference implementation rather than a copy:
 //! a second reader (a TUI, a linter) sees exactly the fields the runner sees, including the ones
-//! the runner's roster JSON does not carry (`supervisor`, `role`, `workspace`, `host`).
+//! the runner's roster JSON does not carry (`supervisor`, `role`, `workspace`, `host`, Resource
+//! bindings).
 //!
 //! Render-only fields (`harness`, `model`, `persona`, `permissions`, `transport`, `strategy`,
 //! `meta{}`) are read by the render layer and deliberately dropped here — that is what keeps a
@@ -25,4 +26,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,
+};

crates/agent-spec/src/spec.rs

@@ -4,9 +4,9 @@
 //! allocates a terminal, an agent harness) and `exec{}` (a plain process — the ding, daemons, a
 //! stage's script; must NOT allocate a terminal, R09). st2 reads only the runner-normative subset:
 //! `identity`, `host`, `role` (metadata only), `type`, `workspace`, `retired`, `keep`, `supervisor`,
-//! `restart{}`, and the tasks. Everything render-only (`harness`, `model`, `persona`, `permissions`,
-//! `transport`, `strategy`, `meta{}`) is baked into the tasks/commands by the render layer and
-//! ignored here.
+//! `restart{}`, Resource bindings (declaration metadata), and the tasks. Everything render-only
+//! (`harness`, `model`, `persona`, `permissions`, `transport`, `strategy`, `meta{}`) is baked into
+//! the tasks/commands by the render layer and ignored here.
 //!
 //! Three on-disk formats lower to this model: KDL (canonical, parsed by hand in `kdl_format`), and
 //! TOML/JSON (serde). Every spec is a `service` — `type = batch` is retired; evals run through the
@@ -16,9 +16,10 @@ use std::collections::BTreeMap;
 use std::path::PathBuf;
 use std::time::Duration;
 
-use serde::Deserialize;
+use serde::de::{self, MapAccess, Visitor};
+use serde::{Deserialize, Serialize};
 
-/// A rendered agent job, lowered to the fields st2 needs to run it.
+/// A rendered agent job, lowered to the shared declaration fields st2 and other readers inspect.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AgentSpec {
     /// Unique id; the bus id is `<host>.<identity>`.
@@ -39,12 +40,27 @@ pub struct AgentSpec {
     pub keep: bool,
     /// Crash/restart policy (§4). `None` → the runner's default policy.
     pub restart: Option<Restart>,
+    /// Named typed references used by the agent. st2 preserves these for readers but does not
+    /// resolve them or assign launch, readiness, access, or lifecycle semantics.
+    pub resources: Vec<Resource>,
     /// The runnable tasks (`pty` + `exec`), sorted by name for determinism.
     pub tasks: Vec<Task>,
     /// Where this spec was loaded from — the anchor for its resources and for edits.
     pub path: PathBuf,
 }
 
+/// One agent-local semantic binding to an externally identified resource.
+///
+/// `name` is the role the resource plays for this agent, `tag` selects the downstream resource
+/// contract, and `uri` is the exact absolute identity. The envelope deliberately carries no policy.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Resource {
+    pub name: String,
+    #[serde(rename = "_tag")]
+    pub tag: String,
+    pub uri: String,
+}
+
 /// The kind of job. Only `service` (long-running) remains — `type = batch` is retired; the native
 /// `st2 eval` path (eval_spec/eval_run) replaces the old staged batch executor.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
@@ -199,6 +215,10 @@ pub(crate) struct RawSpec {
     #[serde(default)]
     pub keep: bool,
     pub restart: Option<RawRestart>,
+    /// Named resource bindings. Singular `resource` matches canonical KDL and keeps TOML/JSON maps
+    /// aligned with `resource "<name>"`.
+    #[serde(default)]
+    pub resource: RawResources,
     /// Compact catalog form: the agent itself is one pty carrying this command.
     pub command: Option<String>,
     /// Compact catalog form: the agent itself is one pty launched directly with this argv.
@@ -217,6 +237,17 @@ pub(crate) struct RawSpec {
     pub exec: BTreeMap<String, RawTask>,
 }
 
+#[derive(Debug, Default)]
+pub(crate) struct RawResources(BTreeMap<String, RawResource>);
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct RawResource {
+    #[serde(rename = "_tag")]
+    pub(crate) tag: String,
+    pub(crate) uri: String,
+}
+
 #[derive(Debug, Default, Deserialize)]
 pub(crate) struct RawTask {
     pub id: Option<String>,
@@ -261,6 +292,113 @@ impl RawRestart {
     }
 }
 
+impl RawResources {
+    pub(crate) fn insert(&mut self, name: String, resource: RawResource) -> anyhow::Result<()> {
+        if self.0.insert(name.clone(), resource).is_some() {
+            anyhow::bail!("duplicate resource binding '{name}'");
+        }
+        Ok(())
+    }
+
+    fn lower(self) -> anyhow::Result<Vec<Resource>> {
+        self.0
+            .into_iter()
+            .map(|(name, resource)| {
+                if name.is_empty() {
+                    anyhow::bail!("resource binding name cannot be empty");
+                }
+                if resource.tag.is_empty() {
+                    anyhow::bail!("resource binding '{name}' has an empty `_tag`");
+                }
+                validate_absolute_uri(&resource.uri).map_err(|reason| {
+                    anyhow::anyhow!(
+                        "resource binding '{name}' `uri` must be an exact absolute URI: {reason}"
+                    )
+                })?;
+                Ok(Resource {
+                    name,
+                    tag: resource.tag,
+                    uri: resource.uri,
+                })
+            })
+            .collect()
+    }
+}
+
+impl<'de> Deserialize<'de> for RawResources {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        struct ResourceMapVisitor;
+
+        impl<'de> Visitor<'de> for ResourceMapVisitor {
+            type Value = RawResources;
+
+            fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                formatter.write_str("a map of uniquely named resource bindings")
+            }
+
+            fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+            where
+                A: MapAccess<'de>,
+            {
+                let mut resources = BTreeMap::new();
+                while let Some((name, resource)) = map.next_entry::<String, RawResource>()? {
+                    if resources.insert(name.clone(), resource).is_some() {
+                        return Err(de::Error::custom(format!(
+                            "duplicate resource binding '{name}'"
+                        )));
+                    }
+                }
+                Ok(RawResources(resources))
+            }
+        }
+
+        deserializer.deserialize_map(ResourceMapVisitor)
+    }
+}
+
+fn validate_absolute_uri(uri: &str) -> Result<(), &'static str> {
+    let Some(colon) = uri.find(':') else {
+        return Err("missing scheme");
+    };
+    let scheme = &uri[..colon];
+    let mut chars = scheme.chars();
+    if !chars
+        .next()
+        .is_some_and(|character| character.is_ascii_alphabetic())
+        || !chars.all(|character| {
+            character.is_ascii_alphanumeric() || matches!(character, '+' | '-' | '.')
+        })
+    {
+        return Err("invalid scheme");
+    }
+    if !uri.is_ascii()
+        || uri
+            .bytes()
+            .any(|byte| byte.is_ascii_whitespace() || byte.is_ascii_control())
+    {
+        return Err("contains characters outside URI syntax");
+    }
+    let bytes = uri.as_bytes();
+    let mut offset = colon + 1;
+    while offset < bytes.len() {
+        if bytes[offset] == b'%' {
+            if offset + 2 >= bytes.len()
+                || !bytes[offset + 1].is_ascii_hexdigit()
+                || !bytes[offset + 2].is_ascii_hexdigit()
+            {
+                return Err("contains an invalid percent escape");
+            }
+            offset += 3;
+        } else {
+            offset += 1;
+        }
+    }
+    Ok(())
+}
+
 impl RawSpec {
     /// A parsed file is a *spec candidate* when it carries an agent-shaped signal — an identity, a
     /// `type`, or task blocks. Random TOML/JSON in the tree has none of these and is skipped.
@@ -270,6 +408,7 @@ impl RawSpec {
             || self.command.is_some()
             || self.argv.is_some()
             || self.ding
+            || !self.resource.0.is_empty()
             || !self.pty.is_empty()
             || !self.exec.is_empty()
     }
@@ -337,6 +476,7 @@ impl RawSpec {
 
         // `service` is the only job type; a stray `type` string is caught by validate (unknown-type).
         let job_type = JobType::Service;
+        let resources = self.resource.lower()?;
 
         Ok(AgentSpec {
             identity,
@@ -348,6 +488,7 @@ impl RawSpec {
             retired: self.retired,
             keep: self.keep,
             restart: self.restart.map(RawRestart::lower),
+            resources,
             tasks,
             path,
         })