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.

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.tsx
new file mode 100644
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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', asyn
await 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.ts
index 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.md
index 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 injected
transaction-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 or
submit.
ACP presentation uses the session owner's transcript capability, independently
diff --git a/crates/agent_code_mode/src/domain/reviews.rs b/crates/agent_code_mode/src/domain/reviews.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.md
index 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 interpretations
aligned; 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 events
project into `SessionMetadata.notifications`, separate from message search and
exports. `SessionNotification` flattens the protocol’s tagged event enum into
diff --git a/crates/folds/agent_fold/src/domain/fold.rs b/crates/folds/agent_fold/src/domain/fold.rs
index 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.rs
new file mode 100644
index 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.rs
index 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(&notification.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(&notification.method) =>
diff --git a/crates/folds/agent_fold/src/domain/model/metadata.rs b/crates/folds/agent_fold/src/domain/model/metadata.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.snap
index 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.md
index 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 still
uploading 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**. Reload
reads the saved version and discards the local edit; it never retries an external
send 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 or
creating 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 effort
diff --git a/packages/sdk/generated/agent-fold/index.ts b/packages/sdk/generated/agent-fold/index.ts
index 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_Deseri
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`]. */
@@ -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.rs
index 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_context
diff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rs
index 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(),