brownian-code 2026.2.12 → 2026.6.4

package/src/agent/tool-executor.ts

@@ -0,0 +1,300 @@
+import { AIMessage } from "@langchain/core/messages";
+import type { ToolCall } from "@langchain/core/messages/tool";
+import { StructuredToolInterface } from "@langchain/core/tools";
+import { createProgressChannel } from "../utils/progress-channel.js";
+import { all } from "../utils/concurrency.js";
+import {
+  exceedsSizeCap,
+  persistLargeResult,
+  buildPersistedContent,
+} from "../utils/tool-result-storage.js";
+import type {
+  ApprovalDecision,
+  ToolApprovalEvent,
+  ToolDeniedEvent,
+  ToolEndEvent,
+  ToolErrorEvent,
+  ToolLimitEvent,
+  ToolProgressEvent,
+  ToolStartEvent,
+} from "./types.js";
+import type { RunContext } from "./run-context.js";
+
+type ToolExecutionEvent =
+  | ToolStartEvent
+  | ToolProgressEvent
+  | ToolEndEvent
+  | ToolErrorEvent
+  | ToolApprovalEvent
+  | ToolDeniedEvent
+  | ToolLimitEvent;
+
+const TOOLS_REQUIRING_APPROVAL = ["write_file", "edit_file"] as const;
+const DEFAULT_MAX_CONCURRENCY = 10;
+
+interface ToolCallBatch {
+  concurrent: boolean;
+  calls: ToolCall[];
+}
+
+/**
+ * Executes tool calls with concurrent support for read-only tools.
+ *
+ * Consecutive concurrent-safe tool calls are batched and run in parallel
+ * (up to maxConcurrency). Non-concurrent tools execute serially with
+ * approval gates where required.
+ */
+export class AgentToolExecutor {
+  private readonly sessionApprovedTools: Set<string>;
+  private readonly maxConcurrency: number;
+
+  constructor(
+    private readonly toolMap: Map<string, StructuredToolInterface>,
+    private readonly concurrencyMap: Map<string, boolean>,
+    private readonly signal?: AbortSignal,
+    private readonly requestToolApproval?: (request: {
+      tool: string;
+      args: Record<string, unknown>;
+    }) => Promise<ApprovalDecision>,
+    sessionApprovedTools?: Set<string>,
+    maxConcurrency?: number,
+  ) {
+    this.sessionApprovedTools = sessionApprovedTools ?? new Set();
+    this.maxConcurrency = maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+  }
+
+  /**
+   * Execute all tool calls from an AIMessage response.
+   * Concurrent-safe tools run in parallel batches; others run serially.
+   */
+  async *executeAll(
+    response: AIMessage,
+    ctx: RunContext,
+  ): AsyncGenerator<ToolExecutionEvent, void> {
+    const batches = this.partitionToolCalls(response.tool_calls!, ctx);
+
+    for (const batch of batches) {
+      if (batch.concurrent && batch.calls.length > 1) {
+        yield* this.executeBatchConcurrently(batch.calls, ctx);
+      } else {
+        for (const call of batch.calls) {
+          yield* this.executeSingleWithId(call, ctx);
+        }
+      }
+    }
+  }
+
+  /**
+   * Partition tool_calls into batches of consecutive concurrent-safe calls
+   * vs individual non-concurrent calls.
+   */
+  private partitionToolCalls(
+    toolCalls: ToolCall[],
+    ctx: RunContext,
+  ): ToolCallBatch[] {
+    const batches: ToolCallBatch[] = [];
+    const seenSkills = new Set<string>();
+
+    for (const call of toolCalls) {
+      // Skill dedup — skip already-executed skills (cross-turn) AND
+      // skip duplicate skill names within the same response (intra-turn).
+      if (call.name === "skill") {
+        const skillName = (call.args as Record<string, unknown>)
+          .skill as string;
+        if (ctx.scratchpad.hasExecutedSkill(skillName)) continue;
+        if (seenSkills.has(skillName)) continue;
+        seenSkills.add(skillName);
+      }
+
+      const isSafe = this.concurrencyMap.get(call.name) ?? false;
+      const lastBatch = batches[batches.length - 1];
+
+      if (isSafe && lastBatch?.concurrent) {
+        lastBatch.calls.push(call);
+      } else {
+        batches.push({ concurrent: isSafe, calls: [call] });
+      }
+    }
+
+    return batches;
+  }
+
+  /**
+   * Execute a batch of concurrent-safe tools in parallel.
+   */
+  private async *executeBatchConcurrently(
+    calls: ToolCall[],
+    ctx: RunContext,
+  ): AsyncGenerator<ToolExecutionEvent, void> {
+    const generators = calls.map((call) => this.executeSingleWithId(call, ctx));
+    yield* all(generators, this.maxConcurrency);
+  }
+
+  /**
+   * Execute a single tool call, emitting toolCallId on every event.
+   */
+  private async *executeSingleWithId(
+    call: ToolCall,
+    ctx: RunContext,
+  ): AsyncGenerator<ToolExecutionEvent, void> {
+    const toolName = call.name;
+    const toolArgs = call.args as Record<string, unknown>;
+    const toolCallId = call.id;
+    const toolQuery = this.extractQueryFromArgs(toolArgs);
+
+    // Approval flow for sensitive tools
+    if (
+      this.requiresApproval(toolName) &&
+      !this.sessionApprovedTools.has(toolName)
+    ) {
+      const decision =
+        (await this.requestToolApproval?.({
+          tool: toolName,
+          args: toolArgs,
+        })) ?? "deny";
+      yield {
+        type: "tool_approval",
+        tool: toolName,
+        args: toolArgs,
+        approved: decision,
+      };
+      if (decision === "deny") {
+        yield {
+          type: "tool_denied",
+          tool: toolName,
+          args: toolArgs,
+          toolCallId,
+        };
+        return;
+      }
+      if (decision === "allow-session") {
+        for (const name of TOOLS_REQUIRING_APPROVAL) {
+          this.sessionApprovedTools.add(name);
+        }
+      }
+    }
+
+    // Tool limit check (warn but never block)
+    const limitCheck = ctx.scratchpad.canCallTool(toolName, toolQuery);
+    if (limitCheck.warning) {
+      yield {
+        type: "tool_limit",
+        tool: toolName,
+        warning: limitCheck.warning,
+        blocked: false,
+      };
+    }
+
+    yield { type: "tool_start", tool: toolName, args: toolArgs, toolCallId };
+
+    const toolStartTime = Date.now();
+
+    try {
+      const tool = this.toolMap.get(toolName);
+      if (!tool) {
+        throw new Error(`Tool '${toolName}' not found`);
+      }
+
+      const channel = createProgressChannel();
+      const config = {
+        metadata: { onProgress: channel.emit },
+        ...(this.signal ? { signal: this.signal } : {}),
+      };
+
+      const toolPromise = tool.invoke(toolArgs, config).then(
+        (raw) => {
+          channel.close();
+          return raw;
+        },
+        (err) => {
+          channel.close();
+          throw err;
+        },
+      );
+
+      for await (const message of channel) {
+        yield {
+          type: "tool_progress",
+          tool: toolName,
+          message,
+          toolCallId,
+        } as ToolProgressEvent;
+      }
+
+      const rawResult = await toolPromise;
+      const result =
+        typeof rawResult === "string" ? rawResult : JSON.stringify(rawResult);
+      const duration = Date.now() - toolStartTime;
+
+      yield {
+        type: "tool_end",
+        tool: toolName,
+        args: toolArgs,
+        result,
+        duration,
+        toolCallId,
+      };
+
+      ctx.scratchpad.recordToolCall(toolName, toolQuery);
+
+      // Cap large results: persist full result to disk and store a preview + path
+      // in the scratchpad so the LLM can recover it via read_file if needed.
+      // Disk failure (full disk, permission denied) falls through to scratchpad's
+      // own MAX_TOOL_RESULT_CHARS truncation.
+      let scratchResult = result;
+      if (exceedsSizeCap(result)) {
+        try {
+          const persistId =
+            toolCallId ??
+            `${toolName}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+          const { preview, filePath } = persistLargeResult(
+            toolName,
+            persistId,
+            result,
+          );
+          scratchResult = buildPersistedContent(
+            filePath,
+            preview,
+            result.length,
+          );
+        } catch {
+          scratchResult = result;
+        }
+      }
+
+      ctx.scratchpad.addToolResult(toolName, toolArgs, scratchResult);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      yield {
+        type: "tool_error",
+        tool: toolName,
+        error: errorMessage,
+        toolCallId,
+      };
+
+      ctx.scratchpad.recordToolCall(toolName, toolQuery);
+      ctx.scratchpad.addToolResult(
+        toolName,
+        toolArgs,
+        `Error: ${errorMessage}`,
+      );
+    }
+  }
+
+  private extractQueryFromArgs(
+    args: Record<string, unknown>,
+  ): string | undefined {
+    const queryKeys = ["query", "search", "question", "q", "text", "input"];
+    for (const key of queryKeys) {
+      if (typeof args[key] === "string") {
+        return args[key] as string;
+      }
+    }
+    return undefined;
+  }
+
+  private requiresApproval(toolName: string): boolean {
+    return (TOOLS_REQUIRING_APPROVAL as readonly string[]).includes(toolName);
+  }
+}

package/src/agent/types.ts

@@ -1,8 +1,27 @@
+/**
+ * Channel profile — controls how the system prompt adapts the agent's output
+ * for different surfaces (CLI vs WhatsApp). Drives the preamble, behavior
+ * bullets, response format bullets, and tables instruction injected into
+ * `buildSystemPrompt`.
+ */
+export interface ChannelProfile {
+  /** Human-readable label used in the system prompt preamble (e.g., "CLI", "WhatsApp") */
+  label: string;
+  /** One-liner describing the output surface, injected after the date line */
+  preamble: string;
+  /** Bullet points for the ## Behavior section */
+  behavior: string[];
+  /** Bullet points for the ## Response Format section */
+  responseFormat: string[];
+  /** Full tables instruction block, or null to omit the section entirely */
+  tables: string | null;
+}
+
 /**
  * Agent configuration
  */
 export interface AgentConfig {
-  /** Model to use for LLM calls (e.g., 'gpt-5.2', 'claude-sonnet-4-20250514') */
+  /** Model to use for LLM calls (e.g., 'gpt-5.5', 'claude-sonnet-4-20250514') */
   model?: string;
   /** Model provider (e.g., 'openai', 'anthropic', 'google', 'ollama') */
   modelProvider?: string;
@@ -10,13 +29,72 @@ export interface AgentConfig {
   maxIterations?: number;
   /** AbortSignal for cancelling agent execution */
   signal?: AbortSignal;
+  /**
+   * Channel surface this agent runs on ('cli' | 'whatsapp'). Drives the
+   * system prompt's behavior + response-format profile. Default: 'cli'.
+   */
+  channel?: string;
+  /**
+   * Group chat context — set by the gateway when an inbound message arrives
+   * in a group thread. When present, the system prompt adds a `## Group Chat`
+   * section so the agent addresses the mentioner and references group context.
+   */
+  groupContext?: import("./prompts.js").GroupContext;
+  /**
+   * Whether the memory subsystem is available to the agent. Set to false for
+   * isolated runs (e.g. heartbeats, evals) that should not persist or read
+   * long-term memory.
+   */
+  memoryEnabled?: boolean;
+  /**
+   * Optional message queue for mid-run user input injection. The agent
+   * drains the queue between iterations and merges queued text into a
+   * follow-up turn.
+   */
+  messageQueue?: import("../utils/message-queue.js").MessageQueue;
+  /**
+   * Called when a tool requires explicit user approval (e.g. write_file, edit_file).
+   * Resolves to one of: 'allow-once', 'allow-session', 'deny'.
+   */
+  requestToolApproval?: (request: {
+    tool: string;
+    args: Record<string, unknown>;
+  }) => Promise<ApprovalDecision>;
+  /**
+   * Shared set of tool names already approved for the entire session
+   * (persists across queries within an Agent instance lifetime).
+   */
+  sessionApprovedTools?: Set<string>;
+  /**
+   * Optional tool override for isolated tests and embedded agent hosts.
+   * Normal app flows should omit this and use the registered tool surface.
+   */
+  tools?: import("@langchain/core/tools").StructuredToolInterface[];
+  /**
+   * Optional concurrency map paired with `tools`. Missing entries default to
+   * serial execution.
+   */
+  concurrencyMap?: Map<string, boolean>;
+  /**
+   * Optional prompt override for isolated tests and embedded agent hosts.
+   * Normal app flows should omit this so Brownian builds the full prompt.
+   */
+  systemPrompt?: string;
 }
 
+/**
+ * Tool-approval decision returned by the user via `requestToolApproval`.
+ *  - 'allow-once'    → run this call, ask again next time
+ *  - 'allow-session' → run this call AND every future call within the session
+ *  - 'deny'          → do not run; emit ToolDeniedEvent
+ */
+export type ApprovalDecision = "allow-once" | "allow-session" | "deny";
+
 /**
  * Message in conversation history
  */
 export interface Message {
-  role: 'user' | 'assistant' | 'tool';
+  role: "user" | "assistant" | "tool";
   content: string;
 }
 
@@ -28,7 +106,7 @@ export interface Message {
  * Agent is processing/thinking
  */
 export interface ThinkingEvent {
-  type: 'thinking';
+  type: "thinking";
   message: string;
 }
 
@@ -36,45 +114,74 @@ export interface ThinkingEvent {
  * Tool execution started
  */
 export interface ToolStartEvent {
-  type: 'tool_start';
+  type: "tool_start";
   tool: string;
   args: Record<string, unknown>;
+  /** Optional LangChain tool_call id — present when emitted via AgentToolExecutor. */
+  toolCallId?: string;
 }
 
 /**
  * Tool execution completed successfully
  */
 export interface ToolEndEvent {
-  type: 'tool_end';
+  type: "tool_end";
   tool: string;
   args: Record<string, unknown>;
   result: string;
   duration: number;
+  /** Optional LangChain tool_call id. */
+  toolCallId?: string;
 }
 
 /**
  * Tool execution failed
  */
 export interface ToolErrorEvent {
-  type: 'tool_error';
+  type: "tool_error";
   tool: string;
   error: string;
+  /** Optional LangChain tool_call id. */
+  toolCallId?: string;
+}
+
+/**
+ * A user-approval request for a sensitive tool was completed. Carries the
+ * decision so downstream UI can record the choice.
+ */
+export interface ToolApprovalEvent {
+  type: "tool_approval";
+  tool: string;
+  args: Record<string, unknown>;
+  approved: ApprovalDecision;
+}
+
+/**
+ * The user denied a tool's approval request; the call did not run.
+ */
+export interface ToolDeniedEvent {
+  type: "tool_denied";
+  tool: string;
+  args: Record<string, unknown>;
+  toolCallId?: string;
 }
 
 /**
  * Mid-execution progress update from a subagent tool
  */
 export interface ToolProgressEvent {
-  type: 'tool_progress';
+  type: "tool_progress";
   tool: string;
   message: string;
+  /** Optional LangChain tool_call id. */
+  toolCallId?: string;
 }
 
 /**
  * Tool call warning due to approaching/exceeding suggested limits
  */
 export interface ToolLimitEvent {
-  type: 'tool_limit';
+  type: "tool_limit";
   tool: string;
   /** Warning message about tool usage limits */
   warning?: string;
@@ -86,18 +193,104 @@ export interface ToolLimitEvent {
  * Context was cleared due to exceeding token threshold (Anthropic-style)
  */
 export interface ContextClearedEvent {
-  type: 'context_cleared';
+  type: "context_cleared";
   /** Number of tool results that were cleared from context */
   clearedCount: number;
   /** Number of most recent tool results that were kept */
   keptCount: number;
 }
 
+/**
+ * LLM-driven context compaction at the token threshold.
+ * Replaces accumulated tool results with a structured summary so the agent
+ * can continue with full context information rather than losing it.
+ */
+export interface CompactionEvent {
+  type: "compaction";
+  /** Lifecycle phase of the compaction call. */
+  phase: "start" | "success" | "fallback";
+  /** Estimated tokens in context before compaction (start/success/fallback). */
+  preCompactTokens?: number;
+  /** Estimated tokens after compaction completed (success only). */
+  postCompactTokens?: number;
+  /** Token usage of the compaction LLM call (success only). */
+  compactionUsage?: TokenUsage;
+  /** Reason compaction failed and fell back to eviction (fallback only). */
+  reason?: string;
+}
+
+/**
+ * Pre-compaction memory flush — promote durable facts from this session's
+ * tool results into long-term memory so they survive the upcoming compaction.
+ * Tier-1 of the three-tier context-management cascade.
+ */
+export interface MemoryFlushEvent {
+  type: "memory_flush";
+  phase: "start" | "end";
+  /** Files written to memory during the flush (end-phase only). */
+  filesWritten?: string[];
+}
+
+/**
+ * Per-turn lightweight trimming of stale ToolMessage content. Replaces old
+ * read-only tool results with a placeholder marker without calling an LLM.
+ * Triggers when compactable ToolMessages exceed COUNT_TRIGGER_THRESHOLD or
+ * total compactable content exceeds TOKEN_TRIGGER_THRESHOLD.
+ */
+export interface MicrocompactEvent {
+  type: "microcompact";
+  /** Number of ToolMessages whose content was cleared. */
+  cleared: number;
+  /** Estimated tokens saved by clearing. */
+  tokensSaved: number;
+}
+
+/**
+ * The agent drained queued user messages between iterations. Indicates the
+ * user typed follow-up text mid-run (typically via the TUI or gateway) and
+ * the agent merged it into a HumanMessage for the next iteration.
+ */
+export interface QueueDrainEvent {
+  type: "queue_drain";
+  /** Number of queued messages that were merged. */
+  messageCount: number;
+  /** Combined text of the merged messages (newline-separated). */
+  mergedText: string;
+}
+
+/**
+ * Streaming-mode lifecycle. Drives the working-indicator UX:
+ *   - 'requesting'  — waiting for the first chunk
+ *   - 'thinking'    — model is in a thinking / reasoning block
+ *   - 'responding'  — model is emitting text
+ *   - 'tool-input'  — model is streaming tool-call arguments
+ *   - 'tool-use'    — stream complete, tool calls are about to execute
+ */
+export type StreamMode =
+  | "requesting"
+  | "thinking"
+  | "responding"
+  | "tool-input"
+  | "tool-use";
+
+/**
+ * Per-chunk streaming progress. Emitted as the LLM streams its response so
+ * the UI can show a live working indicator with mode-specific labels and
+ * an updating character delta.
+ */
+export interface StreamProgressEvent {
+  type: "stream_progress";
+  /** Characters added by this chunk (0 for mode-only transitions). */
+  charDelta: number;
+  /** Most "advanced" mode the chunk contains (per MODE_PRIORITY). */
+  mode: StreamMode;
+}
+
 /**
  * Final answer generation started
  */
 export interface AnswerStartEvent {
-  type: 'answer_start';
+  type: "answer_start";
 }
 
 /**
@@ -109,13 +302,27 @@ export interface TokenUsage {
   totalTokens: number;
 }
 
+/**
+ * Cumulative token usage update emitted after each LLM call within a turn.
+ * Lets the UI display a live in-turn token counter on the working indicator.
+ */
+export interface TokenUsageEvent {
+  type: "token_usage";
+  /** Running total for the current turn. */
+  usage: TokenUsage;
+}
+
 /**
  * Agent completed with final result
  */
 export interface DoneEvent {
-  type: 'done';
+  type: "done";
   answer: string;
-  toolCalls: Array<{ tool: string; args: Record<string, unknown>; result: string }>;
+  toolCalls: Array<{
+    tool: string;
+    args: Record<string, unknown>;
+    result: string;
+  }>;
   iterations: number;
   totalTime: number;
   tokenUsage?: TokenUsage;
@@ -131,7 +338,15 @@ export type AgentEvent =
   | ToolProgressEvent
   | ToolEndEvent
   | ToolErrorEvent
+  | ToolApprovalEvent
+  | ToolDeniedEvent
   | ToolLimitEvent
   | ContextClearedEvent
+  | CompactionEvent
+  | MemoryFlushEvent
+  | MicrocompactEvent
+  | QueueDrainEvent
+  | StreamProgressEvent
+  | TokenUsageEvent
   | AnswerStartEvent
   | DoneEvent;