@team-agent/installer 0.5.113 → 0.5.114

package/crates/team-agent/src/contract_runtime/mcp.rs

@@ -0,0 +1,396 @@
+//! Owned native stdio entry. Invocation arguments identify an expected record;
+//! only actual executable/birth/parent and current instance checks authorize it.
+use std::fmt::Display;
+use std::io::Write;
+use std::path::Path;
+use std::time::{Duration, Instant};
+
+use serde_json::{json, Value};
+use team_agent_contract::contract::types::*;
+use team_agent_contract::host::process::{
+    capture_process, verify_native_ancestry, MAX_NATIVE_PARENT_HOPS,
+};
+use team_agent_contract::orchestration::{
+    mcp::*,
+    protocol::ConnectionRecord,
+    store::{ContractStore, SeatRecord, SeatStatus},
+    Error,
+};
+
+use super::backend::{Backend, BackendError};
+
+// Diagnostics are not protocol facts or admission. Never write them to stdout,
+// include request/argv/env bytes, or let a failed log write change the result.
+struct Diagnostics {
+    log: Option<crate::event_log::EventLog>,
+    fields: Value,
+}
+impl Diagnostics {
+    fn new() -> Self {
+        Self {
+            log: None,
+            fields: json!({
+                "pid": std::process::id(),
+                "entry_ppid": crate::platform::process::current_parent_pid(),
+            }),
+        }
+    }
+
+    fn bind_log(&mut self, workspace: &Path) {
+        let directory = crate::model::paths::logs_dir(workspace);
+        let path = directory.join("events.jsonl");
+        // Entry diagnostics must not create an unverified workspace, follow a
+        // redirected log path, or depend on successfully opening contract.db.
+        let regular_or_absent = std::fs::symlink_metadata(&path).map_or_else(
+            |error| error.kind() == std::io::ErrorKind::NotFound,
+            |metadata| metadata.is_file() && !metadata.file_type().is_symlink(),
+        );
+        if workspace.is_absolute()
+            && workspace.canonicalize().is_ok_and(|path| path == workspace)
+            && directory.canonicalize().is_ok_and(|path| path == directory)
+            && regular_or_absent
+        {
+            self.log = Some(crate::event_log::EventLog::new(workspace));
+        }
+    }
+
+    fn record(&self, stage: &str, outcome: &str, error: Option<&dyn Display>) -> Value {
+        let mut value = self.fields.clone();
+        value["event"] = json!("contract.mcp");
+        value["ts"] = json!(chrono::Utc::now().to_rfc3339());
+        value["stage"] = json!(stage);
+        value["outcome"] = json!(outcome);
+        if let Some(error) = error {
+            let text = crate::redaction::redact_external_text(&error.to_string());
+            value["error"] = json!(text.chars().take(256).collect::<String>());
+            value["error_truncated"] = json!(text.chars().count() > 256);
+        }
+        crate::redaction::redact_external_value(&value)
+    }
+
+    fn emit(&self, stage: &str, outcome: &str, error: Option<&dyn Display>) {
+        let value = self.record(stage, outcome, error);
+        write_diagnostic(self.log.as_ref(), &value, &mut std::io::stderr().lock());
+    }
+
+    fn step<T, E: Display>(
+        &self,
+        stage: &str,
+        action: impl FnOnce() -> Result<T, E>,
+    ) -> Result<T, E> {
+        self.emit(stage, "started", None);
+        let result = action();
+        self.emit(
+            stage,
+            if result.is_ok() { "ok" } else { "error" },
+            result.as_ref().err().map(|error| error as &dyn Display),
+        );
+        result
+    }
+}
+
+fn write_diagnostic(
+    log: Option<&crate::event_log::EventLog>,
+    value: &Value,
+    stderr: &mut impl Write,
+) {
+    if log.is_some_and(|log| log.write("contract.mcp", value.clone()).is_ok()) {
+        return;
+    }
+    if let Ok(mut bytes) = serde_json::to_vec(value) {
+        // Valid bounded JSON even if future diagnostic fields grow unexpectedly.
+        if bytes.len() > 8191 {
+            bytes = br#"{"event":"contract.mcp","stage":"diagnostic_size_limit"}"#.to_vec();
+        }
+        bytes.push(b'\n');
+        let _ = stderr.write_all(&bytes);
+    }
+}
+
+fn arguments(
+    args: &[String],
+) -> Result<(std::path::PathBuf, String, SeatId, InstanceId, Generation), BackendError> {
+    let mut values = std::collections::BTreeMap::new();
+    if !args.len().is_multiple_of(2) {
+        return Err(BackendError::Metadata);
+    }
+    for pair in args.chunks_exact(2) {
+        if !matches!(
+            pair[0].as_str(),
+            "--workspace" | "--team" | "--seat" | "--instance" | "--generation"
+        ) || values.insert(pair[0].as_str(), pair[1].as_str()).is_some()
+        {
+            return Err(BackendError::Metadata);
+        }
+    }
+    if values.len() != 5 {
+        return Err(BackendError::Metadata);
+    }
+    let get = |key| values.get(key).copied().ok_or(BackendError::Metadata);
+    Ok((
+        get("--workspace")?.into(),
+        get("--team")?.into(),
+        SeatId::new(get("--seat")?)?,
+        InstanceId::new(get("--instance")?)?,
+        Generation(
+            get("--generation")?
+                .parse()
+                .map_err(|_| BackendError::Metadata)?,
+        ),
+    ))
+}
+fn wait_target(store: &ContractStore, identity: &InstanceIdentity) -> Result<SeatRecord, Error> {
+    let deadline = Instant::now() + Duration::from_secs(30);
+    loop {
+        let seat = store.assert_current(identity)?;
+        if matches!(seat.status, SeatStatus::Stopped | SeatStatus::Unknown) {
+            return Err(Error::Fence);
+        }
+        if seat.physical.is_some() {
+            return Ok(seat);
+        }
+        if Instant::now() >= deadline {
+            return Err(Error::Host("native target publication timed out"));
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+}
+
+pub fn run(args: &[String]) -> Result<(), BackendError> {
+    let mut diagnostics = Diagnostics::new();
+    // This is the first action in the main.rs contract-mcp dispatch target.
+    // Arguments are not trusted as a log destination yet: stderr only.
+    diagnostics.emit("entry", "entered", None);
+    let result = run_observed(args, &mut diagnostics);
+    diagnostics.emit(
+        "exit",
+        if result.is_ok() { "ok" } else { "error" },
+        result.as_ref().err().map(|error| error as &dyn Display),
+    );
+    result
+}
+
+fn run_observed(args: &[String], diagnostics: &mut Diagnostics) -> Result<(), BackendError> {
+    let (workspace, team, seat, instance, generation) =
+        diagnostics.step("arguments", || arguments(args))?;
+    diagnostics.bind_log(&workspace);
+    diagnostics.fields["seat"] = json!(seat.as_str().chars().take(96).collect::<String>());
+    diagnostics.fields["instance"] = json!(instance.as_str().chars().take(96).collect::<String>());
+    diagnostics.fields["generation"] = json!(generation.0);
+    diagnostics.emit("entry", "arguments_validated", None);
+    let mut backend = diagnostics.step("backend_open", || Backend::open(&workspace, &team))?;
+    let identity = InstanceIdentity {
+        scope: backend.binding.scope.clone(),
+        seat,
+        instance,
+        generation,
+    };
+    diagnostics.fields["scope"] = json!(identity.scope.as_str());
+    let seat = diagnostics.step("target_wait", || wait_target(&backend.store, &identity))?;
+    let target = seat
+        .physical
+        .as_ref()
+        .ok_or(Error::Invalid("native target missing"))?;
+    diagnostics.fields["expected_native_pid"] = json!(target.process.identity.pid);
+    diagnostics.emit("target_published", "observed", None);
+    let process = diagnostics.step("process_capture", || {
+        capture_process(
+            std::process::id(),
+            &backend.binding.candidate,
+            backend.binding.candidate_sha256,
+            Duration::from_secs(10),
+        )
+    })?;
+    diagnostics.fields["captured_ppid"] = json!(process.parent);
+    diagnostics.fields["direct_parent_matches"] =
+        json!(process.parent == target.process.identity.pid);
+    diagnostics.fields["max_parent_hops"] = json!(MAX_NATIVE_PARENT_HOPS);
+    diagnostics.emit("parent_fence", "started", None);
+    let ancestry = verify_native_ancestry(&process, &target.process);
+    diagnostics.fields["parent_matches"] = json!(ancestry.is_ok());
+    if let Ok(chain) = &ancestry {
+        diagnostics.fields["ancestor_chain"] = json!(chain);
+    }
+    diagnostics.emit(
+        "parent_fence",
+        if ancestry.is_ok() { "ok" } else { "error" },
+        ancestry.as_ref().err().map(|error| error as &dyn Display),
+    );
+    ancestry?;
+    let connection = diagnostics
+        .step("connection_identity", || {
+            backend.store.propose_identity(&identity.seat)
+        })?
+        .instance;
+    let record = ConnectionRecord {
+        identity: identity.clone(),
+        connection: connection.clone(),
+        server_key: seat.server_key.clone(),
+        binding_key: seat.binding_key.clone(),
+        process,
+        native_process: target.process.clone(),
+        closed: false,
+    };
+    diagnostics.step("register_connection", || {
+        backend.store.register_connection(&record)
+    })?;
+    // Registration is not an initialize/tools-list/client-consumption fact.
+    // Those continue to be recorded only at the existing protocol boundaries.
+    let result = diagnostics.step("serve", || {
+        serve_with_diagnostics(
+            &mut backend.store,
+            |store, request| {
+                if verify_native_ancestry(&record.process, &record.native_process).is_err() {
+                    return Err(Error::Fence);
+                }
+                let current = store.assert_current(&identity)?;
+                if current.binding_key != record.binding_key
+                    || matches!(current.status, SeatStatus::Stopped | SeatStatus::Unknown)
+                    || current
+                        .physical
+                        .as_ref()
+                        .is_none_or(|target| target.process != record.native_process)
+                {
+                    return Err(Error::Fence);
+                }
+                let business =
+                    request.get("method").and_then(serde_json::Value::as_str) == Some("tools/call");
+                let mut task = String::new();
+                if business {
+                    // A native callback can race the physical receipt's DB commit. Wait
+                    // for that exact generation's submitted turn, never a queued row.
+                    let deadline = Instant::now() + Duration::from_secs(5);
+                    loop {
+                        match store.submitted_task(&identity) {
+                            Ok(Some(bound)) => {
+                                task = bound;
+                                break;
+                            }
+                            Ok(None) | Err(Error::Conflict) if Instant::now() < deadline => {
+                                std::thread::sleep(Duration::from_millis(20))
+                            }
+                            Ok(None) => return Err(Error::Invalid("no submitted native turn")),
+                            Err(error) => return Err(error),
+                        }
+                    }
+                }
+                if verify_native_ancestry(&record.process, &record.native_process).is_err() {
+                    return Err(Error::Fence);
+                }
+                Ok(CallContext {
+                    identity: identity.clone(),
+                    binding_key: record.binding_key.clone(),
+                    connection_id: connection.clone(),
+                    task_id: task,
+                })
+            },
+            std::io::stdin().lock(),
+            std::io::stdout().lock(),
+            |stage, error| {
+                diagnostics.emit(
+                    match stage {
+                        RequestRejectionStage::Context => "request_context",
+                        RequestRejectionStage::Handler => "request_handler",
+                    },
+                    "rejected",
+                    Some(error),
+                );
+            },
+        )
+    });
+    let closed = diagnostics.step("close_connection", || {
+        backend.store.close_connection(&identity, &connection)
+    });
+    result?;
+    closed?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn diagnostics_preserve_errors_and_distinguish_captured_and_expected_parent() {
+        let mut diagnostics = Diagnostics::new();
+        diagnostics.fields["captured_ppid"] = json!(202);
+        diagnostics.fields["expected_native_pid"] = json!(303);
+        diagnostics.fields["parent_matches"] = json!(false);
+        let result = diagnostics.step("parent_fence", || Err::<(), _>(Error::Fence));
+        assert_eq!(result, Err(Error::Fence));
+        let event = diagnostics.record("parent_fence", "error", Some(&Error::Fence));
+        assert_eq!(event["captured_ppid"], 202);
+        assert_eq!(event["expected_native_pid"], 303);
+        assert_eq!(event["parent_matches"], false);
+        assert_eq!(event["error"], Error::Fence.to_string());
+        assert!(event["entry_ppid"].is_number());
+    }
+
+    #[test]
+    fn rejected_requests_keep_the_actual_error_category_and_stage() {
+        let diagnostics = Diagnostics::new();
+        for (stage, error) in [
+            ("request_context", Error::Conflict),
+            ("request_context", Error::Fence),
+            ("request_context", Error::Database),
+            ("request_handler", Error::Invalid("argument type")),
+        ] {
+            let event = diagnostics.record(stage, "rejected", Some(&error));
+            assert_eq!(event["stage"], stage);
+            assert_eq!(event["outcome"], "rejected");
+            assert_eq!(event["error"], error.to_string());
+            assert!(event.get("request").is_none());
+            assert!(event.get("arguments").is_none());
+            let mut stderr = Vec::new();
+            write_diagnostic(None, &event, &mut stderr);
+            assert!(stderr.len() <= 8192);
+            assert_eq!(serde_json::from_slice::<Value>(&stderr).unwrap(), event);
+        }
+    }
+
+    #[test]
+    fn diagnostics_redact_and_bound_error_without_argument_or_environment_fields() {
+        let diagnostics = Diagnostics::new();
+        let error = format!("PASSWORD=do-not-log {}", "x".repeat(20_000));
+        let event = diagnostics.record("arguments", "error", Some(&error));
+        assert_eq!(event["error_truncated"], true);
+        assert!(!event.to_string().contains("do-not-log"));
+        for field in ["argv", "args", "env", "prompt", "request", "content"] {
+            assert!(event.get(field).is_none());
+        }
+        let mut stderr = Vec::new();
+        write_diagnostic(None, &event, &mut stderr);
+        assert!(stderr.len() <= 8192);
+        assert_eq!(serde_json::from_slice::<Value>(&stderr).unwrap(), event);
+    }
+
+    #[test]
+    fn diagnostic_sink_failures_do_not_change_execution_results() {
+        let log = crate::event_log::EventLog::at("/dev/null/contract-mcp-events".into());
+        let diagnostics = Diagnostics::new();
+        let event = diagnostics.record("backend_open", "error", Some(&Error::Fence));
+        let mut stderr = Vec::new();
+        write_diagnostic(Some(&log), &event, &mut stderr);
+        assert_eq!(serde_json::from_slice::<Value>(&stderr).unwrap(), event);
+        struct Broken;
+        impl Write for Broken {
+            fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
+                Err(std::io::ErrorKind::BrokenPipe.into())
+            }
+            fn flush(&mut self) -> std::io::Result<()> {
+                Err(std::io::ErrorKind::BrokenPipe.into())
+            }
+        }
+        write_diagnostic(Some(&log), &event, &mut Broken);
+        assert_eq!(diagnostics.step("fixture", || Ok::<_, Error>(17)), Ok(17));
+        stderr.clear();
+        write_diagnostic(
+            None,
+            &json!({"unexpected": "x".repeat(20_000)}),
+            &mut stderr,
+        );
+        let bounded: Value = serde_json::from_slice(&stderr).unwrap();
+        assert_eq!(bounded["stage"], "diagnostic_size_limit");
+        assert!(stderr.len() <= 8192);
+    }
+}

package/crates/team-agent/src/contract_runtime/mod.rs

@@ -0,0 +1,14 @@
+//! Per-agent boundary into the contract runtime. Existing provider internals
+//! stay on their path, including mixed teams; a seat never has two executors.
+//!
+//! Selection/preflight is read-only. Physical operations require a validated
+//! contract role and its real framework/native binding, not a provider guess.
+pub mod backend;
+pub mod config;
+pub mod discovery;
+pub mod forward;
+pub mod framework;
+pub mod mcp;
+pub mod prompt;
+pub mod pump;
+pub mod registry;

package/crates/team-agent/src/contract_runtime/prompt.rs

@@ -0,0 +1,216 @@
+//! Provider-independent instruction source policy. The Kiro adapter receives
+//! one resolved prompt, never a provider-private home/path search algorithm.
+use std::io::Read;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use team_agent_contract::contract::types::Digest;
+use team_agent_contract::host::digest;
+
+use super::config::ConfigError;
+use crate::communication_mode::CommunicationMode;
+use crate::lifecycle::worker_command_context::{runtime_contract_section, worker_identity_section};
+use crate::model::yaml::Value;
+
+pub const MAX_PROMPT_BYTES: usize = 1024 * 1024;
+
+/// Source contents are private; public diagnostics project only their receipts.
+#[derive(Clone)]
+pub struct Source {
+    pub path: PathBuf,
+    pub contents: String,
+}
+impl Source {
+    pub fn read(path: &Path) -> Result<Self, ConfigError> {
+        let resolved = path.canonicalize()?;
+        let mut bytes = Vec::new();
+        std::fs::File::open(&resolved)?
+            .take(MAX_PROMPT_BYTES as u64 + 1)
+            .read_to_end(&mut bytes)?;
+        if bytes.len() > MAX_PROMPT_BYTES {
+            return Err(ConfigError::Unsupported(
+                "instruction source exceeds the bounded prompt limit; no truncation is performed",
+            ));
+        }
+        let contents = String::from_utf8(bytes).map_err(|_| ConfigError::Invalid {
+            path: path.into(),
+            field: "UTF-8 instructions",
+        })?;
+        if contents.contains('\0') {
+            return Err(ConfigError::Invalid {
+                path: path.into(),
+                field: "NUL in instructions",
+            });
+        }
+        Ok(Self {
+            path: resolved,
+            contents,
+        })
+    }
+    fn optional(path: &Path) -> Result<Option<Self>, ConfigError> {
+        match std::fs::symlink_metadata(path) {
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+            Err(error) => Err(error.into()),
+            Ok(_) => Self::read(path).map(Some),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum Layer {
+    UserGlobal,
+    Project,
+    Role,
+    TeamExplicit,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InstructionReceipt {
+    pub layer: Layer,
+    pub path: PathBuf,
+    pub sha256: Digest,
+    pub bytes: usize,
+    /// Exact UTF-8 byte range in the assembled native prompt, excluding headings.
+    pub start: usize,
+    pub end: usize,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct Prompt {
+    pub text: String,
+    pub sha256: Digest,
+    pub sources: Vec<InstructionReceipt>,
+}
+
+/// Central compatibility default, not a Kiro adapter constant. An explicit
+/// unified TEAM_AGENT_USER_INSTRUCTIONS file takes precedence and is required
+/// to exist. Without an override the authorized user-level AGENTS is optional.
+pub fn user_source() -> Result<Option<Source>, ConfigError> {
+    if let Some(path) = std::env::var_os("TEAM_AGENT_USER_INSTRUCTIONS") {
+        if path.is_empty() {
+            return Err(ConfigError::Unsupported(
+                "TEAM_AGENT_USER_INSTRUCTIONS must name a file",
+            ));
+        }
+        return Source::read(Path::new(&path)).map(Some);
+    }
+    match std::env::var_os("HOME") {
+        Some(home) => Source::optional(&PathBuf::from(home).join(".pi/agent/AGENTS.md")),
+        None => Ok(None),
+    }
+}
+
+/// Selection follows the explicit project workspace, not the roles directory,
+/// generated .kiro directory, current shell directory, or an ancestor guess.
+pub fn project_source(workspace: &Path) -> Result<Option<Source>, ConfigError> {
+    Source::optional(&workspace.join("AGENTS.md"))
+}
+
+/// instruction_files is an explicit path or ordered path list. instructions is
+/// either inline text (retained verbatim in TEAM.md) or an ordered file-list
+/// alias. Paths are relative to TEAM.md, never the generated native config.
+pub fn team_sources(team: &Source, meta: &Value) -> Result<Vec<Source>, ConfigError> {
+    let mut paths = Vec::new();
+    for field in ["instruction_files", "instructions"] {
+        match meta.get(field) {
+            None | Some(Value::Null) => {}
+            Some(Value::Str(_)) if field == "instructions" => {}
+            Some(Value::Str(path)) => paths.push(path),
+            Some(Value::List(values)) => {
+                for value in values {
+                    match value {
+                        Value::Str(path) => paths.push(path),
+                        _ => {
+                            return Err(ConfigError::Invalid {
+                                path: team.path.clone(),
+                                field,
+                            })
+                        }
+                    }
+                }
+            }
+            _ => {
+                return Err(ConfigError::Invalid {
+                    path: team.path.clone(),
+                    field,
+                })
+            }
+        }
+    }
+    let mut sources = vec![team.clone()];
+    for path in paths {
+        if path.trim().is_empty() || path.contains('\0') {
+            return Err(ConfigError::Invalid {
+                path: team.path.clone(),
+                field: "instruction file path",
+            });
+        }
+        let path = Path::new(path);
+        let path = if path.is_absolute() {
+            path.to_owned()
+        } else {
+            team.path
+                .parent()
+                .ok_or(ConfigError::Unsupported("TEAM.md has no parent"))?
+                .join(path)
+        };
+        sources.push(Source::read(&path)?);
+    }
+    Ok(sources)
+}
+
+/// Framework binding precedes the four ordered user-policy layers. Original
+/// documents (including role front matter and CR/LF bytes) are copied whole;
+/// only section separators are new bytes. Dynamic tasks are NOT repeated here:
+/// they enter the same native context later through the one durable outbox.
+pub fn assemble(
+    id: &str,
+    role_name: &str,
+    mode: CommunicationMode,
+    user: Option<&Source>,
+    project: Option<&Source>,
+    role: &Source,
+    team: &[Source],
+) -> Result<Prompt, ConfigError> {
+    let mut text = [
+        worker_identity_section(id, role_name),
+        runtime_contract_section("send_message", "report_result", "get_team_status()"),
+        mode.runtime_contract("send_message"),
+        "The operations above are logical names. Use the bound MCP client's advertised tool names, not guessed prefixes. Original role-template metadata below does not change your bound worker identity or selected native launch parameters.\nFinal completion calls report_result exactly once. Durable storage and actual leader presentation are separate facts; do not claim delivery from registration or persistence alone.".into(),
+    ].join("\n\n");
+    let mut ordered = Vec::new();
+    if let Some(source) = user {
+        ordered.push((Layer::UserGlobal, source));
+    }
+    if let Some(source) = project {
+        ordered.push((Layer::Project, source));
+    }
+    ordered.push((Layer::Role, role));
+    ordered.extend(team.iter().map(|source| (Layer::TeamExplicit, source)));
+    let mut sources = Vec::new();
+    for (layer, source) in ordered {
+        text.push_str(&format!(
+            "\n\n# Team Agent instruction layer: {layer:?}\n\n"
+        ));
+        let start = text.len();
+        text.push_str(&source.contents);
+        if text.len() > MAX_PROMPT_BYTES {
+            return Err(ConfigError::Unsupported(
+                "assembled prompt exceeds the bounded limit; no truncation is performed",
+            ));
+        }
+        sources.push(InstructionReceipt {
+            layer,
+            path: source.path.clone(),
+            sha256: digest(source.contents.as_bytes()),
+            bytes: source.contents.len(),
+            start,
+            end: text.len(),
+        });
+    }
+    Ok(Prompt {
+        sha256: digest(text.as_bytes()),
+        text,
+        sources,
+    })
+}