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-session): stream log rows over a GraphQL subscription (#7531)
Wolf Mermelstein033aa9ae2007
diff --git a/.github/kafka-cluster-topics.json b/.github/kafka-cluster-topics.jsonindex 62c646e88a..da7a002610 100644--- a/.github/kafka-cluster-topics.json+++ b/.github/kafka-cluster-topics.json@@ -1,6 +1,7 @@["macro.activity","macro.agent_session_lifecycle",+ "macro.agent_session_log","macro.agent_sessions","macro.bots","macro.calendar",diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.jsonindex f0148c3e1f..db7e210023 100644--- a/.github/workspace-dep-closures.json+++ b/.github/workspace-dep-closures.json@@ -882,6 +882,105 @@"crates/unfurl","crates/workspace-hack"],+ "agent_session_realtime": [+ "crates/activity",+ "crates/agent",+ "crates/agent_runtime_protocol",+ "crates/agent_session",+ "crates/agent_session_realtime",+ "crates/ai_billing",+ "crates/ai_toolset",+ "crates/ai_usage",+ "crates/analytics_client",+ "crates/attachment",+ "crates/authentication_service_client",+ "crates/bot_id",+ "crates/bot_token",+ "crates/bots",+ "crates/broadcast",+ "crates/calendar_events",+ "crates/call",+ "crates/channel_sender",+ "crates/channels",+ "crates/connection",+ "crates/connection_gateway_client",+ "crates/connection_gateway_models",+ "crates/contacts",+ "crates/cowlike",+ "crates/crm",+ "crates/database_env_vars",+ "crates/document_sub_type",+ "crates/email",+ "crates/email_utils",+ "crates/entity_access",+ "crates/entity_access_db_utils",+ "crates/entity_access_management",+ "crates/entity_mutation",+ "crates/entity_registry/entity_registry",+ "crates/entity_registry/entity_registry_db_utils",+ "crates/entity_registry/shared_entity_registry",+ "crates/filter_ast",+ "crates/folds/agent_fold",+ "crates/frecency",+ "crates/genai_telemetry",+ "crates/generic_email_domains",+ "crates/google_token",+ "crates/harness_id",+ "crates/harness_token",+ "crates/initiative",+ "crates/invite_email",+ "crates/ip_extractor",+ "crates/item_filters",+ "crates/kafka_util",+ "crates/last_online_tracker",+ "crates/lexical_client",+ "crates/macro_auth",+ "crates/macro_authorization",+ "crates/macro_aws_config",+ "crates/macro_entrypoint",+ "crates/macro_env",+ "crates/macro_env_var",+ "crates/macro_event_broker",+ "crates/macro_event_topics",+ "crates/macro_service_urls",+ "crates/macro_tower_layers",+ "crates/macro_user_id",+ "crates/macro_uuid",+ "crates/mention_utils",+ "crates/messages",+ "crates/model",+ "crates/model-entity",+ "crates/model-error-response",+ "crates/model_file_type",+ "crates/model_notifications",+ "crates/model_owner",+ "crates/model_user",+ "crates/models_ai_projection",+ "crates/models_bulk_upload",+ "crates/models_email",+ "crates/models_entity_access_management",+ "crates/models_pagination",+ "crates/models_permissions",+ "crates/models_properties",+ "crates/models_sfs",+ "crates/non_empty",+ "crates/notification",+ "crates/notification_state",+ "crates/prompt",+ "crates/properties",+ "crates/rate_limit",+ "crates/remote_env_var",+ "crates/roles_and_permissions",+ "crates/s3_key",+ "crates/share_permission_db_utils",+ "crates/sqs_client",+ "crates/sqs_worker",+ "crates/static_file_service_client",+ "crates/system_properties",+ "crates/teams",+ "crates/unfurl",+ "crates/workspace-hack"+ ],"agent_trigger": ["crates/activity","crates/agent",@@ -3262,6 +3361,7 @@"crates/agent_changes","crates/agent_runtime_protocol","crates/agent_session",+ "crates/agent_session_realtime","crates/ai_billing","crates/ai_toolset","crates/ai_usage",@@ -4416,6 +4516,7 @@"crates/agent_changes","crates/agent_runtime_protocol","crates/agent_session",+ "crates/agent_session_realtime","crates/agent_trigger","crates/ai_billing","crates/ai_tools",diff --git a/Cargo.lock b/Cargo.lockindex 8165d853fa..d53ff495cd 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -660,6 +660,26 @@ dependencies = ["workspace-hack",]+[[package]]+name = "agent_session_realtime"+version = "0.1.0"+dependencies = [+ "agent_runtime_protocol",+ "agent_session",+ "broadcast",+ "chrono",+ "kafka_util",+ "macro_event_broker",+ "macro_uuid",+ "rdkafka",+ "rootcause",+ "serde_json",+ "tokio",+ "tokio-retry",+ "tracing",+ "workspace-hack",+]+[[package]]name = "agent_trigger"version = "0.1.0"@@ -4393,10 +4413,13 @@ name = "complete_graph"version = "0.1.0"dependencies = ["activity",+ "agent_runtime_protocol","agent_session",+ "agent_session_realtime","anyhow","apollo-compiler","async-graphql",+ "async-stream","axum","bots","chrono",@@ -6119,6 +6142,7 @@ dependencies = ["activity","agent_changes","agent_session",+ "agent_session_realtime","ai_billing","ai_tools","ai_usage",diff --git a/Cargo.toml b/Cargo.tomlindex e5f24f95cf..f12ec30c30 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -8,7 +8,7 @@ members = ["crates/agent_harness","crates/agent_preview","crates/agent_inmem",- "crates/agent_runtime_protocol", "crates/agent_session",+ "crates/agent_runtime_protocol", "crates/agent_session", "crates/agent_session_realtime","crates/agent_trigger","crates/ai_billing","crates/ai_projections",diff --git a/apps/web/src/features/block-agent/context/create-agent-session.test.tsx b/apps/web/src/features/block-agent/context/create-agent-session.test.tsxindex be8d21d87f..3a49392b23 100644--- a/apps/web/src/features/block-agent/context/create-agent-session.test.tsx+++ b/apps/web/src/features/block-agent/context/create-agent-session.test.tsx@@ -38,7 +38,7 @@ vi.mock('@queries/agent-session/log', () => ({fetched: logSource.fetched(),stop: () => {},}),- appendAgentSessionLogRows: vi.fn(async () => undefined),+ canFollowAgentSessionLog: () => false,forgetAgentSessionLog: vi.fn(async () => undefined),}));vi.mock('@queries/agent-session/session-metadata-sync', () => ({diff --git a/apps/web/src/lib/core/agent-session/AgentSession.test.ts b/apps/web/src/lib/core/agent-session/AgentSession.test.tsindex e9e44d0a46..fdde1bac15 100644--- a/apps/web/src/lib/core/agent-session/AgentSession.test.ts+++ b/apps/web/src/lib/core/agent-session/AgentSession.test.ts@@ -29,21 +29,43 @@ const logSource = vi.hoisted(() => {super(`agent session log is ${reason}: ${sessionId}`);}}+ type Follow = {+ rows: (rows: AgentSessionLogEntryDto[]) => void;+ gap: () => void;+ };const source = {Unavailable,cached: vi.fn(),fetched: vi.fn(),- append: vi.fn(),forget: vi.fn(),watch: vi.fn(),+ stop: vi.fn(),+ /** Whether the client can follow the log over GraphQL. */+ following: false,+ /** The follow the latest watch was opened with, when following. */+ follow: undefined as Follow | undefined,};- source.watch.mockImplementation(() => ({- cached: source.cached(),- fetched: source.fetched(),- stop: () => {},- }));+ source.watch.mockImplementation(+ (_id: string, _policy?: string, follow?: Follow) => {+ source.follow = follow;+ return {+ cached: source.cached(),+ fetched: source.fetched(),+ stop: source.stop,+ };+ }+ );return source;});+const soupSocket = vi.hoisted(() => ({+ listeners: new Set<() => void>(),+}));+vi.mock('@service-storage/graphql-soup', () => ({+ subscribeGraphqlSoupReconnected: (listener: () => void) => {+ soupSocket.listeners.add(listener);+ return () => soupSocket.listeners.delete(listener);+ },+}));const socket = vi.hoisted(() => ({listeners: new Set<() => void>(),subscribeSocketSessionStarted: vi.fn((listener: () => void) => {@@ -117,7 +139,7 @@ vi.mock('@queries/agent-session/queue-sync', () => ({vi.mock('@queries/agent-session/log', () => ({AgentSessionLogUnavailable: logSource.Unavailable,watchAgentSessionLog: logSource.watch,- appendAgentSessionLogRows: logSource.append,+ canFollowAgentSessionLog: () => logSource.following,forgetAgentSessionLog: logSource.forget,}));@@ -185,7 +207,9 @@ beforeEach(() => {harness.get.mockResolvedValue(ok(session));logSource.cached.mockResolvedValue(undefined);logSource.fetched.mockResolvedValue(logOf([row(1)]));- logSource.append.mockResolvedValue(undefined);+ logSource.following = false;+ logSource.follow = undefined;+ soupSocket.listeners.clear();logSource.forget.mockResolvedValue(undefined);harness.control.mockImplementation(async (_id: string, request: { actionId: string }) =>@@ -843,42 +867,114 @@ describe('AgentSession', () => {live.release();});- it('appends every row delivered after the fetched log to the cached copy, once', async () => {+ it('stops the watch, and what it owes the cache, on the last release', async () => {const live = AgentSession.acquire(SESSION);await live.load();- AgentSession.ingest({ agentSessionId: SESSION, entries: [row(2)] });- AgentSession.ingest({ agentSessionId: SESSION, entries: [row(2)] });+ expect(logSource.stop).not.toHaveBeenCalled();++ live.release();+ expect(logSource.stop).toHaveBeenCalledOnce();+ });++ it('forgets the cached log when the viewer is refused', async () => {+ logSource.fetched.mockRejectedValueOnce(+ new logSource.Unavailable(SESSION, 'inaccessible')+ );+ const live = AgentSession.acquire(SESSION);+ await expect(live.load()).rejects.toBeInstanceOf(+ AgentSessionAccessDenied+ );+ expect(logSource.forget).toHaveBeenCalledWith(SESSION);+ live.release();+ });+ });++ describe('followed over GraphQL', () => {+ beforeEach(() => {+ logSource.following = true;+ });++ it('folds the rows the subscription delivers and ignores the gateway', async () => {+ const live = AgentSession.acquire(SESSION);+ await live.load();+ const follow = logSource.follow;+ expect(follow).toBeDefined();++ follow?.rows([row(2), row(3)]);+ AgentSession.ingest({ agentSessionId: SESSION, entries: [row(4)] });await settle();- // Debounced: nothing written yet.- expect(logSource.append).not.toHaveBeenCalled();+ expect(inputs()).toEqual([+ { kind: 'snapshot', rows: [row(1)] },+ { kind: 'confirmed', row: row(2) },+ { kind: 'confirmed', row: row(3) },+ ]);live.release();- // The exchange wrote the fetched log itself; only the new row goes.- expect(logSource.append).toHaveBeenCalledWith(SESSION, [row(2)]);});- it('appends rows that waited behind the fetched log too', async () => {+ it('holds rows delivered before the fetched log behind it', async () => {const log = deferred<LogSnapshot>();logSource.fetched.mockReturnValue(log.promise);const live = AgentSession.acquire(SESSION);- AgentSession.ingest({ agentSessionId: SESSION, entries: [row(2)] });+ // The subscription is open before the query goes out.+ expect(logSource.watch).toHaveBeenCalledWith(+ SESSION,+ 'cache-and-network',+ expect.objectContaining({ rows: expect.any(Function) })+ );+ logSource.follow?.rows([row(2)]);log.resolve(logOf([row(1)]));await live.load();++ expect(inputs()).toEqual([+ { kind: 'snapshot', rows: [row(1)] },+ { kind: 'confirmed', row: row(2) },+ ]);live.release();- // The buffered row is folded after the snapshot, and appended too.- expect(logSource.append).toHaveBeenCalledWith(SESSION, [row(2)]);});- it('forgets the cached log when the viewer is refused', async () => {+ it('refetches the log on a gap in the subscription', async () => {+ const live = AgentSession.acquire(SESSION);+ await live.load();+ logSource.fetched.mockResolvedValue(logOf([row(1), row(2)]));++ logSource.follow?.gap();+ await settle();++ expect(inputs().at(-1)).toEqual({+ kind: 'snapshot',+ rows: [row(1), row(2)],+ });+ live.release();+ });++ it('refetches the log when the Soup websocket reconnects', async () => {+ const live = AgentSession.acquire(SESSION);+ await live.load();+ logSource.fetched.mockResolvedValue(logOf([row(1), row(2)]));++ for (const listener of soupSocket.listeners) listener();+ await settle();++ expect(inputs().at(-1)).toEqual({+ kind: 'snapshot',+ rows: [row(1), row(2)],+ });+ live.release();+ expect(soupSocket.listeners.size).toBe(0);+ });++ it('opens a fresh watch, and stops the old one, when a failed load re-runs', async () => {logSource.fetched.mockRejectedValueOnce(- new logSource.Unavailable(SESSION, 'inaccessible')+ new logSource.Unavailable(SESSION, 'failed'));const live = AgentSession.acquire(SESSION);- await expect(live.load()).rejects.toBeInstanceOf(- AgentSessionAccessDenied- );- expect(logSource.forget).toHaveBeenCalledWith(SESSION);- expect(logSource.append).not.toHaveBeenCalled();+ await expect(live.load()).rejects.toThrow('log could not be fetched');+ expect(logSource.watch).toHaveBeenCalledTimes(1);++ await live.load();+ expect(logSource.stop).toHaveBeenCalledTimes(1);+ expect(logSource.watch).toHaveBeenCalledTimes(2);live.release();});});diff --git a/apps/web/src/lib/core/agent-session/AgentSession.ts b/apps/web/src/lib/core/agent-session/AgentSession.tsindex 1beee2ce2d..34a31fafec 100644--- a/apps/web/src/lib/core/agent-session/AgentSession.ts+++ b/apps/web/src/lib/core/agent-session/AgentSession.ts@@ -28,7 +28,7 @@ import {} from '@core/agent-fold/client';import {AgentSessionLogUnavailable,- appendAgentSessionLogRows,+ canFollowAgentSessionLog,forgetAgentSessionLog,type SessionLogWatch,watchAgentSessionLog,@@ -43,17 +43,13 @@ import type {import { agentHarnessServiceClient } from '@service-agent-harness/client';import type {AgentAction,- AgentSessionLogEntryDto,AgentSessionResponse,ControlRequest,SessionBot,} from '@service-agent-harness/generated/schemas';+import { subscribeGraphqlSoupReconnected } from '@service-storage/graphql-soup';import { v7 as uuidv7 } from 'uuid';-import {- SessionLoadTrace,- traceAcquire,- traceCacheWrite,-} from './load-telemetry';+import { SessionLoadTrace, traceAcquire } from './load-telemetry';import { PromptTrace } from './prompt-telemetry';import { publishSessionTurn } from './session-turn';@@ -117,12 +113,6 @@ function occupiesTurn(action: AgentAction): boolean {const RESYNC_RETRY_DELAYS_MS = [1_000, 3_000, 10_000];-/**- * How long appended rows wait before the cached log is extended. A streaming- * turn delivers rows many times a second, and each append re-reads the list.- */-const CACHE_WRITE_DEBOUNCE_MS = 1_000;-export class AgentSession {private static readonly open = new Map<string, AgentSession>();@@ -146,15 +136,19 @@ export class AgentSession {}/**- * Realtime ingress: a run of persisted rows in log order, addressed by- * session. The socket dispatch and the replay driver both call this; a- * session nobody has open ignores it. The run reaches the machine as one- * push, so a flush of many frames costs one worker round trip.+ * Realtime ingress over the connection gateway: a run of persisted rows+ * in log order, addressed by session. The socket dispatch and the replay+ * driver both call this; a session nobody has open ignores it, and so+ * does one following its log over GraphQL, which hears the same rows+ * there. The run reaches the machine as one push, so a flush of many+ * frames costs one worker round trip.*/static ingest(event: AgentSessionLogEvent): void {- AgentSession.open- .get(event.agentSessionId)- ?.enqueueAll(event.entries.map((row) => ({ kind: 'confirmed', row })));+ const session = AgentSession.open.get(event.agentSessionId);+ if (!session || session.followed) return;+ void session.enqueueAll(+ event.entries.map((row) => ({ kind: 'confirmed', row }))+ );}readonly id: string;@@ -170,13 +164,15 @@ export class AgentSession {*/private settled = false;/**- * Rows the socket delivered since the fetched log, not yet appended to- * the cached copy; `knownIds` is everything the cache already holds.+ * Live rows come from the GraphQL log subscription rather than the+ * gateway. Decided once, when the session opens: the client either+ * carries subscriptions or it does not.+ */+ private readonly followed = canFollowAgentSessionLog();+ /**+ * The log query in flight for the current load: cached copy, then+ * fetched; and, when followed, the subscription delivering live rows.*/- private pendingAppend: AgentSessionLogEntryDto[] = [];- private knownIds: Set<string> | undefined;- private cacheWriteTimer?: ReturnType<typeof setTimeout>;- /** The log query in flight for the current load: cached copy, then fetched. */private watch: SessionLogWatch;/** The session row, fetched alongside the log and shared by warm and load. */private sessionRow: Promise<@@ -187,6 +183,7 @@ export class AgentSession {private readonly listeners = new Set<AgentSessionListener>();private readonly unsubscribeSocket: () => void;private readonly unsubscribeUpdated: () => void;+ private readonly unsubscribeReconnected: () => void;private syncing = false;private resyncRequested = false;private resyncRetry = 0;@@ -226,8 +223,13 @@ export class AgentSession {this.unsubscribeUpdated = subscribeAgentSessionUpdated((event) => {if (event.agentSessionId === this.id) void this.resync();});+ // The subscription survives a reconnect, but not the rows published+ // while the socket was down.+ this.unsubscribeReconnected = this.followed+ ? subscribeGraphqlSoupReconnected(() => void this.resync())+ : () => undefined;this.trace = new SessionLoadTrace(id);- this.watch = watchAgentSessionLog(id);+ this.watch = this.openWatch();this.sessionRow = agentHarnessServiceClient.get(id);this.warming = this.startWarm();this.loading = this.startLoad();@@ -237,6 +239,28 @@ export class AgentSession {this.loading.catch(() => undefined);}+ /**+ * The log query for a load, following the session when the client can:+ * each run the subscription delivers folds like a gateway run would, and+ * a gap in it is a reason to refetch.+ */+ private openWatch(): SessionLogWatch {+ return watchAgentSessionLog(+ this.id,+ 'cache-and-network',+ this.followed+ ? {+ rows: (rows) => {+ void this.enqueueAll(+ rows.map((row) => ({ kind: 'confirmed', row }))+ );+ },+ gap: () => void this.resync(),+ }+ : undefined+ );+ }+/*** The session as the GraphQL cache last saw it, folded from the cached* log: what a surface can render while {@link load} is on the wire.@@ -256,7 +280,8 @@ export class AgentSession {if (this.loadFailed) {this.loadFailed = false;this.trace = new SessionLoadTrace(this.id);- this.watch = watchAgentSessionLog(this.id);+ this.watch.stop();+ this.watch = this.openWatch();this.sessionRow = agentHarnessServiceClient.get(this.id);this.loading = this.startLoad();}@@ -470,8 +495,9 @@ export class AgentSession {this.listeners.clear();this.unsubscribeSocket();this.unsubscribeUpdated();+ this.unsubscribeReconnected();clearTimeout(this.resyncTimer);- this.flushCacheWrite();+ this.watch.stop();closeSession(this.id);}@@ -538,6 +564,9 @@ export class AgentSession {(error: unknown) => ({ ok: false as const, error })),]);+ // Released mid-fetch: the stopped watch answers with a failure that is+ // not one.+ if (this.closed) throw new AgentSessionReleased(this.id);if (session.isErr()) {if (accessDenied(session.error)) {this.forgetCached();@@ -554,7 +583,6 @@ export class AgentSession {cause: log.error,});}- if (this.closed) throw new AgentSessionReleased(this.id);this.trace.fetched(fetchStartedAt, log.log.rows.length);const foldStartedAt = performance.now();@@ -577,59 +605,6 @@ export class AgentSession {});}- /**- * Keep the cached log in step with what the machine was given, once the- * fetched log is what it holds. The exchange already wrote each fetched- * snapshot; only confirmed rows after one need appending. The machine- * dedupes by row id on its side; this does the same so a row delivered- * twice is stored once.- */- private remember(inputs: FoldInput[]): void {- if (!this.settled) return;- let changed = false;- for (const input of inputs) {- if (input.kind === 'snapshot') {- this.knownIds = new Set(input.rows.map((row) => row.id));- this.pendingAppend = [];- } else if (input.kind === 'confirmed' && this.knownIds) {- if (this.knownIds.has(input.row.id)) continue;- this.knownIds.add(input.row.id);- this.pendingAppend.push(input.row);- changed = true;- }- }- if (changed) this.scheduleCacheWrite();- }-- private scheduleCacheWrite(): void {- if (this.cacheWriteTimer !== undefined) return;- this.cacheWriteTimer = setTimeout(() => {- this.cacheWriteTimer = undefined;- this.writeCache();- }, CACHE_WRITE_DEBOUNCE_MS);- }-- /** Write now what a pending timer would have: the session is going away. */- private flushCacheWrite(): void {- if (this.cacheWriteTimer === undefined) return;- clearTimeout(this.cacheWriteTimer);- this.cacheWriteTimer = undefined;- this.writeCache();- }-- private writeCache(): void {- const rows = this.pendingAppend;- if (rows.length === 0) return;- this.pendingAppend = [];- const startedAt = performance.now();- void appendAgentSessionLogRows(this.id, rows).then(- () => traceCacheWrite(this.id, startedAt, rows.length),- (error: unknown) => {- console.warn('[agent-session] log rows could not be cached', error);- }- );- }-/*** A reopened socket is a new socket session: rows may have been missed* while it was down. Refetch, and let the machine reconcile the overlap@@ -703,7 +678,6 @@ export class AgentSession {}private apply(inputs: FoldInput[]): Promise<void> {- this.remember(inputs);const run = this.chain.then(async () => {if (this.closed) return;const events = await pushSession(this.id, inputs);diff --git a/apps/web/src/lib/queries/agent-session/log.test.ts b/apps/web/src/lib/queries/agent-session/log.test.tsnew file mode 100644index 0000000000..2e517ce12a--- /dev/null+++ b/apps/web/src/lib/queries/agent-session/log.test.ts@@ -0,0 +1,212 @@+/**+ * The watch against a faked urql client and cache host: a followed watch+ * subscribes before it queries, hands every run on at once, and extends the+ * cached log only once the fetched one is what the cache holds.+ */++import type { AgentSessionLogEntryDto } from '@service-agent-harness/generated/schemas';+import type { AgentSessionLogQuery } from '@service-storage/graphql/generated/graphql';+import type { OperationResult } from '@urql/core';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { makeSubject, type Source } from 'wonka';++vi.mock('@core/constant/featureFlags', () => ({+ enableGraphqlSoup: {},+ isFeatureEnabled: () => true,+}));+vi.mock('@core/agent-session/load-telemetry', () => ({+ traceCacheWrite: () => undefined,+}));++const metadata = vi.hoisted(() => new WeakMap<object, { source: string }>());+vi.mock('@graphql-cache/exchange/normalized-cache-exchange', () => ({+ normalizedCacheResultMetadata: (result: object) => metadata.get(result),+}));++const client = vi.hoisted(() => ({+ query: vi.fn(),+ subscription: vi.fn(),+}));+const host = vi.hoisted(() => ({+ readQuery: vi.fn(),+ writeQuery: vi.fn(),+ deleteRecords: vi.fn(),+}));+vi.mock('@service-storage/graphql-soup', () => ({+ getGraphqlSoupClient: () => client,+ getGraphqlCacheHost: () => host,+}));++import { watchAgentSessionLog } from './log';++const SESSION = '01a0abed-279f-724c-9f49-60dbedc79b6e';++function entry(n: number) {+ return {+ id: `00000000-0000-0000-0000-${n.toString(16).padStart(12, '0')}`,+ createdAt: new Date(Date.UTC(2026, 7, 13, 0, 0, n)).toISOString(),+ userId: null,+ direction: 'to_server',+ content: { type: 'acp', jsonrpc: '2.0', id: n },+ };+}++function row(n: number): AgentSessionLogEntryDto {+ const { userId: _userId, ...rest } = entry(n);+ return rest as unknown as AgentSessionLogEntryDto;+}++const bot = { id: 'bot-id', name: 'Agent', handle: 'agent', avatarUrl: null };++function logData(ids: number[]): AgentSessionLogQuery {+ return {+ user: {+ id: 'user-1',+ agentSession: {+ id: SESSION,+ log: { bot, entries: ids.map(entry) },+ },+ },+ };+}++type Result<T> = OperationResult<T>;++/** A result the exchange marked as coming from the network. */+function fromNetwork<T>(data: T): Result<T> {+ const result = { data, stale: false, hasNext: false } as unknown as Result<T>;+ metadata.set(result, { source: 'live-network' });+ return result;+}++/** A result the exchange marked as a cache read. */+function fromCache<T>(data: T): Result<T> {+ const result = { data, stale: false, hasNext: false } as unknown as Result<T>;+ metadata.set(result, { source: 'normalized-cache-hit' });+ return result;+}++let query: ReturnType<typeof makeSubject<Result<AgentSessionLogQuery>>>;+let appended: ReturnType<+ typeof makeSubject<+ Result<{ agentSessionLogAppended: ReturnType<typeof entry>[] }>+ >+>;+/** The order the client was asked for things in. */+let calls: string[];++beforeEach(() => {+ vi.useFakeTimers();+ calls = [];+ query = makeSubject();+ appended = makeSubject();+ client.query.mockImplementation((): Source<unknown> => {+ calls.push('query');+ return query.source;+ });+ client.subscription.mockImplementation((): Source<unknown> => {+ calls.push('subscription');+ return appended.source;+ });+ host.readQuery.mockResolvedValue({ kind: 'miss' });+ host.writeQuery.mockResolvedValue(undefined);+});++afterEach(() => {+ vi.clearAllMocks();+ vi.useRealTimers();+});++/** Let awaited promises settle under fake timers. */+const settle = () => vi.advanceTimersByTimeAsync(0);++describe('watchAgentSessionLog', () => {+ it('answers from the cache, then the network', async () => {+ const watch = watchAgentSessionLog(SESSION);+ query.next(fromCache(logData([1])));+ query.next(fromNetwork(logData([1, 2])));++ expect((await watch.cached)?.rows).toEqual([row(1)]);+ expect((await watch.fetched).rows).toEqual([row(1), row(2)]);+ expect(client.subscription).not.toHaveBeenCalled();+ });++ it('subscribes before it queries, and hands every run on at once', async () => {+ const rows = vi.fn();+ const watch = watchAgentSessionLog(SESSION, 'cache-and-network', {+ rows,+ gap: () => undefined,+ });+ expect(calls).toEqual(['subscription', 'query']);+ expect(client.subscription).toHaveBeenCalledWith(expect.anything(), {+ sessionId: SESSION,+ });++ appended.next(fromNetwork({ agentSessionLogAppended: [entry(2)] }));+ expect(rows).toHaveBeenCalledWith([row(2)]);+ watch.stop();+ });++ it('extends the cached log after the fetched one, without what it already holds', async () => {+ const watch = watchAgentSessionLog(SESSION, 'cache-and-network', {+ rows: () => undefined,+ gap: () => undefined,+ });+ // Delivered while the query is on the wire: held, not written over a+ // list the fetch is about to replace.+ appended.next(fromNetwork({ agentSessionLogAppended: [entry(2)] }));+ appended.next(fromNetwork({ agentSessionLogAppended: [entry(3)] }));+ await settle();+ expect(host.readQuery).not.toHaveBeenCalled();++ // The fetched log already has row 2.+ query.next(fromNetwork(logData([1, 2])));+ await watch.fetched;+ host.readQuery.mockResolvedValue({ kind: 'hit', data: logData([1, 2]) });+ await vi.advanceTimersByTimeAsync(1_000);++ expect(host.writeQuery).toHaveBeenCalledOnce();+ const written = host.writeQuery.mock.calls[0]?.[0]+ .data as AgentSessionLogQuery;+ expect(+ written.user.agentSession?.log.entries.map((written) => written.id)+ ).toEqual([entry(1).id, entry(2).id, entry(3).id]);+ watch.stop();+ });++ it('writes what it still owes when stopped', async () => {+ const watch = watchAgentSessionLog(SESSION, 'cache-and-network', {+ rows: () => undefined,+ gap: () => undefined,+ });+ query.next(fromNetwork(logData([1])));+ await watch.fetched;+ host.readQuery.mockResolvedValue({ kind: 'hit', data: logData([1]) });+ appended.next(fromNetwork({ agentSessionLogAppended: [entry(2)] }));+ appended.next(fromNetwork({ agentSessionLogAppended: [entry(2)] }));++ watch.stop();+ await settle();++ expect(host.writeQuery).toHaveBeenCalledOnce();+ const written = host.writeQuery.mock.calls[0]?.[0]+ .data as AgentSessionLogQuery;+ expect(written.user.agentSession?.log.entries).toHaveLength(2);+ });++ it('reports a gap when the subscription errors', async () => {+ const gap = vi.fn();+ const watch = watchAgentSessionLog(SESSION, 'cache-and-network', {+ rows: () => undefined,+ gap,+ });+ appended.next({+ error: new Error('closed after falling behind'),+ stale: false,+ hasNext: false,+ } as unknown as Result<{ agentSessionLogAppended: never[] }>);++ expect(gap).toHaveBeenCalledOnce();+ watch.stop();+ });+});diff --git a/apps/web/src/lib/queries/agent-session/log.ts b/apps/web/src/lib/queries/agent-session/log.tsindex accf859432..ddcf1212b5 100644--- a/apps/web/src/lib/queries/agent-session/log.ts+++ b/apps/web/src/lib/queries/agent-session/log.ts@@ -3,11 +3,17 @@** `cache-and-network` answers twice: from disk when the cache holds the log,* then from the network, which the exchange writes back. The caller hears- * both in order. Rows the socket delivers after the fetch are appended to- * the cached list here, so the next open starts from a log as complete as- * the last one ended.+ * both in order. A watch that follows the session subscribes to its appended+ * frames before the query goes out, so no row between the two is lost, and+ * appends what the subscription delivers to the cached list, so the next+ * open starts from a log as complete as the last one ended.*/+import { traceCacheWrite } from '@core/agent-session/load-telemetry';+import {+ enableGraphqlSoup,+ isFeatureEnabled,+} from '@core/constant/featureFlags';import { normalizedCacheResultMetadata } from '@graphql-cache/exchange/normalized-cache-exchange';import type {AgentSessionLogEntryDto,@@ -15,6 +21,9 @@ import type {SessionBot,} from '@service-agent-harness/generated/schemas';import {+ AgentSessionLogAppendedDocument,+ type AgentSessionLogAppendedSubscription,+ type AgentSessionLogAppendedSubscriptionVariables,AgentSessionLogDocument,type AgentSessionLogQuery,type AgentSessionLogQueryVariables,@@ -56,10 +65,33 @@ export type SessionLogWatch = {cached: Promise<SessionLogSnapshot | undefined>;/** The log as the server holds it now. Rejects with {@link AgentSessionLogUnavailable}. */fetched: Promise<SessionLogSnapshot>;- /** Stop listening. Unsettled promises settle as a miss and a failure. */+ /**+ * Stop listening. Unsettled promises settle as a miss and a failure; a+ * follow is unsubscribed and what it still owes the cache is written.+ */stop: () => void;};+/**+ * How a watch follows the session after the fetch: each run of frames the+ * harness appends, in log order, as the harness flushed it. `gap` means+ * rows may have been missed - the subscription fell behind or the socket+ * reconnected - and the caller must refetch the log.+ */+export type SessionLogFollow = {+ rows: (rows: AgentSessionLogEntryDto[]) => void;+ gap: () => void;+};++/**+ * Whether a watch can follow the session over GraphQL. Only the client+ * built with the Soup websocket carries subscriptions; without it, live+ * rows still arrive through the connection gateway.+ */+export function canFollowAgentSessionLog(): boolean {+ return isFeatureEnabled(enableGraphqlSoup);+}+const DIRECTIONS: ReadonlySet<string> = new Set<LogDirectionDto>(['to_server','to_runtime',@@ -70,6 +102,23 @@ function isDirection(value: string): value is LogDirectionDto {}type LogData = NonNullable<AgentSessionLogQuery['user']['agentSession']>['log'];+type LogEntry = LogData['entries'][number];++/** One GraphQL entry in the wire shape the fold reads. */+function toRow(sessionId: string, entry: LogEntry): AgentSessionLogEntryDto {+ if (!isDirection(entry.direction)) {+ throw new AgentSessionLogUnavailable(sessionId, 'failed', {+ cause: new Error(`unknown log direction: ${entry.direction}`),+ });+ }+ return {+ id: entry.id,+ createdAt: entry.createdAt,+ ...(entry.userId === null ? {} : { userId: entry.userId }),+ direction: entry.direction,+ content: entry.content as AgentSessionLogEntryDto['content'],+ };+}/** The wire shape the fold reads, from the GraphQL selection. */function toSnapshot(sessionId: string, log: LogData): SessionLogSnapshot {@@ -80,31 +129,24 @@ function toSnapshot(sessionId: string, log: LogData): SessionLogSnapshot {handle: log.bot.handle,...(log.bot.avatarUrl === null ? {} : { avatarUrl: log.bot.avatarUrl }),},- rows: log.entries.map((entry) => {- if (!isDirection(entry.direction)) {- throw new AgentSessionLogUnavailable(sessionId, 'failed', {- cause: new Error(`unknown log direction: ${entry.direction}`),- });- }- return {- id: entry.id,- createdAt: entry.createdAt,- ...(entry.userId === null ? {} : { userId: entry.userId }),- direction: entry.direction,- content: entry.content as AgentSessionLogEntryDto['content'],- };- }),+ rows: log.entries.map((entry) => toRow(sessionId, entry)),};}+/** How long appended rows wait for company before they are written. */+const CACHE_WRITE_DEBOUNCE_MS = 1_000;+/*** Watch one session's log: the cached copy first when there is one, then* the fetched one. `policy` `network-only` skips the cache read, for a- * resync that wants only what the server holds.+ * resync that wants only what the server holds. With `follow`, the watch+ * also subscribes to the session's appended frames, before the query so+ * the two overlap rather than leave a hole, and hands each run on.*/export function watchAgentSessionLog(sessionId: string,- policy: 'cache-and-network' | 'network-only' = 'cache-and-network'+ policy: 'cache-and-network' | 'network-only' = 'cache-and-network',+ follow?: SessionLogFollow): SessionLogWatch {let resolveCached!: (snapshot: SessionLogSnapshot | undefined) => void;let resolveFetched!: (snapshot: SessionLogSnapshot) => void;@@ -119,6 +161,11 @@ export function watchAgentSessionLog(// A rejection nobody has awaited yet must not be reported as unhandled.fetched.catch(() => undefined);+ const appender = follow ? createAppender(sessionId) : undefined;+ const unsubscribeFollow = follow+ ? followAppended(sessionId, follow, appender)+ : () => undefined;+const settleFetched = (result: OperationResult<AgentSessionLogQuery>) => {resolveCached(undefined);if (result.error) {@@ -135,7 +182,9 @@ export function watchAgentSessionLog(return;}try {- resolveFetched(toSnapshot(sessionId, log));+ const snapshot = toSnapshot(sessionId, log);+ appender?.fetched(snapshot.rows);+ resolveFetched(snapshot);} catch (error) {rejectFetched(error instanceof AgentSessionLogUnavailable@@ -181,21 +230,141 @@ export function watchAgentSessionLog(fetched,stop: () => {unsubscribe();+ unsubscribeFollow();+ appender?.flush();resolveCached(undefined);rejectFetched(new AgentSessionLogUnavailable(sessionId, 'failed'));},};}+/**+ * Subscribe to the session's appended frames. Every run reaches `follow`+ * at once; the appender hears it too, to keep the cached log in step. An+ * error or an end from the server is a gap: the subscription fell behind,+ * and the rows it dropped are only in the durable log.+ */+function followAppended(+ sessionId: string,+ follow: SessionLogFollow,+ appender: Appender | undefined+): () => void {+ const { unsubscribe } = pipe(+ getGraphqlSoupClient().subscription<+ AgentSessionLogAppendedSubscription,+ AgentSessionLogAppendedSubscriptionVariables+ >(AgentSessionLogAppendedDocument, { sessionId }),+ subscribe((result) => {+ if (result.error) {+ console.warn(+ '[agent-session] log subscription interrupted',+ result.error+ );+ follow.gap();+ return;+ }+ const entries = result.data?.agentSessionLogAppended;+ if (!entries || entries.length === 0) return;+ let rows: AgentSessionLogEntryDto[];+ try {+ rows = entries.map((entry) => toRow(sessionId, entry));+ } catch (error) {+ console.warn('[agent-session] log subscription row unreadable', error);+ follow.gap();+ return;+ }+ appender?.appended(rows);+ follow.rows(rows);+ })+ );+ return unsubscribe;+}++type Appender = {+ /** The fetched log landed in the cache; rows held until now go after it. */+ fetched: (rows: AgentSessionLogEntryDto[]) => void;+ /** The subscription delivered a run. */+ appended: (rows: AgentSessionLogEntryDto[]) => void;+ /** Write now what a pending timer would have. */+ flush: () => void;+};++/**+ * Keep the cached log in step with what the subscription delivered, once+ * the fetched log is what the cache holds. The exchange writes each fetched+ * snapshot itself; only rows after one need appending. Rows that arrive+ * before the fetch settles wait: written earlier, the fetched write would+ * replace the list without them. Dedupes by row id, as the fold does, so a+ * row delivered twice is stored once.+ */+function createAppender(sessionId: string): Appender {+ let known: Set<string> | undefined;+ let pending: AgentSessionLogEntryDto[] = [];+ let timer: ReturnType<typeof setTimeout> | undefined;++ const write = () => {+ const rows = pending;+ if (rows.length === 0) return;+ pending = [];+ const startedAt = performance.now();+ void appendAgentSessionLogRows(sessionId, rows).then(+ () => traceCacheWrite(sessionId, startedAt, rows.length),+ (error: unknown) => {+ console.warn('[agent-session] log rows could not be cached', error);+ }+ );+ };+ const schedule = () => {+ if (timer !== undefined) return;+ timer = setTimeout(() => {+ timer = undefined;+ write();+ }, CACHE_WRITE_DEBOUNCE_MS);+ };+ const remember = (rows: AgentSessionLogEntryDto[]) => {+ if (!known) return false;+ let changed = false;+ for (const row of rows) {+ if (known.has(row.id)) continue;+ known.add(row.id);+ pending.push(row);+ changed = true;+ }+ return changed;+ };++ return {+ fetched(rows) {+ known = new Set(rows.map((row) => row.id));+ const held = pending;+ pending = [];+ if (remember(held)) schedule();+ },+ appended(rows) {+ if (!known) {+ pending.push(...rows);+ return;+ }+ if (remember(rows)) schedule();+ },+ flush() {+ if (timer === undefined) return;+ clearTimeout(timer);+ timer = undefined;+ write();+ },+ };+}+const LOG_QUERY = stringifyDocument(AgentSessionLogDocument);const LOG_OPERATION = 'AgentSessionLog';/**- * Append rows the socket delivered to the cached log, so the next open- * folds them before the network answers. A cache without this session's- * log has nothing to extend; the next fetch writes the whole thing.+ * Append rows to the cached log, so the next open folds them before the+ * network answers. A cache without this session's log has nothing to+ * extend; the next fetch writes the whole thing.*/-export async function appendAgentSessionLogRows(+async function appendAgentSessionLogRows(sessionId: string,rows: AgentSessionLogEntryDto[]): Promise<void> {diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.tsindex a6481b64d6..a81d9ff337 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts@@ -294,9 +294,27 @@ const graphqlSoupClient = createClient({preferGetMethod: false,});+const reconnectListeners = new Set<() => void>();++/**+ * Hear every reconnect of the Soup GraphQL websocket after its first+ * connection. A subscription survives a reconnect, but nothing published+ * while the socket was down reaches it: a listener that follows a stream+ * refetches what it may have missed.+ */+export function subscribeGraphqlSoupReconnected(+ listener: () => void+): () => void {+ reconnectListeners.add(listener);+ return () => {+ reconnectListeners.delete(listener);+ };+}+function createGraphqlSoupWebSocketClient(onConnected: () => void): GraphqlWsClient {+ let connections = 0;const resolveWebSocketUrl = createGraphqlSoupWebSocketUrlResolver({dssHost,bearerTokenAuth: ENABLE_BEARER_TOKEN_AUTH,@@ -311,7 +329,14 @@ function createGraphqlSoupWebSocketClient(return createGraphqlWsClient({url: resolveWebSocketUrl,retryAttempts: SOUP_GRAPHQL_WEBSOCKET_RETRY_ATTEMPTS,- on: { connected: onConnected },+ on: {+ connected: () => {+ onConnected();+ connections += 1;+ if (connections === 1) return;+ for (const listener of reconnectListeners) listener();+ },+ },shouldRetry: shouldRetryGraphqlSoupWebSocket,});}diff --git a/apps/web/src/lib/service-clients/service-storage/graphql/agent-session-log-appended.graphql b/apps/web/src/lib/service-clients/service-storage/graphql/agent-session-log-appended.graphqlnew file mode 100644index 0000000000..bf45e8b6d6--- /dev/null+++ b/apps/web/src/lib/service-clients/service-storage/graphql/agent-session-log-appended.graphql@@ -0,0 +1,9 @@+subscription AgentSessionLogAppended($sessionId: ID!) {+ agentSessionLogAppended(sessionId: $sessionId) {+ id+ createdAt+ userId+ direction+ content+ }+}diff --git a/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts b/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.tsindex 1a8b9551fb..3903dd704a 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql/generated/graphql.ts@@ -2125,6 +2125,13 @@ export type ActivityEventFieldsFragment = { __typename: 'GraphqlActivityEvent',| { __typename: 'GraphqlActivityUnknownAction', tag: string, payload: unknown }};+export type AgentSessionLogAppendedSubscriptionVariables = Exact<{+ sessionId: string | number;+}>;+++export type AgentSessionLogAppendedSubscription = { agentSessionLogAppended: Array<{ id: string, createdAt: string, userId: string | null, direction: string, content: unknown }> };+export type AgentSessionLogQueryVariables = Exact<{sessionId: string | number;}>;@@ -15760,6 +15767,7 @@ export const MyActivityDocument = {"kind":"Document","definitions":[{"kind":"Opeexport const MyActivityOverviewDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","name":{"kind":"Name","value":"MyActivityOverview"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"input"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"ActivityOverviewInput"}}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"user"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"activityOverview"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"input"},"value":{"kind":"Variable","name":{"kind":"Name","value":"input"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"from"}},{"kind":"Field","name":{"kind":"Name","value":"to"}},{"kind":"Field","name":{"kind":"Name","value":"timeZone"}},{"kind":"Field","name":{"kind":"Name","value":"total"}},{"kind":"Field","name":{"kind":"Name","value":"days"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"date"}},{"kind":"Field","name":{"kind":"Name","value":"count"}}]}},{"kind":"Field","name":{"kind":"Name","value":"topEntities"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"entityType"}},{"kind":"Field","name":{"kind":"Name","value":"entityId"}},{"kind":"Field","name":{"kind":"Name","value":"count"}}]}}]}}]}}]}}]} as unknown as DocumentNode<MyActivityOverviewQuery, MyActivityOverviewQueryVariables>;export const EntityActivityDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","name":{"kind":"Name","value":"EntityActivity"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"input"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"SoupInput"}}}},{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"limit"}},"type":{"kind":"NamedType","name":{"kind":"Name","value":"Int"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"user"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"soup"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"input"},"value":{"kind":"Variable","name":{"kind":"Name","value":"input"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"items"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"FragmentSpread","name":{"kind":"Name","value":"EntityActivityFields"}}]}}]}}]}}]}},{"kind":"FragmentDefinition","name":{"kind":"Name","value":"ActivityEventFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityEvent"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"actorId"}},{"kind":"Field","name":{"kind":"Name","value":"subjectId"}},{"kind":"Field","name":{"kind":"Name","value":"entityType"}},{"kind":"Field","name":{"kind":"Name","value":"entityId"}},{"kind":"Field","name":{"kind":"Name","value":"occurredAt"}},{"kind":"Field","name":{"kind":"Name","value":"action"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityPropertyChanged"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"property"}},{"kind":"Field","name":{"kind":"Name","value":"from"}},{"kind":"Field","name":{"kind":"Name","value":"to"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityParticipantAdded"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"participant"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityParticipantRemoved"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"participant"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityCallStarted"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"callId"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityUnknownAction"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"tag"}},{"kind":"Field","name":{"kind":"Name","value":"payload"}}]}}]}}]}},{"kind":"FragmentDefinition","name":{"kind":"Name","value":"EntityActivityFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupEntity"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"activity"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"limit"},"value":{"kind":"Variable","name":{"kind":"Name","value":"limit"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"FragmentSpread","name":{"kind":"Name","value":"ActivityEventFields"}}]}}]}}]} as unknown as DocumentNode<EntityActivityQuery, EntityActivityQueryVariables>;export const DatabaseActivityDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","name":{"kind":"Name","value":"DatabaseActivity"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"databaseId"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"ID"}}}},{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"limit"}},"type":{"kind":"NamedType","name":{"kind":"Name","value":"Int"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"user"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"databaseActivity"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"databaseId"},"value":{"kind":"Variable","name":{"kind":"Name","value":"databaseId"}}},{"kind":"Argument","name":{"kind":"Name","value":"limit"},"value":{"kind":"Variable","name":{"kind":"Name","value":"limit"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"FragmentSpread","name":{"kind":"Name","value":"ActivityEventFields"}}]}}]}}]}},{"kind":"FragmentDefinition","name":{"kind":"Name","value":"ActivityEventFields"},"typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityEvent"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"actorId"}},{"kind":"Field","name":{"kind":"Name","value":"subjectId"}},{"kind":"Field","name":{"kind":"Name","value":"entityType"}},{"kind":"Field","name":{"kind":"Name","value":"entityId"}},{"kind":"Field","name":{"kind":"Name","value":"occurredAt"}},{"kind":"Field","name":{"kind":"Name","value":"action"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityPropertyChanged"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"property"}},{"kind":"Field","name":{"kind":"Name","value":"from"}},{"kind":"Field","name":{"kind":"Name","value":"to"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityParticipantAdded"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"participant"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityParticipantRemoved"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"participant"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityCallStarted"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"callId"}}]}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlActivityUnknownAction"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"tag"}},{"kind":"Field","name":{"kind":"Name","value":"payload"}}]}}]}}]}}]} as unknown as DocumentNode<DatabaseActivityQuery, DatabaseActivityQueryVariables>;+export const AgentSessionLogAppendedDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"subscription","name":{"kind":"Name","value":"AgentSessionLogAppended"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"sessionId"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"ID"}}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"agentSessionLogAppended"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"sessionId"},"value":{"kind":"Variable","name":{"kind":"Name","value":"sessionId"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"userId"}},{"kind":"Field","name":{"kind":"Name","value":"direction"}},{"kind":"Field","name":{"kind":"Name","value":"content"}}]}}]}}]} as unknown as DocumentNode<AgentSessionLogAppendedSubscription, AgentSessionLogAppendedSubscriptionVariables>;export const AgentSessionLogDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","name":{"kind":"Name","value":"AgentSessionLog"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"sessionId"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"ID"}}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"user"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"agentSession"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"sessionId"},"value":{"kind":"Variable","name":{"kind":"Name","value":"sessionId"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"log"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"bot"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"handle"}},{"kind":"Field","name":{"kind":"Name","value":"avatarUrl"}}]}},{"kind":"Field","name":{"kind":"Name","value":"entries"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"userId"}},{"kind":"Field","name":{"kind":"Name","value":"direction"}},{"kind":"Field","name":{"kind":"Name","value":"content"}}]}}]}}]}}]}}]}}]} as unknown as DocumentNode<AgentSessionLogQuery, AgentSessionLogQueryVariables>;export const AgentSessionMentionsDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","name":{"kind":"Name","value":"AgentSessionMentions"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"input"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"SoupInput"}}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"user"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"soup"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"input"},"value":{"kind":"Variable","name":{"kind":"Name","value":"input"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"items"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"InlineFragment","typeCondition":{"kind":"NamedType","name":{"kind":"Name","value":"GraphqlSoupAgentSession"}},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"ownerId"}},{"kind":"Field","name":{"kind":"Name","value":"botId"}},{"kind":"Field","name":{"kind":"Name","value":"bot"},"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"name"}},{"kind":"Field","name":{"kind":"Name","value":"avatarUrl"}}]}},{"kind":"Field","name":{"kind":"Name","value":"status"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}}]}}]}}]}}]}}]}}]} as unknown as DocumentNode<AgentSessionMentionsQuery, AgentSessionMentionsQueryVariables>;export const RecordChannelActivityDocument = {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"mutation","name":{"kind":"Name","value":"RecordChannelActivity"},"variableDefinitions":[{"kind":"VariableDefinition","variable":{"kind":"Variable","name":{"kind":"Name","value":"input"}},"type":{"kind":"NonNullType","type":{"kind":"NamedType","name":{"kind":"Name","value":"RecordChannelActivityInput"}}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"recordChannelActivity"},"arguments":[{"kind":"Argument","name":{"kind":"Name","value":"input"},"value":{"kind":"Variable","name":{"kind":"Name","value":"input"}}}],"selectionSet":{"kind":"SelectionSet","selections":[{"kind":"Field","name":{"kind":"Name","value":"__typename"}},{"kind":"Field","name":{"kind":"Name","value":"id"}},{"kind":"Field","name":{"kind":"Name","value":"userId"}},{"kind":"Field","name":{"kind":"Name","value":"channelId"}},{"kind":"Field","name":{"kind":"Name","value":"createdAt"}},{"kind":"Field","name":{"kind":"Name","value":"updatedAt"}},{"kind":"Field","name":{"kind":"Name","value":"viewedAt"}},{"kind":"Field","name":{"kind":"Name","value":"interactedAt"}}]}}]}}]} as unknown as DocumentNode<RecordChannelActivityMutation, RecordChannelActivityMutationVariables>;diff --git a/crates/agent_session/src/domain/events.rs b/crates/agent_session/src/domain/events.rsindex bd4eb17c3b..457a4745b5 100644--- a/crates/agent_session/src/domain/events.rs+++ b/crates/agent_session/src/domain/events.rs@@ -16,13 +16,15 @@ mod test;use agent_runtime_protocol::domain::action::AgentActionId;use bots::domain::models::BotId;use macro_event_broker::{Event, MacroEvent, TopicEvent};-use macro_event_topics::MacroAgentSessionLifecycleTopic;+use macro_event_topics::{MacroAgentSessionLifecycleTopic, MacroAgentSessionLogTopic};use macro_user_id::user_id::MacroUserIdStr;use macro_uuid::Uuid;use messages::domain::models::MessageParent;use serde::{Deserialize, Serialize};-use super::model::{AgentSessionId, TurnId};+use super::model::{+ AgentSessionId, AgentSessionLog, LogAppended, Message, StoredAgentSessionLog, TurnId,+};/// The thread a session was opened from, when it was.#[derive(Debug, Clone, PartialEq, Eq, Serialize)]@@ -463,3 +465,137 @@ impl MacroEvent for AgentSessionLifecycleMacroEvent {Self { key, event }}}++/// A run of frames appended to a session's log, published to+/// [`MacroAgentSessionLogTopic`] and keyed by session id.+///+/// The connection gateway pushes the same run to the viewers this process+/// knows about; this is for a process that serves viewers of its own, such+/// as the GraphQL subscription in document storage. Each entry is exactly+/// the stored row, so a subscriber folds the same bytes a reader of the+/// durable log does.+#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(tag = "event_type", content = "metadata")]+pub enum AgentSessionLogTopicEvent {+ /// Frames were appended to the log, in log order.+ #[serde(rename = "agent_session_log.appended")]+ Appended(LogAppendedMetadata),+}++impl AgentSessionLogTopicEvent {+ /// The session the frames belong to.+ #[must_use]+ pub fn session_id(&self) -> AgentSessionId {+ match self {+ Self::Appended(metadata) => metadata.agent_session_id,+ }+ }+}++impl TopicEvent for AgentSessionLogTopicEvent {+ type Topic = MacroAgentSessionLogTopic;++ const SCHEMA_VERSION: u8 = 1;+}++/// The frames one flush appended, as the log stored them.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct LogAppendedMetadata {+ /// The session the frames belong to.+ pub agent_session_id: AgentSessionId,+ /// The frames, in the order the log holds them.+ pub entries: Vec<LogAppendedEntry>,+}++/// One stored frame: the row's identity and time beside the frame itself.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct LogAppendedEntry {+ /// Durable row identity.+ pub id: Uuid,+ /// When the log recorded the frame.+ pub created_at: chrono::DateTime<chrono::Utc>,+ /// The user whose action produced the frame, absent when no user did.+ pub user_id: Option<MacroUserIdStr<'static>>,+ /// The frame, with its direction.+ pub content: Message,+}++impl From<&LogAppended> for AgentSessionLogTopicEvent {+ fn from(event: &LogAppended) -> Self {+ Self::Appended(LogAppendedMetadata {+ agent_session_id: event.agent_session_id,+ entries: event+ .entries+ .iter()+ .map(|stored| LogAppendedEntry {+ id: stored.id,+ created_at: stored.created_at,+ user_id: stored.entry.user_id.clone(),+ content: stored.entry.content.clone(),+ })+ .collect(),+ })+ }+}++impl LogAppendedMetadata {+ /// The frames as stored rows again, for a consumer that reads them the+ /// way it reads the durable log.+ #[must_use]+ pub fn into_stored(self) -> Vec<StoredAgentSessionLog> {+ let agent_session_id = self.agent_session_id;+ self.entries+ .into_iter()+ .map(|entry| StoredAgentSessionLog {+ id: entry.id,+ created_at: entry.created_at,+ entry: AgentSessionLog {+ agent_session_id,+ user_id: entry.user_id,+ content: entry.content,+ },+ })+ .collect()+ }+}++/// Publishable event for [`MacroAgentSessionLogTopic`], keyed by session id+/// so one session's frames stay in order on one partition.+#[derive(Debug, Clone)]+pub struct AgentSessionLogMacroEvent {+ key: String,+ event: Event<AgentSessionLogTopicEvent>,+}++impl AgentSessionLogMacroEvent {+ /// Wrap a run of frames for publication.+ #[must_use]+ pub fn new(event: AgentSessionLogTopicEvent) -> Self {+ Self {+ key: event.session_id().to_string(),+ event: Event::new(event),+ }+ }++ /// The run this event carries.+ #[must_use]+ pub fn into_payload(self) -> AgentSessionLogTopicEvent {+ self.event.event+ }+}++impl MacroEvent for AgentSessionLogMacroEvent {+ type EventPayload = AgentSessionLogTopicEvent;++ fn key(&self) -> &str {+ &self.key+ }++ fn event(&self) -> &Event<Self::EventPayload> {+ &self.event+ }++ fn from_event(key: String, event: Event<Self::EventPayload>) -> Self {+ Self { key, event }+ }+}diff --git a/crates/agent_session/src/outbound/broker_log_realtime.rs b/crates/agent_session/src/outbound/broker_log_realtime.rsnew file mode 100644index 0000000000..01f4b8e629--- /dev/null+++ b/crates/agent_session/src/outbound/broker_log_realtime.rs@@ -0,0 +1,82 @@+//! [`AgentSessionRealtime`] that also publishes each appended run to the+//! event broker, so a process serving viewers of its own - the GraphQL+//! subscription in document storage - hears the frames too.++#[cfg(test)]+mod test;++use crate::domain::events::{AgentSessionLogMacroEvent, AgentSessionLogTopicEvent};+use crate::domain::model::{AgentSessionId, AgentSessionRenamed, LogAppended};+use crate::domain::ports::{AgentSessionQueueChanged, AgentSessionRealtime};+use macro_event_broker::MacroEventBroker;++/// `inner` keeps doing what it does; each run of frames is published to+/// `macro.agent_session_log` as well. The broker publish is best effort, as+/// the port allows: a refusal is logged and the inner result is returned.+#[derive(Debug, Clone)]+pub struct BrokerLogRealtime<Inner, Broker> {+ inner: Inner,+ broker: Broker,+}++impl<Inner, Broker> BrokerLogRealtime<Inner, Broker> {+ /// Publish through `inner`, and each log run through `broker` too.+ pub fn new(inner: Inner, broker: Broker) -> Self {+ Self { inner, broker }+ }+}++impl<Inner, Broker> AgentSessionRealtime for BrokerLogRealtime<Inner, Broker>+where+ Inner: AgentSessionRealtime + Sync,+ Broker: MacroEventBroker + Sync,+{+ async fn publish(&self, event: LogAppended) -> Result<(), rootcause::Report> {+ let session_id = event.agent_session_id;+ let macro_event = AgentSessionLogMacroEvent::new(AgentSessionLogTopicEvent::from(&event));+ let inner = self.inner.publish(event).await;+ let published = match self.broker.send_event(¯o_event) {+ Ok(handle) => match handle.await {+ Ok(result) => result.map_err(|error| error.to_string()),+ Err(join_error) => Err(join_error.to_string()),+ },+ Err(error) => Err(error.to_string()),+ };+ if let Err(error) = published {+ tracing::warn!(+ %error,+ %session_id,+ "failed to publish appended agent session log frames to the broker"+ );+ }+ inner+ }++ fn publish_updated(+ &self,+ session: AgentSessionId,+ ) -> impl Future<Output = Result<(), rootcause::Report>> + Send {+ self.inner.publish_updated(session)+ }++ fn publish_renamed(+ &self,+ event: AgentSessionRenamed,+ ) -> impl Future<Output = Result<(), rootcause::Report>> + Send {+ self.inner.publish_renamed(event)+ }++ fn publish_queue_changed(+ &self,+ event: AgentSessionQueueChanged,+ ) -> impl Future<Output = Result<(), rootcause::Report>> + Send {+ self.inner.publish_queue_changed(event)+ }++ fn publish_changes_updated(+ &self,+ session: AgentSessionId,+ ) -> impl Future<Output = Result<(), rootcause::Report>> + Send {+ self.inner.publish_changes_updated(session)+ }+}diff --git a/crates/agent_session/src/outbound/broker_log_realtime/test.rs b/crates/agent_session/src/outbound/broker_log_realtime/test.rsnew file mode 100644index 0000000000..8fff5ef743--- /dev/null+++ b/crates/agent_session/src/outbound/broker_log_realtime/test.rs@@ -0,0 +1,123 @@+use std::sync::{Arc, Mutex};++use agent_runtime_protocol::domain::schema::v0::{SystemEvent, ToServerMessage};+use macro_event_broker::{EventBrokerError, MacroEvent, MacroEventBroker};+use macro_uuid::Uuid;++use super::BrokerLogRealtime;+use crate::domain::model::{+ AgentSessionId, AgentSessionLog, LogAppended, Message, StoredAgentSessionLog,+};+use crate::domain::ports::{AgentSessionRealtime, NoOpRealtime};++#[derive(Debug, Clone)]+struct Published {+ topic: String,+ key: String,+ envelope: serde_json::Value,+}++/// Records what was handed to the broker, or refuses everything.+#[derive(Clone, Default)]+struct FakeBroker {+ published: Arc<Mutex<Vec<Published>>>,+ refuses: bool,+}++impl MacroEventBroker for FakeBroker {+ fn send_event<E: MacroEvent + ?Sized>(+ &self,+ event: &E,+ ) -> Result<tokio::task::JoinHandle<Result<(), EventBrokerError>>, EventBrokerError> {+ self.published+ .lock()+ .expect("fake broker is not poisoned")+ .push(Published {+ topic: event.topic().to_string(),+ key: event.key().to_string(),+ envelope: serde_json::to_value(event.event())?,+ });+ let refuses = self.refuses;+ Ok(tokio::spawn(async move {+ if refuses {+ Err(EventBrokerError::UnknownTopic("refused".to_owned()))+ } else {+ Ok(())+ }+ }))+ }+}++/// Counts what the wrapped realtime was handed.+#[derive(Clone, Default)]+struct CountingRealtime {+ published: Arc<Mutex<usize>>,+}++impl AgentSessionRealtime for CountingRealtime {+ async fn publish(&self, _event: LogAppended) -> Result<(), rootcause::Report> {+ *self.published.lock().expect("not poisoned") += 1;+ Ok(())+ }+}++fn appended() -> LogAppended {+ LogAppended {+ turn_state: None,+ agent_session_id: AgentSessionId::TEST_A,+ entries: vec![StoredAgentSessionLog {+ id: Uuid::from_u128(1),+ created_at: chrono::Utc::now(),+ entry: AgentSessionLog {+ agent_session_id: AgentSessionId::TEST_A,+ user_id: None,+ content: Message::ToServer(ToServerMessage::Event {+ event: SystemEvent::AcpReady,+ }),+ },+ }],+ }+}++#[tokio::test]+async fn publishes_the_run_to_both_the_inner_realtime_and_the_log_topic() {+ let broker = FakeBroker::default();+ let inner = CountingRealtime::default();+ let realtime = BrokerLogRealtime::new(inner.clone(), broker.clone());++ realtime.publish(appended()).await.expect("published");++ assert_eq!(*inner.published.lock().expect("not poisoned"), 1);+ let published = broker+ .published+ .lock()+ .expect("fake broker is not poisoned");+ assert_eq!(published.len(), 1);+ assert_eq!(published[0].topic, "macro.agent_session_log");+ assert_eq!(published[0].key, AgentSessionId::TEST_A.to_string());+ assert_eq!(+ published[0].envelope["event_type"],+ "agent_session_log.appended"+ );+ assert_eq!(published[0].envelope["schema_version"], 1);+ let entries = published[0].envelope["metadata"]["entries"]+ .as_array()+ .expect("entries");+ assert_eq!(entries.len(), 1);+ assert_eq!(entries[0]["id"], Uuid::from_u128(1).to_string());+ assert_eq!(entries[0]["content"]["direction"], "to_server");+}++#[tokio::test]+async fn a_refused_broker_publish_does_not_fail_the_append() {+ let broker = FakeBroker {+ refuses: true,+ ..FakeBroker::default()+ };+ let realtime = BrokerLogRealtime::new(NoOpRealtime, broker.clone());++ realtime+ .publish(appended())+ .await+ .expect("inner result wins");+}diff --git a/crates/agent_session/src/outbound/mod.rs b/crates/agent_session/src/outbound/mod.rsindex c7033f8b55..4dbf95a72f 100644--- a/crates/agent_session/src/outbound/mod.rs+++ b/crates/agent_session/src/outbound/mod.rs@@ -13,3 +13,6 @@ pub mod connection_gateway_realtime;/// Publishing lifecycle facts to the event broker.pub mod broker_lifecycle_publisher;++/// Mirroring each appended log run to the event broker.+pub mod broker_log_realtime;diff --git a/crates/agent_session_realtime/Cargo.toml b/crates/agent_session_realtime/Cargo.tomlnew file mode 100644index 0000000000..68669b64dd--- /dev/null+++ b/crates/agent_session_realtime/Cargo.toml@@ -0,0 +1,35 @@+[package]+edition = "2024"+name = "agent_session_realtime"+publish = false+version = "0.1.0"++[features]+# The Kafka consumer feeding the fan-out; without it only the ports and the+# fan-out service compile, for the GraphQL schema crate.+consumer = [+ "dep:kafka_util",+ "dep:rdkafka",+ "macro_event_broker/outbound",+]+default = ["consumer"]++[dependencies]+agent_session = { path = "../agent_session", default-features = false }+broadcast = { path = "../broadcast" }+kafka_util = { path = "../kafka_util", optional = true }+macro_event_broker = { path = "../macro_event_broker", default-features = false }+rdkafka = { workspace = true, optional = true }+rootcause = { workspace = true }+tokio = { workspace = true, features = ["sync", "time"] }+tokio-retry = { workspace = true }+tracing = { workspace = true }+workspace-hack = { version = "0.1", path = "../workspace-hack" }++[dev-dependencies]+agent_runtime_protocol = { path = "../agent_runtime_protocol" }+agent_session = { path = "../agent_session", default-features = false, features = ["test-utils"] }+chrono = { workspace = true }+macro_uuid = { path = "../macro_uuid" }+serde_json = { workspace = true }+tokio = { workspace = true, features = ["macros", "rt-multi-thread", "test-util", "time"] }diff --git a/crates/agent_session_realtime/src/domain/mod.rs b/crates/agent_session_realtime/src/domain/mod.rsnew file mode 100644index 0000000000..ab2737c77a--- /dev/null+++ b/crates/agent_session_realtime/src/domain/mod.rs@@ -0,0 +1,6 @@+//! Ports and orchestration for log-frame fan-out.++/// Inbound and outbound ports.+pub mod ports;+/// The fan-out service.+pub mod service;diff --git a/crates/agent_session_realtime/src/domain/ports.rs b/crates/agent_session_realtime/src/domain/ports.rsnew file mode 100644index 0000000000..e333543e9a--- /dev/null+++ b/crates/agent_session_realtime/src/domain/ports.rs@@ -0,0 +1,53 @@+//! Ports for log-frame fan-out.++use std::future::Future;++use agent_session::domain::events::LogAppendedMetadata;+use agent_session::domain::model::{AgentSessionId, StoredAgentSessionLog};+use rootcause::Report;++/// Receives runs of appended frames from wherever the harness published them.+pub trait AgentSessionLogConsumer: Send + Sync + 'static {+ /// Waits for and returns the next appended run.+ fn recv(&self) -> impl Future<Output = Result<LogAppendedMetadata, Report>> + Send;+}++/// Session-scoped subscriptions to received runs of frames.+///+/// Object safe on purpose: the GraphQL schema holds it erased in request+/// data rather than as one more type parameter.+pub trait AgentSessionLogSubscriptionService: Send + Sync + 'static {+ /// Subscribes to runs appended to `session_id` from now on. The receiver+ /// closes when the subscriber falls too far behind; a closed receiver+ /// means rows were missed and the subscriber must refetch the log.+ fn subscribe(+ &self,+ session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>>;+}++impl<S> AgentSessionLogSubscriptionService for std::sync::Arc<S>+where+ S: AgentSessionLogSubscriptionService + ?Sized,+{+ fn subscribe(+ &self,+ session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>> {+ self.as_ref().subscribe(session_id)+ }+}++/// Subscriptions that never deliver, for when only the schema shape is needed.+#[derive(Clone, Copy, Debug, Default)]+pub struct NoOpAgentSessionLogSubscriptionService;++impl AgentSessionLogSubscriptionService for NoOpAgentSessionLogSubscriptionService {+ fn subscribe(+ &self,+ _session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>> {+ let (_sender, receiver) = tokio::sync::mpsc::channel(1);+ receiver+ }+}diff --git a/crates/agent_session_realtime/src/domain/service.rs b/crates/agent_session_realtime/src/domain/service.rsnew file mode 100644index 0000000000..fad6340f24--- /dev/null+++ b/crates/agent_session_realtime/src/domain/service.rs@@ -0,0 +1,102 @@+//! Fan-out of received runs to per-session subscribers.++#[cfg(test)]+mod test;++use std::{num::NonZeroUsize, time::Duration};++use agent_session::domain::model::{AgentSessionId, StoredAgentSessionLog};+use broadcast::{BroadcastManager, GlobalSpawner};+use rootcause::prelude::{Report, ResultExt as _};+use tokio_retry::{Retry, strategy::ExponentialBackoff};++use super::ports::{AgentSessionLogConsumer, AgentSessionLogSubscriptionService};++/// Runs retained by each session-keyed broadcast channel.+const BROADCAST_BUFFER_CAPACITY: NonZeroUsize = NonZeroUsize::new(64).unwrap();+/// Runs buffered for each individual subscriber.+const SUBSCRIBER_BUFFER_CAPACITY: NonZeroUsize = NonZeroUsize::new(16).unwrap();+/// Total receive attempts before the consumer returns for supervision.+const MAX_RECEIVE_ATTEMPTS: usize = 5;++/// Retries after one, two, four, and eight seconds.+fn receive_retry_strategy() -> impl Iterator<Item = Duration> {+ ExponentialBackoff::from_millis(2)+ .factor(500)+ .take(MAX_RECEIVE_ATTEMPTS - 1)+}++/// Receives runs from `consumer` and hands each to the session's subscribers.+pub struct AgentSessionLogConsumerService<C>+where+ C: AgentSessionLogConsumer,+{+ consumer: C,+ broadcasts: BroadcastManager<GlobalSpawner, AgentSessionId, Vec<StoredAgentSessionLog>>,+}++impl<C> AgentSessionLogConsumerService<C>+where+ C: AgentSessionLogConsumer,+{+ /// Fan out what `consumer` receives.+ pub fn new(consumer: C) -> Self {+ Self {+ consumer,+ broadcasts: BroadcastManager::new(GlobalSpawner, BROADCAST_BUFFER_CAPACITY),+ }+ }++ /// Subscribes to runs appended to `session_id`.+ ///+ /// The receiver is closed if its buffer fills, so a slow subscriber+ /// cannot delay the shared consumer or other subscribers.+ #[must_use]+ pub fn subscribe(+ &self,+ session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>> {+ self.broadcasts+ .subscribe(session_id, SUBSCRIBER_BUFFER_CAPACITY)+ .into_receiver()+ }++ /// Receives runs and distributes them until reception fails for good.+ ///+ /// Run this in a supervised task. A run for a session nobody subscribed+ /// to is dropped: the durable log already has it.+ #[tracing::instrument(skip(self), err)]+ pub async fn run(&self) -> Result<(), Report> {+ loop {+ let appended = Retry::start(receive_retry_strategy(), || self.consumer.recv())+ .await+ .context(format!(+ "failed to receive appended agent session log frames after {MAX_RECEIVE_ATTEMPTS} attempts"+ ))?;+ let session_id = appended.agent_session_id;+ match self.broadcasts.publish(&session_id, appended.into_stored()) {+ Ok(subscriber_count) => tracing::trace!(+ %session_id,+ subscriber_count,+ "distributed appended agent session log frames"+ ),+ Err(_) => tracing::trace!(+ %session_id,+ "dropping appended agent session log frames without subscribers"+ ),+ }+ }+ }+}++impl<C> AgentSessionLogSubscriptionService for AgentSessionLogConsumerService<C>+where+ C: AgentSessionLogConsumer,+{+ fn subscribe(+ &self,+ session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>> {+ AgentSessionLogConsumerService::subscribe(self, session_id)+ }+}diff --git a/crates/agent_session_realtime/src/domain/service/test.rs b/crates/agent_session_realtime/src/domain/service/test.rsnew file mode 100644index 0000000000..8675d91abf--- /dev/null+++ b/crates/agent_session_realtime/src/domain/service/test.rs@@ -0,0 +1,86 @@+use std::sync::{Arc, Mutex};++use agent_runtime_protocol::domain::schema::v0::{SystemEvent, ToServerMessage};+use agent_session::domain::events::{LogAppendedEntry, LogAppendedMetadata};+use agent_session::domain::model::{AgentSessionId, Message};+use macro_uuid::Uuid;+use rootcause::Report;++use super::AgentSessionLogConsumerService;+use crate::domain::ports::AgentSessionLogConsumer;++/// Hands out queued runs, then blocks forever.+#[derive(Clone, Default)]+struct QueuedConsumer {+ runs: Arc<Mutex<Vec<LogAppendedMetadata>>>,+}++impl AgentSessionLogConsumer for QueuedConsumer {+ async fn recv(&self) -> Result<LogAppendedMetadata, Report> {+ loop {+ let next = self.runs.lock().expect("not poisoned").pop();+ match next {+ Some(run) => return Ok(run),+ None => tokio::time::sleep(std::time::Duration::from_millis(5)).await,+ }+ }+ }+}++fn run(session: AgentSessionId, ids: impl IntoIterator<Item = u128>) -> LogAppendedMetadata {+ LogAppendedMetadata {+ agent_session_id: session,+ entries: ids+ .into_iter()+ .map(|id| LogAppendedEntry {+ id: Uuid::from_u128(id),+ created_at: chrono::Utc::now(),+ user_id: None,+ content: Message::ToServer(ToServerMessage::Event {+ event: SystemEvent::AcpReady,+ }),+ })+ .collect(),+ }+}++#[tokio::test]+async fn delivers_each_run_to_its_sessions_subscribers_as_stored_rows() {+ let consumer = QueuedConsumer::default();+ let service = Arc::new(AgentSessionLogConsumerService::new(consumer.clone()));+ let mut a = service.subscribe(AgentSessionId::TEST_A);+ let mut b = service.subscribe(AgentSessionId::TEST_B);+ let running = tokio::spawn({+ let service = Arc::clone(&service);+ async move { service.run().await }+ });++ consumer.runs.lock().expect("not poisoned").extend([+ run(AgentSessionId::TEST_B, [3]),+ run(AgentSessionId::TEST_A, [1, 2]),+ ]);++ let rows = tokio::time::timeout(std::time::Duration::from_secs(2), a.recv())+ .await+ .expect("delivered in time")+ .expect("open");+ assert_eq!(+ rows.iter().map(|row| row.id).collect::<Vec<_>>(),+ [Uuid::from_u128(1), Uuid::from_u128(2)]+ );+ assert!(+ rows.iter()+ .all(|row| row.entry.agent_session_id == AgentSessionId::TEST_A)+ );+ let rows = tokio::time::timeout(std::time::Duration::from_secs(2), b.recv())+ .await+ .expect("delivered in time")+ .expect("open");+ assert_eq!(rows.len(), 1);+ assert_eq!(rows[0].id, Uuid::from_u128(3));+ assert!(+ a.try_recv().is_err(),+ "a session's run does not reach another session"+ );+ running.abort();+}diff --git a/crates/agent_session_realtime/src/lib.rs b/crates/agent_session_realtime/src/lib.rsnew file mode 100644index 0000000000..94bbbc1c90--- /dev/null+++ b/crates/agent_session_realtime/src/lib.rs@@ -0,0 +1,13 @@+#![deny(missing_docs)]+//! Session-scoped fan-out of appended agent session log frames.+//!+//! The harness publishes each run of frames it stores to+//! `macro.agent_session_log`; a process serving viewers over GraphQL consumes+//! that topic here and hands each run to whoever subscribed to the session.+//! No composition root and no tasks are started here.++/// Ports and the fan-out service.+pub mod domain;+/// The Kafka consumer feeding the fan-out.+#[cfg(feature = "consumer")]+pub mod outbound;diff --git a/crates/agent_session_realtime/src/outbound/log_topic_consumer.rs b/crates/agent_session_realtime/src/outbound/log_topic_consumer.rsnew file mode 100644index 0000000000..1c9118834f--- /dev/null+++ b/crates/agent_session_realtime/src/outbound/log_topic_consumer.rs@@ -0,0 +1,111 @@+//! Independent Kafka consumer of appended agent session log frames.+//!+//! Every process receives every run published after it starts: the adapter+//! manually assigns all `macro.agent_session_log` partitions without joining+//! a durable consumer group, and commits no offsets. A viewer who missed a+//! run while this process was down refetches the durable log, which is what+//! the receiver closing tells them to do.++#[cfg(test)]+mod test;++use std::time::Duration;++use agent_session::domain::events::{+ AgentSessionLogMacroEvent, AgentSessionLogTopicEvent, LogAppendedMetadata,+};+use kafka_util::{InitialOffset, KafkaEventConsumer, Ungrouped};+use macro_event_broker::{+ EventBrokerError, KafkaConsumerAdapter, MacroEventCollection, MacroEventConsumerService,+};+use rdkafka::message::Message as _;+use rootcause::prelude::{Report, ResultExt as _};++use crate::domain::ports::AgentSessionLogConsumer;++/// Maximum time to wait for topic metadata during partition assignment.+const TOPIC_METADATA_TIMEOUT: Duration = Duration::from_secs(10);++type IndependentKafkaConsumer = KafkaConsumerAdapter<Ungrouped, DeclaredMacroEvent>;+type LogEventConsumer = MacroEventConsumerService<DeclaredMacroEvent, IndependentKafkaConsumer>;++macro_event_broker::declare_topics!(DeclaredMacroEvent: AgentSessionLogMacroEvent);++/// Independent consumer of appended agent session log frames.+///+/// Starts at the end of every current partition, so it receives only runs+/// published after construction. Partitions added later need a new consumer.+pub struct LogTopicConsumer {+ consumer: LogEventConsumer,+}++impl LogTopicConsumer {+ /// Creates a consumer and assigns every current partition of the topic.+ #[tracing::instrument(fields(brokers), err)]+ pub fn from_env(brokers: &str) -> Result<Self, Report> {+ let consumer = KafkaEventConsumer::<Ungrouped>::from_env(brokers)+ .context("failed to create independent agent session log consumer")?;+ let consumer =+ IndependentKafkaConsumer::new(consumer, InitialOffset::Latest, TOPIC_METADATA_TIMEOUT)+ .context("failed to assign agent session log topic partitions")?;+ tracing::info!(+ topics = ?DeclaredMacroEvent::topics(),+ "independent agent session log consumer listening"+ );+ Ok(Self {+ consumer: LogEventConsumer::new(consumer),+ })+ }++ /// Receives and decodes the next run.+ ///+ /// Cancel-safe. An unsupported schema version is a poison record and is+ /// skipped; other malformed payloads are returned as errors.+ pub async fn recv(&self) -> Result<LogAppendedMetadata, Report> {+ loop {+ let message = self+ .consumer+ .recv()+ .await+ .context("failed to receive agent session log event")?;+ let event = match message.decode_payload() {+ Ok(event) => event,+ Err(EventBrokerError::UnsupportedSchemaVersion {+ topic,+ expected,+ actual,+ }) => {+ let kafka_message = message.inner();+ tracing::warn!(+ topic,+ expected,+ actual,+ partition = kafka_message.partition(),+ offset = kafka_message.offset(),+ "dropping agent session log event with unsupported schema version"+ );+ continue;+ }+ Err(error) => {+ return Err(Report::new(error)+ .context("failed to decode agent session log event")+ .into_dynamic());+ }+ };++ return match event {+ DeclaredMacroEvent::AgentSessionLogMacroEvent(event) => {+ let AgentSessionLogTopicEvent::Appended(appended) = event.into_payload();+ Ok(appended)+ }+ };+ }+ }+}++impl AgentSessionLogConsumer for LogTopicConsumer {+ #[tracing::instrument(err, skip(self))]+ async fn recv(&self) -> Result<LogAppendedMetadata, Report> {+ LogTopicConsumer::recv(self).await+ }+}diff --git a/crates/agent_session_realtime/src/outbound/log_topic_consumer/test.rs b/crates/agent_session_realtime/src/outbound/log_topic_consumer/test.rsnew file mode 100644index 0000000000..03ba676ffb--- /dev/null+++ b/crates/agent_session_realtime/src/outbound/log_topic_consumer/test.rs@@ -0,0 +1,83 @@+use agent_runtime_protocol::domain::schema::v0::{SystemEvent, ToServerMessage};+use agent_session::domain::model::Message;+use macro_event_broker::{+ EventBrokerError, MacroEventCollection as _, MessageParts, MessageWrapper,+};++use super::DeclaredMacroEvent;++struct TestMessage {+ payload: Vec<u8>,+}++impl MessageParts for TestMessage {+ fn key(&self) -> Option<&str> {+ Some("0000000a-0000-0000-0000-000000000000")+ }++ fn payload(&self) -> Option<&[u8]> {+ Some(&self.payload)+ }++ fn topic(&self) -> &str {+ "macro.agent_session_log"+ }+}++#[test]+fn assigns_only_the_log_topic() {+ assert_eq!(DeclaredMacroEvent::topics(), ["macro.agent_session_log"]);+}++#[test]+fn decodes_an_appended_run() {+ let content = serde_json::to_value(Message::ToServer(ToServerMessage::Event {+ event: SystemEvent::AcpReady,+ }))+ .expect("serializable");+ let message = MessageWrapper::<_, DeclaredMacroEvent>::new(TestMessage {+ payload: serde_json::to_vec(&serde_json::json!({+ "event_id": "00000000-0000-0000-0000-000000000001",+ "schema_version": 1,+ "event_type": "agent_session_log.appended",+ "metadata": {+ "agent_session_id": "0000000a-0000-0000-0000-000000000000",+ "entries": [{+ "id": "00000000-0000-0000-0000-000000000001",+ "created_at": "2026-08-13T12:34:56.789Z",+ "user_id": null,+ "content": content+ }]+ }+ }))+ .expect("serializable"),+ });++ let DeclaredMacroEvent::AgentSessionLogMacroEvent(event) =+ message.decode_payload().expect("decodes");+ let super::AgentSessionLogTopicEvent::Appended(appended) = event.into_payload();+ let rows = appended.into_stored();+ assert_eq!(rows.len(), 1);+ assert_eq!(+ rows[0].entry.agent_session_id.to_string(),+ "0000000a-0000-0000-0000-000000000000"+ );+}++#[test]+fn rejects_unsupported_schema_versions() {+ let message = MessageWrapper::<_, DeclaredMacroEvent>::new(TestMessage {+ payload: serde_json::to_vec(&serde_json::json!({+ "event_id": "00000000-0000-0000-0000-000000000001",+ "schema_version": 2,+ "event_type": "agent_session_log.appended",+ "metadata": { "agent_session_id": "0000000a-0000-0000-0000-000000000000", "entries": [] }+ }))+ .expect("serializable"),+ });++ assert!(matches!(+ message.decode_payload(),+ Err(EventBrokerError::UnsupportedSchemaVersion { .. })+ ));+}diff --git a/crates/agent_session_realtime/src/outbound/mod.rs b/crates/agent_session_realtime/src/outbound/mod.rsnew file mode 100644index 0000000000..f2bc298bf1--- /dev/null+++ b/crates/agent_session_realtime/src/outbound/mod.rs@@ -0,0 +1,4 @@+//! Transport adapters feeding the fan-out.++/// Independent Kafka consumer of `macro.agent_session_log`.+pub mod log_topic_consumer;diff --git a/crates/complete_graph/Cargo.toml b/crates/complete_graph/Cargo.tomlindex b6bb176d72..76aca34cbf 100644--- a/crates/complete_graph/Cargo.toml+++ b/crates/complete_graph/Cargo.toml@@ -11,6 +11,8 @@ anyhow = { workspace = true }async-graphql = { workspace = true, features = ["dataloader"] }axum = { workspace = true }agent_session = { path = "../agent_session", default-features = false }+agent_session_realtime = { path = "../agent_session_realtime", default-features = false }+async-stream = { workspace = true }bots = { path = "../bots", default-features = false, features = ["ports"] }email = { path = "../email", default-features = false, features = ["axum",@@ -54,6 +56,7 @@ workspace-hack = { version = "0.1", path = "../workspace-hack" }[dev-dependencies]activity = { path = "../activity", default-features = false, features = ["realtime"] }+agent_runtime_protocol = { path = "../agent_runtime_protocol" }apollo-compiler = { workspace = true }chrono = { workspace = true }model_owner = { path = "../model_owner" }diff --git a/crates/complete_graph/src/lib.rs b/crates/complete_graph/src/lib.rsindex b6ebfae0df..ad9409777f 100644--- a/crates/complete_graph/src/lib.rs+++ b/crates/complete_graph/src/lib.rs@@ -7,6 +7,7 @@/// Cross-domain fields composed onto Soup entities.mod edges;+mod realtime;/// Complete schema types and construction helpers.mod schema;#[cfg(test)]@@ -69,6 +70,7 @@ pub use graphql_properties::{PropertiesEntityPropertyReader, PropertiesEntityPropertyWriter, PropertiesMutationRoot,entity_properties_loader,};+pub use realtime::{AgentSessionLogSubscriptions, agent_session_log_subscriptions};pub use schema::{EmailThreadInput, SchemaOnlySoupSchema, SchemaOnlyState, SharedSoupSchema, SoupQueryRoot,SoupSchema, SoupSubscriptionRoot, build_schema, build_schema_from_arc, build_schema_from_arcs,diff --git a/crates/complete_graph/src/realtime.rs b/crates/complete_graph/src/realtime.rsnew file mode 100644index 0000000000..807967385e--- /dev/null+++ b/crates/complete_graph/src/realtime.rs@@ -0,0 +1,29 @@+//! Where a log subscription gets its frames: request data the composition+//! root fills, so the schema needs no type parameter for it.++use std::sync::Arc;++use agent_session::domain::model::{AgentSessionId, StoredAgentSessionLog};+use agent_session_realtime::domain::ports::AgentSessionLogSubscriptionService;++/// The fan-out a `agentSessionLogAppended` subscription draws from.+#[derive(Clone)]+pub struct AgentSessionLogSubscriptions(Arc<dyn AgentSessionLogSubscriptionService>);++impl AgentSessionLogSubscriptions {+ /// Subscribe to runs appended to `session_id` from now on.+ #[must_use]+ pub fn subscribe(+ &self,+ session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>> {+ self.0.subscribe(session_id)+ }+}++/// Request data for log subscriptions, over `service`.+pub fn agent_session_log_subscriptions(+ service: impl AgentSessionLogSubscriptionService,+) -> AgentSessionLogSubscriptions {+ AgentSessionLogSubscriptions(Arc::new(service))+}diff --git a/crates/complete_graph/src/schema.rs b/crates/complete_graph/src/schema.rsindex d31e23e3a7..0b034ce4dd 100644--- a/crates/complete_graph/src/schema.rs+++ b/crates/complete_graph/src/schema.rs@@ -3,6 +3,9 @@ mod test;use std::{marker::PhantomData, sync::Arc};+use crate::edges::GraphqlAgentSessionLogEntry;+use crate::realtime::AgentSessionLogSubscriptions;+use agent_session::domain::model::AgentSessionId;use async_graphql::{Context, ID, MergedObject, MergedSubscription, Object, Schema, Subscription};use axum::extract::FromRef;use email::{@@ -606,6 +609,48 @@ whereresolve_soup_updates::<R, Auth, St, SoupEdges<NR, PR, ER, FR, AR, AcR>>(&self.service, ctx).await}++ /// Frames appended to one accessible agent session's log from now on,+ /// one run per flush, in log order. Each entry is the row `agentSession.log`+ /// serves, so a subscriber folds the same bytes a reader of the log does.+ /// The stream ends with an error when the subscriber falls behind: rows+ /// were missed, and the log must be refetched.+ async fn agent_session_log_appended(+ &self,+ ctx: &Context<'_>,+ session_id: ID,+ ) -> async_graphql::Result<+ impl async_graphql::futures_util::Stream<+ Item = async_graphql::Result<Vec<GraphqlAgentSessionLogEntry>>,+ > + 'static,+ > {+ let user_id = require_authorized_user::<Auth, St>(ctx).await?;+ let session_id = parse_id(session_id, "sessionId")?;+ // Access is what `agentSession` checks: a session the viewer cannot+ // read is one they cannot follow either.+ let accessible = resolve_soup_agent_session::<SoupEdges<NR, PR, ER, FR, AR, AcR>>(+ ctx, user_id, session_id,+ )+ .await?+ .is_some();+ if !accessible {+ return Err(async_graphql::Error::new("agent session not found"));+ }+ let subscriptions = ctx.data::<AgentSessionLogSubscriptions>()?;+ let mut receiver = subscriptions.subscribe(AgentSessionId::new_from_uuid(session_id));+ Ok(async_stream::stream! {+ while let Some(rows) = receiver.recv().await {+ yield rows+ .into_iter()+ .map(GraphqlAgentSessionLogEntry::try_from)+ .collect::<Result<Vec<_>, _>>()+ .map_err(|error| async_graphql::Error::new(error.to_string()));+ }+ yield Err(async_graphql::Error::new(+ "agent session log subscription closed after falling behind",+ ));+ })+ }}/// The authenticated user and their user-scoped data.diff --git a/crates/complete_graph/src/schema/test.rs b/crates/complete_graph/src/schema/test.rsindex cee583c324..fa8c66b18e 100644--- a/crates/complete_graph/src/schema/test.rs+++ b/crates/complete_graph/src/schema/test.rs@@ -90,6 +90,30 @@ fn soup_document(id: Uuid) -> SoupItem<()> {grouped_document(id).map_extra(|_| ())}+fn soup_agent_session(id: Uuid) -> SoupItem<()> {+ SoupItem::AgentSession(models_soup::agent_session::SoupAgentSession {+ id,+ name: "A session".to_string(),+ is_archived: false,+ owner_id: Owner::from_principal_str(VALID_USER_ID).unwrap(),+ bot_id: Uuid::from_u128(99),+ harness: "claude".to_string(),+ repo_url: None,+ repo_branch: None,+ pull_request_url: None,+ working_branch: None,+ pull_request_state: None,+ pull_request_id: None,+ turn_state: None,+ thread_id: None,+ status: "no_messages".to_string(),+ created_at: Default::default(),+ updated_at: Default::default(),+ viewed_at: None,+ extra: (),+ })+}+fn soup_initiative(id: Uuid) -> SoupItem<()> {SoupItem::Initiative(SoupInitiative {id,@@ -1326,6 +1350,127 @@ async fn soup_updates_subscribes_as_the_authenticated_user() {);}+#[tokio::test]+async fn agent_session_log_appended_streams_runs_for_an_accessible_session() {+ use agent_runtime_protocol::domain::schema::v0::{SystemEvent, ToServerMessage};+ use agent_session::domain::model::{+ AgentSessionId, AgentSessionLog, Message, StoredAgentSessionLog,+ };+ use agent_session_realtime::domain::ports::AgentSessionLogSubscriptionService;+ use async_graphql::futures_util::{StreamExt as _, pin_mut};++ struct TestLogSubscriptions {+ receiver: Arc<Mutex<Option<tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>>>>>,+ subscribed: Arc<Mutex<Option<AgentSessionId>>>,+ }++ impl AgentSessionLogSubscriptionService for TestLogSubscriptions {+ fn subscribe(+ &self,+ session_id: AgentSessionId,+ ) -> tokio::sync::mpsc::Receiver<Vec<StoredAgentSessionLog>> {+ *self.subscribed.lock().expect("subscribed lock") = Some(session_id);+ self.receiver+ .lock()+ .expect("receiver lock")+ .take()+ .expect("subscribed once")+ }+ }++ let user_id = MacroUserIdStr::parse_from_str(VALID_USER_ID).unwrap();+ let session_id = Uuid::from_u128(7);+ let other_session_id = Uuid::from_u128(8);+ let (sender, receiver) = tokio::sync::mpsc::channel(2);+ let subscribed = Arc::new(Mutex::new(None));+ let subscriptions = crate::agent_session_log_subscriptions(TestLogSubscriptions {+ receiver: Arc::new(Mutex::new(Some(receiver))),+ subscribed: Arc::clone(&subscribed),+ });+ let soup_service = CountingSoupService::default();+ soup_service.set_raw_response(vec![soup_agent_session(session_id)]);+ let loader = graphql_soup::soup_item_loader(soup_service.clone(), Arc::new(NoOpEmailService));+ let schema = build_schema_with_service::<+ CountingSoupService,+ NoOpEmailService,+ NoOpEntityAccessService,+ SchemaOnlyAuthorizationService,+ SchemaOnlyState,+ NoOpEntityPropertyWriter,+ UnavailableEntityMutationService,+ NoOpFavoriteMutationService,+ NoOpChannelActivityMutationService,+ NoOpNotificationMutationService,+ NoOpSoupNotificationEdgeReader,+ NoOpEntityPropertyReader,+ NoOpSoupEmailContentEdgeReader,+ NoOpEntityFavoriteEdgeReader,+ NoOpEntityPermissionEdgeReader,+ NoOpActivityReader,+ >(soup_service);+ let query = format!(+ "subscription {{ agentSessionLogAppended(sessionId: \"{session_id}\") {{ id userId direction content }} }}"+ );++ // A session the viewer cannot see cannot be followed.+ let refused = schema+ .execute_stream(+ async_graphql::Request::new(format!(+ "subscription {{ agentSessionLogAppended(sessionId: \"{other_session_id}\") {{ id }} }}"+ ))+ .data(user_id.clone())+ .data(loader.clone())+ .data(subscriptions.clone()),+ )+ .next()+ .await+ .expect("one response");+ assert!(!refused.errors.is_empty());+ assert!(subscribed.lock().expect("subscribed lock").is_none());++ let responses = schema.execute_stream(+ async_graphql::Request::new(query)+ .data(user_id)+ .data(loader)+ .data(subscriptions),+ );+ pin_mut!(responses);+ sender+ .send(vec![StoredAgentSessionLog {+ id: Uuid::from_u128(1),+ created_at: Default::default(),+ entry: AgentSessionLog {+ agent_session_id: AgentSessionId::new_from_uuid(session_id),+ user_id: None,+ content: Message::ToServer(ToServerMessage::Event {+ event: SystemEvent::AcpReady,+ }),+ },+ }])+ .await+ .expect("subscription remains open");+ drop(sender);++ let response = responses.next().await.expect("a run");+ assert!(response.errors.is_empty(), "{:?}", response.errors);+ let data = response.data.into_json().expect("response data is JSON");+ let run = data["agentSessionLogAppended"]+ .as_array()+ .expect("a run is a list");+ assert_eq!(run.len(), 1);+ assert_eq!(run[0]["id"], Uuid::from_u128(1).to_string());+ assert_eq!(run[0]["direction"], "to_server");+ assert!(run[0]["content"].is_object());+ assert_eq!(+ *subscribed.lock().expect("subscribed lock"),+ Some(AgentSessionId::new_from_uuid(session_id))+ );+ // The fan-out closing means rows were missed: the stream ends with an error.+ let closed = responses.next().await.expect("a closing response");+ assert!(!closed.errors.is_empty());+ assert!(responses.next().await.is_none());+}+#[tokio::test]async fn activity_updates_subscribes_as_the_authenticated_user() {use activity::{diff --git a/crates/macro_event_topics/src/lib.rs b/crates/macro_event_topics/src/lib.rsindex 811fc46388..30042476f8 100644--- a/crates/macro_event_topics/src/lib.rs+++ b/crates/macro_event_topics/src/lib.rs@@ -85,6 +85,8 @@ topics! {MacroCalendarTopic => "macro.calendar",/// Agent session lifecycle facts: opened, turns, waiting for input, settled, stopped, renamed, deleted.MacroAgentSessionLifecycleTopic => "macro.agent_session_lifecycle",+ /// Runs of frames appended to an agent session's log, for realtime viewers served by another process.+ MacroAgentSessionLogTopic => "macro.agent_session_log",/// Database lifecycle (created, renamed, trashed, restored, purged) and table-change events.MacroDatabasesTopic => "macro.databases",}diff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rsindex 9187da8f01..7da454a3a9 100644--- a/services/agent_harness_service/src/main.rs+++ b/services/agent_harness_service/src/main.rs@@ -94,6 +94,7 @@ use agent_session::inbound::axum_router::{AgentSessionControlState, AgentSessionRouterState, CreateSessionState,};use agent_session::outbound::broker_lifecycle_publisher::BrokerLifecyclePublisher;+use agent_session::outbound::broker_log_realtime::BrokerLogRealtime;use agent_session::outbound::connection_gateway_realtime::ConnectionGatewayAgentSessionRealtime;use agent_session::outbound::name_generator::HaikuAgentSessionNameGenerator;use agent_session::outbound::postgres::PgAgentSessionRepo;@@ -312,9 +313,14 @@ async fn run() -> anyhow::Result<()> {let sessions = AgentSessionServiceImpl::new(session_repo.clone(),FoldedMessageService::new(session_repo.clone()),- ConnectionGatewayAgentSessionRealtime::new(- connection_gateway.clone(),- session_audience.clone(),+ // Frames reach this process's viewers through the gateway and every+ // other process's through the broker (the GraphQL log subscription).+ BrokerLogRealtime::new(+ ConnectionGatewayAgentSessionRealtime::new(+ connection_gateway.clone(),+ session_audience.clone(),+ ),+ broker.clone(),),agent_session::domain::name_generation::AdmittedAgentSessionNameGenerator::new(HaikuAgentSessionNameGenerator::new(recorder.clone()),diff --git a/services/document_storage_service/Cargo.toml b/services/document_storage_service/Cargo.tomlindex 92879c0397..9ac7a82ccb 100644--- a/services/document_storage_service/Cargo.toml+++ b/services/document_storage_service/Cargo.toml@@ -34,6 +34,7 @@ agent_changes = { path = "../../crates/agent_changes", default-features = false,dictation = { path = "../../crates/dictation", features = ["inbound", "outbound"] }initiative_description = { path = "../../crates/initiative_description" }agent_session = { path = "../../crates/agent_session", features = ["outbound"] }+agent_session_realtime = { path = "../../crates/agent_session_realtime" }activity = { path = "../../crates/activity" }ai_tools = { path = "../../crates/ai_tools" }ai_usage = { path = "../../crates/ai_usage" }diff --git a/services/document_storage_service/src/api/context.rs b/services/document_storage_service/src/api/context.rsindex ee646e0d54..5ee26c4545 100644--- a/services/document_storage_service/src/api/context.rs+++ b/services/document_storage_service/src/api/context.rs@@ -757,6 +757,7 @@ pub(crate) struct ApiContext {pub dynamo_db: aws_sdk_dynamodb::Client,pub soup_router_state: DssSoupState,pub graphql_soup_schema: DssGraphqlSoupSchema,+ pub agent_session_log_subscriptions: complete_graph::AgentSessionLogSubscriptions,pub graphql_notification_reader: Arc<ai_tools::ToolNotificationService>,pub activity_reader: DssActivityReader,pub graphql_entity_mutation_service: Arc<DssEntityMutationService>,diff --git a/services/document_storage_service/src/api/graphql_soup.rs b/services/document_storage_service/src/api/graphql_soup.rsindex 4ff7833305..a62cb7934a 100644--- a/services/document_storage_service/src/api/graphql_soup.rs+++ b/services/document_storage_service/src/api/graphql_soup.rs@@ -184,6 +184,7 @@ fn insert_graphql_context_data(data.insert(state.soup_router_state.email_service());data.insert(state.entity_access_service.clone());data.insert(soup_item_loader);+ data.insert(state.agent_session_log_subscriptions.clone());// Mutation replies must read their committed state from the primary email// service. Ordinary Soup lists and subscriptions retain their own reader.data.insert(email_mutation_thread_loader(diff --git a/services/document_storage_service/src/main.rs b/services/document_storage_service/src/main.rsindex b5b57eeae5..e53ac5fa80 100644--- a/services/document_storage_service/src/main.rs+++ b/services/document_storage_service/src/main.rs@@ -12,6 +12,9 @@ use crate::{},service::s3::S3,};+use agent_session_realtime::{+ domain::service::AgentSessionLogConsumerService, outbound::log_topic_consumer::LogTopicConsumer,+};use analytics_client::{AnalyticsClient, AnalyticsClientConfig, MetaConfig};use anyhow::Context;use bots::{domain::service::BotServiceImpl, outbound::pg_bots_repo::PgBotsRepo};@@ -1617,6 +1620,42 @@ async fn run() -> anyhow::Result<()> {}});+ let agent_session_log_realtime = Arc::new(AgentSessionLogConsumerService::new(+ LogTopicConsumer::from_env(config.kafka_brokers.as_ref()).map_err(|error| {+ anyhow::anyhow!("failed to create agent session log topic consumer: {error:?}")+ })?,+ ));+ consumer_tracker.spawn({+ let service = Arc::clone(&agent_session_log_realtime);+ let cancellation_token = consumer_cancellation_token.clone();+ async move {+ loop {+ let result = tokio::select! {+ biased;+ _ = cancellation_token.cancelled() => break,+ result = service.run() => result,+ };++ if cancellation_token.is_cancelled() {+ break;+ }++ let _ = result.inspect_err(|error| {+ tracing::error!(+ error = ?error,+ "agent session log subscription consumer stopped"+ );+ });++ tokio::select! {+ biased;+ _ = cancellation_token.cancelled() => break,+ _ = tokio::time::sleep(Duration::from_secs(1)) => {}+ }+ }+ }+ });+consumer_tracker.spawn({let brokers = config.kafka_brokers.as_ref().to_string();let entity_access_service = entity_access_service.as_ref().clone();@@ -1867,6 +1906,9 @@ async fn run() -> anyhow::Result<()> {websocket_notification_consumer_service,activity_realtime_service,),+ agent_session_log_subscriptions: complete_graph::agent_session_log_subscriptions(+ agent_session_log_realtime,+ ),graphql_notification_reader,// GraphQL reads the activity log through the readonly pool; the// Kafka consumer's writer-pool repo above is separate on purpose.diff --git a/static_assets/schema.graphql b/static_assets/schema.graphqlindex 28a9d5bc49..9a20b825e8 100644--- a/static_assets/schema.graphql+++ b/static_assets/schema.graphql@@ -183,6 +183,14 @@ type CompleteSubscriptionRoot {"""soupUpdates: [SoupPatch!]!"""+ Frames appended to one accessible agent session's log from now on,+ one run per flush, in log order. Each entry is the row `agentSession.log`+ serves, so a subscriber folds the same bytes a reader of the log does.+ The stream ends with an error when the subscriber falls behind: rows+ were missed, and the log must be refetched.+ """+ agentSessionLogAppended(sessionId: ID!): [GraphqlAgentSessionLogEntry!]!+ """Subscribe to realtime notifications for the authenticated user."""notificationUpdates: GraphqlNotificationPatch!