@team-agent/installer 0.5.113 → 0.5.115

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

@@ -0,0 +1,16 @@
+//! 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 commands;
+pub mod config;
+pub mod discovery;
+pub mod forward;
+pub mod framework;
+pub mod mcp;
+pub mod prompt;
+pub mod pump;
+pub mod registry;
+mod workspace;

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,
+    })
+}

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

@@ -0,0 +1,269 @@
+//! One coordinator-owned consumer of the K3 outbox. No CLI send side channel,
+//! implicit business retry, queue flush, or replay of uncertain messages.
+use super::{
+    backend::{self, Backend, BackendError},
+    forward, framework, registry,
+};
+use serde_json::Value;
+use std::path::Path;
+use std::time::Duration;
+use team_agent_contract::contract::{delivery::InputSurface, probe::*, types::*};
+use team_agent_contract::host::{
+    clock::{Clock, RealClock},
+    process::verify_native_ancestry,
+};
+use team_agent_contract::orchestration::{physical::*, store::*, supervisor::*};
+use team_agent_contract::runtime::probes::*;
+
+pub(super) fn protocol(
+    backend: &mut Backend,
+    seat: &SeatRecord,
+    clock: &RealClock,
+) -> Result<ProtocolSnapshot, BackendError> {
+    let target = seat.physical.as_ref().ok_or(BackendError::Metadata)?;
+    let active: Vec<_> = backend
+        .store
+        .connections(&seat.identity)?
+        .into_iter()
+        .filter(|record| {
+            !record.closed
+                && record.identity == seat.identity
+                && record.server_key == seat.server_key
+                && record.binding_key == seat.binding_key
+                && record.native_process == target.process
+                && verify_native_ancestry(&record.process, &record.native_process).is_ok()
+        })
+        .collect();
+    if active.len() != 1 {
+        return Ok(collect_protocol(
+            target,
+            &seat.identity.instance,
+            &seat.server_key,
+            &[],
+            clock.now(),
+            Duration::from_secs(2),
+        ));
+    }
+    let connection = &active[0];
+    let facts = backend
+        .store
+        .connection_facts(&seat.identity, &connection.connection)?;
+    let mut events = Vec::new();
+    // T3a is connection state, sampled against BOTH captured process births.
+    // Completed server writes are never promoted to client discovery.
+    for (fact, protocol) in [
+        (
+            "initialize_response_written",
+            ProtocolFact::InitializeResponseWritten {
+                server_instance: connection.connection.clone(),
+            },
+        ),
+        (
+            "tools_list_response_written",
+            ProtocolFact::ToolsListResponseWritten {
+                server_instance: connection.connection.clone(),
+            },
+        ),
+    ] {
+        if facts.iter().any(|value| value == fact) {
+            events.push(ProtocolEvent {
+                scope: target.scope(
+                    events.len() as u64,
+                    clock.now(),
+                    Duration::from_secs(2),
+                    "live-owned-stdio-state",
+                ),
+                fact: protocol,
+            });
+        }
+    }
+    if registry::provider(seat.provider.as_str())?.uses_tool_roundtrips() {
+        let session = seat.session.as_ref().ok_or(BackendError::Metadata)?;
+        if target.identity() != &seat.identity || target.binding != seat.binding_key
+            || target.provider != seat.provider || target.native != seat.native
+            || target.native_session.as_ref() != Some(&session.native_session)
+            || session.source != seat.identity || session.provider != seat.provider
+            || session.native != seat.native || session.cwd != target.cwd
+            || target.candidate_sha256 != backend.binding.candidate_sha256
+        {
+            return Err(ContractError::Mismatch("native roundtrip current binding").into());
+        }
+        // The core returns only per-tool invocation + actual successful
+        // write/flush pairs for THIS captured connection and generation.
+        // Server list writes or another connection's facts cannot qualify.
+        let tools = backend.store.completed_connection_tools(&seat.identity, &connection.connection)?;
+        if !tools.is_empty() {
+            events.push(ProtocolEvent {
+                scope: target.scope(events.len() as u64, clock.now(), Duration::from_secs(2),
+                    "live-native-tool-roundtrip-ledger"),
+                fact: ProtocolFact::ClientBound {
+                    server_instance: connection.connection.clone(),
+                    evidence: ClientBindingEvidence {
+                        server_key: seat.server_key.clone(), tools,
+                        source: ClientBindingSource::NativeToolRoundtrip,
+                    },
+                },
+            });
+        }
+    }
+    Ok(collect_protocol(
+        target,
+        &connection.connection,
+        &seat.server_key,
+        &events,
+        clock.now(),
+        Duration::from_secs(2),
+    ))
+}
+
+fn deliver_one(backend: &mut Backend, seat: &SeatRecord) -> Result<(), BackendError> {
+    if matches!(seat.status, SeatStatus::Stopped | SeatStatus::Unknown)
+        || !backend.store.has_queued_for(&seat.identity)?
+    {
+        return Ok(());
+    }
+    let selected = registry::provider(seat.provider.as_str())?;
+    let bootstrap_allowed = selected.first_business_bootstrap() && !seat.bootstrap_used;
+    let profiles = selected.descriptor().input.profiles.require("native input profiles")?;
+    let profile = profiles.iter().find(|profile| profile.id == seat.profile && profile.matches_native(&seat.native))
+        .ok_or(ContractError::ProfileUnavailable)?;
+    profile.policy.require("native submit policy")?;
+    let role = backend::read_role(&backend.binding, &seat.identity)?;
+    if role.provider != seat.provider {
+        return Err(BackendError::Metadata);
+    }
+    let clock = RealClock::new();
+    let adapter = backend::adapter(&backend.binding, &seat.identity, &seat.provider)?;
+    let hooks = adapter.hooks();
+    let operation = OperationId::new(format!(
+        "deliver-{}",
+        backend
+            .store
+            .propose_identity(&seat.identity.seat)?
+            .instance
+            .as_str()
+    ))?;
+    let mut physical = PhysicalRuntime::new(
+        Registration {
+            descriptor: selected.descriptor(),
+            hooks: &hooks,
+            controls: selected.controls(),
+        },
+        backend::settings(&backend.binding, selected),
+        operation.clone(),
+        &clock,
+    )?;
+    physical.evidence = backend::policy_evidence(
+        &seat.provider, &seat.native, backend.binding.candidate_sha256,
+    )?;
+    physical.protocol = Some(protocol(backend, seat, &clock)?);
+    let sample = physical.readiness(seat)?;
+    if !matches!(sample.pane.outcome, ProbeOutcome::Observed(ref pane) if pane.surface == InputSurface::ComposerReady)
+        || !matches!(sample.server.outcome, ProbeOutcome::Observed(ref server) if server.initialize_response_written && server.tools_list_response_written)
+    {
+        return Ok(());
+    }
+    // A roundtrip provider consumes only its captured protocol evidence. An
+    // Unknown/partial binding is left to the typed readiness gate; it never
+    // triggers a guessed TUI /tools command or a Kiro inspector fallback.
+    if !bootstrap_allowed && !selected.uses_tool_roundtrips() {
+        let panel = selected.tool_panel()?;
+        if panel.profile_id != seat.profile || panel.server_key != seat.server_key
+            || panel.policy_sha256 != profile.policy_sha256
+        {
+            return Err(ContractError::Mismatch("native inspector seat binding").into());
+        }
+        backend.store.begin_observation(&seat.identity, &operation)?;
+        // Uncertain inspection quarantines the seat without an orphan lease.
+        // No replay or blind Escape clears an unrelated composer/approval.
+        let binding = match physical.client_binding(seat, panel) {
+            Ok(binding) => binding,
+            Err(error) => {
+                backend.store.fail_observation(&seat.identity, &operation)?;
+                return Err(error.into());
+            }
+        };
+        backend.store.finish_observation(&seat.identity, &operation)?;
+        if !matches!(binding.outcome, ProbeOutcome::Observed(_)) {
+            return Ok(());
+        }
+        let mut current_protocol = protocol(backend, seat, &clock)?;
+        current_protocol.binding = binding;
+        physical.protocol = Some(current_protocol);
+    }
+    // H3's owned prompt receipt is independently checked by PhysicalRuntime;
+    // only the one durable first-business claim can carry this instruction.
+    if bootstrap_allowed {
+        physical.initial_prompt = Some(role.prompt.text.clone());
+    }
+    let mut bootstrap = OutboxBootstrap::new(ContractStore::open(
+        &backend.binding.transport_root,
+        backend.binding.scope.clone(),
+        &backend.binding.endpoint,
+    )?);
+    physical.bootstrap = Some(&mut bootstrap);
+    let sample = physical.readiness(seat)?;
+    let authorization = DeliveryAuthorization {
+        allow_first_business_bootstrap: bootstrap_allowed,
+        require_server_handshake: true,
+        channel: Channel::Tmux,
+        policy_sha256: profile.policy_sha256,
+    };
+    let _ = team_agent_contract::orchestration::supervisor::tick(
+        &mut backend.store,
+        &seat.identity,
+        &sample,
+        &authorization,
+        &mut physical,
+    )?;
+    Ok(())
+}
+
+pub fn tick(workspace: &Path, state: &mut Value) -> Result<(), BackendError> {
+    if !framework::has_contract(state) {
+        return Ok(());
+    }
+    let team = crate::state::projection::team_state_key(state);
+    let ids: Vec<_> = state
+        .get("agents")
+        .and_then(Value::as_object)
+        .into_iter()
+        .flat_map(|agents| agents.iter())
+        .filter(|(_, agent)| framework::is_contract(agent) && !framework::is_paused_unstarted(agent))
+        .map(|(id, _)| id.clone())
+        .collect();
+    if ids.is_empty() {
+        return Ok(());
+    }
+    let mut backend = Backend::open(workspace, &team)?;
+    let mut failure = None;
+    for id in ids {
+        let Some(seat) = backend.store.seat(&SeatId::new(&id)?)? else {
+            continue;
+        };
+        if let Err(error) = deliver_one(&mut backend, &seat) {
+            failure = Some(error);
+        }
+        if let Some(agent) = state
+            .get_mut("agents")
+            .and_then(|agents| agents.get_mut(&id))
+        {
+            match framework::project_seat(workspace, &team, &id) {
+                Ok(projected) => {
+                    let row = agent.as_object_mut().ok_or(BackendError::Metadata)?;
+                    for (key, value) in projected.as_object().ok_or(BackendError::Metadata)? {
+                        row.insert(key.clone(), value.clone());
+                    }
+                },
+                Err(error) => failure = Some(error),
+            }
+        }
+    }
+    // One blocked seat must not prevent already committed results from reaching
+    // the shared framework task-finalization/leader-presentation path.
+    forward::drain(&backend.binding.framework(), &mut backend.store, 32)?;
+    match failure {
+        Some(error) => Err(error),
+        None => Ok(()),
+    }
+}

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

@@ -0,0 +1,197 @@
+//! The sole new-runtime provider registry. This is not an admission claim:
+//! the descriptor's Unverified gates still apply to each requested operation.
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+use team_agent_contract::contract::{
+    descriptor::{PromptCarrier, ProviderDescriptor, ToolNaming},
+    hooks::{PlanHook, ProviderHooks},
+    plan::{LaunchPlan, ResolvedLaunch},
+    types::{ContractError, Support},
+};
+use team_agent_contract::kiro::{self, KiroAdapter, KIRO_DESCRIPTOR};
+use team_agent_contract::providers::cursor::{self, CursorAdapter, CURSOR_DESCRIPTOR};
+use team_agent_contract::runtime::{delivery::ControlDefinition, native_panel::NativePanelPolicy};
+
+const DESCRIPTORS: &[&ProviderDescriptor] = &[&KIRO_DESCRIPTOR, &CURSOR_DESCRIPTOR];
+
+/// Leaf selection stays here; the framework, lifecycle and outbox remain shared.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum NativeProvider {
+    Kiro,
+    Cursor,
+}
+
+impl NativeProvider {
+    pub fn descriptor(self) -> &'static ProviderDescriptor {
+        match self {
+            Self::Kiro => &KIRO_DESCRIPTOR,
+            Self::Cursor => &CURSOR_DESCRIPTOR,
+        }
+    }
+
+    pub fn action_budget(self) -> std::time::Duration {
+        // Kiro's existing budget is unchanged; Cursor's measured cold-ready
+        // path needs a larger finite bound, not an unbounded readiness wait.
+        std::time::Duration::from_secs(match self { Self::Kiro => 30, Self::Cursor => 90 })
+    }
+
+    pub fn controls(self) -> &'static [ControlDefinition] {
+        match self {
+            Self::Kiro => kiro::interaction::CONTROLS,
+            Self::Cursor => cursor::interaction::CONTROLS,
+        }
+    }
+
+    /// A terminal instruction bridge needs one durable, authorized first packet
+    /// before the native client can demonstrate its Team-tool registry.
+    pub fn first_business_bootstrap(self) -> bool {
+        matches!(self.descriptor().prompt.carrier, Support::Supported(PromptCarrier::RuntimeBridge))
+    }
+
+    /// Cursor has no measured neutral TUI tools panel. Its protocol binding
+    /// must come from the separately fenced native tool-roundtrip ledger.
+    pub fn uses_tool_roundtrips(self) -> bool {
+        matches!(self, Self::Cursor)
+    }
+
+    pub fn tool_panel(self) -> Result<&'static NativePanelPolicy, ContractError> {
+        match self {
+            Self::Kiro => Ok(&kiro::interaction::TOOL_PANEL),
+            Self::Cursor => Err(ContractError::Unverified {
+                field: "Cursor native Team-tool inspector",
+                reason: cursor::UNVERIFIED,
+            }),
+        }
+    }
+
+    pub fn server_key(self) -> Result<&'static str, ContractError> {
+        match self.descriptor().tool_names.naming.require("tool naming")? {
+            ToolNaming::StaticServer { key } => Ok(key),
+            ToolNaming::RuntimeBound => Err(ContractError::Invalid("runtime server-key receipt required")),
+        }
+    }
+
+    pub fn adapter(
+        self,
+        executable: PathBuf,
+        arguments: Vec<String>,
+        environment: BTreeMap<String, String>,
+    ) -> Result<NativeAdapter, ContractError> {
+        match self {
+            Self::Kiro => KiroAdapter::new(kiro::McpStdio {
+                executable, arguments, environment,
+            }).map(NativeAdapter::Kiro),
+            Self::Cursor => CursorAdapter::new(cursor::McpStdio {
+                executable, arguments, environment,
+            }).map(NativeAdapter::Cursor),
+        }
+    }
+}
+
+pub(super) enum NativeAdapter {
+    Kiro(KiroAdapter),
+    Cursor(CursorAdapter),
+}
+
+impl NativeAdapter {
+    pub fn with_launch_context(
+        self,
+        project: PathBuf,
+        runtime: Option<cursor::native::RuntimeInstallation>,
+    ) -> Result<Self, ContractError> {
+        match self {
+            Self::Kiro(adapter) if runtime.is_none() => Ok(Self::Kiro(adapter)),
+            Self::Kiro(_) => Err(ContractError::Mismatch("native runtime provider")),
+            Self::Cursor(adapter) => {
+                let adapter = adapter.with_project(project)?;
+                Ok(Self::Cursor(match runtime {
+                    Some(runtime) => adapter.with_runtime(runtime),
+                    None => adapter,
+                }))
+            }
+        }
+    }
+
+    pub fn hooks(&self) -> ProviderHooks<'_> {
+        match self {
+            Self::Kiro(adapter) => adapter.hooks(),
+            Self::Cursor(adapter) => adapter.hooks(),
+        }
+    }
+
+    pub fn plan(&self, request: &ResolvedLaunch) -> Result<LaunchPlan, ContractError> {
+        match self {
+            Self::Kiro(adapter) => adapter.plan(request),
+            Self::Cursor(adapter) => adapter.plan(request),
+        }
+    }
+}
+
+pub(super) fn provider(key: &str) -> Result<NativeProvider, ContractError> {
+    let descriptor = descriptor(key).ok_or(ContractError::Invalid("unregistered contract provider"))?;
+    match descriptor.identity.id {
+        "kiro" => Ok(NativeProvider::Kiro),
+        "cursor" => Ok(NativeProvider::Cursor),
+        _ => Err(ContractError::Invalid("contract provider dispatcher")),
+    }
+}
+
+pub(crate) fn descriptors() -> &'static [&'static ProviderDescriptor] {
+    DESCRIPTORS
+}
+
+pub fn descriptor(key: &str) -> Option<&'static ProviderDescriptor> {
+    DESCRIPTORS.iter().copied().find(|descriptor| {
+        descriptor.identity.id == key || descriptor.identity.aliases.contains(&key)
+    })
+}
+
+/// Recognize a misspelled/case-modified contract declaration so it can fail
+/// explicitly instead of accidentally selecting a legacy default provider.
+pub fn recognizes(key: &str) -> bool {
+    let key = key.trim();
+    DESCRIPTORS.iter().any(|descriptor| {
+        descriptor.identity.id.eq_ignore_ascii_case(key)
+            || descriptor
+                .identity
+                .aliases
+                .iter()
+                .any(|alias| alias.eq_ignore_ascii_case(key))
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn canonical_cursor_does_not_reclassify_legacy_names() {
+        assert_eq!(provider("cursor").unwrap(), NativeProvider::Cursor);
+        assert_eq!(provider("kiro").unwrap(), NativeProvider::Kiro);
+        for legacy in ["cursor_agent", "agent", "pi", "codex"] {
+            assert!(descriptor(legacy).is_none());
+            assert!(!recognizes(legacy));
+            assert!(provider(legacy).is_err());
+        }
+        assert!(recognizes(" Cursor "));
+        assert!(descriptor("Cursor").is_none());
+        for descriptor in descriptors() {
+            assert_eq!(provider(descriptor.identity.id).unwrap().descriptor(), *descriptor);
+        }
+    }
+
+    #[test]
+    fn cursor_has_no_kiro_control_or_tool_inspector_fallback() {
+        assert!(NativeProvider::Cursor.controls().is_empty());
+        assert!(matches!(NativeProvider::Cursor.tool_panel(), Err(ContractError::Unverified { .. })));
+        assert_eq!(NativeProvider::Cursor.server_key().unwrap(), "team");
+        assert!(NativeProvider::Cursor.first_business_bootstrap());
+        assert!(NativeProvider::Cursor.uses_tool_roundtrips());
+        assert!(!NativeProvider::Kiro.first_business_bootstrap());
+        assert!(!NativeProvider::Kiro.uses_tool_roundtrips());
+        let kiro_panel = NativeProvider::Kiro.tool_panel().unwrap();
+        assert_eq!(kiro_panel.server_key, NativeProvider::Kiro.server_key().unwrap());
+        assert_eq!(kiro_panel.policy_sha256, kiro::interaction::POLICY);
+        assert!(!NativeProvider::Kiro.controls().is_empty());
+    }
+}