@renxqoo/renx-code 0.0.3 → 0.0.5

package/src/agent/runtime/runtime.usage-forwarding.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('./tool-confirmation', () => ({
+  resolveToolConfirmDecision: vi.fn(),
+}));
+
+vi.mock('./source-modules', () => ({
+  getSourceModules: vi.fn(),
+  resolveWorkspaceRoot: vi.fn(),
+}));
+
+import { disposeAgentRuntime, runAgentPrompt } from './runtime';
+import * as sourceModules from './source-modules';
+import type { AgentEventHandlers } from './types';
+
+describe('runAgentPrompt usage forwarding', () => {
+  const mockGetSourceModules = sourceModules.getSourceModules as unknown as ReturnType<
+    typeof vi.fn
+  >;
+  const mockResolveWorkspaceRoot = sourceModules.resolveWorkspaceRoot as unknown as ReturnType<
+    typeof vi.fn
+  >;
+  const originalApiKey = process.env.TEST_API_KEY;
+  const loggerFromEnv = {
+    calls: [] as string[],
+    info(message: string) {
+      this.calls.push(`info:${message}`);
+    },
+    warn(message: string) {
+      this.calls.push(`warn:${message}`);
+    },
+    error(message: string) {
+      this.calls.push(`error:${message}`);
+    },
+    close: vi.fn(),
+  };
+  let receivedAgentConfig: Record<string, unknown> | undefined;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env.TEST_API_KEY = 'test-key';
+    mockResolveWorkspaceRoot.mockReturnValue('/test/workspace');
+    receivedAgentConfig = undefined;
+    loggerFromEnv.calls.length = 0;
+
+    class FakeToolManager {
+      registerTool = vi.fn();
+      getTools = vi.fn(() => []);
+    }
+
+    class FakeTool {
+      toToolSchema() {
+        return {
+          type: 'function',
+          function: {
+            name: 'fake_tool',
+          },
+        };
+      }
+    }
+
+    class FakeAgent {
+      constructor(_provider: unknown, _toolManager: unknown, config: Record<string, unknown>) {
+        receivedAgentConfig = config;
+      }
+
+      on = vi.fn();
+      off = vi.fn();
+    }
+
+    class FakeAppService {
+      async listContextMessages() {
+        return [];
+      }
+
+      async runForeground(
+        _request: unknown,
+        callbacks?: {
+          onUsage?: (usage: {
+            sequence: number;
+            stepIndex: number;
+            messageId: string;
+            usage: {
+              prompt_tokens: number;
+              completion_tokens: number;
+              total_tokens: number;
+            };
+            cumulativeUsage: {
+              prompt_tokens: number;
+              completion_tokens: number;
+              total_tokens: number;
+            };
+            contextTokens?: number;
+            contextLimitTokens?: number;
+            contextUsagePercent?: number;
+          }) => void | Promise<void>;
+        }
+      ) {
+        await callbacks?.onUsage?.({
+          sequence: 1,
+          stepIndex: 1,
+          messageId: 'msg_usage',
+          usage: {
+            prompt_tokens: 10,
+            completion_tokens: 5,
+            total_tokens: 15,
+          },
+          cumulativeUsage: {
+            prompt_tokens: 10,
+            completion_tokens: 5,
+            total_tokens: 15,
+          },
+          contextTokens: 123,
+          contextLimitTokens: 1000,
+          contextUsagePercent: 12.3,
+        });
+
+        return {
+          executionId: 'exec_usage',
+          conversationId: 'conv_usage',
+          messages: [
+            {
+              messageId: 'msg_assistant',
+              role: 'assistant',
+              type: 'assistant-text',
+              content: 'done',
+            },
+          ],
+          finishReason: 'stop' as const,
+          steps: 1,
+          run: {},
+        };
+      }
+    }
+
+    mockGetSourceModules.mockResolvedValue({
+      ProviderRegistry: {
+        getModelIds: () => ['test-model'],
+        getModelConfig: () => ({
+          name: 'Test Model',
+          envApiKey: 'TEST_API_KEY',
+          model: 'test-model',
+        }),
+        createFromEnv: () => ({}),
+      },
+      loadEnvFiles: vi.fn().mockResolvedValue([]),
+      loadConfigToEnv: vi.fn().mockReturnValue([]),
+      buildSystemPrompt: vi.fn(() => 'Test system prompt'),
+      resolveRenxDatabasePath: vi.fn(() => '/tmp/renx/data.db'),
+      resolveRenxTaskDir: vi.fn(() => '/tmp/renx/task'),
+      createLoggerFromEnv: vi.fn(() => loggerFromEnv),
+      createAgentLoggerAdapter: vi.fn((logger: typeof loggerFromEnv) => ({
+        info: (message: string, _context?: Record<string, unknown>, _data?: unknown) =>
+          logger.info(message),
+        warn: (message: string, _context?: Record<string, unknown>, _data?: unknown) =>
+          logger.warn(message),
+        error: (message: string, _error?: unknown, _context?: Record<string, unknown>) =>
+          logger.error(message),
+      })),
+      StatelessAgent: FakeAgent,
+      AgentAppService: FakeAppService,
+      createSqliteAgentAppStore: () => ({
+        prepare: vi.fn().mockResolvedValue(undefined),
+        close: vi.fn().mockResolvedValue(undefined),
+      }),
+      DefaultToolManager: FakeToolManager,
+      BashTool: FakeTool,
+      WriteFileTool: FakeTool,
+      FileReadTool: FakeTool,
+      FileEditTool: FakeTool,
+      FileHistoryListTool: FakeTool,
+      FileHistoryRestoreTool: FakeTool,
+      GlobTool: FakeTool,
+      GrepTool: FakeTool,
+      SkillTool: FakeTool,
+      TaskTool: FakeTool,
+      TaskCreateTool: FakeTool,
+      TaskGetTool: FakeTool,
+      TaskListTool: FakeTool,
+      TaskUpdateTool: FakeTool,
+      TaskStopTool: FakeTool,
+      TaskOutputTool: FakeTool,
+      TaskStore: class {},
+      RealSubagentRunnerAdapter: class {},
+    } as unknown as Awaited<ReturnType<typeof sourceModules.getSourceModules>>);
+  });
+
+  afterEach(async () => {
+    await disposeAgentRuntime();
+    if (originalApiKey === undefined) {
+      delete process.env.TEST_API_KEY;
+    } else {
+      process.env.TEST_API_KEY = originalApiKey;
+    }
+  });
+
+  it('forwards usage events to TUI handlers and returns final usage', async () => {
+    const onUsage = vi.fn();
+    const handlers = {
+      onUsage,
+    } as AgentEventHandlers;
+
+    const result = await runAgentPrompt('show usage', handlers);
+
+    expect(onUsage).toHaveBeenCalledTimes(1);
+    expect(onUsage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        promptTokens: 10,
+        completionTokens: 5,
+        totalTokens: 15,
+        cumulativePromptTokens: 10,
+        cumulativeCompletionTokens: 5,
+        cumulativeTotalTokens: 15,
+      })
+    );
+    expect(result.usage).toEqual(
+      expect.objectContaining({
+        promptTokens: 10,
+        completionTokens: 5,
+        totalTokens: 15,
+      })
+    );
+    expect(receivedAgentConfig?.logger).not.toBe(loggerFromEnv);
+    expect(typeof (receivedAgentConfig?.logger as { info?: unknown }).info).toBe('function');
+    (receivedAgentConfig?.logger as { info?: (message: string) => void }).info?.('bound');
+    expect(loggerFromEnv.calls).toContain('info:bound');
+  });
+});

package/src/agent/runtime/source-modules.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const runtimeDir = fileURLToPath(new URL('.', import.meta.url));
+const packageRoot = resolve(runtimeDir, '../../..');
+const workspaceRoot = resolve(runtimeDir, '../../../..');
+const sourceModulesUrl = pathToFileURL(resolve(runtimeDir, 'source-modules.ts')).href;
+
+const importSourceModules = async () => {
+  return import(`${sourceModulesUrl}?real=${Date.now()}-${Math.random()}`);
+};
+
+beforeEach(() => {
+  delete process.env.AGENT_REPO_ROOT;
+  delete process.env.AGENT_WORKDIR;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('resolveRepoRoot', () => {
+  it('finds the workspace root when launched from opentui-agent-cli', async () => {
+    const { resolveRepoRoot } = await importSourceModules();
+    vi.spyOn(process, 'cwd').mockReturnValue(packageRoot);
+
+    expect(resolveRepoRoot()).toBe(workspaceRoot);
+  });
+
+  it('respects AGENT_REPO_ROOT when provided', async () => {
+    const { resolveRepoRoot } = await importSourceModules();
+    process.env.AGENT_REPO_ROOT = workspaceRoot;
+    vi.spyOn(process, 'cwd').mockReturnValue('D:\\temp\\example-workspace');
+
+    expect(resolveRepoRoot()).toBe(workspaceRoot);
+  });
+});

package/src/agent/runtime/source-modules.ts

@@ -0,0 +1,370 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import type { MessageContent } from '../../types/message-content';
+
+type ProviderModelConfig = {
+  name: string;
+  envApiKey: string;
+  provider?: string;
+  model?: string;
+  LLMMAX_TOKENS?: number;
+  modalities?: {
+    image?: boolean;
+    audio?: boolean;
+    video?: boolean;
+  };
+};
+
+export type ProviderRegistryLike = {
+  getModelIds: () => string[];
+  getModelConfig: (modelId: string) => ProviderModelConfig;
+  createFromEnv: (modelId: string, options?: Record<string, unknown>) => unknown;
+};
+
+export type ToolDecisionLike = {
+  approved: boolean;
+  message?: string;
+};
+
+export type ToolConfirmEventLike = {
+  toolCallId: string;
+  toolName: string;
+  arguments: string;
+  reason?: string;
+  metadata?: Record<string, unknown>;
+  resolve: (decision: ToolDecisionLike) => void;
+};
+
+export type AgentV4MessageLike = {
+  messageId: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  type: string;
+  content: unknown;
+  tool_call_id?: string;
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+};
+
+export type CliEventEnvelopeLike = {
+  conversationId: string;
+  executionId: string;
+  seq: number;
+  eventType: string;
+  data: unknown;
+  createdAt: number;
+};
+
+export type AgentAppRunResultLike = {
+  executionId: string;
+  conversationId: string;
+  messages: AgentV4MessageLike[];
+  finishReason: 'stop' | 'max_steps' | 'error';
+  steps: number;
+  run: {
+    errorMessage?: string;
+  };
+};
+
+type AgentAppRunRequestLike = {
+  conversationId: string;
+  userInput: MessageContent;
+  historyMessages?: AgentV4MessageLike[];
+  systemPrompt?: string;
+  tools?: Array<{ type: string; function: Record<string, unknown> }>;
+  config?: Record<string, unknown>;
+  maxSteps?: number;
+  contextLimitTokens?: number;
+  abortSignal?: AbortSignal;
+  modelLabel?: string;
+};
+
+export type AgentAppUsageLike = {
+  sequence: number;
+  stepIndex: number;
+  messageId: string;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  cumulativeUsage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  contextTokens?: number;
+  contextLimitTokens?: number;
+  contextUsagePercent?: number;
+};
+
+export type AgentAppContextUsageLike = {
+  stepIndex: number;
+  messageCount: number;
+  contextTokens: number;
+  contextLimitTokens: number;
+  contextUsagePercent: number;
+};
+
+type AgentAppRunCallbacksLike = {
+  onEvent?: (event: CliEventEnvelopeLike) => void | Promise<void>;
+  onContextUsage?: (usage: AgentAppContextUsageLike) => void | Promise<void>;
+  onUsage?: (usage: AgentAppUsageLike) => void | Promise<void>;
+  onError?: (error: unknown) => void | Promise<void>;
+};
+
+export type AgentAppServiceLike = {
+  runForeground: (
+    request: AgentAppRunRequestLike,
+    callbacks?: AgentAppRunCallbacksLike
+  ) => Promise<AgentAppRunResultLike>;
+  listContextMessages: (conversationId: string) => Promise<AgentV4MessageLike[]>;
+};
+
+type AgentLoggerLike = {
+  debug?: (message: string, context?: Record<string, unknown>, data?: unknown) => void;
+  info?: (message: string, context?: Record<string, unknown>, data?: unknown) => void;
+  warn?: (message: string, context?: Record<string, unknown>, data?: unknown) => void;
+  error?: (message: string, error?: unknown, context?: Record<string, unknown>) => void;
+};
+
+export type StatelessAgentLike = {
+  on: (eventName: 'tool_confirm', listener: (event: ToolConfirmEventLike) => void) => void;
+  off: (eventName: 'tool_confirm', listener: (event: ToolConfirmEventLike) => void) => void;
+};
+
+export type ToolManagerLike = {
+  registerTool: (tool: unknown) => void;
+  getTools: () => Array<{ name?: string; toToolSchema?: () => unknown }>;
+};
+
+export type AgentAppStoreLike = {
+  close: () => Promise<void>;
+};
+
+type StatelessAgentCtor = new (
+  provider: unknown,
+  toolExecutor: ToolManagerLike,
+  config: Record<string, unknown>
+) => StatelessAgentLike;
+type AgentAppServiceCtor = new (deps: {
+  agent: StatelessAgentLike;
+  executionStore: AgentAppStoreLike;
+  eventStore: AgentAppStoreLike;
+  messageStore: AgentAppStoreLike;
+}) => AgentAppServiceLike;
+type ToolManagerCtor = new (config?: Record<string, unknown>) => ToolManagerLike;
+type ToolCtor = new (options?: Record<string, unknown>) => unknown;
+type TaskStoreCtor = new (options?: Record<string, unknown>) => unknown;
+type TaskRunnerCtor = new (options: Record<string, unknown>) => unknown;
+
+export type SourceModules = {
+  repoRoot: string;
+  ProviderRegistry: ProviderRegistryLike;
+  loadEnvFiles: (cwd?: string) => Promise<string[]>;
+  loadConfigToEnv: (options?: Record<string, unknown>) => string[];
+  buildSystemPrompt: (options: {
+    directory: string;
+    language?: string;
+    currentDateTime?: string;
+    sandboxMode?: string;
+    networkPolicy?: string;
+    runtimeToolNames?: string[];
+  }) => string;
+  resolveRenxDatabasePath: (env?: NodeJS.ProcessEnv) => string;
+  resolveRenxTaskDir: (env?: NodeJS.ProcessEnv) => string;
+  createLoggerFromEnv: (env?: NodeJS.ProcessEnv, cwd?: string) => unknown;
+  createAgentLoggerAdapter: (
+    logger: Record<string, unknown>,
+    baseContext?: Record<string, unknown>
+  ) => AgentLoggerLike;
+  StatelessAgent: StatelessAgentCtor;
+  AgentAppService: AgentAppServiceCtor;
+  createSqliteAgentAppStore: (dbPath: string) => AgentAppStoreLike;
+  DefaultToolManager: ToolManagerCtor;
+  BashTool: ToolCtor;
+  WriteFileTool: ToolCtor;
+  FileReadTool: ToolCtor;
+  FileEditTool: ToolCtor;
+  FileHistoryListTool: ToolCtor;
+  FileHistoryRestoreTool: ToolCtor;
+  GlobTool: ToolCtor;
+  GrepTool: ToolCtor;
+  SkillTool: ToolCtor;
+  TaskTool: ToolCtor;
+  TaskCreateTool: ToolCtor;
+  TaskGetTool: ToolCtor;
+  TaskListTool: ToolCtor;
+  TaskUpdateTool: ToolCtor;
+  TaskStopTool: ToolCtor;
+  TaskOutputTool: ToolCtor;
+  TaskStore: TaskStoreCtor;
+  RealSubagentRunnerAdapter: TaskRunnerCtor;
+};
+
+let modulesPromise: Promise<SourceModules> | null = null;
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const requiredSourceModulePaths = [
+  'src/providers/index.ts',
+  'src/config/index.ts',
+  'src/agent/app/index.ts',
+] as const;
+
+const hasRequiredSourceModules = (root: string) =>
+  requiredSourceModulePaths.every(relativePath => existsSync(resolve(root, relativePath)));
+
+export const resolveRepoRoot = () => {
+  const cwd = process.cwd();
+  const explicit = process.env.AGENT_REPO_ROOT?.trim();
+  const candidates = [
+    explicit ? resolve(explicit) : null,
+    resolve(moduleDir, '../../../../'),
+    resolve(moduleDir, '../../..'),
+    resolve(cwd),
+    resolve(cwd, '..'),
+  ].filter((candidate): candidate is string => Boolean(candidate));
+
+  for (const candidate of new Set(candidates)) {
+    if (hasRequiredSourceModules(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve agent source repo root from ${cwd}. Set AGENT_REPO_ROOT to override.`
+  );
+};
+
+export const resolveWorkspaceRoot = () => {
+  const explicit = process.env.AGENT_WORKDIR?.trim();
+  if (explicit) {
+    return resolve(explicit);
+  }
+  return resolve(process.cwd());
+};
+
+const toModuleUrl = (path: string) => pathToFileURL(path).href;
+
+const getRequiredExport = <T>(moduleObj: Record<string, unknown>, name: string): T => {
+  const value = moduleObj[name];
+  if (!value) {
+    throw new Error(`Missing export ${name}.`);
+  }
+  return value as T;
+};
+
+const loadSourceModules = async (): Promise<SourceModules> => {
+  const repoRoot = resolveRepoRoot();
+
+  const [
+    providerMod,
+    configMod,
+    pathConfigMod,
+    systemPromptMod,
+    appMod,
+    agentV4Mod,
+    agentLoggerMod,
+    toolManagerMod,
+    bashToolMod,
+    writeToolMod,
+    fileReadToolMod,
+    fileEditToolMod,
+    fileHistoryListToolMod,
+    fileHistoryRestoreToolMod,
+    globToolMod,
+    grepToolMod,
+    skillToolMod,
+    taskToolMod,
+    taskCreateToolMod,
+    taskGetToolMod,
+    taskListToolMod,
+    taskUpdateToolMod,
+    taskStopToolMod,
+    taskOutputToolMod,
+    taskStoreMod,
+    taskRunnerAdapterMod,
+  ] = await Promise.all([
+    import(toModuleUrl(resolve(repoRoot, 'src/providers/index.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/config/index.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/config/paths.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/prompts/system.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/app/index.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/agent/index.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/agent/logger.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/tool-manager.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/bash.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/write-file.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/file-read-tool.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/file-edit-tool.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/file-history-list.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/file-history-restore.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/glob.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/grep.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/skill-tool.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-create.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-get.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-list.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-update.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-stop.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-output.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-store.ts'))),
+    import(toModuleUrl(resolve(repoRoot, 'src/agent/tool/task-runner-adapter.ts'))),
+  ]);
+
+  return {
+    repoRoot,
+    ProviderRegistry: getRequiredExport<ProviderRegistryLike>(providerMod, 'ProviderRegistry'),
+    loadEnvFiles: getRequiredExport(configMod, 'loadEnvFiles'),
+    loadConfigToEnv: getRequiredExport(configMod, 'loadConfigToEnv'),
+    buildSystemPrompt: getRequiredExport(systemPromptMod, 'buildSystemPrompt'),
+    resolveRenxDatabasePath: getRequiredExport(pathConfigMod, 'resolveRenxDatabasePath'),
+    resolveRenxTaskDir: getRequiredExport(pathConfigMod, 'resolveRenxTaskDir'),
+    createLoggerFromEnv: getRequiredExport(configMod, 'createLoggerFromEnv'),
+    createAgentLoggerAdapter: getRequiredExport(agentLoggerMod, 'createAgentLoggerAdapter'),
+    StatelessAgent: getRequiredExport<StatelessAgentCtor>(agentV4Mod, 'StatelessAgent'),
+    AgentAppService: getRequiredExport<AgentAppServiceCtor>(appMod, 'AgentAppService'),
+    createSqliteAgentAppStore: getRequiredExport<(dbPath: string) => AgentAppStoreLike>(
+      appMod,
+      'createSqliteAgentAppStore'
+    ),
+    DefaultToolManager: getRequiredExport<ToolManagerCtor>(toolManagerMod, 'DefaultToolManager'),
+    BashTool: getRequiredExport<ToolCtor>(bashToolMod, 'BashTool'),
+    WriteFileTool: getRequiredExport<ToolCtor>(writeToolMod, 'WriteFileTool'),
+    FileReadTool: getRequiredExport<ToolCtor>(fileReadToolMod, 'FileReadTool'),
+    FileEditTool: getRequiredExport<ToolCtor>(fileEditToolMod, 'FileEditTool'),
+    FileHistoryListTool: getRequiredExport<ToolCtor>(fileHistoryListToolMod, 'FileHistoryListTool'),
+    FileHistoryRestoreTool: getRequiredExport<ToolCtor>(
+      fileHistoryRestoreToolMod,
+      'FileHistoryRestoreTool'
+    ),
+    GlobTool: getRequiredExport<ToolCtor>(globToolMod, 'GlobTool'),
+    GrepTool: getRequiredExport<ToolCtor>(grepToolMod, 'GrepTool'),
+    SkillTool: getRequiredExport<ToolCtor>(skillToolMod, 'SkillTool'),
+    TaskTool: getRequiredExport<ToolCtor>(taskToolMod, 'TaskTool'),
+    TaskCreateTool: getRequiredExport<ToolCtor>(taskCreateToolMod, 'TaskCreateTool'),
+    TaskGetTool: getRequiredExport<ToolCtor>(taskGetToolMod, 'TaskGetTool'),
+    TaskListTool: getRequiredExport<ToolCtor>(taskListToolMod, 'TaskListTool'),
+    TaskUpdateTool: getRequiredExport<ToolCtor>(taskUpdateToolMod, 'TaskUpdateTool'),
+    TaskStopTool: getRequiredExport<ToolCtor>(taskStopToolMod, 'TaskStopTool'),
+    TaskOutputTool: getRequiredExport<ToolCtor>(taskOutputToolMod, 'TaskOutputTool'),
+    TaskStore: getRequiredExport<TaskStoreCtor>(taskStoreMod, 'TaskStore'),
+    RealSubagentRunnerAdapter: getRequiredExport<TaskRunnerCtor>(
+      taskRunnerAdapterMod,
+      'RealSubagentRunnerAdapter'
+    ),
+  };
+};
+
+export const getSourceModules = async () => {
+  modulesPromise ??= loadSourceModules().catch(error => {
+    modulesPromise = null;
+    throw error;
+  });
+  return modulesPromise;
+};

package/src/agent/runtime/tool-call-buffer.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AgentToolUseEvent } from './types';
+import { ToolCallBuffer } from './tool-call-buffer';
+
+const createFileReadToolUseEvent = (callId: string, path: string): AgentToolUseEvent => ({
+  id: callId,
+  function: {
+    name: 'file_read',
+    arguments: JSON.stringify({ path }),
+  },
+});
+
+describe('ToolCallBuffer', () => {
+  it('keeps llm-planned tool calls hidden until tool execution starts', () => {
+    const buffer = new ToolCallBuffer();
+    const emitted: AgentToolUseEvent[] = [];
+
+    buffer.register(createFileReadToolUseEvent('call_1', '/tmp/a.ts'), event =>
+      emitted.push(event)
+    );
+    buffer.register(createFileReadToolUseEvent('call_1', '/tmp/a.ts'), event =>
+      emitted.push(event)
+    );
+    buffer.register(createFileReadToolUseEvent('call_2', '/tmp/b.ts'), event =>
+      emitted.push(event)
+    );
+    buffer.register(createFileReadToolUseEvent('call_3', '/tmp/c.ts'), event =>
+      emitted.push(event)
+    );
+
+    expect(emitted).toEqual([]);
+
+    buffer.flush(event => emitted.push(event));
+
+    expect(emitted).toEqual([
+      createFileReadToolUseEvent('call_1', '/tmp/a.ts'),
+      createFileReadToolUseEvent('call_2', '/tmp/b.ts'),
+      createFileReadToolUseEvent('call_3', '/tmp/c.ts'),
+    ]);
+  });
+
+  it('emits a planned tool call as soon as its stream starts', () => {
+    const buffer = new ToolCallBuffer();
+    const emitted: AgentToolUseEvent[] = [];
+
+    buffer.register(createFileReadToolUseEvent('call_1', '/tmp/a.ts'), event =>
+      emitted.push(event)
+    );
+    buffer.register(createFileReadToolUseEvent('call_2', '/tmp/b.ts'), event =>
+      emitted.push(event)
+    );
+
+    buffer.ensureEmitted('call_2', event => emitted.push(event));
+
+    expect(emitted).toEqual([createFileReadToolUseEvent('call_2', '/tmp/b.ts')]);
+
+    buffer.flush(event => emitted.push(event));
+
+    expect(emitted).toEqual([
+      createFileReadToolUseEvent('call_2', '/tmp/b.ts'),
+      createFileReadToolUseEvent('call_1', '/tmp/a.ts'),
+    ]);
+  });
+});