feat(api): wire LlmClient injection seam; stop stderr writes; prune dead Planner trait (#68)

Framework-vs-host boundary tightening from the architecture audit.

Added — SessionOptions::with_llm_client(Arc<dyn LlmClient>):
- The LlmClient trait + Arc<dyn> engine already existed but were injectable
  only in #[cfg(test)] code (build_session); every public session path resolved
  via a hardcoded provider-string factory. This adds the public seam and has
  resolve_session_llm_client prefer a host-supplied client, bringing the
  Action-layer backend to parity with workspace/memory/store/security (all
  object-injectable). The provider/model factory stays the default when unset.
  Enables custom/unsupported providers, record/replay clients, and proxy/audit
  wrappers without forking core.

Fixed — framework no longer writes to the host's stderr:
- Replaced a stray eprintln!("[DEBUG] HTTP error...") in the OpenAI client
  (fired on every transport error) with tracing::error!, matching the rest of
  the crate.

Removed — dead Planner trait (planning::Planner):
- Re-exported but had zero dyn-dispatch and no consumer; all call sites use
  LlmPlanner's inherent methods. Pruned per Rule 9 (the only real variability,
  the LLM, is now swappable via with_llm_client). LlmPlanner unchanged.

Tests: 2 new resolver tests (override bypasses config; control case errors).
cargo test -p a3s-code-core --lib: 1757 passed, 0 failed. clippy clean.

Co-authored-by: Claude <claude@anthropic.com>

Author: ZhiXiao-Lin

CHANGELOG.md

@@ -14,6 +14,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   computed fresh each turn in `turn_context.rs` (no shell-out). Most importantly
   it pins the current date, which the model otherwise cannot infer past its
   training cutoff.
+- **`SessionOptions::with_llm_client`** — hosts can now inject a custom
+  `Arc<dyn LlmClient>` (custom/unsupported provider, deterministic record/replay
+  client, or HTTP proxy/audit wrapper). The `LlmClient` trait and `Arc<dyn>`
+  engine already existed but were only injectable in test code; this wires the
+  seam through the public API, bringing the Action-layer backend to parity with
+  workspace/memory/store/security (all object-injectable). The `provider/model`
+  factory remains the default when unset.
 
 ### Security
 
@@ -39,6 +46,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   discourages re-printing already-read code and creating unsolicited report
   `.md` files.
 
+### Fixed
+
+- **Framework no longer writes to the host's stderr** — replaced a stray
+  `eprintln!("[DEBUG] HTTP error...")` in the OpenAI client (fired on every
+  transport error, also leaking into the host terminal) with `tracing::error!`,
+  consistent with the rest of the crate.
+
+### Removed
+
+- **Dead `Planner` trait** (`planning::Planner`) — it was re-exported but had no
+  `dyn Planner` dispatch and no consumer; every call site uses `LlmPlanner`'s
+  inherent methods directly. Removed per the pruning rule (the real variability,
+  the LLM, is swappable via `with_llm_client`). `LlmPlanner` is unchanged.
+
 ## [3.4.0] - 2026-05-30
 
 Programmable, deterministic multi-agent orchestration — a grammar for

core/src/agent_api.rs

@@ -136,6 +136,14 @@ pub struct SessionOptions {
     pub queue_config: Option<SessionQueueConfig>,
     /// Optional security provider for taint tracking and output sanitization
     pub security_provider: Option<Arc<dyn crate::security::SecurityProvider>>,
+    /// Optional host-supplied LLM client.
+    ///
+    /// When set, it is used directly, overriding the `provider/model`
+    /// factory resolution — the one Action-layer backend that was previously
+    /// only injectable in test code. Lets a host plug in a provider the
+    /// built-in factory does not cover, a deterministic record/replay client,
+    /// or an HTTP-layer proxy/audit wrapper. Mirrors `workspace_services`.
+    pub llm_client: Option<Arc<dyn crate::llm::LlmClient>>,
     /// Optional context providers for RAG
     pub context_providers: Vec<Arc<dyn crate::context::ContextProvider>>,
     /// Optional confirmation manager for HITL

core/src/agent_api/session_config.rs

@@ -10,6 +10,13 @@ pub(super) fn resolve_session_llm_client(
     opts: &SessionOptions,
     session_id: Option<&str>,
 ) -> Result<Arc<dyn LlmClient>> {
+    // A host-supplied client overrides the provider-string factory entirely:
+    // the host owns the full Action-layer dependency (custom provider, replay
+    // client, proxy/audit wrapper). Config-based model resolution is bypassed.
+    if let Some(ref client) = opts.llm_client {
+        return Ok(Arc::clone(client));
+    }
+
     let model_ref = if let Some(ref model) = opts.model {
         model.as_str()
     } else {
@@ -94,6 +101,62 @@ pub(super) fn resolve_session_memory(opts: &SessionOptions) -> ResolvedSessionMe
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::llm::{LlmResponse, Message, StreamEvent, ToolDefinition};
+    // The LlmClient trait returns anyhow::Result; shadow super's crate::error::Result.
+    use anyhow::Result;
+    use async_trait::async_trait;
+    use tokio::sync::mpsc;
+    use tokio_util::sync::CancellationToken;
+
+    struct DummyClient;
+
+    #[async_trait]
+    impl LlmClient for DummyClient {
+        async fn complete(
+            &self,
+            _: &[Message],
+            _: Option<&str>,
+            _: &[ToolDefinition],
+        ) -> Result<LlmResponse> {
+            anyhow::bail!("resolver short-circuits before the client is called")
+        }
+        async fn complete_streaming(
+            &self,
+            _: &[Message],
+            _: Option<&str>,
+            _: &[ToolDefinition],
+            _: CancellationToken,
+        ) -> Result<mpsc::Receiver<StreamEvent>> {
+            anyhow::bail!("not used")
+        }
+    }
+
+    // A default CodeConfig has no default_model, so the provider-string factory
+    // path errors — proving the override is what makes resolution succeed.
+    #[test]
+    fn host_supplied_llm_client_overrides_factory() {
+        let config = CodeConfig::default();
+        let opts = SessionOptions::new().with_llm_client(Arc::new(DummyClient));
+        assert!(
+            resolve_session_llm_client(&config, &opts, None).is_ok(),
+            "with_llm_client must bypass provider/model config resolution"
+        );
+    }
+
+    #[test]
+    fn without_llm_client_missing_default_model_errors() {
+        let config = CodeConfig::default();
+        let opts = SessionOptions::new();
+        assert!(
+            resolve_session_llm_client(&config, &opts, None).is_err(),
+            "no host client + no default_model should error (control case)"
+        );
+    }
+}
+
 pub(super) fn resolve_session_store(
     code_config: &CodeConfig,
     opts: &SessionOptions,

core/src/agent_api/session_options.rs

@@ -21,6 +21,7 @@ impl std::fmt::Debug for SessionOptions {
             .field("skill_dirs", &self.skill_dirs)
             .field("queue_config", &self.queue_config)
             .field("security_provider", &self.security_provider.is_some())
+            .field("llm_client", &self.llm_client.is_some())
             .field("context_providers", &self.context_providers.len())
             .field("confirmation_manager", &self.confirmation_manager.is_some())
             .field("permission_checker", &self.permission_checker.is_some())
@@ -110,6 +111,18 @@ impl SessionOptions {
         self
     }
 
+    /// Provide a custom LLM client for this session.
+    ///
+    /// When set, this client is used directly, overriding the `provider/model`
+    /// factory resolution. Use it to plug in a provider the built-in factory
+    /// does not cover, a deterministic record/replay client for tests, or an
+    /// HTTP-layer proxy/audit wrapper. Mirrors [`Self::with_workspace_backend`];
+    /// the `provider/model` config path remains the default when unset.
+    pub fn with_llm_client(mut self, client: Arc<dyn crate::llm::LlmClient>) -> Self {
+        self.llm_client = Some(client);
+        self
+    }
+
     /// Add a file system context provider for simple RAG
     pub fn with_fs_context(mut self, root_path: impl Into<PathBuf>) -> Self {
         let config = crate::context::FileSystemContextConfig::new(root_path);

core/src/llm/openai.rs

@@ -356,7 +356,7 @@ impl LlmClient for OpenAiClient {
                             }
                         }
                         Err(e) => {
-                            eprintln!("[DEBUG] HTTP error: {:?}", e);
+                            tracing::error!("HTTP error: {e:?}");
                             AttemptOutcome::Fatal(e)
                         }
                     }

core/src/planning/llm_planner.rs

@@ -7,7 +7,6 @@
 use crate::llm::{LlmClient, Message};
 use crate::planning::{AgentGoal, Complexity, ExecutionPlan, Task};
 use anyhow::{Context, Result};
-use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 
@@ -33,27 +32,6 @@ pub struct PreAnalysis {
     pub optimized_input: String,
 }
 
-/// Trait for planning providers
-///
-/// Abstracts plan generation, goal extraction, and achievement evaluation.
-/// Allows different implementations (LLM-based, heuristic, test mocks).
-#[async_trait]
-pub trait Planner: Send + Sync {
-    /// Generate an execution plan from a prompt
-    async fn create_plan(&self, llm: &Arc<dyn LlmClient>, prompt: &str) -> Result<ExecutionPlan>;
-
-    /// Extract a goal with success criteria from a prompt
-    async fn extract_goal(&self, llm: &Arc<dyn LlmClient>, prompt: &str) -> Result<AgentGoal>;
-
-    /// Evaluate whether a goal has been achieved given current state
-    async fn check_achievement(
-        &self,
-        llm: &Arc<dyn LlmClient>,
-        goal: &AgentGoal,
-        current_state: &str,
-    ) -> Result<AchievementResult>;
-}
-
 /// LLM-powered planner that generates plans, extracts goals, and evaluates achievement
 pub struct LlmPlanner;
 
@@ -380,27 +358,6 @@ impl LlmPlanner {
     }
 }
 
-// Implement Planner trait for LlmPlanner
-#[async_trait]
-impl Planner for LlmPlanner {
-    async fn create_plan(&self, llm: &Arc<dyn LlmClient>, prompt: &str) -> Result<ExecutionPlan> {
-        LlmPlanner::create_plan(llm, prompt).await
-    }
-
-    async fn extract_goal(&self, llm: &Arc<dyn LlmClient>, prompt: &str) -> Result<AgentGoal> {
-        LlmPlanner::extract_goal(llm, prompt).await
-    }
-
-    async fn check_achievement(
-        &self,
-        llm: &Arc<dyn LlmClient>,
-        goal: &AgentGoal,
-        current_state: &str,
-    ) -> Result<AchievementResult> {
-        LlmPlanner::check_achievement(llm, goal, current_state).await
-    }
-}
-
 // ============================================================================
 // Tests
 // ============================================================================

core/src/planning/mod.rs

@@ -7,7 +7,7 @@
 
 pub mod llm_planner;
 
-pub use llm_planner::{AchievementResult, LlmPlanner, Planner, PreAnalysis};
+pub use llm_planner::{AchievementResult, LlmPlanner, PreAnalysis};
 
 use serde::{Deserialize, Serialize};
 use std::fmt;