Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

17.0 KB
Raw Blame
//! Capturing, storing, and serving a session's changes.
//!
//! One capture is one round trip through the extractor: read the changes,
//! store a raw patch under the session or point at the pull request changeset
//! every reader of the same base and head shares, replace the summary, tell
//! the viewers. Captures run after every turn - the moment a session has
//! something new to show - and on demand from the pane. A session never has
//! two captures running at once: a request that lands mid-capture is folded
//! into a rerun, so the stored changeset always reflects a state at least as
//! new as the request that asked for it.

use std::collections::HashMap;
use std::future::Future;
use std::sync::{Arc, Mutex};

use agent_session::domain::model::AgentSession;
use agent_session::domain::ports::{AgentSessionRealtime, AgentSessionRepo, SessionTurnObserver};
use agent_session::domain::session::StopReason;
use chrono::Utc;
use entity_access::domain::models::{
    EditAccessLevel, EntityAccessReceipt, EntityType, RequiredPermission, ViewAccessLevel,
};
use macro_uuid::Uuid;
use tracing::Instrument as _;

use super::error::{ChangesError, ExtractError, Result};
use super::model::{
    AgentSessionId, AttemptOutcome, Changeset, ChangesetId, ChangesetSource, ExtractedChangeset,
    SessionChanges,
};
use super::patch::{self, MAX_FILE_PATCH_BYTES, MAX_PATCH_BYTES};
use super::ports::{
    ChangesetBlobStore, ChangesetExtractor, ChangesetRepo, PatchBlobKey, PatchLocation,
};

#[cfg(test)]
mod test;

/// How one capture ended.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CaptureOutcome {
    /// A changeset (possibly empty) was stored.
    Captured(Box<Changeset>),
    /// The pull request was not available; the reason was recorded.
    NotReady,
    /// The extractor or the storage failed; the reason was recorded.
    Failed,
    /// A capture was already running; it will run once more when it ends,
    /// so the caller's request is not lost.
    Queued,
}

/// What the inbound adapters ask of the service, so they can be generic over
/// one type rather than the service's five.
pub trait AgentChanges: Send + Sync + 'static {
    /// The latest changeset and attempt for the session the receipt names.
    fn changes(
        &self,
        access: &EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<SessionChanges>> + Send;

    /// The stored patch for the session the receipt names.
    fn patch(
        &self,
        access: &EntityAccessReceipt<ViewAccessLevel>,
    ) -> impl Future<Output = Result<String>> + Send;

    /// Start a capture without waiting for it; answer with the state as it
    /// stands.
    fn request_capture(
        &self,
        access: &EntityAccessReceipt<EditAccessLevel>,
    ) -> impl Future<Output = Result<SessionChanges>> + Send;
}

struct Inner<Sessions, Extractor, Repo, Blobs, Realtime> {
    sessions: Sessions,
    extractor: Extractor,
    repo: Repo,
    blobs: Blobs,
    realtime: Realtime,
    /// Sessions with a capture running, and whether another was asked for
    /// while it ran.
    in_flight: Mutex<HashMap<AgentSessionId, bool>>,
}

/// The changes service: one per process, cloned wherever a capture can start.
pub struct AgentChangesService<Sessions, Extractor, Repo, Blobs, Realtime> {
    inner: Arc<Inner<Sessions, Extractor, Repo, Blobs, Realtime>>,
}

// Manual Clone so the port types need not be Clone; a clone is another
// handle on the same in-flight table, which is what makes "one capture per
// session" hold across every handle.
impl<Sessions, Extractor, Repo, Blobs, Realtime> Clone
    for AgentChangesService<Sessions, Extractor, Repo, Blobs, Realtime>
{
    fn clone(&self) -> Self {
        Self {
            inner: Arc::clone(&self.inner),
        }
    }
}

impl<Sessions, Extractor, Repo, Blobs, Realtime>
    AgentChangesService<Sessions, Extractor, Repo, Blobs, Realtime>
where
    Sessions: AgentSessionRepo,
    Extractor: ChangesetExtractor,
    Repo: ChangesetRepo,
    Blobs: ChangesetBlobStore,
    Realtime: AgentSessionRealtime + Send + Sync + 'static,
{
    /// Build the service from its ports.
    pub fn new(
        sessions: Sessions,
        extractor: Extractor,
        repo: Repo,
        blobs: Blobs,
        realtime: Realtime,
    ) -> Self {
        Self {
            inner: Arc::new(Inner {
                sessions,
                extractor,
                repo,
                blobs,
                realtime,
                in_flight: Mutex::new(HashMap::new()),
            }),
        }
    }

    /// The latest changeset and attempt for the session the receipt names.
    async fn read_changes(
        &self,
        access: &EntityAccessReceipt<ViewAccessLevel>,
    ) -> Result<SessionChanges> {
        let session = session_of(access)?;
        self.inner
            .repo
            .get(session)
            .await
            .map_err(ChangesError::Storage)
    }

    /// The stored patch for the session the receipt names.
    async fn read_patch(&self, access: &EntityAccessReceipt<ViewAccessLevel>) -> Result<String> {
        let session = session_of(access)?;
        let location = self
            .inner
            .repo
            .patch_location(session)
            .await
            .map_err(ChangesError::Storage)?
            .ok_or(ChangesError::NoChangeset)?;
        let patch = match location {
            PatchLocation::Blob(key) => self.inner.blobs.get_patch(&key).await,
            PatchLocation::PullRequest(changeset) => {
                let row = self.inner.sessions.get(session).await?;
                self.inner
                    .extractor
                    .pull_request_patch(&row, changeset)
                    .await
            }
        };
        patch
            .map_err(ChangesError::Storage)?
            .ok_or(ChangesError::PatchMissing)
    }

    /// Start a capture for the session the receipt names, without waiting
    /// for it, and answer with the state as it stands - which includes the
    /// attempt just started, once the repo has noted it.
    async fn start_capture(
        &self,
        access: &EntityAccessReceipt<EditAccessLevel>,
    ) -> Result<SessionChanges> {
        let session = session_of(access)?;
        self.capture_in_background(session);
        // Give the spawned capture a chance to mark its attempt so the
        // answer already says "running" - but never wait on the extractor.
        tokio::task::yield_now().await;
        self.inner
            .repo
            .get(session)
            .await
            .map_err(ChangesError::Storage)
    }

    /// Run a capture on a task of its own. Safe to call from anywhere on a
    /// runtime - the session actor's task included - because it returns
    /// before any work happens.
    pub fn capture_in_background(&self, session: AgentSessionId) {
        let service = self.clone();
        let span = tracing::info_span!("agent.changes.capture", agent.session.id = %session);
        tokio::spawn(
            async move {
                if let Err(error) = service.capture(session).await {
                    tracing::warn!(error = ?error, %session, "capturing session changes failed");
                }
            }
            .instrument(span),
        );
    }

    /// Capture the session's changes now, rerunning once if another capture
    /// was requested while this one ran.
    pub async fn capture(&self, session: AgentSessionId) -> Result<CaptureOutcome> {
        if !self.claim(session) {
            return Ok(CaptureOutcome::Queued);
        }
        let mut outcome = self.capture_once(session).await;
        while self.release(session) {
            // Somebody asked again mid-capture; their request is the newer
            // state, so capture once more before letting go.
            if !self.claim(session) {
                break;
            }
            outcome = self.capture_once(session).await;
        }
        outcome
    }

    /// Take the session's capture slot, or note a rerun if it is taken.
    fn claim(&self, session: AgentSessionId) -> bool {
        let mut in_flight = self
            .inner
            .in_flight
            .lock()
            .expect("in-flight table poisoned");
        match in_flight.get_mut(&session) {
            Some(rerun) => {
                *rerun = true;
                false
            }
            None => {
                in_flight.insert(session, false);
                true
            }
        }
    }

    /// Give the slot back. Whether a rerun was asked for meanwhile.
    fn release(&self, session: AgentSessionId) -> bool {
        let mut in_flight = self
            .inner
            .in_flight
            .lock()
            .expect("in-flight table poisoned");
        in_flight.remove(&session).unwrap_or(false)
    }

    async fn capture_once(&self, session: AgentSessionId) -> Result<CaptureOutcome> {
        let started_at = Utc::now();
        let row = self.inner.sessions.get(session).await?;
        self.inner
            .repo
            .begin_attempt(session, started_at)
            .await
            .map_err(ChangesError::Storage)?;
        // Viewers learn a capture is running the same way they learn it
        // ended: by re-reading the summary.
        self.notify(session).await;

        let extracted = self.inner.extractor.extract(&row).await;
        let outcome = match extracted {
            Ok(extracted) => self.store(&row, extracted).await,
            Err(ExtractError::NotReady(reason)) => {
                tracing::info!(%session, reason, "changes are not ready to capture");
                self.fail(session, AttemptOutcome::NotReady, reason)
                    .await
                    .map(|()| CaptureOutcome::NotReady)
            }
            Err(ExtractError::Failed(report)) => {
                tracing::warn!(%session, error = ?report, "extracting session changes failed");
                self.fail(
                    session,
                    AttemptOutcome::Failed,
                    "Collecting the changes failed. Try again after the agent's next turn."
                        .to_owned(),
                )
                .await
                .map(|()| CaptureOutcome::Failed)
            }
        };
        self.notify(session).await;
        outcome
    }

    async fn store(
        &self,
        row: &AgentSession,
        extracted: ExtractedChangeset,
    ) -> Result<CaptureOutcome> {
        let session = row.id;
        let (changeset, location) = match extracted {
            ExtractedChangeset::Patch {
                source,
                range,
                patch,
                truncated,
            } => {
                let parsed = patch::parse_git_patch(&patch);
                let budgeted = patch::budget_patch(parsed, MAX_PATCH_BYTES, MAX_FILE_PATCH_BYTES);
                let (additions, deletions) = patch::totals(&budgeted.files);
                let id = ChangesetId::new();
                let key =
                    (!budgeted.patch.is_empty()).then(|| PatchBlobKey::for_changeset(session, id));
                if let Some(key) = &key
                    && let Err(error) = self.inner.blobs.put_patch(key, &budgeted.patch).await
                {
                    let _ = self
                        .fail(
                            session,
                            AttemptOutcome::Failed,
                            "Storing the changes failed.".to_owned(),
                        )
                        .await;
                    return Err(ChangesError::Storage(error));
                }
                let changeset = Changeset {
                    id,
                    session,
                    source,
                    range,
                    patch_bytes: budgeted.patch.len() as u64,
                    files: budgeted.files,
                    additions,
                    deletions,
                    truncated: budgeted.truncated || truncated,
                    captured_at: Utc::now(),
                };
                (changeset, key.map(PatchLocation::Blob))
            }
            ExtractedChangeset::PullRequest(shared) => {
                let changeset = Changeset {
                    id: ChangesetId::from_uuid(shared.id),
                    session,
                    source: ChangesetSource::GithubPullRequest,
                    range: shared.range,
                    files: shared.files,
                    additions: shared.additions,
                    deletions: shared.deletions,
                    patch_bytes: shared.patch_bytes,
                    truncated: shared.truncated,
                    captured_at: Utc::now(),
                };
                (changeset, Some(PatchLocation::PullRequest(shared.id)))
            }
        };
        let superseded = match self
            .inner
            .repo
            .record_changeset(&changeset, location.as_ref(), Utc::now())
            .await
        {
            Ok(superseded) => superseded,
            Err(error) => {
                let _ = self
                    .fail(
                        session,
                        AttemptOutcome::Failed,
                        "Storing the changes failed.".to_owned(),
                    )
                    .await;
                return Err(ChangesError::Storage(error));
            }
        };
        // The old patch is unreachable now that the row points elsewhere;
        // deleting it is tidiness, not correctness, so a failure only logs.
        if let Some(old) = superseded
            && !matches!(&location, Some(PatchLocation::Blob(key)) if *key == old)
            && let Err(error) = self.inner.blobs.delete_patch(&old).await
        {
            tracing::warn!(error = ?error, %session, key = %old, "could not delete a superseded patch");
        }
        tracing::info!(
            %session,
            files = changeset.files.len(),
            additions = changeset.additions,
            deletions = changeset.deletions,
            truncated = changeset.truncated,
            source = %changeset.source,
            "captured session changes"
        );
        Ok(CaptureOutcome::Captured(Box::new(changeset)))
    }

    async fn fail(
        &self,
        session: AgentSessionId,
        outcome: AttemptOutcome,
        reason: String,
    ) -> Result<()> {
        self.inner
            .repo
            .record_failure(session, outcome, Some(&reason), Utc::now())
            .await
            .map_err(ChangesError::Storage)
    }

    async fn notify(&self, session: AgentSessionId) {
        if let Err(error) = self.inner.realtime.publish_changes_updated(session).await {
            tracing::warn!(error = ?error, %session, "could not publish a changes update");
        }
    }
}

impl<Sessions, Extractor, Repo, Blobs, Realtime> AgentChanges
    for AgentChangesService<Sessions, Extractor, Repo, Blobs, Realtime>
where
    Sessions: AgentSessionRepo,
    Extractor: ChangesetExtractor,
    Repo: ChangesetRepo,
    Blobs: ChangesetBlobStore,
    Realtime: AgentSessionRealtime + Send + Sync + 'static,
{
    async fn changes(
        &self,
        access: &EntityAccessReceipt<ViewAccessLevel>,
    ) -> Result<SessionChanges> {
        self.read_changes(access).await
    }

    async fn patch(&self, access: &EntityAccessReceipt<ViewAccessLevel>) -> Result<String> {
        self.read_patch(access).await
    }

    async fn request_capture(
        &self,
        access: &EntityAccessReceipt<EditAccessLevel>,
    ) -> Result<SessionChanges> {
        self.start_capture(access).await
    }
}

/// The session a receipt is for. Anything else is a wiring bug: every route
/// here resolves access against an agent session.
fn session_of<T: RequiredPermission>(access: &EntityAccessReceipt<T>) -> Result<AgentSessionId> {
    if access.entity().entity_type != EntityType::AgentSession {
        return Err(ChangesError::Forbidden);
    }
    let id = Uuid::parse_str(&access.entity().entity_id).map_err(|_| ChangesError::Forbidden)?;
    Ok(AgentSessionId::new_from_uuid(id))
}

/// Captures a session's changes each time one of its turns ends.
///
/// The observer runs on the session actor's task, so it only spawns; the
/// capture itself - a provider round trip and two writes - happens elsewhere.
pub struct CaptureOnTurnEnd<Service> {
    service: Service,
}

impl<Service> CaptureOnTurnEnd<Service> {
    /// Capture through `service` whenever a turn ends.
    pub fn new(service: Service) -> Self {
        Self { service }
    }
}

impl<Sessions, Extractor, Repo, Blobs, Realtime> SessionTurnObserver
    for CaptureOnTurnEnd<AgentChangesService<Sessions, Extractor, Repo, Blobs, Realtime>>
where
    Sessions: AgentSessionRepo,
    Extractor: ChangesetExtractor,
    Repo: ChangesetRepo,
    Blobs: ChangesetBlobStore,
    Realtime: AgentSessionRealtime + Send + Sync + 'static,
{
    fn signal(&self, id: AgentSessionId, signal: agent_fold::domain::model::TurnSignal) {
        if matches!(
            signal,
            agent_fold::domain::model::TurnSignal::TurnEnded { .. }
        ) {
            self.service.capture_in_background(id);
        }
    }

    fn session_stopped(&self, _id: AgentSessionId, _reason: StopReason) {}

    fn runtime_closed(&self, _id: AgentSessionId) {}
}