feat: add iii-shell worker

shell/Cargo.toml

@@ -0,0 +1,27 @@
+[workspace]
+
+[package]
+name = "iii-shell"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "iii-shell"
+path = "src/main.rs"
+
+[dependencies]
+iii-sdk = "=0.11.3"
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "signal", "process", "time", "io-util"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+serde_yaml = "0.9"
+anyhow = "1"
+thiserror = "2"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter"] }
+clap = { version = "4", features = ["derive"] }
+uuid = { version = "1", features = ["v4"] }
+once_cell = "1"
+regex = "1"
+shell-words = "1"

shell/README.md

@@ -0,0 +1,69 @@
+# iii-shell
+
+Unix shell execution worker for iii agents. Mike's priority-1 fundamental — every agent worker that needs to touch the OS (run a build, read a file via `cat`, list a directory, call a CLI) goes through this worker so there is a single place to enforce allowlists, timeouts, and output caps.
+
+## Functions
+
+| id | shape |
+|----|-------|
+| `shell::exec` | run to completion, return `{exit_code, stdout, stderr, duration_ms, timed_out, stdout_truncated, stderr_truncated}` |
+| `shell::exec_bg` | spawn in background, return `{job_id, argv}` |
+| `shell::kill` | kill a running `job_id` |
+| `shell::status` | return `{job: JobRecord}` for a `job_id` |
+| `shell::list` | return all jobs + counts |
+
+## HTTP triggers
+
+```
+POST /api/shell/exec     → shell::exec
+POST /api/shell/exec_bg  → shell::exec_bg
+POST /api/shell/kill     → shell::kill
+POST /api/shell/status   → shell::status
+GET  /api/shell/list     → shell::list
+```
+
+## Safety
+
+- `allowlist` — if non-empty, command (basename) must be present. Empty list = open.
+- `denylist_patterns` — regex patterns tested against the full joined argv. Example: `rm\s+-rf\s+/`, `:()\s*\{\s*:\|` (fork bomb), `mkfs`, `shutdown`.
+- `max_timeout_ms` — hard cap; per-call `timeout_ms` is clamped.
+- `max_output_bytes` — stdout/stderr are truncated at this size, flagged via `*_truncated`.
+- `inherit_env: false` by default. Only variables in `allowed_env` are forwarded.
+- `working_dir` — pins cwd.
+- `max_concurrent_jobs` — rejects new `exec_bg` requests past the cap.
+- `job_retention_secs` — old finished jobs are pruned on every `shell::list` call.
+
+## Example
+
+```bash
+curl -X POST localhost:3111/api/shell/exec -d '{
+  "command": "ls",
+  "args": ["-la", "/tmp"],
+  "timeout_ms": 5000
+}'
+# → {"exit_code": 0, "stdout": "total …", "stderr": "", "duration_ms": 12, ...}
+
+curl -X POST localhost:3111/api/shell/exec_bg -d '{
+  "command": "cargo",
+  "args": ["build", "--release"]
+}'
+# → {"job_id": "job-abc…", "argv": ["cargo", "build", "--release"]}
+
+curl -X POST localhost:3111/api/shell/status -d '{"job_id": "job-abc…"}'
+```
+
+## Run locally
+
+```bash
+cargo run --release -- --config ./config.yaml --url ws://127.0.0.1:49134
+```
+
+## What this is NOT
+
+- Not a PTY. Interactive shells, TUIs, password prompts all break.
+- Not a remote executor. Runs on the worker's host only.
+- Not a sandbox. For isolation use `sandbox-docker`/`sandbox-firecracker` and call through `shell` only for trusted commands.
+
+## Deferred
+
+- `shell::exec_stream` — live stdout/stderr via iii Streams (for long-running commands). Next iteration.

shell/build.rs

@@ -0,0 +1,6 @@
+fn main() {
+    println!(
+        "cargo:rustc-env=TARGET={}",
+        std::env::var("TARGET").unwrap_or_default()
+    );
+}

shell/config.yaml

@@ -0,0 +1,60 @@
+max_timeout_ms: 30000
+default_timeout_ms: 10000
+max_output_bytes: 1048576
+working_dir: null
+inherit_env: false
+allowed_env:
+  - PATH
+  - HOME
+  - LANG
+  - LC_ALL
+  - TERM
+# Default allowlist is intentionally read-only. Tools that can shell out
+# (git hooks, curl -o/file://, find -exec, awk system(), sed e/-i, cargo
+# build.rs, node -e, python3 -c, npm run) are left out on purpose — add them
+# per deployment after you've decided on the threat model. This worker is
+# NOT a sandbox.
+allowlist:
+  - ls
+  - cat
+  - pwd
+  - echo
+  - grep
+  - wc
+  - head
+  - tail
+  - sort
+  - uniq
+  - cut
+  - date
+  - whoami
+  - hostname
+  - which
+  - jq
+  - uname
+  - df
+  - du
+  - ps
+  - env
+  - printenv
+  - basename
+  - dirname
+denylist_patterns:
+  - "rm\\s+-rf\\s+/"
+  - ":\\(\\)\\s*\\{\\s*:\\|"
+  - "mkfs"
+  - "dd\\s+if="
+  - "shutdown"
+  - "reboot"
+  - "/etc/passwd"
+  - "/etc/shadow"
+  # Sub-execution / write escapes for commonly-added tools
+  - "\\bfind\\b[^|;&]*-exec(dir)?\\b"
+  - "\\bawk\\b[^|;&]*system\\s*\\("
+  - "\\bsed\\b[^|;&]*(-i\\b|\\be\\b)"
+  - "\\bcurl\\b[^|;&]*(file://|-o\\s|--output-dir\\b|-F\\s+@)"
+  - "\\bgit\\b[^|;&]*(--upload-pack|--receive-pack|core\\.pager|core\\.hooksPath|GIT_SSH_COMMAND)"
+  - "\\b(node|python3?)\\b[^|;&]*\\s-(e|c)\\b"
+  - "\\bnpm\\b[^|;&]*\\brun\\b"
+max_concurrent_jobs: 16
+job_retention_secs: 3600

shell/src/config.rs

@@ -0,0 +1,206 @@
+use anyhow::{Context, Result};
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ShellConfig {
+    #[serde(default = "default_max_timeout_ms")]
+    pub max_timeout_ms: u64,
+
+    #[serde(default = "default_default_timeout_ms")]
+    pub default_timeout_ms: u64,
+
+    #[serde(default = "default_max_output_bytes")]
+    pub max_output_bytes: usize,
+
+    #[serde(default)]
+    pub working_dir: Option<PathBuf>,
+
+    #[serde(default)]
+    pub inherit_env: bool,
+
+    #[serde(default = "default_allowed_env")]
+    pub allowed_env: Vec<String>,
+
+    #[serde(default)]
+    pub allowlist: Vec<String>,
+
+    #[serde(default)]
+    pub denylist_patterns: Vec<String>,
+
+    #[serde(default = "default_max_concurrent_jobs")]
+    pub max_concurrent_jobs: usize,
+
+    #[serde(default = "default_job_retention_secs")]
+    pub job_retention_secs: u64,
+
+    #[serde(default, skip)]
+    pub compiled_denylist: Vec<Regex>,
+}
+
+fn default_max_timeout_ms() -> u64 {
+    30_000
+}
+fn default_default_timeout_ms() -> u64 {
+    10_000
+}
+fn default_max_output_bytes() -> usize {
+    1_048_576
+}
+fn default_allowed_env() -> Vec<String> {
+    vec!["PATH", "HOME", "LANG", "LC_ALL", "TERM"]
+        .into_iter()
+        .map(String::from)
+        .collect()
+}
+fn default_max_concurrent_jobs() -> usize {
+    16
+}
+fn default_job_retention_secs() -> u64 {
+    3600
+}
+
+impl Default for ShellConfig {
+    fn default() -> Self {
+        Self {
+            max_timeout_ms: default_max_timeout_ms(),
+            default_timeout_ms: default_default_timeout_ms(),
+            max_output_bytes: default_max_output_bytes(),
+            working_dir: None,
+            inherit_env: false,
+            allowed_env: default_allowed_env(),
+            allowlist: Vec::new(),
+            denylist_patterns: Vec::new(),
+            max_concurrent_jobs: default_max_concurrent_jobs(),
+            job_retention_secs: default_job_retention_secs(),
+            compiled_denylist: Vec::new(),
+        }
+    }
+}
+
+pub fn load_config(path: &str) -> Result<ShellConfig> {
+    let content = fs::read_to_string(path).with_context(|| format!("read {}", path))?;
+    let mut cfg: ShellConfig =
+        serde_yaml::from_str(&content).with_context(|| format!("parse {}", path))?;
+    cfg.compile_denylist()?;
+    Ok(cfg)
+}
+
+impl ShellConfig {
+    pub fn compile_denylist(&mut self) -> Result<()> {
+        self.compiled_denylist = self
+            .denylist_patterns
+            .iter()
+            .map(|p| Regex::new(p).with_context(|| format!("bad denylist pattern: {}", p)))
+            .collect::<Result<Vec<_>>>()?;
+        Ok(())
+    }
+
+    pub fn is_command_allowed(&self, argv: &[String]) -> Result<(), String> {
+        let cmd = argv
+            .first()
+            .ok_or_else(|| "empty command".to_string())?
+            .clone();
+
+        if !self.allowlist.is_empty() {
+            let base = std::path::Path::new(&cmd)
+                .file_name()
+                .and_then(|s| s.to_str())
+                .unwrap_or(&cmd);
+            if !self.allowlist.iter().any(|a| a == base || a == &cmd) {
+                return Err(format!("command '{}' not in allowlist", base));
+            }
+        }
+
+        let joined = argv.join(" ");
+        for re in &self.compiled_denylist {
+            if re.is_match(&joined) {
+                return Err(format!("command matches denylist: {}", re.as_str()));
+            }
+        }
+        Ok(())
+    }
+
+    pub fn resolve_timeout(&self, requested: Option<u64>) -> u64 {
+        let t = requested.unwrap_or(self.default_timeout_ms);
+        t.min(self.max_timeout_ms)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn cfg_with(allow: Vec<&str>, deny: Vec<&str>) -> ShellConfig {
+        let mut c = ShellConfig {
+            allowlist: allow.into_iter().map(String::from).collect(),
+            denylist_patterns: deny.into_iter().map(String::from).collect(),
+            ..Default::default()
+        };
+        c.compile_denylist().unwrap();
+        c
+    }
+
+    #[test]
+    fn test_defaults() {
+        let c = ShellConfig::default();
+        assert_eq!(c.max_timeout_ms, 30_000);
+        assert_eq!(c.default_timeout_ms, 10_000);
+        assert!(!c.inherit_env);
+        assert_eq!(c.max_concurrent_jobs, 16);
+    }
+
+    #[test]
+    fn test_allowlist_permits() {
+        let c = cfg_with(vec!["ls", "cat"], vec![]);
+        assert!(c.is_command_allowed(&["ls".into(), "-la".into()]).is_ok());
+    }
+
+    #[test]
+    fn test_allowlist_rejects() {
+        let c = cfg_with(vec!["ls"], vec![]);
+        let err = c
+            .is_command_allowed(&["nmap".into()])
+            .expect_err("must reject");
+        assert!(err.contains("not in allowlist"));
+    }
+
+    #[test]
+    fn test_allowlist_empty_means_open() {
+        let c = cfg_with(vec![], vec![]);
+        assert!(c.is_command_allowed(&["anything".into()]).is_ok());
+    }
+
+    #[test]
+    fn test_allowlist_basename_match() {
+        let c = cfg_with(vec!["ls"], vec![]);
+        assert!(c
+            .is_command_allowed(&["/usr/bin/ls".into(), "-la".into()])
+            .is_ok());
+    }
+
+    #[test]
+    fn test_denylist_blocks() {
+        let c = cfg_with(vec![], vec![r"rm\s+-rf\s+/"]);
+        let err = c
+            .is_command_allowed(&["rm".into(), "-rf".into(), "/".into()])
+            .expect_err("must reject");
+        assert!(err.contains("denylist"));
+    }
+
+    #[test]
+    fn test_empty_argv_rejected() {
+        let c = ShellConfig::default();
+        assert!(c.is_command_allowed(&[]).is_err());
+    }
+
+    #[test]
+    fn test_resolve_timeout_caps_at_max() {
+        let c = ShellConfig::default();
+        assert_eq!(c.resolve_timeout(Some(60_000)), 30_000);
+        assert_eq!(c.resolve_timeout(Some(5_000)), 5_000);
+        assert_eq!(c.resolve_timeout(None), 10_000);
+    }
+}