Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! 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) {}
}