Add artifact recipe adapter prototype (#88)

Add an artifact-capable CLI recipe adapter and route Matrix/Telegram replies through an internal outbound message envelope.

Document the recipes/adapters/orchestrators direction and add Docker smoke coverage for npcsh, OmO/oh-my-opencode, and Gas Town CLI surfaces.

Author: bglusman

crates/calciforge/src/adapters/artifact_cli.rs

@@ -22,6 +22,7 @@ use std::fmt;
 
 pub mod acp;
 pub mod acpx;
+pub mod artifact_cli;
 pub mod cli;
 pub mod codex_cli;
 pub mod dirac_cli;
@@ -35,6 +36,7 @@ pub mod zeroclaw_native;
 
 pub use acp::AcpAdapter;
 pub use acpx::AcpxAdapter;
+pub use artifact_cli::ArtifactCliAdapter;
 pub use cli::CliAdapter;
 pub use codex_cli::CodexCliAdapter;
 pub use dirac_cli::DiracCliAdapter;
@@ -45,6 +47,7 @@ pub use zeroclaw::ZeroClawAdapter;
 pub use zeroclaw_native::ZeroClawNativeAdapter;
 
 use crate::config::AgentConfig;
+use crate::messages::OutboundMessage;
 
 // ---------------------------------------------------------------------------
 // Error type
@@ -161,6 +164,20 @@ pub trait AgentAdapter: Send + Sync {
         self.dispatch(ctx.message).await
     }
 
+    /// Dispatch and return a channel-agnostic outbound envelope.
+    ///
+    /// Text-only adapters inherit this compatibility wrapper. Artifact-aware
+    /// adapters override it so channels can render media natively where
+    /// supported, or fall back to text paths elsewhere.
+    async fn dispatch_message_with_context(
+        &self,
+        ctx: DispatchContext<'_>,
+    ) -> Result<OutboundMessage, AdapterError> {
+        self.dispatch_with_context(ctx)
+            .await
+            .map(OutboundMessage::text)
+    }
+
     /// Short name for logs and `!agents` output (e.g. "openclaw-channel", "zeroclaw", "cli").
     fn kind(&self) -> &'static str;
 
@@ -193,7 +210,7 @@ pub fn agent_supports_model_override(agent: &AgentConfig) -> bool {
 
     matches!(
         agent.kind.as_str(),
-        "zeroclaw-http" | "zeroclaw-native" | "zeroclaw" | "cli" | "codex-cli"
+        "zeroclaw-http" | "zeroclaw-native" | "zeroclaw" | "cli" | "artifact-cli" | "codex-cli"
     )
 }
 
@@ -216,6 +233,7 @@ pub fn agent_supports_model_override(agent: &AgentConfig) -> bool {
 /// | `zeroclaw-native`  | `/webhook` + history | ✅ in-process ring buffer | ✅ |
 /// | `zeroclaw`         | `/webhook`          | per-ZeroClaw-config | n/a |
 /// | `cli`              | subprocess stdin    | ❌ one-shot         | n/a |
+/// | `artifact-cli`     | subprocess stdin + artifact dir | ❌ one-shot | n/a |
 /// | `codex-cli`        | `codex exec`        | ❌ one-shot         | n/a |
 /// | `dirac-cli`        | `dirac --yolo --json` | ❌ one-shot       | n/a |
 /// | `acp`              | SACP stdio          | ✅ persistent proc  | n/a |
@@ -316,6 +334,18 @@ pub fn build_adapter(agent: &AgentConfig) -> Result<Box<dyn AgentAdapter>, Strin
                 agent.timeout_ms,
             )))
         }
+        "artifact-cli" => {
+            let command = agent.command.clone().ok_or_else(|| {
+                format!("agent '{}': kind='artifact-cli' requires command", agent.id)
+            })?;
+            Ok(Box::new(ArtifactCliAdapter::new(
+                command,
+                agent.args.clone(),
+                agent.env.clone().unwrap_or_default(),
+                agent.model.clone(),
+                agent.timeout_ms,
+            )))
+        }
         "codex-cli" => Ok(Box::new(CodexCliAdapter::new(
             agent.command.clone(),
             agent.args.clone(),
@@ -489,6 +519,15 @@ mod tests {
         assert_eq!(adapter.kind(), "cli");
     }
 
+    #[test]
+    fn test_build_artifact_cli_adapter() {
+        let mut agent = cli_agent();
+        agent.id = "test-artifact-cli".to_string();
+        agent.kind = "artifact-cli".to_string();
+        let adapter = build_adapter(&agent).expect("should build artifact-cli adapter");
+        assert_eq!(adapter.kind(), "artifact-cli");
+    }
+
     #[test]
     fn test_build_codex_cli_adapter() {
         let agent = AgentConfig {
@@ -722,6 +761,9 @@ mod tests {
         agent.kind = "cli".to_string();
         assert!(agent_supports_model_override(&agent));
 
+        agent.kind = "artifact-cli".to_string();
+        assert!(agent_supports_model_override(&agent));
+
         agent.kind = "acpx".to_string();
         assert!(
             !agent_supports_model_override(&agent),

crates/calciforge/src/adapters/mod.rs

@@ -28,6 +28,7 @@ use crate::{
     commands::CommandHandler,
     config::{expand_tilde, CalciforgeConfig},
     context::ContextStore,
+    messages::OutboundMessage,
     router::Router,
 };
 
@@ -323,6 +324,25 @@ async fn send_matrix_message(
     Ok(())
 }
 
+async fn send_matrix_outbound_message(
+    homeserver: &str,
+    http: &reqwest::Client,
+    auth_header: &str,
+    room_id: &str,
+    message: &OutboundMessage,
+) -> Result<()> {
+    // First prototype: preserve attachments through the internal envelope and
+    // render a text fallback. Native Matrix media upload can be added here.
+    send_matrix_message(
+        homeserver,
+        http,
+        auth_header,
+        room_id,
+        &message.render_text_fallback(),
+    )
+    .await
+}
+
 async fn join_matrix_room(
     homeserver: &str,
     http: &reqwest::Client,
@@ -642,6 +662,34 @@ async fn handle_message(
             }
         }
     };
+    let send_outbound = |message: OutboundMessage, reply_kind: &'static str| {
+        let homeserver = homeserver.to_string();
+        let http = http.clone();
+        let auth_header = auth_header.to_string();
+        let room_id = room_id.to_string();
+        async move {
+            let start = std::time::Instant::now();
+            let response_len = message.response_len();
+            match send_matrix_outbound_message(&homeserver, &http, &auth_header, &room_id, &message)
+                .await
+            {
+                Ok(()) => telemetry::reply_sent(
+                    "matrix",
+                    &room_id,
+                    reply_kind,
+                    response_len,
+                    start.elapsed().as_millis() as u64,
+                ),
+                Err(e) => telemetry::reply_failed(
+                    "matrix",
+                    &room_id,
+                    reply_kind,
+                    start.elapsed().as_millis() as u64,
+                    e,
+                ),
+            }
+        }
+    };
 
     // --- Command fast-path ---
     if let Some(reply) = cmd_handler.handle(body) {
@@ -767,7 +815,7 @@ async fn handle_message(
     let model_override = cmd_handler.active_model_for_identity(identity_id);
 
     match router
-        .dispatch_with_sender_and_model(
+        .dispatch_message_with_sender_and_model(
             &augmented,
             &agent,
             config,
@@ -776,20 +824,22 @@ async fn handle_message(
         )
         .await
     {
-        Ok(response) => {
+        Ok(response_message) => {
+            let response = response_message.render_text_fallback();
             let latency_ms = dispatch_start.elapsed().as_millis() as u64;
             cmd_handler.record_dispatch(latency_ms);
             telemetry::agent_dispatch_succeeded(
                 "matrix",
                 identity_id,
                 &agent_id,
                 latency_ms,
-                response.len(),
+                response_message.response_len(),
             );
             debug!(
                 identity = %identity_id,
                 agent_id = %agent_id,
-                response_len = response.len(),
+                response_len = response_message.response_len(),
+                attachments = response_message.attachments.len(),
                 "Matrix: got agent response"
             );
             ctx_store.push_with_options(
@@ -800,7 +850,7 @@ async fn handle_message(
                 &response,
                 preserve_native_commands,
             );
-            send(response, "agent_response").await;
+            send_outbound(response_message, "agent_response").await;
         }
         Err(e) => {
             // Clash approval flow

crates/calciforge/src/channels/matrix.rs

@@ -17,6 +17,7 @@ use crate::{
     commands::CommandHandler,
     config::{expand_tilde, CalciforgeConfig},
     context::ContextStore,
+    messages::OutboundMessage,
     router::Router,
 };
 
@@ -478,7 +479,7 @@ fn handle_message_nonblocking(
 
         let dispatch_start = std::time::Instant::now();
         match router
-            .dispatch_with_sender_and_model(
+            .dispatch_message_with_sender_and_model(
                 &augmented_text,
                 &agent,
                 &config,
@@ -487,20 +488,22 @@ fn handle_message_nonblocking(
             )
             .await
         {
-            Ok(response) => {
+            Ok(response_message) => {
+                let response = response_message.render_text_fallback();
                 let latency_ms = dispatch_start.elapsed().as_millis() as u64;
                 command_handler.record_dispatch(latency_ms);
                 telemetry::agent_dispatch_succeeded(
                     "telegram",
                     &identity.id,
                     &agent_id,
                     latency_ms,
-                    response.len(),
+                    response_message.response_len(),
                 );
                 debug!(
                     identity = %identity.id,
                     agent_id = %agent_id,
-                    response_len = %response.len(),
+                    response_len = %response_message.response_len(),
+                    attachments = response_message.attachments.len(),
                     "got agent response"
                 );
 
@@ -514,8 +517,7 @@ fn handle_message_nonblocking(
                     preserve_native_commands,
                 );
 
-                // Send response — try MarkdownV2 first, fall back to plain text.
-                send_markdown_reply(bot, chat_id, response, "agent_response").await;
+                send_outbound_reply(bot, chat_id, response_message, "agent_response").await;
             }
             Err(e) => {
                 // ── Clash approval flow ─────────────────────────────────────
@@ -567,6 +569,18 @@ fn handle_message_nonblocking(
     });
 }
 
+async fn send_outbound_reply(
+    bot: Bot,
+    chat_id: ChatId,
+    reply: OutboundMessage,
+    reply_kind: &'static str,
+) {
+    // First prototype: preserve artifacts through the envelope and use the
+    // text fallback for all Telegram replies. Native photo/document sending can
+    // plug in here without changing adapter/orchestrator contracts.
+    send_markdown_reply(bot, chat_id, reply.render_text_fallback(), reply_kind).await;
+}
+
 async fn send_plain_reply(
     bot: Bot,
     chat_id: ChatId,

crates/calciforge/src/channels/telegram.rs

@@ -17,6 +17,7 @@ mod hooks;
 #[allow(dead_code)] // installer has production CLI entrypoints plus wizard/test support.
 mod install;
 mod local_model;
+mod messages;
 #[cfg(feature = "persistent-context")]
 mod persistent_context;
 mod providers;