Skip to content
Python
19.5 KB
Raw Blame
//! Portable model-handoff requests. These identify intended work; they never
//! authorize provider I/O, declare publication, or attest verification success.
use super::{component, oid, Manifest, ObjectFormat, Producer};
use anyhow::{ensure, Result};
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Call {
    pub turn_id: String,
    pub call_id: String,
}
impl Call {
    pub fn validate(&self) -> Result<()> {
        component(&self.turn_id, 80)?;
        ensure!(
            !self.call_id.is_empty()
                && self.call_id.len() <= 200
                && !self.call_id.chars().any(char::is_control),
            "Invalid originating model call"
        );
        Ok(())
    }
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Submission {
    pub id: String,
    pub producer: Producer,
    /// The first accepted model call, retained on duplicate delivery.
    pub origin: Call,
    pub source_manifest: String,
    pub repository: String,
    pub object_format: ObjectFormat,
    pub base_commit: String,
    pub submitted_commit: String,
    /// Untrusted descriptive data, never included in a harness authority notice.
    pub summary: String,
}
impl Submission {
    pub fn new(
        producer: Producer,
        origin: Call,
        source: &Manifest,
        commit: String,
        summary: String,
    ) -> Result<Self> {
        producer.validate()?;
        origin.validate()?;
        source.validate()?;
        ensure!(
            producer.team_id == source.producer.team_id,
            "Submission source belongs to another team"
        );
        let mut request = Self {
            id: String::new(),
            producer,
            origin,
            source_manifest: source.digest()?,
            repository: source.repository.clone(),
            object_format: source.object_format,
            base_commit: source.base_commit.clone(),
            submitted_commit: commit,
            summary,
        };
        request.id = request.key()?;
        request.validate()?;
        Ok(request)
    }
    fn key(&self) -> Result<String> {
        // Commit/source identity deduplicates an uncertain submission even when
        // a model asks again using a NEW call ID. Summary text cannot create a
        // second export of this same intended revision.
        Ok(format!(
            "hs_{}",
            crate::bundle::digest(&serde_json::to_vec(&(
                "coding-submission-v1",
                &self.producer,
                &self.source_manifest,
                &self.repository,
                self.object_format,
                &self.base_commit,
                &self.submitted_commit,
            ))?)
        ))
    }
    pub fn validate(&self) -> Result<()> {
        component(&self.id, 80)?;
        self.producer.validate()?;
        self.origin.validate()?;
        super::hex(&self.source_manifest, 64)?;
        super::repository(&self.repository)?;
        oid(&self.base_commit, self.object_format)?;
        oid(&self.submitted_commit, self.object_format)?;
        ensure!(
            !self.summary.trim().is_empty()
                && self.summary.len() <= 2000
                && !self.summary.contains('\0'),
            "Bounded submission summary required"
        );
        ensure!(self.id == self.key()?, "Submission identity changed");
        Ok(())
    }
    /// Descriptive text/new call IDs do not authorize a second external action.
    pub fn same_revision(&self, other: &Self) -> Result<bool> {
        self.validate()?;
        other.validate()?;
        Ok(self.id == other.id)
    }
    pub fn require_manifest(&self, manifest: &Manifest) -> Result<()> {
        self.validate()?;
        manifest.require_source(&self.repository, &self.base_commit)?;
        ensure!(
            manifest.kind == super::Kind::Submission
                && manifest.producer == self.producer
                && manifest.object_format == self.object_format
                && manifest.submitted_commit == self.submitted_commit,
            "Published handoff differs from originating submission"
        );
        Ok(())
    }
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Verification {
    pub id: String,
    pub submission_id: String,
    pub manifest_digest: String,
    pub submitted_commit: String,
    pub reporter: Producer,
    pub origin: Call,
    /// Attributed agent report, not proof tests passed or an approval to merge.
    pub text: String,
}
impl Verification {
    pub fn require_submission(&self, request: &Submission, manifest: &Manifest) -> Result<()> {
        request.require_manifest(manifest)?;
        component(&self.id, 80)?;
        self.reporter.validate()?;
        self.origin.validate()?;
        ensure!(
            self.submission_id == request.id
                && self.manifest_digest == manifest.digest()?
                && self.submitted_commit == manifest.submitted_commit
                && self.reporter.team_id == request.producer.team_id
                && !self.text.trim().is_empty()
                && self.text.len() <= 8000
                && !self.text.contains('\0'),
            "Verification report differs from exact same-team submitted revision"
        );
        Ok(())
    }
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Integration {
    pub submission_id: String,
    pub manifest_digest: String,
    pub expected_head: String,
}
impl Integration {
    pub fn require_submission(&self, request: &Submission, manifest: &Manifest) -> Result<()> {
        request.require_manifest(manifest)?;
        oid(&self.expected_head, manifest.object_format)?;
        ensure!(
            self.submission_id == request.id && self.manifest_digest == manifest.digest()?,
            "Integration is not bound to the immutable submission"
        );
        // Actual branch, working tree, descendant check and original operation
        // marker belong to the trusted Git adapter, not this metadata contract.
        Ok(())
    }
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct State {
    pub request: Submission,
    /// Set only by the qualified artifact adapter after byte verification.
    pub manifest: Option<Manifest>,
    #[serde(default)]
    pub reports: Vec<Verification>,
    #[serde(default)]
    pub error: Option<String>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub uncertain: bool,
}

/// Metadata-only domain action. The adapter must persist it atomically with the
/// tool result, and qualify the separate export/publication before acknowledging.
pub fn submit(
    doc: &mut crate::agent_team::Document,
    session: &crate::store::Session,
    commit: String,
    summary: String,
) -> Result<serde_json::Value> {
    use anyhow::Context;
    let member = session.agent_team.as_ref().context("Not a team member")?;
    ensure!(
        doc.coding_selection && doc.coding.is_some(),
        "Coding handoff is unavailable on this adapter"
    );
    let source = doc
        .source_imports
        .get(&member.agent_id)
        .context("Submit from an acknowledged independent source checkout")?;
    let request = Submission::new(
        Producer {
            team_id: doc.id.clone(),
            agent_id: member.agent_id.clone(),
            session_id: session.id.clone(),
        },
        current_call(session, "team_submit_code")?,
        &source.manifest,
        commit,
        summary,
    )?;
    if let Some(existing) = doc.submissions.get(&request.id) {
        ensure!(
            existing.request.same_revision(&request)?,
            "Submission retry changed revision"
        );
        return Ok(view(existing));
    }
    ensure!(
        doc.submissions.len() < 256,
        "Team submission capacity reached"
    );
    let state = State {
        request,
        manifest: None,
        reports: vec![],
        error: None,
        uncertain: false,
    };
    let result = view(&state);
    doc.submissions.insert(state.request.id.clone(), state);
    Ok(result)
}
pub(super) fn current_call(session: &crate::store::Session, name: &str) -> Result<Call> {
    use anyhow::Context;
    let turn = session
        .turn
        .as_ref()
        .context("Handoff requires an originating tool turn")?;
    let call = turn.queue.first().context("No originating tool call")?;
    ensure!(
        turn.status == "running" && call["name"] == name,
        "Stale handoff tool call"
    );
    let origin = Call {
        turn_id: turn.id.clone(),
        call_id: call["call_id"]
            .as_str()
            .context("Missing originating call ID")?
            .into(),
    };
    origin.validate()?;
    Ok(origin)
}
/// The report is attributed to a verifier that imported this EXACT manifest.
/// Its text remains a claim; neither a green status nor merge authority follows.
pub fn report(
    doc: &mut crate::agent_team::Document,
    session: &crate::store::Session,
    id: &str,
    text: String,
) -> Result<serde_json::Value> {
    use anyhow::Context;
    let member = session.agent_team.as_ref().context("Not a team member")?;
    ensure!(doc.coding_selection, "Coding handoff unavailable");
    let imported = doc
        .source_imports
        .get(&member.agent_id)
        .context("No acknowledged submission checkout")?;
    ensure!(
        imported.choice == (super::config::Choice::Submission { id: id.into() }),
        "Verifier did not import this submission"
    );
    let team_report_bytes: usize = doc
        .submissions
        .values()
        .flat_map(|s| &s.reports)
        .map(|r| r.text.len())
        .sum();
    let state = doc
        .submissions
        .get_mut(id)
        .context("Unknown same-team submission")?;
    let manifest = state
        .manifest
        .as_ref()
        .context("Submission is not published")?;
    ensure!(
        imported.manifest == *manifest,
        "Verifier checkout differs from immutable submission"
    );
    let origin = current_call(session, "team_report_verification")?;
    let reporter = Producer {
        team_id: doc.id.clone(),
        agent_id: member.agent_id.clone(),
        session_id: session.id.clone(),
    };
    let key = format!(
        "vr_{}",
        crate::bundle::digest(&serde_json::to_vec(&(id, &reporter, &text))?)
    );
    let report = Verification {
        id: key,
        submission_id: id.into(),
        manifest_digest: manifest.digest()?,
        submitted_commit: manifest.submitted_commit.clone(),
        reporter,
        origin,
        text,
    };
    report.require_submission(&state.request, manifest)?;
    if let Some(old) = state.reports.iter().find(|r| r.id == report.id) {
        return Ok(serde_json::json!(old));
    }
    ensure!(
        state.reports.len() < 16
            && state.reports.iter().map(|r| r.text.len()).sum::<usize>() + report.text.len()
                <= 32768
            && team_report_bytes + report.text.len() <= 262144,
        "Submission report capacity reached"
    );
    state.reports.push(report.clone());
    Ok(serde_json::json!(report))
}
pub fn view(state: &State) -> serde_json::Value {
    serde_json::json!({"id":state.request.id,"producer":state.request.producer.agent_id,"commit":state.request.submitted_commit,"summary":state.request.summary,"status":if state.manifest.is_some(){"ready"}else if state.error.is_some(){"blocked"}else if state.uncertain{"outcome_unknown"}else{"pending"},"error":state.error,"reports":state.reports})
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Reception {
    pub submission_id: String,
    pub manifest_digest: String,
    pub origin: Call,
    pub workspace: crate::team_workspace::Request,
    pub receipt: Option<crate::team_workspace::Receipt>,
    pub error: Option<String>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub uncertain: bool,
}
pub fn receive(
    doc: &mut crate::agent_team::Document,
    session: &crate::store::Session,
    id: &str,
) -> Result<serde_json::Value> {
    use anyhow::Context;
    ensure!(
        doc.coding_selection
            && session
                .agent_team
                .as_ref()
                .is_some_and(|m| m.agent_id == doc.lead),
        "Only the original coding lead may receive a submission"
    );
    let state = doc
        .submissions
        .get(id)
        .context("Unknown same-team submission")?;
    let manifest = state
        .manifest
        .as_ref()
        .context("Submission not published")?;
    state.request.require_manifest(manifest)?;
    if let Some(original) = doc.receptions.get(id) {
        return Ok(reception_view(original));
    }
    let operation_id = format!("rcv_{}", crate::bundle::digest(id.as_bytes()));
    let scope_digest = crate::bundle::digest(&serde_json::to_vec(&(
        "coding-reception-v1",
        &doc.id,
        &session.id,
        &session.workspace,
        &session.environment,
        id,
        manifest.digest()?,
    ))?);
    let request = crate::team_workspace::Request {
        operation_id,
        scope_digest,
        selection: crate::team_workspace::Selection::Directory {
            path: format!(".openworker-received/{}/{id}", doc.id),
        },
    };
    request.validate()?;
    let reception = Reception {
        submission_id: id.into(),
        manifest_digest: manifest.digest()?,
        origin: current_call(session, "team_receive_submission")?,
        workspace: request,
        receipt: None,
        error: None,
        uncertain: false,
    };
    let result = reception_view(&reception);
    doc.receptions.insert(id.into(), reception);
    Ok(result)
}
pub fn reception_view(r: &Reception) -> serde_json::Value {
    serde_json::json!({"submission_id":r.submission_id,"status":if r.receipt.is_some(){"ready"}else if r.error.is_some(){"blocked"}else if r.uncertain{"outcome_unknown"}else{"pending"},"path":r.receipt.as_ref().map(|p|&p.path),"operation_id":r.workspace.operation_id,"error":r.error})
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IntegrationState {
    pub id: String,
    pub request: Integration,
    pub origin: Call,
    pub outcome: Option<super::integrate::Observation>,
    pub error: Option<String>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub uncertain: bool,
}
pub fn request_integration(
    doc: &mut crate::agent_team::Document,
    session: &crate::store::Session,
    id: &str,
    expected_head: String,
) -> Result<serde_json::Value> {
    use anyhow::Context;
    ensure!(
        doc.coding_selection
            && session
                .agent_team
                .as_ref()
                .is_some_and(|m| m.agent_id == doc.lead),
        "Only the coding lead may integrate"
    );
    let state = doc
        .submissions
        .get(id)
        .context("Unknown same-team submission")?;
    let manifest = state
        .manifest
        .as_ref()
        .context("Submission is not published")?;
    let request = Integration {
        submission_id: id.into(),
        manifest_digest: manifest.digest()?,
        expected_head,
    };
    request.require_submission(&state.request, manifest)?;
    let reception = doc
        .receptions
        .get(id)
        .context("Receive the submission before integration")?;
    ensure!(
        reception.manifest_digest == request.manifest_digest && reception.receipt.is_some(),
        "Original reception not acknowledged"
    );
    let key = format!(
        "int_{}",
        crate::bundle::digest(&serde_json::to_vec(&(
            "coding-integration-v1",
            &doc.id,
            &session.id,
            &session.environment,
            &request
        ))?)
    );
    if let Some(old) = doc.integrations.get(&key) {
        return Ok(integration_view(old));
    }
    ensure!(
        doc.integrations.len() < 256,
        "Team integration capacity reached"
    );
    let state = IntegrationState {
        id: key.clone(),
        request,
        origin: current_call(session, "team_integrate_submission")?,
        outcome: None,
        error: None,
        uncertain: false,
    };
    let result = integration_view(&state);
    doc.integrations.insert(key, state);
    Ok(result)
}
pub fn integration_view(i: &IntegrationState) -> serde_json::Value {
    serde_json::json!({"id":i.id,"submission_id":i.request.submission_id,"expected_head":i.request.expected_head,"status":match i.outcome.as_ref(){Some(super::integrate::Observation::Applied{..})=>"applied",Some(super::integrate::Observation::Rejected{..})=>"rejected",None if i.error.is_some()=>"blocked",None if i.uncertain=>"outcome_unknown",None=>"pending"},"outcome":i.outcome,"error":i.error})
}

pub fn approval_required(alias: &str) -> bool {
    matches!(
        alias,
        "team_submit_code" | "team_receive_submission" | "team_integrate_submission"
    )
}
#[derive(Debug)]
pub struct ApprovalInvalidated;
impl std::fmt::Display for ApprovalInvalidated {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Handoff approval is missing, revoked or bound to different policy"
        )
    }
}
impl std::error::Error for ApprovalInvalidated {}
/// Called INSIDE the adapter's session transaction, immediately before the
/// intent/tool-result commit. The earlier LLM-loop check alone cannot fence a
/// concurrent session-grant revocation. No tool label can override these pins.
pub fn require_approval(s: &crate::store::Session, call: &serde_json::Value) -> Result<()> {
    let alias = call["name"].as_str().unwrap_or_default();
    if !approval_required(alias) {
        return Ok(());
    }
    require_tool_approval(s, call, None, None)
}
/// Recheck the exact ordinary native/MCP tool approval at a durable effect-intent
/// boundary. Called while holding the session lock, including for bypass-origin
/// approvals; no label or previously revoked Allow Always entry can waive it.
pub fn require_tool_approval(
    s: &crate::store::Session,
    call: &serde_json::Value,
    server: Option<&str>,
    remote: Option<&str>,
) -> Result<()> {
    let alias = call["name"].as_str().unwrap_or_default();
    let valid = (|| {
        let turn = s.turn.as_ref()?;
        let i = s
            .interactions
            .iter()
            .rev()
            .find(|i| i.turn_id == turn.id && i.call == *call)?;
        let approved = matches!(i.response.as_deref(), Some("once" | "session"));
        let binding = i.kind == "approval"
            && i.bundle_digest == s.bundle_digest
            && Some(&i.schema_digest) == s.schema_digest.as_ref()
            && i.policy_digest == s.tool_policy.digest
            && i.resource_policy_digest == s.resource_policy.digest
            && i.server.as_deref() == server
            && i.remote_tool.as_deref() == remote;
        let grant = i.grant_id.as_ref().is_none_or(|id| {
            s.approval_grants.iter().any(|g| {
                g.id == *id
                    && g.tool == alias
                    && g.server.as_deref() == server
                    && g.remote_tool.as_deref() == remote
                    && g.bundle_digest == s.bundle_digest
                    && Some(&g.schema_digest) == s.schema_digest.as_ref()
                    && g.policy_digest == s.tool_policy.digest
                    && g.resource_policy_digest == s.resource_policy.digest
            })
        });
        Some(approved && binding && grant)
    })()
    .unwrap_or(false);
    ensure!(valid, ApprovalInvalidated);
    Ok(())
}