Merge pull request #63 from efecnc/feat/semble-scout

feat: add Semble Scout agent

Author: monatis

AGENTS.md

@@ -37,7 +37,7 @@ Git worktrees (`git_worktree`): **off** in a minimal `config.toml` until you set
 
 Sub-agents (`subagent_spawn`, `task_*`, `subagent_plan_execute`, `task_history_list`): **off** in a minimal config until `[harness.subagents] enabled = true`. The onboarding template enables this for new workspaces. Sub-agents run a second `run_reasoning_loop` with a synthetic chat id (`subagent-…`) and optional tool allowlist. `cancel_children_on_parent_cancel` (default true) controls whether an **explicit** parent cancel (`BusMessage::Cancel` / API cancel / terminal **`/cancel`**) also cancels those child tasks (not triggered by queued follow-up user messages). Completed runs are recorded in the workspace SQLite table **`subagent_tasks`** (same DB as session memory). See `docs/harness-implementation-plan.md` Phase 5.
 
-**Named agents** (Phase 5b): `subagent_spawn` now accepts an optional `agent` parameter to invoke specialized sub-agents defined in config. Each named agent has its own system prompt, tool allowlist, and optional model/temperature overrides (wired at spawn in `subagent.rs` via `ProviderCredentials`). Three built-in defaults are registered when no `[agents.<name>]` blocks exist in `config.toml`: **researcher** (web+read tools, temp 0.1), **coder** (full harness allowlist, temp 0.2), and **evaluator** (read-only review tools, temp 0.0). Tools: `agent_list` (list available agents), `task_dashboard` (unified active+history view). The coordinator system prompt is auto-injected with agent descriptions. `wake_on_completion` (default true) enqueues a synthetic inbound when a subagent finishes so the parent can consume the result without polling. Config keys (under `[harness.subagents]`): `wake_on_completion`, `task_history_retention`. Agent definitions use `[agents.<name>]` blocks or `[harness.agents.<name>]` (harness-level wins in merge): `description` (required), `mode` ("subagent"), `system_prompt`, `system_prompt_file`, `allowed_tools`, `model`, `temperature`, `max_iterations`, `hidden`, `color`. Implementation: `src/agent/registry.rs`, `src/agent/subagent.rs`. **`subagent_plan_execute`** accepts optional per-step `"agent"` in plan JSON (same schema as spawn).
+**Named agents** (Phase 5b): `subagent_spawn` now accepts an optional `agent` parameter to invoke specialized agents defined in config. Four built-in defaults are registered when no `[agents.<name>]` blocks exist in `config.toml`: **Semble Scout** (modelsiz local code retrieval), **researcher** (web+read tools, temp 0.1), **coder** (full harness allowlist, temp 0.2), and **evaluator** (read-only review tools, temp 0.0). Semble Scout is a deterministic `mode = "semble_scout"` worker: it invokes `uvx --from semble[mcp]==0.5.1 semble search` against the host-supplied project root, never accepts a root from the LLM, and keeps its cache under `.isanagent/cache/semble`. Tools: `agent_list` (list available agents), `task_dashboard` (unified active+history view). The coordinator system prompt is auto-injected with agent descriptions. `wake_on_completion` (default true) enqueues a synthetic inbound when a subagent finishes so the parent can consume the result without polling. Config keys (under `[harness.subagents]`): `wake_on_completion`, `task_history_retention`. Agent definitions use `[agents.<name>]` blocks or `[harness.agents.<name>]` (harness-level wins in merge): `description` (required), `mode` (`"subagent"` or `"semble_scout"`), `system_prompt`, `system_prompt_file`, `allowed_tools`, `model`, `temperature`, `max_iterations`, `hidden`, `color`. Implementation: `src/agent/registry.rs`, `src/agent/subagent.rs`. **`subagent_plan_execute`** accepts optional per-step `"agent"` in plan JSON (same schema as spawn).
 
 **MaxEvolve kernel porting** (`[harness.kernel_porting] enabled = true`): Triton/PyTorch→JAX/Pallas workflow via named agents (`kernel_orchestrator`, `gpu_to_jax`, `evolve_orchestrator`, …), `kernel-porting` skill, Python validators under `skills/kernel-porting/scripts/`, MAP-Elites tools (`kernel_db_init`, `kernel_db_sample`, `kernel_db_insert`, `kernel_db_status` in `src/tools/kernel_porting.rs`), and Colab/SSH hardware profiling. Operator guide: `docs/kernel-porting-user-guide.md`. Projects live under `kernels/projects/{id}/`. Onboarding copies prompts to `.agents/prompts/`, reference docs to `kernels/reference/`, and benchmarks to `benchmarks/`.
 

src/agent/mod.rs

@@ -1510,6 +1510,9 @@ pub struct SubagentHarnessParams {
     pub wake_on_completion: bool,
     pub task_history_retention: usize,
     pub bus_tx: Option<tokio::sync::mpsc::Sender<crate::bus::BusMessage>>,
+    /// Canonical project root available to deterministic local worker agents.
+    /// This is intentionally separate from IsanAgent's state directory.
+    pub workspace_dir: std::path::PathBuf,
 }
 
 /// The central logic for an autonomous Agent running inside an ActorNode.
@@ -1609,6 +1612,7 @@ impl AgentLogic {
                 wake_on_completion: p.wake_on_completion,
                 task_history_retention: p.task_history_retention,
                 bus_tx: p.bus_tx.clone(),
+                workspace_dir: p.workspace_dir.clone(),
             }))
         });
 

src/agent/registry.rs

@@ -84,15 +84,20 @@ impl AgentRegistry {
             return String::new();
         }
         let mut s = String::from("\n\n## Available Specialized Agents\n\n");
-        s.push_str("You are a coordinator. Delegate work to specialized sub-agents using the `agent_spawn` tool. ");
+        s.push_str("You are a coordinator. Delegate work to specialized agents using the `subagent_spawn` tool. ");
         s.push_str(
             "Use `agent_list` to refresh your knowledge of available agents at any time.\n\n",
         );
         for m in &visible {
-            let tools_summary = match &m.allowed_tools {
-                None => "inherits harness allowlist".to_string(),
-                Some(v) if v.is_empty() => "read-only, no tools".to_string(),
-                Some(v) => v.join(", "),
+            let tools_summary = if m.mode == AgentMode::SembleScout {
+                "local Semble code search only (no model, arbitrary shell, or project writes)"
+                    .to_string()
+            } else {
+                match &m.allowed_tools {
+                    None => "inherits harness allowlist".to_string(),
+                    Some(v) if v.is_empty() => "read-only, no tools".to_string(),
+                    Some(v) => v.join(", "),
+                }
             };
             let iter_hint = match m.max_iterations {
                 Some(n) => format!(", max {} iterations", n),
@@ -104,6 +109,7 @@ impl AgentRegistry {
             ));
         }
         s.push_str("\nGuidelines:\n- For research: delegate to a research-capable agent.\n");
+        s.push_str("- For exploring an unfamiliar local codebase, delegate to Semble Scout before broad grep or full-file reads.\n");
         s.push_str("- For code changes: delegate to a coder agent.\n");
         s.push_str("- For review: delegate to a read-only review agent.\n");
         s.push_str("- Use `wait=false` for parallel work; `wait=true` when result is needed.\n");
@@ -168,6 +174,21 @@ fn resolve_system_prompt(def: &AgentDefinition, sandbox_dir: &std::path::Path) -
 
 pub fn default_agent_definitions() -> HashMap<String, AgentDefinition> {
     let mut map = HashMap::new();
+    map.insert(
+        "semble-scout".to_string(),
+        AgentDefinition {
+            description: "Find the most relevant local code snippets for a natural-language or symbol query using Semble".to_string(),
+            mode: AgentMode::SembleScout,
+            system_prompt: None,
+            system_prompt_file: None,
+            allowed_tools: Some(vec![]),
+            model: None,
+            temperature: None,
+            max_iterations: None,
+            hidden: false,
+            color: Some("#8B5CF6".into()),
+        },
+    );
     map.insert(
         "researcher".to_string(),
         AgentDefinition {
@@ -275,7 +296,11 @@ mod tests {
     #[test]
     fn default_agents_have_expected_roles() {
         let defs = default_agent_definitions();
-        assert_eq!(defs.len(), 3);
+        assert_eq!(defs.len(), 4);
+        assert!(matches!(
+            defs.get("semble-scout").map(|agent| agent.mode.clone()),
+            Some(AgentMode::SembleScout)
+        ));
         assert!(defs.contains_key("researcher"));
         assert!(defs.contains_key("coder"));
         assert!(defs.contains_key("evaluator"));

src/agent/subagent.rs

@@ -7,6 +7,7 @@ use async_trait::async_trait;
 use dashmap::DashMap;
 use serde::Deserialize;
 use serde_json::Value;
+use std::path::{Path, PathBuf};
 use tokio_util::sync::CancellationToken;
 
 use super::ReasoningLoopCtx;
@@ -17,7 +18,7 @@ use crate::channels::terminal_ui::protocol::{
     METADATA_SUBAGENT_STATUS, METADATA_SUBAGENT_TASK_ID,
 };
 use crate::clarification::ClarificationHub;
-use crate::config::ResolvedShellPolicy;
+use crate::config::{AgentMode, ResolvedShellPolicy};
 use crate::logging::LoggerHandle;
 use crate::memory::{MemoryMessage, SharedReply};
 use crate::session::SessionManager;
@@ -82,6 +83,9 @@ pub struct SubagentSpawnDeps {
     pub task_history_retention: usize,
     /// Optional extra bus sender for enqueuing synthetic follow-up messages.
     pub bus_tx: Option<tokio::sync::mpsc::Sender<BusMessage>>,
+    /// Project root used by deterministic local worker agents. The worker
+    /// never accepts a root from an LLM tool argument.
+    pub workspace_dir: PathBuf,
 }
 
 struct TaskRecord {
@@ -260,6 +264,74 @@ impl SubagentHarness {
             .ok_or_else(|| "Subagent harness is not wired to tools yet".to_string())
     }
 
+    /// Run Semble as a constrained local worker. The LLM controls only the
+    /// query text; the search root, executable shape, cache location, and
+    /// content policy are owned by the host application.
+    async fn run_semble_scout(workspace_dir: &Path, query: &str) -> Result<String, String> {
+        let query = query.trim();
+        if query.is_empty() {
+            return Err("Semble Scout needs a non-empty code search query.".to_string());
+        }
+        if !workspace_dir.is_dir() {
+            return Err(format!(
+                "Semble Scout workspace is unavailable: {}",
+                workspace_dir.display()
+            ));
+        }
+
+        let cache_dir = workspace_dir
+            .join(".isanagent")
+            .join("cache")
+            .join("semble");
+        tokio::fs::create_dir_all(&cache_dir)
+            .await
+            .map_err(|e| format!("Could not prepare Semble cache: {e}"))?;
+
+        let mut command = tokio::process::Command::new("uvx");
+        command
+            .args([
+                "--from",
+                "semble[mcp]==0.5.1",
+                "semble",
+                "search",
+                "--content",
+                "code",
+                "--top-k",
+                "8",
+                "--max-snippet-lines",
+                "16",
+                "--",
+                query,
+            ])
+            .arg(workspace_dir)
+            .current_dir(workspace_dir)
+            .env("SEMBLE_CACHE_LOCATION", &cache_dir)
+            // A cancelled parent must not leave a package install or indexer
+            // process running after its agent turn is gone.
+            .kill_on_drop(true);
+
+        // The first `uvx` run may need to download Semble and its model assets.
+        // Do not impose an arbitrary timeout here: on a slow but healthy
+        // network that would turn a one-time install into a false failure.
+        // `kill_on_drop(true)` still cleans up the child if the runtime itself
+        // drops this task during shutdown.
+        let output = command.output().await.map_err(|e| {
+            format!("Semble Scout could not start `uvx`: {e}. Install uv first, then retry.")
+        })?;
+        let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
+        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+        if !output.status.success() {
+            let detail = if stderr.is_empty() { stdout } else { stderr };
+            return Err(format!("Semble Scout search failed: {detail}"));
+        }
+        if stdout.is_empty() {
+            return Ok("Semble Scout found no matching code snippets.".to_string());
+        }
+        Ok(format!(
+            "Semble Scout results (local code search):\n\n{stdout}"
+        ))
+    }
+
     pub async fn spawn(&self, spec: SubagentSpawnSpec) -> Result<String, String> {
         let SubagentSpawnSpec {
             parent_channel,
@@ -301,6 +373,24 @@ impl SubagentHarness {
             None => None,
         };
 
+        // Semble Scout is deliberately a named agent rather than an MCP
+        // integration: no LLM/provider is spawned for it. It receives the
+        // coordinator's query, searches only the configured project root,
+        // and returns the retrieved snippets directly to that coordinator.
+        if manifest
+            .as_ref()
+            .is_some_and(|agent| agent.mode == AgentMode::SembleScout)
+        {
+            let result = Self::run_semble_scout(&self.inner.deps.workspace_dir, &prompt).await?;
+            return Ok(serde_json::json!({
+                "agent": "semble-scout",
+                "status": "completed",
+                "wait": true,
+                "result": result,
+            })
+            .to_string());
+        }
+
         let tools = self.tools()?;
         let task_id = uuid::Uuid::new_v4().simple().to_string();
         let child_chat_id = format!("subagent-{}", &task_id[..12.min(task_id.len())]);
@@ -1334,6 +1424,7 @@ mod tests {
             wake_on_completion: false,
             task_history_retention: 20,
             bus_tx: None,
+            workspace_dir: skills_dir.path().to_path_buf(),
         }));
 
         let err = harness
@@ -1355,4 +1446,14 @@ mod tests {
             "unexpected error: {err}"
         );
     }
+
+    #[tokio::test]
+    async fn semble_scout_rejects_a_missing_workspace_before_spawning_processes() {
+        let missing =
+            std::env::temp_dir().join(format!("isanagent-absent-{}", uuid::Uuid::new_v4()));
+        let err = SubagentHarness::run_semble_scout(&missing, "find agent startup")
+            .await
+            .expect_err("missing workspace must be rejected");
+        assert!(err.contains("workspace is unavailable"));
+    }
 }

src/channels/terminal_ui/run.rs

@@ -545,8 +545,7 @@ fn jobs_strip_lines(app: &App, max_width: usize, include_stream_tail: bool) -> V
         if let Some(last) = app
             .execution_stream_recent
             .lines()
-            .filter(|s| !s.trim().is_empty())
-            .next_back()
+            .rfind(|s| !s.trim().is_empty())
         {
             let label = app
                 .execution_stream_label
@@ -1591,12 +1590,7 @@ pub(crate) fn run_ratatui_main(config: RatatuiMainConfig) -> io::Result<()> {
                 .and_then(|v| v.as_str())
             {
                 // General background job output: update strip, don't add to transcript.
-                if let Some(line) = msg
-                    .content
-                    .lines()
-                    .filter(|l| !l.trim().is_empty())
-                    .next_back()
-                {
+                if let Some(line) = msg.content.lines().rfind(|l| !l.trim().is_empty()) {
                     app.job_strip_set_last_line(jid, line);
                 }
 

src/config.rs

@@ -161,6 +161,10 @@ pub enum AgentMode {
     /// Invoked by the coordinator via tools.
     #[default]
     Subagent,
+    /// A deterministic, local-only code retrieval worker powered by Semble.
+    /// It never invokes an LLM and may only search the configured workspace.
+    #[serde(rename = "semble_scout")]
+    SembleScout,
 }
 
 /// HF ml-intern–style ML policy overlay + optional autonomy hints (see `assets/ml_engineer_overlay.md`).

src/execution/jupyter.rs

@@ -818,16 +818,12 @@ fn fold_execute_ws_message(v: &Value, exec_msg_id: &str, ctx: &mut ExecuteFoldCt
             // Shell reply: sync status / exit only. Traceback belongs on iopub `error` to avoid duplicates.
             let status = v["content"]["status"].as_str().unwrap_or("");
             match status {
-                "error" => {
-                    if ctx.exit_code.is_none() || *ctx.exit_code == Some(0) {
-                        *ctx.exit_code = Some(1);
-                    }
+                "error" if ctx.exit_code.is_none() || *ctx.exit_code == Some(0) => {
+                    *ctx.exit_code = Some(1);
                 }
                 "abort" => *ctx.exit_code = Some(130),
-                "ok" => {
-                    if ctx.exit_code.is_none() || *ctx.exit_code == Some(0) {
-                        *ctx.exit_code = Some(0);
-                    }
+                "ok" if ctx.exit_code.is_none() || *ctx.exit_code == Some(0) => {
+                    *ctx.exit_code = Some(0);
                 }
                 _ => {}
             }

src/execution/ssh.rs

@@ -627,17 +627,15 @@ async fn run_ssh_channel_oneway(
             break;
         };
         match msg {
-            ChannelMsg::Data { data } => {
-                if stdout.len() < max_each {
-                    let take = (max_each - stdout.len()).min(data.len());
-                    stdout.extend_from_slice(&data[..take]);
-                }
+            ChannelMsg::Data { data } if stdout.len() < max_each => {
+                let take = (max_each - stdout.len()).min(data.len());
+                stdout.extend_from_slice(&data[..take]);
             }
-            ChannelMsg::ExtendedData { data, ext } => {
-                if ext == SSH_STDERR && stderr.len() < max_each {
-                    let take = (max_each - stderr.len()).min(data.len());
-                    stderr.extend_from_slice(&data[..take]);
-                }
+            ChannelMsg::ExtendedData { data, ext }
+                if ext == SSH_STDERR && stderr.len() < max_each =>
+            {
+                let take = (max_each - stderr.len()).min(data.len());
+                stderr.extend_from_slice(&data[..take]);
             }
             ChannelMsg::ExitStatus { exit_status } => {
                 code = Some(exit_status);

src/main.rs

@@ -790,6 +790,7 @@ Enable [api], [slack], or [email] (with enabled = true) so the agent can receive
             wake_on_completion: workspace.config.subagent_wake_on_completion(),
             task_history_retention: workspace.config.subagent_task_history_retention(),
             bus_tx: Some(bus_tx.clone()),
+            workspace_dir: workspace.sandbox_dir.clone(),
         })
     } else {
         None

src/skills.rs

@@ -342,11 +342,10 @@ impl SkillRegistry {
             }
         }
 
-        if specific_skill.is_some() && installed_skills.is_empty() {
+        if let Some(skill) = specific_skill.filter(|_| installed_skills.is_empty()) {
             return Err(format!(
                 "Skill '{}' not found in repository {}",
-                specific_skill.unwrap(),
-                full_repo_url
+                skill, full_repo_url
             ));
         }