Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat: add agent event correlation utility and integrate it into heartbeat and event streams

0xken152b9cd7bf8412
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index dee3f2304..3f1d28d2b 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -3,6 +3,7 @@ import { readFileSync } from 'fs'
import { fileURLToPath } from 'url'
import { BackendSocket, compactRuntimePickerModels, deviceAgentListItem, grokHistoryPage } from './backendSocket.js'
import type { TerminalStreamManager } from './lib/terminalStreamManager.js'
+import { registry, type RegisteredSession } from './lib/registry.js'
const wsMock = vi.hoisted(() => {
const instances: MockWebSocket[] = []
@@ -175,6 +176,56 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
+ it('includes engine session correlation in the web agent list', async () => {
+ const session: RegisteredSession = {
+ schemaVersion: 2,
+ active: true,
+ agentId: 'agent-1',
+ sessionId: 'session-1',
+ boundAt: 1,
+ engine: 'codex',
+ transcriptPath: null,
+ projectDir: 'workspace',
+ cwd: '/tmp/workspace',
+ runtimes: [],
+ primaryRuntimeKey: '',
+ tmuxPane: '',
+ source: null,
+ title: 'Agent one',
+ model: null,
+ cliVersion: null,
+ processIdentity: null,
+ registeredAt: 1,
+ updatedAt: 1,
+ lastHookAt: 1,
+ lastTranscriptAt: 1,
+ }
+ vi.spyOn(registry, 'active').mockReturnValue([session])
+ const socket = new BackendSocket('token')
+ socket.connect()
+ const ws = wsMock.instances[0]
+ ws.open()
+ vi.spyOn(socket.e2ee, 'unwrapDown').mockReturnValue({
+ type: 'agents_list', payload: { requestId: 'agents-1' },
+ })
+ vi.spyOn(socket.e2ee, 'hasSession').mockReturnValue(true)
+ const wrapReply = vi.spyOn(socket.e2ee, 'wrapRpcReply').mockReturnValue({
+ type: 'agents_list_result', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } },
+ })
+ ws.message({
+ t: 'down',
+ connId: 'web-1',
+ frame: { type: 'agents_list', payload: { __e2e: { v: 1, k: 's', n: 1, ct: 'ciphertext' } } },
+ })
+
+ await vi.waitFor(() => {
+ expect(wrapReply).toHaveBeenCalledWith('web-1', 'agents_list_result', 'agents-1', {
+ agents: [expect.objectContaining({ id: 'agent-1', sessionId: 'session-1', engine: 'codex' })],
+ })
+ })
+ await socket.stop()
+ })
+
it('filters and compacts the runtime catalog for a device agent', async () => {
const socket = new BackendSocket('token')
const provider = vi.fn(async (_sessionId?: string) => [
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 7b1c0c5a6..f0aade3ba 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -107,6 +107,7 @@ import { adaptSlashCommand } from './lib/goalCommand.js'
import { RuntimeProfileManager } from './lib/runtimeProfile.js'
import { RuntimeProfileController } from './lib/runtimeProfileController.js'
import { deviceErrorText } from './lib/deviceErrors.js'
+import { correlateAgentEvent, turnHeartbeatFrame } from './lib/agentEvent.js'
import {
installTimestampedConsole, sid, preview,
prepareLogFile, trimLogFile, LOG_CHECK_INTERVAL_MS,
@@ -1370,12 +1371,7 @@ async function runForeground(token: string): Promise<void> {
// Web: unchanged — heartbeat only while the turn itself is open (summarizing uses turn_summary_pending).
if (turnOpen) {
const agentId = agentIdFor(sessionId)
- backend.send({
- type: 'turn_heartbeat',
- agentId,
- dbSessionId: sessionId,
- payload: { agentId, sessionId },
- })
+ backend.send(turnHeartbeatFrame(sessionId, agentId))
}
// Self-cancel only once the turn is closed AND the summarize is done (no more device heartbeat needed).
if (!turnOpen && !deviceBusy) stopHeartbeat(sessionId)
@@ -1387,12 +1383,7 @@ async function runForeground(token: string): Promise<void> {
if (!events.length || !registry.bySession(sessionId)?.active) return
for (const event of events) {
const agentId = agentIdFor(sessionId)
- backend.send({
- ...event,
- agentId,
- dbSessionId: sessionId,
- payload: { ...event.payload, agentId, sessionId },
- })
+ backend.send(correlateAgentEvent(event, sessionId, agentId))
if (event.type === 'turn_started') {
turnStartedAt.set(sessionId, Date.now())
// Analytics: count HERE, inside the one funnel every engine's normalizer feeds and BEFORE
diff --git a/cli/src/lib/agentEvent.spec.ts b/cli/src/lib/agentEvent.spec.ts
new file mode 100644
index 000000000..aec697760
--- /dev/null
+++ b/cli/src/lib/agentEvent.spec.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { correlateAgentEvent, turnHeartbeatFrame } from './agentEvent.js'
+
+describe('agent event correlation', () => {
+ it.each(['turn_started', 'turn_ended'])('correlates %s to both agent and session identity', (type) => {
+ expect(correlateAgentEvent({ type, payload: { value: 1 } }, 'session-1', 'agent-1')).toEqual({
+ type,
+ agentId: 'agent-1',
+ dbSessionId: 'session-1',
+ payload: { value: 1, agentId: 'agent-1', sessionId: 'session-1' },
+ })
+ })
+
+ it('correlates turn heartbeats with the same wire shape', () => {
+ expect(turnHeartbeatFrame('session-1', 'agent-1')).toEqual({
+ type: 'turn_heartbeat',
+ agentId: 'agent-1',
+ dbSessionId: 'session-1',
+ payload: { agentId: 'agent-1', sessionId: 'session-1' },
+ })
+ })
+})
diff --git a/cli/src/lib/agentEvent.ts b/cli/src/lib/agentEvent.ts
new file mode 100644
index 000000000..c64c57b9e
--- /dev/null
+++ b/cli/src/lib/agentEvent.ts
@@ -0,0 +1,25 @@
+export interface AgentEvent extends Record<string, unknown> {
+ type: string
+ payload: Record<string, unknown>
+}
+
+/** Add stable agent identity without removing the engine session id used by transcript events. */
+export function correlateAgentEvent(
+ event: AgentEvent,
+ sessionId: string,
+ agentId: string,
+): AgentEvent & { agentId: string; dbSessionId: string } {
+ return {
+ ...event,
+ agentId,
+ dbSessionId: sessionId,
+ payload: { ...event.payload, agentId, sessionId },
+ }
+}
+
+export function turnHeartbeatFrame(
+ sessionId: string,
+ agentId: string,
+): AgentEvent & { agentId: string; dbSessionId: string } {
+ return correlateAgentEvent({ type: 'turn_heartbeat', payload: {} }, sessionId, agentId)
+}