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
feat(agent-reviews): push review card updates through the session log (#9610)
Wolf Mermelstein24baafa7b055
diff --git a/apps/web/src/features/agent-reviews/queries/reviews.test.tsx b/apps/web/src/features/agent-reviews/queries/reviews.test.tsxnew file mode 100644index 0000000000..41c6b35241--- /dev/null+++ b/apps/web/src/features/agent-reviews/queries/reviews.test.tsx@@ -0,0 +1,154 @@+/** @vitest-environment jsdom */+import { agentReviewClient } from '@service-agent-harness/reviews';+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';+import { ok } from 'neverthrow';+import { createSignal, Suspense } from 'solid-js';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import type { Review } from '../core/review';+import { type ReviewUpdates, useReview, useReviewActions } from './reviews';++vi.mock('@service-agent-harness/reviews', () => ({+ agentReviewClient: { get: vi.fn(), decide: vi.fn() },+}));++function saved(revision: number, status: 'pending' | 'completed'): Review {+ return {+ id: 'review',+ sessionId: 'session',+ actingUser: 'macro|[email protected]',+ executionId: null,+ kind: 'email',+ title: 'Review',+ revision,+ updatedAt: revision,+ presentedAt: 1,+ decision: null,+ items: [+ {+ id: 'item',+ draft: { subject: 'Hello', body: '', to: [{ email: '[email protected]' }] },+ status,+ error: null,+ result: null,+ },+ ],+ };+}++const clients: QueryClient[] = [];+beforeEach(() => {+ vi.useFakeTimers({ shouldAdvanceTime: true });+});+afterEach(() => {+ cleanup();+ for (const client of clients.splice(0)) client.clear();+ vi.useRealTimers();+ vi.clearAllMocks();+});++function mount(updates: ReviewUpdates) {+ const client = new QueryClient();+ clients.push(client);+ let actions!: ReturnType<typeof useReviewActions>;+ function Card() {+ const query = useReview(+ () => 'session',+ () => 'review',+ () => updates+ );+ actions = useReviewActions(+ () => 'session',+ () => 'review'+ );+ return (+ <output>+ {query.data?.revision}:{query.data?.items[0].status}+ </output>+ );+ }+ render(() => (+ <QueryClientProvider client={client}>+ <Suspense fallback={<p>Loading</p>}>+ <Card />+ </Suspense>+ </QueryClientProvider>+ ));+ return () => actions;+}++describe('useReview', () => {+ it('fetches an announced revision and makes no requests between announcements', async () => {+ const [announced, setAnnounced] = createSignal<number>();+ vi.mocked(agentReviewClient.get).mockResolvedValue(ok(saved(1, 'pending')));+ mount({ kind: 'announced', revision: announced });+ await waitFor(() =>+ expect(screen.getByRole('status').textContent).toBe('1:pending')+ );++ await vi.advanceTimersByTimeAsync(10_000);+ expect(agentReviewClient.get).toHaveBeenCalledTimes(1);++ // Its own announcement is no news.+ setAnnounced(1);+ await vi.advanceTimersByTimeAsync(10_000);+ expect(agentReviewClient.get).toHaveBeenCalledTimes(1);++ vi.mocked(agentReviewClient.get).mockResolvedValue(+ ok(saved(2, 'completed'))+ );+ setAnnounced(2);+ await waitFor(() =>+ expect(screen.getByRole('status').textContent).toBe('2:completed')+ );+ expect(agentReviewClient.get).toHaveBeenCalledTimes(2);+ });++ it('leaves the revision its own save commits to that save', async () => {+ const [announced, setAnnounced] = createSignal<number>();+ vi.mocked(agentReviewClient.get).mockResolvedValue(ok(saved(1, 'pending')));+ const actions = mount({ kind: 'announced', revision: announced });+ await waitFor(() =>+ expect(screen.getByRole('status').textContent).toBe('1:pending')+ );+ const response =+ Promise.withResolvers<+ Awaited<ReturnType<typeof agentReviewClient.decide>>+ >();+ vi.mocked(agentReviewClient.decide).mockReturnValue(response.promise);++ const decided = actions().decide({+ action: 'submit',+ revision: 1,+ items: [],+ });+ // The save's announcement can arrive before its response.+ setAnnounced(2);+ await vi.advanceTimersByTimeAsync(10_000);+ response.resolve(ok(saved(2, 'completed')));+ await decided;++ expect(screen.getByRole('status').textContent).toBe('2:completed');+ expect(agentReviewClient.get).toHaveBeenCalledTimes(1);+ });++ it('polls a pending review where nothing announces its changes', async () => {+ vi.mocked(agentReviewClient.get).mockResolvedValue(ok(saved(1, 'pending')));+ mount({ kind: 'polled' });+ await waitFor(() =>+ expect(screen.getByRole('status').textContent).toBe('1:pending')+ );++ vi.mocked(agentReviewClient.get).mockResolvedValue(+ ok(saved(2, 'completed'))+ );+ await vi.advanceTimersByTimeAsync(2_000);+ await waitFor(() =>+ expect(screen.getByRole('status').textContent).toBe('2:completed')+ );++ // Nothing can change a finished review, so polling stops.+ await vi.advanceTimersByTimeAsync(10_000);+ expect(agentReviewClient.get).toHaveBeenCalledTimes(2);+ });+});diff --git a/apps/web/src/features/agent-reviews/queries/reviews.ts b/apps/web/src/features/agent-reviews/queries/reviews.tsindex 48c214dc48..ff8fb96bbd 100644--- a/apps/web/src/features/agent-reviews/queries/reviews.ts+++ b/apps/web/src/features/agent-reviews/queries/reviews.ts@@ -1,51 +1,117 @@+import { fireAndForget } from '@core/util/fireAndForget';import { throwOnErr } from '@core/util/result';import { agentReviewClient } from '@service-agent-harness/reviews';-import { queryOptions, useQuery, useQueryClient } from '@tanstack/solid-query';-import type { Accessor } from 'solid-js';+import {+ type Query,+ type QueryClient,+ queryOptions,+ useIsMutating,+ useMutation,+ useQuery,+ useQueryClient,+} from '@tanstack/solid-query';+import { type Accessor, createEffect } from 'solid-js';import type { Review, ReviewDecision } from '../core/review';import { reviewKeys } from './keys';-function options(session: string, review: string) {+/**+ * How an open card learns that its saved review changed. `PresentedReviewPart`+ * decides which applies.+ */+export type ReviewUpdates =+ /**+ * Inside its session's live view, the session log announces every saved+ * revision (`reviewRevisions` in the fold metadata); the card fetches only+ * a revision newer than the one it holds.+ */+ | { kind: 'announced'; revision: Accessor<number | undefined> }+ /**+ * Elsewhere (DM and channel activity snapshots) nothing announces changes,+ * so the card polls while the review can still change.+ */+ | { kind: 'polled' };++/** Poll while the record is unpresented or an item can still move. */+function pollWhileChanging(query: Query<Review>) {+ const record = query.state.data;+ if (!record) return false;+ const changing =+ record.presentedAt == null ||+ record.items.some(+ (item) => item.status === 'pending' || item.status === 'submitting'+ );+ return changing ? 2_000 : false;+}++function options(session: string, review: string, polled: boolean) {return queryOptions({queryKey: reviewKeys.detail(session, review).queryKey,queryFn: () => throwOnErr(() => agentReviewClient.get(session, review)),enabled: Boolean(review && session),retry: false,staleTime: 0,- refetchInterval: (query) =>- query.state.data &&- (query.state.data.presentedAt == null ||- query.state.data.items.some(- (item) => item.status === 'pending' || item.status === 'submitting'- ))- ? 2_000- : false,+ refetchInterval: polled ? pollWhileChanging : false,});}-/** ACP announces the review identity; polling only refreshes its saved status. */-export function useReview(session: Accessor<string>, review: Accessor<string>) {- return useQuery(() => options(session(), review()));++function decideOptions(client: QueryClient, session: string, review: string) {+ const key = reviewKeys.detail(session, review).queryKey;+ return {+ mutationKey: key,+ mutationFn: (decision: ReviewDecision) =>+ throwOnErr(() => agentReviewClient.decide(session, review, decision)),+ onSuccess: (record: Review) => {+ client.setQueryData(key, record);+ },+ };}++/** ACP announces the review identity; the card fetches its saved status. */+export function useReview(+ session: Accessor<string>,+ review: Accessor<string>,+ updates: Accessor<ReviewUpdates>+) {+ const query = useQuery(() =>+ options(session(), review(), updates().kind === 'polled')+ );+ // A decision's response carries the revision it committed, and its+ // announcement can arrive first; that revision is not someone else's.+ const deciding = useIsMutating(() => ({+ mutationKey: reviewKeys.detail(session(), review()).queryKey,+ }));+ createEffect(() => {+ const current = updates();+ if (current.kind !== 'announced') return;+ const announced = current.revision();+ const held = query.data?.revision;+ if (announced === undefined || held === undefined) return;+ if (announced <= held || deciding() > 0 || query.isFetching) return;+ fireAndForget(query.refetch(), 'agent-reviews');+ });+ return query;+}+export function useReviewActions(session: Accessor<string>,review: Accessor<string>) {const client = useQueryClient();- const save = (record: Review) => {- client.setQueryData(- reviewKeys.detail(session(), review()).queryKey,- record- );- return record;- };+ const decision = useMutation(() =>+ decideOptions(client, session(), review())+ );return {- decide: async (decision: ReviewDecision): Promise<Review> =>- save(- await throwOnErr(() =>- agentReviewClient.decide(session(), review(), decision)- )- ),- reload: async (): Promise<Review> =>- save(await throwOnErr(() => agentReviewClient.get(session(), review()))),+ decide: (next: ReviewDecision): Promise<Review> =>+ decision.mutateAsync(next),+ reload: async (): Promise<Review> => {+ const record = await throwOnErr(() =>+ agentReviewClient.get(session(), review())+ );+ client.setQueryData(+ reviewKeys.detail(session(), review()).queryKey,+ record+ );+ return record;+ },};}diff --git a/apps/web/src/features/agent-reviews/views/persisted-review.test.tsx b/apps/web/src/features/agent-reviews/views/persisted-review.test.tsxindex cb17b97873..09f5603156 100644--- a/apps/web/src/features/agent-reviews/views/persisted-review.test.tsx+++ b/apps/web/src/features/agent-reviews/views/persisted-review.test.tsx@@ -126,6 +126,7 @@ describe('PersistedReview', () => {sessionId="session"reviewId="review"canAct+ updates={{ kind: 'polled' }}onDecision={onDecision}/>));@@ -147,6 +148,7 @@ describe('PersistedReview', () => {sessionId="session"reviewId="review"canAct+ updates={{ kind: 'polled' }}onDecision={onDecision}/>));@@ -159,7 +161,12 @@ describe('PersistedReview', () => {const [record, setRecord] = createSignal<Review>(emailReview);reviews.record = record;render(() => (- <PersistedReview sessionId="session" reviewId="review" canAct />+ <PersistedReview+ sessionId="session"+ reviewId="review"+ canAct+ updates={{ kind: 'polled' }}+ />));expect(screen.getByRole('status').textContent).toBe('1:pending');diff --git a/apps/web/src/features/agent-reviews/views/persisted-review.tsx b/apps/web/src/features/agent-reviews/views/persisted-review.tsxindex 47d1a424c2..20122ae48f 100644--- a/apps/web/src/features/agent-reviews/views/persisted-review.tsx+++ b/apps/web/src/features/agent-reviews/views/persisted-review.tsx@@ -3,7 +3,11 @@ import { fireAndForget } from '@core/util/fireAndForget';import { createEffect, on, Show, Suspense } from 'solid-js';import { match } from 'ts-pattern';import { decisionWakesAgent, type Review } from '../core/review';-import { useReview, useReviewActions } from '../queries/reviews';+import {+ type ReviewUpdates,+ useReview,+ useReviewActions,+} from '../queries/reviews';import { ImportReview } from './import-review';import { ReviewStack } from './review-stack';@@ -12,6 +16,7 @@ export function PersistedReview(props: {sessionId: string;reviewId: string;canAct: boolean;+ updates: ReviewUpdates;eventId?: string;onDecision?: () => void;onDecisionFailed?: () => void;@@ -19,7 +24,8 @@ export function PersistedReview(props: {const userId = useUserId();const query = useReview(() => props.sessionId,- () => props.reviewId+ () => props.reviewId,+ () => props.updates);const actions = useReviewActions(() => props.sessionId,@@ -63,7 +69,7 @@ export function PersistedReview(props: {<Show when={query.isSuccess ? query.data : undefined}>{(record) => {const canAct = () => props.canAct && userId() === record().actingUser;- // A review's kind is fixed when it is saved; polls keep its status live.+ // A review's kind is fixed when it is saved; `updates` keeps its status live.return match(record().kind).with('import', () => (<Show when={importReview(record())}>diff --git a/apps/web/src/features/block-agent/browser-test/session.ts b/apps/web/src/features/block-agent/browser-test/session.tsindex 07dd293039..1b53eb53ad 100644--- a/apps/web/src/features/block-agent/browser-test/session.ts+++ b/apps/web/src/features/block-agent/browser-test/session.ts@@ -17,6 +17,7 @@ const [metadata, setMetadata] = createSignal<SessionMetadata>({pendingInteractions: [],turn: 'idle',notifications: [],+ reviewRevisions: [],noopTurn: null,});export const session = {diff --git a/apps/web/src/features/block-agent/state/session-notifications.test.ts b/apps/web/src/features/block-agent/state/session-notifications.test.tsindex c575c5b9e8..c0eea78938 100644--- a/apps/web/src/features/block-agent/state/session-notifications.test.ts+++ b/apps/web/src/features/block-agent/state/session-notifications.test.ts@@ -206,3 +206,42 @@ it('suppresses review events only when their trusted card is in the thread', ()};expect(timelineNotifications([externalCard], events)).toEqual(events);});++it('announces a subscribed review revision as a metadata change, not a message', () => {+ const stream = new wasm.FoldStream('019a0000-0000-7000-8000-000000000001');+ try {+ stream.push([{ kind: 'snapshot', rows: [] }]);+ const events = stream.push([+ {+ kind: 'confirmed',+ row: {+ id: '019a0000-0000-7000-8000-000000000002',+ createdAt: '2026-11-04T00:00:00Z',+ direction: 'to_server',+ content: {+ type: 'acp',+ jsonrpc: '2.0',+ method: '_macro/review_updated',+ params: {+ reviewId: '019a0000-0000-7000-8000-000000000005',+ revision: 3,+ },+ },+ },+ },+ ]);+ expect(events).toEqual([+ expect.objectContaining({+ kind: 'metadata',+ metadata: expect.objectContaining({+ reviewRevisions: [+ { reviewId: '019a0000-0000-7000-8000-000000000005', revision: 3 },+ ],+ }),+ }),+ ]);+ expect(stream.messages()).toEqual([]);+ } finally {+ stream.free();+ }+});diff --git a/apps/web/src/features/block-agent/views/PresentedReviewPart.tsx b/apps/web/src/features/block-agent/views/PresentedReviewPart.tsxindex b7e10f84a0..b12c9fb101 100644--- a/apps/web/src/features/block-agent/views/PresentedReviewPart.tsx+++ b/apps/web/src/features/block-agent/views/PresentedReviewPart.tsx@@ -1,5 +1,6 @@import { isSessionArchived } from '@service-agent-harness/session-archive';import { createEffect, createMemo, createSignal, Show } from 'solid-js';+import type { ReviewUpdates } from '../../agent-reviews/queries/reviews';import { PersistedReview } from '../../agent-reviews/views/persisted-review';import { useOptionalAgentSession } from '../context/AgentSessionContext';import { WorkingLine } from '../ui/WorkingLine';@@ -53,6 +54,21 @@ export function PresentedReviewPart(props: {)setPendingDecision(undefined);});+ // The one place a card chooses: inside its own session's view, the log+ // announces each saved revision; anywhere else (activity snapshots in DMs+ // and channels) it polls.+ const updates = (): ReviewUpdates =>+ session?.sessionId() === props.sessionId+ ? {+ kind: 'announced',+ revision: () =>+ session+ .metadata()+ ?.reviewRevisions.find(+ (announced) => announced.reviewId === props.reviewId+ )?.revision,+ }+ : { kind: 'polled' };const canAct = () =>Boolean(session?.sessionId() === props.sessionId &&@@ -66,6 +82,7 @@ export function PresentedReviewPart(props: {sessionId={props.sessionId}reviewId={props.reviewId}canAct={canAct()}+ updates={updates()}eventId={latestNotification()?.id}onDecision={() =>setPendingDecision({ previousEvent: latestNotification()?.id })diff --git a/apps/web/src/features/email-compose/browser-test/agent-review-fixture.tsx b/apps/web/src/features/email-compose/browser-test/agent-review-fixture.tsxindex 3c6da16bc3..8e06470bdc 100644--- a/apps/web/src/features/email-compose/browser-test/agent-review-fixture.tsx+++ b/apps/web/src/features/email-compose/browser-test/agent-review-fixture.tsx@@ -1,4 +1,5 @@import '@app/index.css';+import type { ReviewUpdates } from '@app/features/agent-reviews/queries/reviews';import { PersistedReview } from '@app/features/agent-reviews/views/persisted-review';import { AnalyticsContextProvider } from '@app/lib/analytics/analytics-context';import { PosthogProvider } from '@app/lib/analytics/posthog';@@ -18,10 +19,20 @@ import { createSignal } from 'solid-js';import { render } from 'solid-js/web';/**- * A saved agent email review, polled from the routed review API, beside the- * app's global Create hotkey. Typing that escapes the draft presses `c`.+ * A saved agent email review from the routed review API, beside the app's+ * global Create hotkey. Typing that escapes the draft presses `c`. The card+ * polls, or with `?updates=announced` hears each saved revision from a+ * `review-updated` window event, as the session log announces it.*/function Fixture() {+ const [announced, setAnnounced] = createSignal<number>();+ window.addEventListener('review-updated', (event) => {+ if (event instanceof CustomEvent) setAnnounced(Number(event.detail));+ });+ const updates: ReviewUpdates =+ new URLSearchParams(location.search).get('updates') === 'announced'+ ? { kind: 'announced', revision: announced }+ : { kind: 'polled' };useHotKeyRoot();attachGlobalDOMScope(document.body);const [created, setCreated] = createSignal(0);@@ -48,6 +59,7 @@ function Fixture() {sessionId="019a0000-0000-7000-8000-000000000001"reviewId="019a0000-0000-7000-8000-000000000005"canAct+ updates={updates}/><output data-testid="created">{created()}</output></main>diff --git a/apps/web/src/features/email-compose/browser-test/agent-review.app.e2e.ts b/apps/web/src/features/email-compose/browser-test/agent-review.app.e2e.tsindex b7fd0b93c6..95fedc7c86 100644--- a/apps/web/src/features/email-compose/browser-test/agent-review.app.e2e.ts+++ b/apps/web/src/features/email-compose/browser-test/agent-review.app.e2e.ts@@ -48,7 +48,7 @@ const initial: SavedReview = {};/**- * Serves the review the card polls every two seconds. `onSave` decides when+ * Serves the review the card reads, polled or announced. `onSave` decides when* an edit's response is released; the edit is committed when it arrives.*/async function serveReview(@@ -213,3 +213,53 @@ test('a review loaded before presentation becomes editable once presented', asynawait expect(body).toHaveText('Hello again');await expect(page.getByTestId('created')).toHaveText('0');});++test('an announced revision replaces the open card, and nothing else reads it', async ({+ page,+}) => {+ await page.clock.install();+ const server = await serveReview(page, initial);+ const reads: string[] = [];+ page.on('request', (request) => {+ if (request.method() === 'GET' && request.url().includes('/reviews/'))+ reads.push(request.url());+ });+ // The composer saves its normalized draft once it mounts.+ const mounted = page.waitForResponse(+ (response) =>+ response.request().method() === 'POST' &&+ response.url().includes('/reviews/')+ );+ await page.goto(+ '/src/features/email-compose/browser-test/agent-review.html?updates=announced'+ );+ await mounted;++ // The log announces the card's own save, then nothing for a while.+ await page.evaluate(() =>+ window.dispatchEvent(new CustomEvent('review-updated', { detail: 2 }))+ );+ await page.clock.runFor(10_000);+ expect(reads).toHaveLength(1);++ server.record = {+ ...server.record,+ revision: 3,+ items: server.record.items.map((item) => ({+ ...item,+ status: 'dismissed',+ })),+ };+ const read = page.waitForResponse(+ (response) =>+ response.request().method() === 'GET' &&+ response.url().includes('/reviews/')+ );+ await page.evaluate(() =>+ window.dispatchEvent(new CustomEvent('review-updated', { detail: 3 }))+ );+ await read;++ await expect(page.getByRole('status').getByText('Dismissed')).toBeVisible();+ expect(reads).toHaveLength(2);+});diff --git a/apps/web/src/lib/service-clients/service-agent-fold/generated/types.ts b/apps/web/src/lib/service-clients/service-agent-fold/generated/types.tsindex 0bb2b4e284..4581616a98 100644--- a/apps/web/src/lib/service-clients/service-agent-fold/generated/types.ts+++ b/apps/web/src/lib/service-clients/service-agent-fold/generated/types.ts@@ -2539,6 +2539,17 @@ export type ReviewSettlement_Serialize =/** The decided actions' confirmed results. */| ReviewOutcome_Serialize;+/**+ * A review's saved record moved to `revision`: presented, edited, decided,+ * or an item's action finished.+ */+export type ReviewUpdatedNotification = {+ /** The review that changed. */+ reviewId: string;+ /** Its saved revision after the change. */+ revision: number;+};+/** A run of a reply's parts that reads as one unit. */export type Segment = Segment_Serialize | Segment_Deserialize;@@ -2649,6 +2660,11 @@ export type SessionMetadata =export type SessionMetadata_Deserialize = {/** System events, projected independently of the conversation messages. */notifications: SessionNotification_Deserialize[];+ /**+ * The newest saved revision of each review the log announced, in the+ * order they were first announced.+ */+ reviewRevisions: ReviewUpdatedNotification[];/** The last notification turn whose entire answer was suppressed. */noopTurn: number | null;/** The agent that produced the log. See [`Harness`]. */@@ -2701,6 +2717,11 @@ export type SessionMetadata_Deserialize = {export type SessionMetadata_Serialize = {/** System events, projected independently of the conversation messages. */notifications: SessionNotification_Serialize[];+ /**+ * The newest saved revision of each review the log announced, in the+ * order they were first announced.+ */+ reviewRevisions: ReviewUpdatedNotification[];/** The last notification turn whose entire answer was suppressed. */noopTurn: number | null;/** The agent that produced the log. See [`Harness`]. */diff --git a/crates/agent_code_mode/AGENTS.md b/crates/agent_code_mode/AGENTS.mdindex 5baf76ea6f..ec7134a82a 100644--- a/crates/agent_code_mode/AGENTS.md+++ b/crates/agent_code_mode/AGENTS.md@@ -68,6 +68,9 @@ session presentation. Never replay an uncertain submitted action.Reviews write `review.decided` and `review.settled` through the injectedtransaction-aware notification writer in the same revision-checked transaction.+After every successful save, `ReviewActions::announce_update` logs a+`_macro/review_updated` frame (review id and revision, no draft content) in the+session, best effort, so open session views refetch instead of polling.Reviews persist the immutable acting account. Only that account may edit orsubmit.ACP presentation uses the session owner's transcript capability, independentlydiff --git a/crates/agent_code_mode/src/domain/reviews.rs b/crates/agent_code_mode/src/domain/reviews.rsindex 0827e8378e..4bd292ad34 100644--- a/crates/agent_code_mode/src/domain/reviews.rs+++ b/crates/agent_code_mode/src/domain/reviews.rs@@ -286,6 +286,10 @@ pub trait ReviewActions: Send + Sync + 'static {owner: &MacroUserIdStr<'static>,record: &ReviewRecord,) -> Result<(), CodeModeError>;+ /// Tell the session's viewers that `record` was saved at its current+ /// revision, so open cards fetch it instead of polling. Carries no draft+ /// content.+ async fn announce_update(&self, record: &ReviewRecord) -> Result<(), CodeModeError>;/// Stream a checked view as a completed `PresentView` call. Nothing is/// saved: the presented call is the view's only record.async fn present_view(@@ -521,7 +525,18 @@ impl ReviewService {.map_err(|error| CodeModeError::Storage(rootcause::report!(error).into()))}).transpose()?;- self.store.save(previous, record, pending.as_ref()).await+ self.store.save(previous, record, pending.as_ref()).await?;+ // Best effort: the save stands either way, and a card that misses+ // this revision fetches it with the next one or on reload.+ if let Err(error) = self.actions.announce_update(record).await {+ tracing::error!(+ error = ?error,+ review_id = %record.id.0,+ revision = record.revision,+ "could not announce a saved review"+ );+ }+ Ok(())}/// Claim the exact saved revision, then complete independently of the request./// Persisted submitting states become unknown after interrupted work.diff --git a/crates/agent_code_mode/src/domain/reviews/test.rs b/crates/agent_code_mode/src/domain/reviews/test.rsindex ca89111ee1..44ae00e97c 100644--- a/crates/agent_code_mode/src/domain/reviews/test.rs+++ b/crates/agent_code_mode/src/domain/reviews/test.rs@@ -123,6 +123,8 @@ struct Actions {calls: Mutex<Vec<String>>,actors: Mutex<Vec<String>>,presentations: Mutex<Vec<ReviewId>>,+ announcements: Mutex<Vec<(ReviewId, i64)>>,+ announced: tokio::sync::Notify,views: Mutex<Vec<(AgentSessionId, PresentedView)>>,fail_presentation: AtomicBool,block_actions: AtomicBool,@@ -203,6 +205,14 @@ impl ReviewActions for Actions {}Ok(())}+ async fn announce_update(&self, record: &ReviewRecord) -> Result<(), CodeModeError> {+ self.announcements+ .lock()+ .unwrap()+ .push((record.id, record.revision));+ self.announced.notify_waiters();+ Ok(())+ }async fn present_view(&self,owner: &MacroUserIdStr<'static>,@@ -236,6 +246,8 @@ impl Fixture {calls: Mutex::default(),actors: Mutex::default(),presentations: Mutex::default(),+ announcements: Mutex::default(),+ announced: tokio::sync::Notify::new(),views: Mutex::default(),fail_presentation: AtomicBool::new(false),block_actions: AtomicBool::new(false),@@ -381,6 +393,81 @@ async fn owner_receipt_execution_and_archive_are_enforced_before_creation() {assert!(f.store.0.lock().unwrap().is_empty());}#[tokio::test]+async fn every_saved_change_is_announced_with_its_revision_and_refused_ones_are_not() {+ let f = Fixture::new();+ let row = f+ .create(vec![+ json!({"subject":"x", "body":"Hello", "to":[{"email":"[email protected]"}]}),+ ])+ .await;+ let item = row.items.states()[0].id;+ let edited = f+ .service+ .decide(+ &f.edit(),+ &f.actions.owner,+ row.id,+ ReviewDecision::Edit {+ revision: row.revision,+ item,+ draft: Box::new(+ serde_json::from_value(json!({"kind":"email", "draft": {"subject":"edited", "body":"Hello", "to":[{"email":"[email protected]"}]}}))+ .unwrap(),+ ),+ },+ )+ .await+ .unwrap();+ assert!(matches!(+ f.service+ .decide(+ &f.edit(),+ &f.actions.owner,+ row.id,+ ReviewDecision::Dismiss {+ revision: row.revision,+ items: vec![],+ },+ )+ .await,+ Err(CodeModeError::Conflict)+ ));+ f.service+ .decide(+ &f.edit(),+ &f.actions.owner,+ row.id,+ ReviewDecision::Submit {+ revision: edited.revision,+ items: vec![],+ },+ )+ .await+ .unwrap();+ // The send's own save is announced after it lands.+ let announcements = tokio::time::timeout(std::time::Duration::from_secs(3), async {+ loop {+ let announced = f.actions.announced.notified();+ tokio::pin!(announced);+ announced.as_mut().enable();+ let announcements = f.actions.announcements.lock().unwrap().clone();+ if announcements.len() == 4 {+ return announcements;+ }+ announced.await;+ }+ })+ .await+ .expect("the send was announced");++ // Presented, edited, claimed for sending, and sent; the stale dismiss+ // saved nothing.+ assert_eq!(+ announcements,+ vec![(row.id, 1), (row.id, 2), (row.id, 3), (row.id, 4)]+ );+}+#[tokio::test]async fn double_submit_claims_before_work_and_never_repeats_an_action() {let f = Fixture::new();f.actions.block_actions.store(true, Ordering::SeqCst);diff --git a/crates/agent_runtime_protocol/src/domain/mod.rs b/crates/agent_runtime_protocol/src/domain/mod.rsindex afe06e1a77..f726f0fcdd 100644--- a/crates/agent_runtime_protocol/src/domain/mod.rs+++ b/crates/agent_runtime_protocol/src/domain/mod.rs@@ -12,6 +12,8 @@ pub mod connection;pub mod context;/// The physical transport port.pub mod ports;+/// The log frame a saved review leaves each time it changes.+pub mod review;/// Versioned protocol message types.pub mod schema;/// The log frame an MCP tool call held for the owner's approval leaves.diff --git a/crates/agent_runtime_protocol/src/domain/review.rs b/crates/agent_runtime_protocol/src/domain/review.rsnew file mode 100644index 0000000000..c7a108ab4a--- /dev/null+++ b/crates/agent_runtime_protocol/src/domain/review.rs@@ -0,0 +1,47 @@+//! The log frame a saved review leaves each time it changes.+//!+//! A review's record lives beside the session, not in its log, so viewers of+//! the session would otherwise have to poll it. Every save logs one of these:+//! an ACP extension notification (`_macro/...`) in the runtime's direction,+//! like the egress proxy's held tool calls, so every existing reader of the+//! log accepts it and ignores a method it does not know. It names the review+//! and its new revision and nothing else; readers fetch the record.++use agent_client_protocol::{JsonRpcMessage as _, JsonRpcNotification, RawJsonRpcMessage};+use macro_uuid::Uuid;+use serde::{Deserialize, Serialize};+use specta::Type;++use super::schema::v0::{AcpMessage, ToServerMessage};++#[cfg(test)]+mod test;++/// A review's saved record moved to `revision`: presented, edited, decided,+/// or an item's action finished.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonRpcNotification, Type)]+#[notification(method = "_macro/review_updated")]+#[serde(rename_all = "camelCase")]+pub struct ReviewUpdatedNotification {+ /// The review that changed.+ #[specta(type = String)]+ pub review_id: Uuid,+ /// Its saved revision after the change.+ #[specta(type = i32)]+ pub revision: i64,+}++impl ReviewUpdatedNotification {+ /// The frame to log.+ ///+ /// # Panics+ ///+ /// Never: the notification is plain data and always serializes.+ #[must_use]+ pub fn to_server_message(&self) -> ToServerMessage {+ let params = serde_json::to_value(self).expect("a review update serializes");+ let frame = RawJsonRpcMessage::notification(self.method().to_owned(), params)+ .expect("an object is valid notification params");+ ToServerMessage::Acp(AcpMessage(frame))+ }+}diff --git a/crates/agent_runtime_protocol/src/domain/review/test.rs b/crates/agent_runtime_protocol/src/domain/review/test.rsnew file mode 100644index 0000000000..c9b2110c46--- /dev/null+++ b/crates/agent_runtime_protocol/src/domain/review/test.rs@@ -0,0 +1,22 @@+use super::*;++#[test]+fn a_review_update_is_logged_as_a_macro_extension_notification_with_only_its_identity() {+ let update = ReviewUpdatedNotification {+ review_id: "0192f7a0-0000-7000-8000-000000000001".parse().unwrap(),+ revision: 3,+ };++ assert_eq!(+ serde_json::to_value(update.to_server_message()).unwrap(),+ serde_json::json!({+ "type": "acp",+ "jsonrpc": "2.0",+ "method": "_macro/review_updated",+ "params": {+ "reviewId": "0192f7a0-0000-7000-8000-000000000001",+ "revision": 3,+ },+ })+ );+}diff --git a/crates/agent_session/src/domain/service.rs b/crates/agent_session/src/domain/service.rsindex 6913b7b11d..ade0c9dfa7 100644--- a/crates/agent_session/src/domain/service.rs+++ b/crates/agent_session/src/domain/service.rs@@ -212,6 +212,17 @@ pub trait AgentSessionService: Send + Sync + 'static {message: ToServerMessage,) -> impl Future<Output = Result<()>> + Send;+ /// Append a frame nothing projects session state from - no turn,+ /// status, or model - and push it to the session's viewers, without the+ /// whole-log fold [`record_frame`](Self::record_frame) runs first. What a+ /// review writes on every save. Any replica may call this; the frame is+ /// ordered by when it is stored.+ fn record_unprojected_frame(+ &self,+ id: AgentSessionId,+ message: ToServerMessage,+ ) -> impl Future<Output = Result<()>> + Send;+/// Record who prompted the turn `id` is about to run, before it runs.fn set_turn_prompter(&self,@@ -1092,6 +1103,51 @@ where.unwrap_or(Err(AgentSessionError::LogTimedOut(id)))}+ #[tracing::instrument(+ name = "agent.session.record_unprojected_frame",+ err,+ skip(self, message),+ fields(agent.session.id = %id),+ )]+ async fn record_unprojected_frame(+ &self,+ id: AgentSessionId,+ message: ToServerMessage,+ ) -> Result<()> {+ tokio::time::timeout(SESSION_PERSIST_TIMEOUT, async {+ let stored = self+ .repo+ .create_projected(+ AgentSessionLog {+ agent_session_id: id,+ user_id: None,+ content: Message::ToServer(message),+ logged_at: None,+ },+ None,+ None,+ None,+ )+ .await?;+ // Best effort, as for every other frame: it is already durable,+ // so a viewer who misses it reads it on the next log fetch.+ if let Err(error) = self+ .realtime+ .publish(LogAppended {+ turn_state: None,+ agent_session_id: id,+ entries: vec![stored],+ })+ .await+ {+ tracing::error!(error = ?error, %id, "failed to stream an agent session frame");+ }+ Ok(())+ })+ .await+ .unwrap_or(Err(AgentSessionError::LogTimedOut(id)))+ }+async fn attach_session<Connector>(&self,id: AgentSessionId,diff --git a/crates/agent_session/src/domain/service/test.rs b/crates/agent_session/src/domain/service/test.rsindex d2fa44185a..c541615ca5 100644--- a/crates/agent_session/src/domain/service/test.rs+++ b/crates/agent_session/src/domain/service/test.rs@@ -1678,6 +1678,64 @@ async fn a_recorded_frame_is_stored_and_published_at_once() {);}+/// A review's change announcement is stored and reaches viewers at once,+/// and projects nothing: viewers are not told to refetch the session.+#[tokio::test]+async fn an_unprojected_frame_is_stored_and_published_without_a_session_update() {+ let repo = InMemoryAgentSessionRepo::new();+ let session = test_session();+ repo.insert_session(test_agent_session(session));+ for entry in parse_log_as(+ session,+ r#"{"direction":"to_runtime","content":{"type":"acp","jsonrpc":"2.0","id":1,"method":"session/prompt","params":{"sessionId":"s","prompt":[{"type":"text","text":"Draft the email"}]}}}"#,+ ) {+ AgentSessionLogRepo::create(&repo, entry)+ .await+ .expect("the prompt is stored");+ }+ let realtime = RecordingRealtime::new();+ let service = AgentSessionServiceImpl::new(+ repo.clone(),+ FoldedMessageService::new(repo.clone()),+ realtime.clone(),+ NoOpAgentSessionNameGenerator,+ Arc::new(NoOpTurnObserver),+ Arc::new(NoopLifecyclePublisher),+ ReplicaId::mint(),+ );+ let update = agent_runtime_protocol::domain::review::ReviewUpdatedNotification {+ review_id: Uuid::from_u128(0xA),+ revision: 4,+ };++ service+ .record_unprojected_frame(session, update.to_server_message())+ .await+ .expect("the frame is recorded");++ let stored = AgentSessionLogRepo::list_by_session(&repo, session)+ .await+ .expect("stored log can be read");+ assert_eq!(stored.len(), 2);+ let published = realtime.published();+ assert_eq!(published.len(), 1);+ assert_eq!(published[0].entries.len(), 1);+ assert_eq!(published[0].entries[0].id, stored[1].id);+ assert_eq!(+ serde_json::to_value(&published[0].entries[0].entry.content).unwrap(),+ serde_json::json!({+ "direction": "to_server",+ "content": {+ "type": "acp",+ "jsonrpc": "2.0",+ "method": "_macro/review_updated",+ "params": {"reviewId": "00000000-0000-0000-0000-00000000000a", "revision": 4},+ },+ })+ );+ assert!(realtime.updated().is_empty());+}+#[tokio::test(start_paused = true)]async fn marking_disconnected_is_bounded_when_persistence_hangs() {let repo = InMemoryAgentSessionRepo::new();diff --git a/crates/folds/agent_fold/AGENTS.md b/crates/folds/agent_fold/AGENTS.mdindex a8fb32c764..b68b4b2c35 100644--- a/crates/folds/agent_fold/AGENTS.md+++ b/crates/folds/agent_fold/AGENTS.md@@ -67,6 +67,9 @@ to the browser via `inbound/wasm`.signals and harness recovery from a persisted log. Keep these interpretationsaligned; recovery must never guess the answer from another turn.+`_macro/review_updated` frames project each review's newest saved revision+into `SessionMetadata.reviewRevisions`; they never touch messages or the turn.+Notification log frames open system turns without user messages. Their eventsproject into `SessionMetadata.notifications`, separate from message search andexports. `SessionNotification` flattens the protocol’s tagged event enum intodiff --git a/crates/folds/agent_fold/src/domain/fold.rs b/crates/folds/agent_fold/src/domain/fold.rsindex 853365e71c..29ef61042f 100644--- a/crates/folds/agent_fold/src/domain/fold.rs+++ b/crates/folds/agent_fold/src/domain/fold.rs@@ -77,6 +77,8 @@ mod permission;mod plan;/// Transactional generic ACP history replacement.mod replay;+/// Saved reviews announcing their new revisions.+mod review;/// The fold's state and the per-frame dispatch.mod state;/// Delegated agents and the calls nested under them.diff --git a/crates/folds/agent_fold/src/domain/fold/review.rs b/crates/folds/agent_fold/src/domain/fold/review.rsnew file mode 100644index 0000000000..5a3dc3502d--- /dev/null+++ b/crates/folds/agent_fold/src/domain/fold/review.rs@@ -0,0 +1,35 @@+//! Saved reviews announcing their new revisions.+//!+//! A review's record lives outside the log; each save logs only its id and+//! revision, so a reader knows when to fetch the record again.++use agent_client_protocol::RawJsonRpcParams;+use agent_runtime_protocol::domain::review::ReviewUpdatedNotification;++use super::convert::deserialize_params;+use super::state::FoldState;++impl FoldState {+ /// Record a review's newer revision. Whether the metadata moved: a save+ /// that committed first can be logged after a later one.+ pub(super) fn record_review_update(&mut self, params: Option<&RawJsonRpcParams>) -> bool {+ let Some(update) = deserialize_params::<ReviewUpdatedNotification>(params) else {+ return false;+ };+ let revisions = &mut self.metadata.review_revisions;+ match revisions+ .iter_mut()+ .find(|known| known.review_id == update.review_id)+ {+ Some(known) if known.revision >= update.revision => false,+ Some(known) => {+ known.revision = update.revision;+ true+ }+ None => {+ revisions.push(update);+ true+ }+ }+ }+}diff --git a/crates/folds/agent_fold/src/domain/fold/state.rs b/crates/folds/agent_fold/src/domain/fold/state.rsindex 8a0e1b22e8..ed6e49eaa8 100644--- a/crates/folds/agent_fold/src/domain/fold/state.rs+++ b/crates/folds/agent_fold/src/domain/fold/state.rs@@ -17,6 +17,7 @@ use agent_client_protocol::schema::v1::{use agent_client_protocol::{JsonRpcMessage, RawJsonRpcMessage, RawJsonRpcParams};use agent_runtime_protocol::domain::action::AgentAction;use agent_runtime_protocol::domain::context::ContextSummaryNotification;+use agent_runtime_protocol::domain::review::ReviewUpdatedNotification;use agent_runtime_protocol::domain::schema::v0::{SystemEvent, ToRuntimeMessage, ToServerMessage};use agent_runtime_protocol::domain::tool_approval::TOOL_APPROVAL_METHOD;use serde::Deserialize;@@ -374,6 +375,12 @@ impl FoldState {Self::message_and_metadata(message, metadata)})}+ // A saved review moved to a new revision.+ RawJsonRpcMessage::Notification(notification)+ if ReviewUpdatedNotification::matches_method(¬ification.method) =>+ {+ StepChange::metadata(self.record_review_update(notification.params.as_ref()))+ }// The agent reporting that a URL interaction finished.RawJsonRpcMessage::Notification(notification)if CompleteElicitationNotification::matches_method(¬ification.method) =>diff --git a/crates/folds/agent_fold/src/domain/model/metadata.rs b/crates/folds/agent_fold/src/domain/model/metadata.rsindex 84bf13cacf..052eac026a 100644--- a/crates/folds/agent_fold/src/domain/model/metadata.rs+++ b/crates/folds/agent_fold/src/domain/model/metadata.rs@@ -1,5 +1,6 @@//! Session-level state derived from the log.+use agent_runtime_protocol::domain::review::ReviewUpdatedNotification;use serde::{Deserialize, Serialize};use specta::Type;@@ -51,6 +52,9 @@ pub enum Harness {pub struct SessionMetadata {/// System events, projected independently of the conversation messages.pub notifications: Vec<SessionNotification>,+ /// The newest saved revision of each review the log announced, in the+ /// order they were first announced.+ pub review_revisions: Vec<ReviewUpdatedNotification>,/// The last notification turn whose entire answer was suppressed.pub noop_turn: Option<u32>,/// The agent that produced the log. See [`Harness`].diff --git a/crates/folds/agent_fold/src/domain/test.rs b/crates/folds/agent_fold/src/domain/test.rsindex 73f0d0df2b..5354a45921 100644--- a/crates/folds/agent_fold/src/domain/test.rs+++ b/crates/folds/agent_fold/src/domain/test.rs@@ -17,6 +17,7 @@ mod tool_name;mod util;mod replay;+mod review_updates;mod notifications;diff --git a/crates/folds/agent_fold/src/domain/test/review_updates.rs b/crates/folds/agent_fold/src/domain/test/review_updates.rsnew file mode 100644index 0000000000..66026946ff--- /dev/null+++ b/crates/folds/agent_fold/src/domain/test/review_updates.rs@@ -0,0 +1,55 @@+//! Saved reviews announcing their new revisions through the log.+use super::util::parse_log;+use crate::domain::lifecycle::LifecycleFold;+use crate::domain::model::{FoldEvent, TurnState};+use agent_runtime_protocol::domain::review::ReviewUpdatedNotification;++#[test]+fn review_updates_project_each_reviews_newest_revision_without_touching_the_turn() {+ let log = parse_log(+ r#"+{"direction":"to_runtime","content":{"type":"acp","jsonrpc":"2.0","id":1,"method":"session/prompt","params":{"sessionId":"s","prompt":[{"type":"text","text":"Draft the email"}]}}}+{"direction":"to_server","content":{"type":"acp","jsonrpc":"2.0","method":"session/update","params":{"sessionId":"s","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Drafted."}}}}}+{"direction":"to_server","content":{"type":"acp","jsonrpc":"2.0","method":"_macro/review_updated","params":{"reviewId":"0192f7a0-0000-7000-8000-00000000000a","revision":2}}}+{"direction":"to_server","content":{"type":"acp","jsonrpc":"2.0","method":"_macro/review_updated","params":{"reviewId":"0192f7a0-0000-7000-8000-00000000000a","revision":1}}}+{"direction":"to_server","content":{"type":"acp","jsonrpc":"2.0","method":"_macro/review_updated","params":{"reviewId":"0192f7a0-0000-7000-8000-00000000000b","revision":1}}}+"#,+ );+ let mut machine = LifecycleFold::new();+ let _ = machine.push(log[0].clone());+ let _ = machine.push(log[1].clone());++ let newer = machine.push(log[2].clone());+ assert!(matches!(+ newer.events.as_slice(),+ [FoldEvent::MetadataUpdated(_)]+ ));+ assert_eq!(+ machine.inner().metadata().review_revisions,+ vec![ReviewUpdatedNotification {+ review_id: "0192f7a0-0000-7000-8000-00000000000a".parse().unwrap(),+ revision: 2,+ }]+ );++ // A save that committed first can be logged second; it is not news.+ let older = machine.push(log[3].clone());+ assert!(older.events.is_empty());++ let _ = machine.push(log[4].clone());+ assert_eq!(+ machine.inner().metadata().review_revisions,+ vec![+ ReviewUpdatedNotification {+ review_id: "0192f7a0-0000-7000-8000-00000000000a".parse().unwrap(),+ revision: 2,+ },+ ReviewUpdatedNotification {+ review_id: "0192f7a0-0000-7000-8000-00000000000b".parse().unwrap(),+ revision: 1,+ },+ ]+ );+ assert_eq!(machine.inner().metadata().turn, TurnState::Running);+ assert_eq!(machine.inner().messages().len(), 2);+}diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@command_invocation.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@command_invocation.jsonl.snapindex 3afddec1f0..873623c1e9 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@command_invocation.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@command_invocation.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/command_invocation.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@elicitation_claude_single_select.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@elicitation_claude_single_select.jsonl.snapindex 8ec2205282..e3de1bcce9 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@elicitation_claude_single_select.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@elicitation_claude_single_select.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/elicitation_claude_single_sele---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@long_multi_resume.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@long_multi_resume.jsonl.snapindex e537cf833e..9146a7d2a3 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@long_multi_resume.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@long_multi_resume.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/long_multi_resume.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@plan_todo.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@plan_todo.jsonl.snapindex 8bde3580ce..39ebda34e9 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@plan_todo.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@plan_todo.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/plan_todo.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_multi_turn.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_multi_turn.jsonl.snapindex 0ae4a61ef6..68f8f9d59b 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_multi_turn.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_multi_turn.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/real_multi_turn.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_single_turn.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_single_turn.jsonl.snapindex 04a69b0c17..d901d48a50 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_single_turn.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@real_single_turn.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/real_single_turn.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_and_continued.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_and_continued.jsonl.snapindex 04634ac3f9..88041d013f 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_and_continued.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_and_continued.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/resumed_and_continued.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_no_prompt.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_no_prompt.jsonl.snapindex d3a93d6fa9..3a9f70d1c5 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_no_prompt.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@resumed_no_prompt.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/resumed_no_prompt.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_claude_code.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_claude_code.jsonl.snapindex 6de5e1a725..0e5b761aed 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_claude_code.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_claude_code.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/subagent_claude_code.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: ClaudeCode,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_cursor.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_cursor.jsonl.snapindex d1322134b5..0f3e30422d 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_cursor.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_cursor.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/subagent_cursor.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: Cursor,model: Some(diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_macro_inmem.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_macro_inmem.jsonl.snapindex c7b844233e..ef2724e17f 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_macro_inmem.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_macro_inmem.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/subagent_macro_inmem.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: Macro,model: None,diff --git a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_opencode.jsonl.snap b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_opencode.jsonl.snapindex 2efadc88ec..9b6f84549f 100644--- a/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_opencode.jsonl.snap+++ b/crates/folds/agent_fold/src/domain/test/snapshots/agent_fold__domain__test__real_recordings__real_fixtures_derive_their_pinned_metadata@subagent_opencode.jsonl.snap@@ -5,6 +5,7 @@ input_file: crates/folds/agent_fold/fixtures/real/subagent_opencode.jsonl---SessionMetadata {notifications: [],+ review_revisions: [],noop_turn: None,harness: OpenCode,model: Some(diff --git a/docs/agent-guide/ai-chat.md b/docs/agent-guide/ai-chat.mdindex ed8656f85d..31bc74eab7 100644--- a/docs/agent-guide/ai-chat.md+++ b/docs/agent-guide/ai-chat.md@@ -2408,9 +2408,13 @@ draft before starting any sends/creates, and waits for attachments stilluploading in the active email.Invalid drafts remain editable; navigation opens the first draft needing attention.-The card polls its saved review while it is preparing or has pending drafts, so-statuses set by the agent or another editor appear in place. A poll that returns-the card's own in-flight save is not a conflict and leaves the editor focused.+Each saved change to a review (presentation, edits, decisions, finished sends)+logs a `_macro/review_updated` frame in its session, so in the session view the+card refetches only when a newer revision is announced and statuses set by the+agent or another editor appear in place. Cards shown outside the session view+(DM and channel activity) still poll while the review is preparing or has+pending drafts. A fetch that returns the card's own in-flight save is not a+conflict and leaves the editor focused.A revision conflict or uncertain request shows **Reload saved review**. Reloadreads the saved version and discards the local edit; it never retries an externalsend automatically. If the outcome is unknown, check the inbox/calendar before@@ -2434,8 +2438,8 @@ navigation and page reload,that a single draft has no stack controls, that a batch's picker finds drafts,that chat remains usable, and that another account cannot submit. Sending an email orcreating an event is a real action, including from a local app connected to dev.-The backend-free browser regression for polling, presentation, and typing during-a save is `bunx playwright test --config src/features/email-compose/browser-test/playwright.app.config.ts agent-review`+The backend-free browser regression for polling, announced revisions,+presentation, and typing during a save is `bunx playwright test --config src/features/email-compose/browser-test/playwright.app.config.ts agent-review`(from `apps/web`).## Agent reasoning effortdiff --git a/packages/sdk/generated/agent-fold/index.ts b/packages/sdk/generated/agent-fold/index.tsindex 2c58a30a0b..4c344c2f7a 100644--- a/packages/sdk/generated/agent-fold/index.ts+++ b/packages/sdk/generated/agent-fold/index.ts@@ -1834,6 +1834,17 @@ import: ImportSettlement_Serialize } |/** The decided actions' confirmed results. */ReviewOutcome_Serialize;+/**+ * A review's saved record moved to `revision`: presented, edited, decided,+ * or an item's action finished.+ */+export type ReviewUpdatedNotification = {+ /** The review that changed. */+ reviewId: string,+ /** Its saved revision after the change. */+ revision: number,+};+/** A run of a reply's parts that reads as one unit. */export type Segment = Segment_Serialize | Segment_Deserialize;@@ -1938,6 +1949,11 @@ export type SessionMetadata = SessionMetadata_Serialize | SessionMetadata_Deseriexport type SessionMetadata_Deserialize = {/** System events, projected independently of the conversation messages. */notifications: SessionNotification_Deserialize[],+ /**+ * The newest saved revision of each review the log announced, in the+ * order they were first announced.+ */+ reviewRevisions: ReviewUpdatedNotification[],/** The last notification turn whose entire answer was suppressed. */noopTurn: number | null,/** The agent that produced the log. See [`Harness`]. */@@ -1990,6 +2006,11 @@ export type SessionMetadata_Deserialize = {export type SessionMetadata_Serialize = {/** System events, projected independently of the conversation messages. */notifications: SessionNotification_Serialize[],+ /**+ * The newest saved revision of each review the log announced, in the+ * order they were first announced.+ */+ reviewRevisions: ReviewUpdatedNotification[],/** The last notification turn whose entire answer was suppressed. */noopTurn: number | null,/** The agent that produced the log. See [`Harness`]. */diff --git a/services/agent_harness_service/src/code_mode/reviews.rs b/services/agent_harness_service/src/code_mode/reviews.rsindex 04a097b259..ba7e418d80 100644--- a/services/agent_harness_service/src/code_mode/reviews.rs+++ b/services/agent_harness_service/src/code_mode/reviews.rs@@ -1,8 +1,10 @@//! Compose persistent reviews with existing tool actions and the session queue.use agent_code_mode::domain::{CodeModeError, reviews::*};+use agent_runtime_protocol::domain::review::ReviewUpdatedNotification;use agent_session::domain::{model::AgentSessionId,ports::{AgentSessionNotificationRecipient, AgentSessionRepo},+ service::AgentSessionService,};use ai_toolset::RequestContext;use async_trait::async_trait;@@ -27,14 +29,21 @@ fn import_source(}}-pub struct Actions<S, H> {+pub struct Actions<S, L, H> {pub sessions: S,+ /// Where each save is announced to the session's viewers.+ pub log: L,pub harness: Arc<H>,pub context: ai_tools::ToolServiceContext,pub tools: Arc<ai_tools::AiToolSet>,}#[async_trait]-impl<S: AgentSessionRepo, H: AgentSessionNotificationRecipient> ReviewActions for Actions<S, H> {+impl<S, L, H> ReviewActions for Actions<S, L, H>+where+ S: AgentSessionRepo,+ L: AgentSessionService + Send + Sync + 'static,+ H: AgentSessionNotificationRecipient,+{async fn session(&self, session: AgentSessionId) -> Result<ReviewSession, CodeModeError> {let row = self.sessions@@ -138,6 +147,16 @@ impl<S: AgentSessionRepo, H: AgentSessionNotificationRecipient> ReviewActions fo},).await.map_err(|_| CodeModeError::Invalid(format!("Review {} was saved, but presentation is pending. Read this review to retry presentation without creating another draft.", record.id.0)))}+ async fn announce_update(&self, record: &ReviewRecord) -> Result<(), CodeModeError> {+ let update = ReviewUpdatedNotification {+ review_id: record.id.0,+ revision: record.revision,+ };+ self.log+ .record_unprojected_frame(record.session_id, update.to_server_message())+ .await+ .map_err(|error| CodeModeError::Storage(rootcause::report!(error).into()))+ }async fn present_view(&self,owner: &MacroUserIdStr<'static>,@@ -167,7 +186,7 @@ impl<S: AgentSessionRepo, H: AgentSessionNotificationRecipient> ReviewActions fo}}-impl<S, H> Actions<S, H> {+impl<S, L, H> Actions<S, L, H> {fn import_service(&self) -> Result<&ai_tools::ToolImportService, CodeModeError> {self.context.import_tool_contextdiff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rsindex 27f6dda198..a4969991ea 100644--- a/services/agent_harness_service/src/main.rs+++ b/services/agent_harness_service/src/main.rs@@ -1268,6 +1268,8 @@ async fn run() -> anyhow::Result<()> {// to speak through: it is the same service instance the harness routes// commands with, and a clone shares its replica identity.let draining_sessions = sessions.clone();+ // Reviews announce each save in their session's log.+ let review_log = sessions.clone();let conversation_turns = Arc::new(agent_harness::outbound::conversation_turns::PgConversationTurnStore::new(pool.clone()),);@@ -1341,6 +1343,7 @@ async fn run() -> anyhow::Result<()> {)),Arc::new(code_mode::reviews::Actions {sessions: session_repo.clone(),+ log: review_log,harness: harness.clone(),context: tool_context.clone(),tools: ai_tools::code_mode_tools(),