feat: expose authoritative agent graph primitives

agent-identity: dev3.direct.omp.jmg9x29x
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.0.11
agent-runtime: OMP 18.0.11
tooling-profile: dotfiles@2161b9c

Author: schickling-assistant

crates/agent-spec/src/kdl_format.rs

@@ -146,6 +146,22 @@ fn agent_node_to_raw(node: &DeclaredNode) -> anyhow::Result<RawSpec> {
                     anyhow::anyhow!("agent `deliver` value must be a string")
                 })?));
             }
+            "session-driver" => {
+                anyhow::ensure!(
+                    raw.session_driver.is_none(),
+                    "agent declares `session-driver` more than once"
+                );
+                anyhow::ensure!(
+                    child.type_name.is_none()
+                        && child.children.is_empty()
+                        && child.entries.len() == 1
+                        && child.entries[0].name.is_none(),
+                    "agent `session-driver` must contain exactly one positional string"
+                );
+                raw.session_driver = Some(Some(arg_string(child).ok_or_else(|| {
+                    anyhow::anyhow!("agent `session-driver` value must be a string")
+                })?));
+            }
             "claude" => {
                 anyhow::ensure!(
                     raw.driver.claude.is_none(),

crates/agent-spec/src/lib.rs

@@ -47,8 +47,8 @@ pub use discovery::{
 };
 pub use spec::{
     AgentDesiredState, AgentSpec, ClaudeDriver, CodexDriver, DeliveryTransport, Driver, JobType,
-    OpenCodeDriver, PiDriver, Resource, Restart, RestartMode, STREAM_TASK_PREFIX, Stream,
-    StreamLaunch, Task, TaskKind, TaskLifecycle, parse_duration, stream_name_of_task,
+    OpenCodeDriver, PiDriver, Resource, Restart, RestartMode, STREAM_TASK_PREFIX, SessionDriver,
+    Stream, StreamLaunch, Task, TaskKind, TaskLifecycle, parse_duration, stream_name_of_task,
     validate_desired_state_reason,
 };
 pub use profile::{

crates/agent-spec/src/spec.rs

@@ -5,10 +5,10 @@
 //! stage's script; must NOT allocate a terminal, R09). st2 reads only the runner-normative subset:
 //! `identity`, presentation (`name`, `description`), `host`, `role` (metadata only), `type`,
 //! `workspace`, whole-agent desired state (plus legacy `retired`), `keep`, `supervisor`,
-//! `restart{}`, `deliver`, typed harness drivers, task lifecycle, Resource bindings (declaration
-//! metadata), and the tasks. Everything else that is render-only (`harness`, `model`, `persona`,
-//! `permissions`, legacy `transport` metadata, `strategy`, `meta{}`) is baked into the
-//! tasks/commands by the render layer and ignored here.
+//! `restart{}`, `deliver`, `session-driver`, typed harness drivers, task lifecycle, Resource
+//! bindings (declaration metadata), and the tasks. Everything else that is render-only (`harness`,
+//! `model`, `persona`, `permissions`, legacy `transport` metadata, `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
@@ -69,6 +69,44 @@ impl DeliveryTransport {
         }
     }
 }
+/// The native session driver entered by an otherwise opaque launch.
+///
+/// This is an ownership assertion only. It does not render a provider launch or select a message
+/// delivery transport.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SessionDriver {
+    Claude,
+    Codex,
+    Pi,
+    OpenCode,
+    Omp,
+}
+
+impl SessionDriver {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Claude => "claude",
+            Self::Codex => "codex",
+            Self::Pi => "pi",
+            Self::OpenCode => "opencode",
+            Self::Omp => "omp",
+        }
+    }
+
+    fn parse(value: &str) -> anyhow::Result<Self> {
+        match value {
+            "claude" => Ok(Self::Claude),
+            "codex" => Ok(Self::Codex),
+            "pi" => Ok(Self::Pi),
+            "opencode" => Ok(Self::OpenCode),
+            "omp" => Ok(Self::Omp),
+            _ => anyhow::bail!(
+                "unsupported `session-driver` value '{value}' (expected `claude`, `codex`, `pi`, `opencode`, or `omp`)"
+            ),
+        }
+    }
+}
+
 
 /// One typed harness driver declaration.
 ///
@@ -216,6 +254,8 @@ pub struct AgentSpec {
     pub restart: Option<Restart>,
     /// Provider-native delivery selected by `deliver`; `None` means legacy `ding` or no delivery.
     pub delivery: Option<DeliveryTransport>,
+    /// Native session ownership asserted for an otherwise opaque launch.
+    pub session_driver: Option<SessionDriver>,
     /// Typed harness declaration used by task and render compilation.
     pub driver: Option<Driver>,
     /// Named typed references used by the agent. st2 preserves these for readers but does not
@@ -560,7 +600,10 @@ pub(crate) struct RawSpec {
     /// Compact catalog form: select one provider-native delivery transport.
     #[serde(default, deserialize_with = "deserialize_explicit_optional")]
     pub deliver: Option<Option<String>>,
-    /// Direct `claude {}` or `codex {}` provider block.
+    /// Native session ownership asserted for an otherwise opaque launch.
+    #[serde(default, deserialize_with = "deserialize_explicit_optional")]
+    pub session_driver: Option<Option<String>>,
+    /// Direct typed provider driver block.
     #[serde(flatten)]
     pub driver: RawDriver,
     /// Compact catalog form: reconciliation policy for the generated agent PTY.
@@ -1080,6 +1123,7 @@ impl RawSpec {
             || self.argv.is_some()
             || self.ding
             || self.deliver.is_some()
+            || self.session_driver.is_some()
             || self.driver.claude.is_some()
             || self.driver.codex.is_some()
             // pi predates this predicate gaining driver awareness and was silently skipped too:
@@ -1121,12 +1165,34 @@ impl RawSpec {
             .as_deref()
             .map(DeliveryTransport::parse)
             .transpose()?;
+        let session_driver = reject_explicit_null("session_driver", self.session_driver)?
+            .as_deref()
+            .map(SessionDriver::parse)
+            .transpose()?;
         let driver = self.driver.lower(&identity)?;
         let has_driver = driver.is_some();
         anyhow::ensure!(
             !(self.ding && delivery.is_some()),
             "agent '{identity}' declares both `ding` and `deliver`; choose one transport"
         );
+        anyhow::ensure!(
+            !(self.ding && has_driver),
+            "agent '{identity}' declares both `ding` and a typed driver; choose one session owner"
+        );
+        if session_driver.is_some() {
+            anyhow::ensure!(
+                !self.ding,
+                "agent '{identity}' declares both `session-driver` and `ding`; choose one session owner"
+            );
+            anyhow::ensure!(
+                delivery.is_none(),
+                "agent '{identity}' declares both `session-driver` and `deliver`; choose one session owner"
+            );
+            anyhow::ensure!(
+                !has_driver,
+                "agent '{identity}' declares both `session-driver` and a typed driver; choose one session owner"
+            );
+        }
         validate_launch(
             &identity,
             self.command.as_ref(),
@@ -1277,6 +1343,7 @@ impl RawSpec {
             keep: self.keep,
             restart: self.restart.map(RawRestart::lower),
             delivery,
+            session_driver,
             driver,
             resources,
             streams,

crates/agent-spec/tests/discovery.rs

@@ -13,7 +13,7 @@ use agent_spec::spec::{
     TaskLifecycle,
 };
 use agent_spec::{
-    AgentDesiredState, AgentSpec, JobType, Resource, Task, discover, discover_file,
+    AgentDesiredState, AgentSpec, JobType, Resource, SessionDriver, Task, discover, discover_file,
     discover_strict,
 };
 
@@ -390,6 +390,7 @@ agent "cos" {
         Some("Silber.cos")
     );
     assert!(spec.delivery.is_none());
+    assert!(spec.session_driver.is_none());
     assert!(spec.has_delivery_transport());
 }
 
@@ -480,6 +481,165 @@ fn deliver_rejects_unknown_duplicate_mixed_and_malformed_declarations() {
         );
     }
 }
+#[test]
+fn session_driver_is_closed_ownership_for_an_opaque_launch() {
+    let tmp = tempfile::tempdir().unwrap();
+    for driver in ["claude", "codex", "pi", "opencode", "omp"] {
+        write(
+            tmp.path(),
+            &format!("agents/h/{driver}/agent.kdl"),
+            &format!(
+                r#"agent "{driver}" {{ host "h"; argv "axe" "agent" "launch"; session-driver "{driver}" }}"#
+            ),
+        );
+    }
+
+    let found = discover(tmp.path());
+    assert!(found.errors.is_empty(), "{:?}", found.errors);
+    for (name, expected) in [
+        ("claude", SessionDriver::Claude),
+        ("codex", SessionDriver::Codex),
+        ("pi", SessionDriver::Pi),
+        ("opencode", SessionDriver::OpenCode),
+        ("omp", SessionDriver::Omp),
+    ] {
+        let spec = find(&found.specs, name);
+        assert_eq!(spec.session_driver, Some(expected));
+        assert_eq!(spec.session_driver.unwrap().as_str(), name);
+        assert!(spec.driver.is_none());
+        assert!(spec.delivery.is_none());
+        assert_eq!(spec.tasks.len(), 1);
+        assert_eq!(argv(&spec.tasks[0]), ["axe", "agent", "launch"]);
+        assert!(!spec.tasks[0].derived);
+    }
+}
+
+#[test]
+fn session_driver_rejects_unknown_duplicate_malformed_and_conflicting_declarations() {
+    for (name, declaration, expected) in [
+        (
+            "unknown",
+            r#"agent "worker" { argv "axe"; session-driver "cursor" }"#,
+            "unsupported `session-driver` value 'cursor'",
+        ),
+        (
+            "duplicate",
+            r#"agent "worker" { argv "axe"; session-driver "claude"; session-driver "codex" }"#,
+            "declares `session-driver` more than once",
+        ),
+        (
+            "missing",
+            r#"agent "worker" { argv "axe"; session-driver }"#,
+            "must contain exactly one positional string",
+        ),
+        (
+            "non-string",
+            r#"agent "worker" { argv "axe"; session-driver #true }"#,
+            "value must be a string",
+        ),
+        (
+            "property",
+            r#"agent "worker" { argv "axe"; session-driver "claude" mode="owner" }"#,
+            "must contain exactly one positional string",
+        ),
+        (
+            "children",
+            r#"agent "worker" { argv "axe"; session-driver "claude" { prompt "ignored" } }"#,
+            "must contain exactly one positional string",
+        ),
+        (
+            "ding",
+            r#"agent "worker" { argv "axe"; session-driver "claude"; ding }"#,
+            "declares both `session-driver` and `ding`",
+        ),
+        (
+            "deliver",
+            r#"agent "worker" { argv "axe"; session-driver "claude"; deliver "mcp" }"#,
+            "declares both `session-driver` and `deliver`",
+        ),
+        (
+            "driver",
+            r#"agent "worker" { session-driver "claude"; claude { prompt "go" } }"#,
+            "declares both `session-driver` and a typed driver",
+        ),
+    ] {
+        let tmp = tempfile::tempdir().unwrap();
+        write(
+            tmp.path(),
+            &format!("agents/h/{name}/agent.kdl"),
+            declaration,
+        );
+        let found = discover(tmp.path());
+        assert!(found.specs.is_empty(), "{name}: {:?}", found.specs);
+        assert_eq!(found.errors.len(), 1, "{name}: {:?}", found.errors);
+        assert!(
+            found.errors[0].message.contains(expected),
+            "{name}: expected {expected:?}, got {:?}",
+            found.errors[0]
+        );
+    }
+}
+
+#[test]
+fn session_driver_lowers_from_toml_and_json_and_rejects_null() {
+    let tmp = tempfile::tempdir().unwrap();
+    write(
+        tmp.path(),
+        "agents/h/toml/agent.toml",
+        "identity = \"toml\"\nhost = \"h\"\nargv = [\"axe\"]\nsession_driver = \"codex\"\n",
+    );
+    write(
+        tmp.path(),
+        "agents/h/json/agent.json",
+        r#"{"identity":"json","host":"h","argv":["axe"],"session_driver":"pi"}"#,
+    );
+    write(
+        tmp.path(),
+        "agents/h/null/agent.json",
+        r#"{"identity":"null","host":"h","argv":["axe"],"session_driver":null}"#,
+    );
+
+    let found = discover(tmp.path());
+    assert_eq!(find(&found.specs, "toml").session_driver, Some(SessionDriver::Codex));
+    assert_eq!(find(&found.specs, "json").session_driver, Some(SessionDriver::Pi));
+    assert_eq!(found.errors.len(), 1, "{:?}", found.errors);
+    assert!(
+        found.errors[0]
+            .message
+            .contains("field `session_driver` must not be null"),
+        "{:?}",
+        found.errors[0]
+    );
+}
+
+#[test]
+fn typed_driver_blocks_reject_legacy_ding() {
+    for (name, driver) in [
+        ("claude", r#"claude { prompt "go" }"#),
+        ("codex", r#"codex { prompt "go" }"#),
+        ("pi", r#"pi { prompt "go" }"#),
+        ("opencode", r#"opencode { prompt "go" }"#),
+        ("omp", r#"omp { prompt "go" }"#),
+    ] {
+        let tmp = tempfile::tempdir().unwrap();
+        write(
+            tmp.path(),
+            &format!("agents/h/{name}/agent.kdl"),
+            &format!(r#"agent "{name}" {{ ding; {driver} }}"#),
+        );
+        let found = discover(tmp.path());
+        assert!(found.specs.is_empty(), "{name}: {:?}", found.specs);
+        assert_eq!(found.errors.len(), 1, "{name}: {:?}", found.errors);
+        assert!(
+            found.errors[0]
+                .message
+                .contains("declares both `ding` and a typed driver"),
+            "{name}: {:?}",
+            found.errors[0]
+        );
+    }
+}
+
 
 #[test]
 fn compact_adopt_only_lifecycle_lowers_to_the_generated_agent_task() {