@lumenflow/surfaces 5.1.0

package/cli/__tests__/task-lifecycle.test.ts

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type {
+  ClaimTaskResult,
+  CompleteTaskResult,
+  CreateTaskResult,
+  KernelRuntime,
+  TaskSpec,
+  TaskInspection,
+  ToolOutput,
+} from '@lumenflow/kernel';
+import { createTaskLifecycleCommands, initializeTaskLifecycleCommands } from '../task-lifecycle.js';
+
+function createTaskSpec(taskId: string): TaskSpec {
+  return {
+    id: taskId,
+    workspace_id: 'workspace-surfaces-cli',
+    lane_id: 'framework-cli-wu-commands',
+    domain: 'software-delivery',
+    title: `Task ${taskId}`,
+    description: `Task for ${taskId}`,
+    acceptance: ['CLI lifecycle flow works'],
+    declared_scopes: [{ type: 'path', pattern: '**', access: 'read' }],
+    risk: 'medium',
+    type: 'feature',
+    priority: 'P1',
+    created: '2026-02-16',
+  };
+}
+
+async function writeWorkspaceFixture(root: string): Promise<void> {
+  const packsRoot = join(root, 'packs');
+  const packRoot = join(packsRoot, 'software-delivery');
+  await mkdir(packRoot, { recursive: true });
+
+  await writeFile(
+    join(root, 'workspace.yaml'),
+    [
+      'id: workspace-surfaces-cli',
+      'name: Surfaces CLI Workspace',
+      'packs:',
+      '  - id: software-delivery',
+      '    version: 1.0.0',
+      '    integrity: dev',
+      '    source: local',
+      'lanes:',
+      '  - id: framework-cli-wu-commands',
+      '    title: Framework CLI WU Commands',
+      '    allowed_scopes:',
+      '      - type: path',
+      '        pattern: "**"',
+      '        access: read',
+      'security:',
+      '  allowed_scopes:',
+      '    - type: path',
+      '      pattern: "**"',
+      '      access: read',
+      '  network_default: off',
+      '  deny_overlays: []',
+      'software_delivery: {}',
+      'memory_namespace: mem',
+      'event_namespace: evt',
+    ].join('\n'),
+    'utf8',
+  );
+
+  await writeFile(
+    join(packRoot, 'manifest.yaml'),
+    [
+      'id: software-delivery',
+      'version: 1.0.0',
+      'task_types:',
+      '  - work-unit',
+      'tools: []',
+      'policies:',
+      '  - id: runtime.completion.allow',
+      '    trigger: on_completion',
+      '    decision: allow',
+      'state_aliases:',
+      '  active: in_progress',
+      'evidence_types: []',
+      'lane_templates: []',
+      'config_key: software_delivery',
+    ].join('\n'),
+    'utf8',
+  );
+}
+
+describe('surfaces/cli task lifecycle tracer bullet', () => {
+  let tempRoot: string;
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(join(tmpdir(), 'lumenflow-surfaces-cli-'));
+    await writeWorkspaceFixture(tempRoot);
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it('routes task commands to KernelRuntime methods', async () => {
+    const createTask = vi.fn<(task: TaskSpec) => Promise<CreateTaskResult>>();
+    const claimTask =
+      vi.fn<
+        (input: { task_id: string; by: string; session_id: string }) => Promise<ClaimTaskResult>
+      >();
+    const inspectTask = vi.fn<(taskId: string) => Promise<TaskInspection>>();
+    const completeTask = vi.fn<(input: { task_id: string }) => Promise<CompleteTaskResult>>();
+    const executeTool = vi.fn<(name: string, input: unknown, ctx: never) => Promise<ToolOutput>>();
+
+    const runtime = {
+      createTask,
+      claimTask,
+      inspectTask,
+      completeTask,
+      executeTool,
+      getToolHost: vi.fn(),
+      getPolicyEngine: vi.fn(),
+    } as unknown as KernelRuntime;
+
+    const commands = createTaskLifecycleCommands(runtime);
+    const taskSpec = createTaskSpec('WU-1736-routing');
+
+    await commands['task:create'](taskSpec);
+    await commands['task:claim']({
+      task_id: taskSpec.id,
+      by: 'maintainer@example.com',
+      session_id: 'session-routing',
+    });
+    await commands['task:status'](taskSpec.id);
+    await commands['task:complete']({ task_id: taskSpec.id });
+
+    expect(createTask).toHaveBeenCalledWith(taskSpec);
+    expect(claimTask).toHaveBeenCalledWith({
+      task_id: taskSpec.id,
+      by: 'maintainer@example.com',
+      session_id: 'session-routing',
+    });
+    expect(inspectTask).toHaveBeenCalledWith(taskSpec.id);
+    expect(completeTask).toHaveBeenCalledWith({ task_id: taskSpec.id });
+  });
+
+  it('executes create -> claim -> status -> complete -> status through KernelRuntime', async () => {
+    const initialized = await initializeTaskLifecycleCommands({
+      workspaceRoot: tempRoot,
+      packsRoot: join(tempRoot, 'packs'),
+      taskSpecRoot: join(tempRoot, 'tasks'),
+      eventsFilePath: join(tempRoot, 'events.jsonl'),
+      eventLockFilePath: join(tempRoot, 'events.lock'),
+      evidenceRoot: join(tempRoot, 'evidence'),
+    });
+
+    const commands = initialized.commands;
+    const taskSpec = createTaskSpec('WU-1736-e2e');
+
+    await commands['task:create'](taskSpec);
+    await commands['task:claim']({
+      task_id: taskSpec.id,
+      by: 'maintainer@example.com',
+      session_id: 'session-e2e',
+    });
+
+    const activeStatus = await commands['task:status'](taskSpec.id);
+    expect(activeStatus.state.status).toBe('active');
+
+    await commands['task:complete']({ task_id: taskSpec.id });
+
+    const doneStatus = await commands['task:status'](taskSpec.id);
+    expect(doneStatus.state.status).toBe('done');
+
+    const eventKinds = doneStatus.events.map((event) => event.kind);
+    expect(eventKinds).toEqual([
+      'task_created',
+      'task_claimed',
+      'run_started',
+      'run_succeeded',
+      'task_completed',
+    ]);
+  });
+
+  it('surface implementation avoids direct @lumenflow/core imports', async () => {
+    const sourcePath = join(
+      process.cwd(),
+      'packages',
+      '@lumenflow',
+      'surfaces',
+      'cli',
+      'task-lifecycle.ts',
+    );
+    const source = await readFile(sourcePath, 'utf8');
+
+    expect(source.includes('@lumenflow/core')).toBe(false);
+    expect(source.includes('runtime.createTask')).toBe(true);
+    expect(source.includes('runtime.claimTask')).toBe(true);
+    expect(source.includes('runtime.inspectTask')).toBe(true);
+    expect(source.includes('runtime.completeTask')).toBe(true);
+  });
+});

package/cli/gates.ts

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  POLICY_TRIGGERS,
+  type KernelRuntime,
+  type PolicyEvaluationResult,
+  type TaskInspection,
+} from '@lumenflow/kernel';
+
+export interface GateRunInput {
+  task_id: string;
+  run_id: string;
+  lane_id?: string;
+  pack_id?: string;
+}
+
+export interface GateCommands {
+  'gates:run': (input: GateRunInput) => Promise<PolicyEvaluationResult>;
+}
+
+export interface OrchestrationCommands {
+  'orchestration:init-status': (taskId: string) => Promise<TaskInspection>;
+  'orchestration:monitor': (taskId: string) => Promise<TaskInspection>;
+}
+
+export function createGateCommands(runtime: KernelRuntime): GateCommands {
+  return {
+    'gates:run': async (input) => {
+      return runtime.getPolicyEngine().evaluate({
+        trigger: POLICY_TRIGGERS.ON_COMPLETION,
+        task_id: input.task_id,
+        run_id: input.run_id,
+        lane_id: input.lane_id,
+        pack_id: input.pack_id,
+      });
+    },
+  };
+}
+
+export function createOrchestrationCommands(runtime: KernelRuntime): OrchestrationCommands {
+  return {
+    'orchestration:init-status': async (taskId) => runtime.inspectTask(taskId),
+    'orchestration:monitor': async (taskId) => runtime.inspectTask(taskId),
+  };
+}

package/cli/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './gates.js';
+export * from './inspect.js';
+export * from './task-lifecycle.js';

package/cli/inspect.ts

@@ -0,0 +1,138 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import { readFile } from 'node:fs/promises';
+import type {
+  KernelRuntime,
+  TaskInspection,
+  TaskInspection as KernelTaskInspection,
+  ToolOutput,
+} from '@lumenflow/kernel';
+
+export interface InspectView extends KernelTaskInspection {
+  evidence: string[];
+}
+
+export interface InspectCommands {
+  'task:inspect': (taskId: string) => Promise<InspectView>;
+}
+
+export interface ReplayRunInput {
+  task_id: string;
+  run_id: string;
+  session_id: string;
+}
+
+export interface ReplayOutput {
+  receipt_id: string;
+  tool_name: string;
+  output: ToolOutput;
+}
+
+export interface ReplayRunResult {
+  task_id: string;
+  run_id: string;
+  replay_run_id: string;
+  outputs: ReplayOutput[];
+}
+
+export interface ReplayCommands {
+  'task:replay': (input: ReplayRunInput) => Promise<ReplayRunResult>;
+}
+
+function collectEvidence(inspection: TaskInspection): string[] {
+  const evidence = new Set<string>();
+
+  for (const event of inspection.events) {
+    if (!('evidence_refs' in event)) {
+      continue;
+    }
+    const refs = event.evidence_refs;
+    if (!Array.isArray(refs)) {
+      continue;
+    }
+    for (const ref of refs) {
+      evidence.add(ref);
+    }
+  }
+
+  for (const receipt of inspection.receipts) {
+    if (receipt.kind === 'tool_call_started') {
+      evidence.add(receipt.input_ref);
+      continue;
+    }
+    if (receipt.output_ref) {
+      evidence.add(receipt.output_ref);
+    }
+  }
+
+  return [...evidence];
+}
+
+export function createInspectCommands(runtime: KernelRuntime): InspectCommands {
+  return {
+    'task:inspect': async (taskId) => {
+      const inspection = await runtime.inspectTask(taskId);
+      return {
+        ...inspection,
+        evidence: collectEvidence(inspection),
+      };
+    },
+  };
+}
+
+async function loadReplayInput(inputRef: string): Promise<unknown> {
+  const payload = await readFile(inputRef, 'utf8');
+  try {
+    return JSON.parse(payload) as unknown;
+  } catch {
+    return payload;
+  }
+}
+
+export function createReplayCommands(runtime: KernelRuntime): ReplayCommands {
+  return {
+    'task:replay': async (input) => {
+      const inspection = await runtime.inspectTask(input.task_id);
+      const replayRunId = `${input.run_id}:replay`;
+      const replayOutputs: ReplayOutput[] = [];
+
+      const startedReceipts = inspection.receipts.filter((receipt) => {
+        return receipt.kind === 'tool_call_started' && receipt.run_id === input.run_id;
+      });
+
+      for (const receipt of startedReceipts) {
+        const replayInput = await loadReplayInput(receipt.input_ref);
+        const output = await runtime.executeTool(receipt.tool_name, replayInput, {
+          run_id: replayRunId,
+          task_id: input.task_id,
+          session_id: input.session_id,
+          allowed_scopes: receipt.scope_enforced,
+          metadata: {
+            workspace_allowed_scopes: receipt.scope_enforced,
+            lane_allowed_scopes: receipt.scope_enforced,
+            task_declared_scopes: receipt.scope_enforced,
+            workspace_config_hash: receipt.workspace_config_hash,
+            runtime_version: receipt.runtime_version,
+            pack_id: receipt.pack_id,
+            pack_version: receipt.pack_version,
+            pack_integrity: receipt.pack_integrity,
+          },
+        });
+
+        replayOutputs.push({
+          receipt_id: receipt.receipt_id,
+          tool_name: receipt.tool_name,
+          output,
+        });
+      }
+
+      return {
+        task_id: input.task_id,
+        run_id: input.run_id,
+        replay_run_id: replayRunId,
+        outputs: replayOutputs,
+      };
+    },
+  };
+}

package/cli/task-lifecycle.ts

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  initializeKernelRuntime,
+  type ClaimTaskInput,
+  type ClaimTaskResult,
+  type CompleteTaskInput,
+  type CompleteTaskResult,
+  type CreateTaskResult,
+  type InitializeKernelRuntimeOptions,
+  type KernelRuntime,
+  type TaskSpec,
+  type TaskInspection,
+} from '@lumenflow/kernel';
+
+export interface TaskLifecycleCommands {
+  'task:create': (taskSpec: TaskSpec) => Promise<CreateTaskResult>;
+  'task:claim': (input: ClaimTaskInput) => Promise<ClaimTaskResult>;
+  'task:status': (taskId: string) => Promise<TaskInspection>;
+  'task:complete': (input: CompleteTaskInput) => Promise<CompleteTaskResult>;
+}
+
+export interface InitializedTaskLifecycleCommands {
+  runtime: KernelRuntime;
+  commands: TaskLifecycleCommands;
+}
+
+export function createTaskLifecycleCommands(runtime: KernelRuntime): TaskLifecycleCommands {
+  return {
+    'task:create': async (taskSpec) => runtime.createTask(taskSpec),
+    'task:claim': async (input) => runtime.claimTask(input),
+    'task:status': async (taskId) => runtime.inspectTask(taskId),
+    'task:complete': async (input) => runtime.completeTask(input),
+  };
+}
+
+export async function initializeTaskLifecycleCommands(
+  options: InitializeKernelRuntimeOptions,
+): Promise<InitializedTaskLifecycleCommands> {
+  const runtime = await initializeKernelRuntime(options);
+  return {
+    runtime,
+    commands: createTaskLifecycleCommands(runtime),
+  };
+}

package/http/__tests__/agent-runtime-remote-controls.test.ts

@@ -0,0 +1,249 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+//
+// WU-2732 (INIT-060 Phase 3, ADR-013 §1 + §6 tracer bullet):
+// End-to-end wire-contract proof for the six agent-runtime
+// remote-control tools. Dispatches POST /tools/:name through the
+// HTTP tool-api router into the real mock tool implementations and
+// asserts:
+//   1. 200 round-trip for every tool on the allowlist.
+//   2. Response JSON carries the mock shape (tool_name, session_id,
+//      plus cleanup_status/recovery_action for abort_turn).
+//   3. agent-runtime:tool_called is emitted on each invocation.
+//
+// The test pins the wire contract BEFORE WU-2733 ships the real
+// kernel-side pause/resume/abort logic. WU-2733 replaces the mock
+// entries without changing names, scopes, approvals, or response
+// shapes — this suite runs unchanged against the real implementations.
+
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AGENT_RUNTIME_REMOTE_CALLABLE_TOOLS } from '../../../packs/agent-runtime/manifest.js';
+import {
+  AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES,
+  type AgentRuntimeRemoteControlToolName,
+} from '../../../packs/agent-runtime/remote-controls/types.js';
+import {
+  AGENT_RUNTIME_EVENT_KINDS,
+  resetAgentRuntimeSeqCounter,
+  type AgentRuntimeEvent,
+} from '../../../packs/agent-runtime/turn-lifecycle-events.js';
+import {
+  abortTurnMockTool,
+  approveInflightMockTool,
+  elevateAutonomyMockTool,
+  lowerAutonomyMockTool,
+  pauseTurnMockTool,
+  resumeWorkflowMockTool,
+  setMockRemoteControlEventSink,
+} from '../../../packs/agent-runtime/tool-impl/remote-controls.mock.js';
+import { createToolApiRouter } from '../tool-api.js';
+
+const HTTP_METHOD = { POST: 'POST' } as const;
+const HTTP_STATUS = { OK: 200 } as const;
+const CONTENT_TYPE_JSON = 'application/json; charset=utf-8';
+
+const MOCK_TOOL_DISPATCH: Record<AgentRuntimeRemoteControlToolName, typeof resumeWorkflowMockTool> =
+  {
+    [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.RESUME_WORKFLOW]: resumeWorkflowMockTool,
+    [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.PAUSE_TURN]: pauseTurnMockTool,
+    [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN]: abortTurnMockTool,
+    [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ELEVATE_AUTONOMY]: elevateAutonomyMockTool,
+    [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.LOWER_AUTONOMY]: lowerAutonomyMockTool,
+    [AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.APPROVE_INFLIGHT]: approveInflightMockTool,
+  };
+
+class MockResponse extends EventEmitter {
+  statusCode = HTTP_STATUS.OK;
+  body = '';
+  private readonly headers = new Map<string, string>();
+
+  setHeader(name: string, value: string | number | readonly string[]): this {
+    this.headers.set(name.toLowerCase(), String(value));
+    return this;
+  }
+
+  write(chunk: string | Buffer): boolean {
+    this.body += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk;
+    return true;
+  }
+
+  end(chunk?: string | Buffer): this {
+    if (chunk !== undefined) {
+      this.write(chunk);
+    }
+    this.emit('finish');
+    return this;
+  }
+}
+
+interface CreateRequestOptions {
+  method: string;
+  body?: unknown;
+}
+
+function createRequest(options: CreateRequestOptions): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: IncomingHttpHeaders;
+  };
+  request.method = options.method;
+  request.url = '/';
+  request.headers = {
+    'content-type': CONTENT_TYPE_JSON,
+    // WU-2779: POST /tools/:name now requires an Authorization header. Use a
+    // legacy opaque token — this suite exercises the agent-runtime wire
+    // contract, not auth; scope enforcement is covered elsewhere.
+    authorization: 'Bearer legacy-opaque-agent-runtime-test-token',
+  };
+  const payload = options.body === undefined ? '' : JSON.stringify(options.body);
+  (request as unknown as PassThrough).end(payload);
+  return request;
+}
+
+function createContext() {
+  return {
+    run_id: 'run-wu-2732',
+    task_id: 'WU-2732',
+    session_id: 'session-http-e2e',
+    allowed_scopes: [{ type: 'path' as const, pattern: '**', access: 'read' as const }],
+  };
+}
+
+interface RouterRuntime {
+  executeTool: (
+    name: string,
+    input: unknown,
+    ctx: ReturnType<typeof createContext>,
+  ) => Promise<unknown>;
+}
+
+function createRemoteControlMockRuntime(): RouterRuntime {
+  return {
+    async executeTool(name, input, ctx) {
+      const tool = MOCK_TOOL_DISPATCH[name as AgentRuntimeRemoteControlToolName];
+      if (!tool) {
+        throw new Error(`Test harness: unknown tool "${name}"`);
+      }
+      return tool(input, ctx as unknown as never);
+    },
+  };
+}
+
+function parseJsonBody(body: string): { success: boolean; data: unknown } {
+  return JSON.parse(body) as { success: boolean; data: unknown };
+}
+
+describe('WU-2732 E2E: POST /tools/agent-runtime:* round-trips the wire contract', () => {
+  let capturedEvents: AgentRuntimeEvent[];
+
+  beforeEach(() => {
+    capturedEvents = [];
+    resetAgentRuntimeSeqCounter();
+    setMockRemoteControlEventSink((event) => capturedEvents.push(event));
+  });
+
+  afterEach(() => {
+    setMockRemoteControlEventSink(undefined);
+  });
+
+  it.each(AGENT_RUNTIME_REMOTE_CALLABLE_TOOLS)(
+    'POST /tools/%s returns 200 with success=true and the mock-shape payload',
+    async (toolName) => {
+      const runtime = createRemoteControlMockRuntime();
+      const router = createToolApiRouter(runtime as never, {
+        allowlistedTools: [...AGENT_RUNTIME_REMOTE_CALLABLE_TOOLS],
+      });
+
+      const request = createRequest({
+        method: HTTP_METHOD.POST,
+        body: {
+          input: { session_id: 'session-from-cloud' },
+          context: createContext(),
+        },
+      });
+      const response = new MockResponse();
+
+      await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+        toolName,
+      ]);
+
+      expect(response.statusCode).toBe(HTTP_STATUS.OK);
+      const body = parseJsonBody(response.body);
+      expect(body.success).toBe(true);
+
+      const data = body.data as { tool_name: string; session_id: string; status: string };
+      expect(data.tool_name).toBe(toolName);
+      expect(data.session_id).toBe('session-from-cloud');
+      expect(data.status).toBe('ok');
+    },
+  );
+
+  it('POST /tools/agent-runtime:abort_turn returns the ADR-013 §1 abort payload', async () => {
+    const runtime = createRemoteControlMockRuntime();
+    const router = createToolApiRouter(runtime as never, {
+      allowlistedTools: [...AGENT_RUNTIME_REMOTE_CALLABLE_TOOLS],
+    });
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      body: {
+        input: { session_id: 'session-abort-e2e', reason: 'operator-requested' },
+        context: createContext(),
+      },
+    });
+    const response = new MockResponse();
+
+    await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+      AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN,
+    ]);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.OK);
+    const body = parseJsonBody(response.body);
+    const data = body.data as {
+      tool_name: string;
+      session_id: string;
+      cleanup_status: string;
+      recovery_action: string | null;
+    };
+    expect(data.tool_name).toBe(AGENT_RUNTIME_REMOTE_CONTROL_TOOL_NAMES.ABORT_TURN);
+    expect(data.session_id).toBe('session-abort-e2e');
+    expect(data.cleanup_status).toBe('clean');
+    expect(data.recovery_action).toBeNull();
+  });
+
+  it.each(AGENT_RUNTIME_REMOTE_CALLABLE_TOOLS)(
+    'invoking %s over HTTP emits exactly one agent-runtime:tool_called event',
+    async (toolName) => {
+      const runtime = createRemoteControlMockRuntime();
+      const router = createToolApiRouter(runtime as never, {
+        allowlistedTools: [...AGENT_RUNTIME_REMOTE_CALLABLE_TOOLS],
+      });
+      const request = createRequest({
+        method: HTTP_METHOD.POST,
+        body: {
+          input: { session_id: 'session-emit-e2e' },
+          context: createContext(),
+        },
+      });
+      const response = new MockResponse();
+
+      await router.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>, [
+        toolName,
+      ]);
+
+      const toolCalledEvents = capturedEvents.filter(
+        (event) => event.kind === AGENT_RUNTIME_EVENT_KINDS.TOOL_CALLED,
+      );
+      expect(toolCalledEvents).toHaveLength(1);
+      const [event] = toolCalledEvents;
+      if (event?.kind !== AGENT_RUNTIME_EVENT_KINDS.TOOL_CALLED) {
+        throw new Error('expected a tool_called event');
+      }
+      expect(event.tool_name).toBe(toolName);
+      expect(event.session_id).toBe('session-emit-e2e');
+    },
+  );
+});