Skip to content

armgit / macro

Public Imported from GitHub
0

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

feat(agent-session): stream log rows over a GraphQL subscription (#7531)

Wolf Mermelstein033aa9ae2007
diff --git a/.github/kafka-cluster-topics.json b/.github/kafka-cluster-topics.json
index 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.json
index 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.lock
index 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.toml
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.graphql
new file mode 100644
index 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.ts
index 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":"Ope
export 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.rs
index 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.rs
new file mode 100644
index 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(&macro_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.rs
new file mode 100644
index 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.rs
index 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.toml
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.toml
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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 @@ where
resolve_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.rs
index 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.rs
index 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.rs
index 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.toml
index 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.rs
index 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.rs
index 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.rs
index 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.graphql
index 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!