stagent 0.4.0 → 0.6.0

package/src/lib/agents/agentic-loop.ts

@@ -0,0 +1,235 @@
+/**
+ * Provider-agnostic agentic loop for direct API runtimes.
+ *
+ * The loop handles turn counting, budget tracking, abort signaling,
+ * and HITL tool permission checks. Provider-specific logic (API calls,
+ * event mapping, tool result formatting) is injected via callbacks.
+ */
+
+import type { ToolResult } from "@/lib/chat/tool-registry";
+import type { ToolPermissionResponse } from "./tool-permissions";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/** A single tool call extracted from the model response. */
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/** Usage snapshot from a single model turn. */
+export interface TurnUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  modelId?: string;
+  costUsd?: number;
+}
+
+/** Events emitted during the loop for SSE streaming. */
+export type AgentStreamEvent =
+  | { type: "status"; phase: "running" | "tool_use" | "thinking"; message?: string }
+  | { type: "delta"; content: string }
+  | { type: "done"; finalText: string }
+  | { type: "error"; message: string };
+
+/** Result of a single model API call (accumulated from stream). */
+export interface ModelTurnResult {
+  /** Concatenated text output from the model. */
+  text: string;
+  /** Tool calls requested by the model. */
+  toolCalls: ToolCall[];
+  /** Whether the model indicated it is done (end_turn / stop). */
+  isComplete: boolean;
+  /** Whether output was truncated by max_tokens. */
+  needsContinuation: boolean;
+  /** Usage for this turn. */
+  usage: TurnUsage;
+}
+
+/** Message in the conversation history (provider-agnostic shape). */
+export type LoopMessage = Record<string, unknown>;
+
+/** Configuration for the agentic loop — provider injects callbacks. */
+export interface AgenticLoopConfig {
+  /**
+   * Call the model API with the current messages. Must stream events
+   * via `emitEvent` and return the accumulated turn result.
+   */
+  callModel: (
+    messages: LoopMessage[],
+    signal: AbortSignal,
+  ) => Promise<ModelTurnResult>;
+
+  /** Format a tool result for appending to the message history. */
+  formatToolResult: (
+    toolCallId: string,
+    toolName: string,
+    result: ToolResult,
+  ) => LoopMessage;
+
+  /** Format a continuation message (e.g. after max_tokens truncation). */
+  formatContinuation: () => LoopMessage;
+
+  /** Execute a Stagent tool by name. */
+  executeTool: (
+    name: string,
+    args: Record<string, unknown>,
+  ) => Promise<ToolResult>;
+
+  /** HITL permission check. Return allow/deny. */
+  checkPermission: (
+    toolName: string,
+    args: Record<string, unknown>,
+  ) => Promise<ToolPermissionResponse>;
+
+  /** Emit SSE event for real-time UI streaming. */
+  emitEvent: (event: AgentStreamEvent) => void;
+
+  /** Maximum model turns before stopping. */
+  maxTurns: number;
+
+  /** Maximum budget in USD before stopping. */
+  maxBudgetUsd?: number;
+
+  /** Abort signal for cancellation. */
+  signal: AbortSignal;
+}
+
+/** Result of the agentic loop. */
+export interface AgenticLoopResult {
+  finalText: string;
+  turnCount: number;
+  totalUsage: TurnUsage;
+  stopReason: "complete" | "max_turns" | "budget_exceeded" | "cancelled" | "error";
+}
+
+// ── Loop implementation ──────────────────────────────────────────────
+
+function mergeTurnUsage(total: TurnUsage, turn: TurnUsage): TurnUsage {
+  return {
+    inputTokens: (total.inputTokens ?? 0) + (turn.inputTokens ?? 0),
+    outputTokens: (total.outputTokens ?? 0) + (turn.outputTokens ?? 0),
+    totalTokens: (total.totalTokens ?? 0) + (turn.totalTokens ?? 0),
+    modelId: turn.modelId ?? total.modelId,
+    costUsd: (total.costUsd ?? 0) + (turn.costUsd ?? 0),
+  };
+}
+
+/**
+ * Run a provider-agnostic agentic loop.
+ *
+ * Repeatedly calls the model, handles tool execution with HITL checks,
+ * and enforces turn/budget limits until the model completes or a limit
+ * is reached.
+ */
+export async function runAgenticLoop(
+  initialMessages: LoopMessage[],
+  config: AgenticLoopConfig,
+): Promise<AgenticLoopResult> {
+  const messages = [...initialMessages];
+  let turnCount = 0;
+  let totalUsage: TurnUsage = {};
+  let lastText = "";
+
+  while (turnCount < config.maxTurns) {
+    // Check cancellation
+    if (config.signal.aborted) {
+      return { finalText: lastText, turnCount, totalUsage, stopReason: "cancelled" };
+    }
+
+    // Check budget
+    if (config.maxBudgetUsd && (totalUsage.costUsd ?? 0) >= config.maxBudgetUsd) {
+      config.emitEvent({ type: "error", message: "Budget limit exceeded" });
+      return { finalText: lastText, turnCount, totalUsage, stopReason: "budget_exceeded" };
+    }
+
+    // Call model
+    turnCount++;
+    let turnResult: ModelTurnResult;
+
+    try {
+      turnResult = await config.callModel(messages, config.signal);
+    } catch (err) {
+      if (config.signal.aborted) {
+        return { finalText: lastText, turnCount, totalUsage, stopReason: "cancelled" };
+      }
+      const message = err instanceof Error ? err.message : "Model API call failed";
+      config.emitEvent({ type: "error", message });
+      return { finalText: lastText, turnCount, totalUsage, stopReason: "error" };
+    }
+
+    totalUsage = mergeTurnUsage(totalUsage, turnResult.usage);
+    if (turnResult.text) lastText = turnResult.text;
+
+    // Handle completion
+    if (turnResult.isComplete && turnResult.toolCalls.length === 0) {
+      config.emitEvent({ type: "done", finalText: lastText });
+      return { finalText: lastText, turnCount, totalUsage, stopReason: "complete" };
+    }
+
+    // Handle tool calls
+    if (turnResult.toolCalls.length > 0) {
+      for (const toolCall of turnResult.toolCalls) {
+        if (config.signal.aborted) {
+          return { finalText: lastText, turnCount, totalUsage, stopReason: "cancelled" };
+        }
+
+        config.emitEvent({
+          type: "status",
+          phase: "tool_use",
+          message: toolCall.name,
+        });
+
+        // HITL permission check
+        const permission = await config.checkPermission(
+          toolCall.name,
+          toolCall.arguments,
+        );
+
+        let result: ToolResult;
+        if (permission.behavior === "deny") {
+          result = {
+            content: [{ type: "text", text: JSON.stringify({ error: permission.message ?? "Tool denied by user" }) }],
+            isError: true,
+          };
+        } else {
+          try {
+            result = await config.executeTool(
+              toolCall.name,
+              (permission.updatedInput as Record<string, unknown>) ?? toolCall.arguments,
+            );
+          } catch (err) {
+            result = {
+              content: [{ type: "text", text: JSON.stringify({ error: err instanceof Error ? err.message : "Tool execution failed" }) }],
+              isError: true,
+            };
+          }
+        }
+
+        // Append tool result to messages
+        messages.push(
+          config.formatToolResult(toolCall.id, toolCall.name, result),
+        );
+      }
+
+      // Continue loop — model needs to process tool results
+      continue;
+    }
+
+    // Handle max_tokens continuation
+    if (turnResult.needsContinuation) {
+      messages.push(config.formatContinuation());
+      continue;
+    }
+
+    // Shouldn't reach here — safeguard
+    config.emitEvent({ type: "done", finalText: lastText });
+    return { finalText: lastText, turnCount, totalUsage, stopReason: "complete" };
+  }
+
+  // Max turns exceeded
+  config.emitEvent({ type: "error", message: `Max turns (${config.maxTurns}) reached` });
+  return { finalText: lastText, turnCount, totalUsage, stopReason: "max_turns" };
+}

package/src/lib/agents/browser-mcp.ts

@@ -0,0 +1,174 @@
+import { getSetting } from "@/lib/settings/helpers";
+import { SETTINGS_KEYS } from "@/lib/constants/settings";
+
+// ── MCP server config types (matches Claude Agent SDK shape) ─────────
+
+interface McpStdioConfig {
+  type?: "stdio";
+  command: string;
+  args: string[];
+}
+
+interface McpHttpConfig {
+  type: "http";
+  url: string;
+  headers?: Record<string, string>;
+}
+
+type AnyMcpServerConfig = McpStdioConfig | McpHttpConfig;
+
+// ── Read-only browser tools — auto-approved in chat & task permission callbacks
+
+export const BROWSER_READ_ONLY_TOOLS = new Set([
+  // Chrome DevTools MCP — read-only
+  "mcp__chrome-devtools__take_screenshot",
+  "mcp__chrome-devtools__take_snapshot",
+  "mcp__chrome-devtools__take_memory_snapshot",
+  "mcp__chrome-devtools__list_pages",
+  "mcp__chrome-devtools__list_console_messages",
+  "mcp__chrome-devtools__list_network_requests",
+  "mcp__chrome-devtools__get_console_message",
+  "mcp__chrome-devtools__get_network_request",
+  "mcp__chrome-devtools__lighthouse_audit",
+  "mcp__chrome-devtools__performance_start_trace",
+  "mcp__chrome-devtools__performance_stop_trace",
+  "mcp__chrome-devtools__performance_analyze_insight",
+  // Playwright MCP — read-only
+  "mcp__playwright__browser_snapshot",
+  "mcp__playwright__browser_console_messages",
+  "mcp__playwright__browser_network_requests",
+  "mcp__playwright__browser_tabs",
+  "mcp__playwright__browser_take_screenshot",
+]);
+
+// ── Helper: check if a tool name belongs to a browser MCP server ─────
+
+export function isBrowserTool(toolName: string): boolean {
+  return (
+    toolName.startsWith("mcp__chrome-devtools__") ||
+    toolName.startsWith("mcp__playwright__")
+  );
+}
+
+export function isBrowserReadOnly(toolName: string): boolean {
+  return BROWSER_READ_ONLY_TOOLS.has(toolName);
+}
+
+// ── Config builder ───────────────────────────────────────────────────
+
+function parseExtraArgs(config: string | null): string[] {
+  if (!config) return [];
+  const trimmed = config.trim();
+  if (!trimmed) return [];
+
+  // Try JSON array first (e.g. '["--browser", "firefox"]')
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) return parsed.filter((a): a is string => typeof a === "string");
+    } catch {
+      // Fall through to space-split
+    }
+  }
+
+  // Plain string: split on whitespace (e.g. "--headless --browser-url http://localhost:9222")
+  return trimmed.split(/\s+/).filter(Boolean);
+}
+
+/**
+ * Read browser MCP settings from DB and return MCP server configs
+ * for any enabled browser servers.
+ *
+ * Returns `{}` when neither server is enabled — zero overhead.
+ */
+export async function getBrowserMcpServers(): Promise<Record<string, McpStdioConfig>> {
+  const [chromeEnabled, playwrightEnabled, chromeConfig, playwrightConfig] =
+    await Promise.all([
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_CHROME_DEVTOOLS_ENABLED),
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_PLAYWRIGHT_ENABLED),
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_CHROME_DEVTOOLS_CONFIG),
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_PLAYWRIGHT_CONFIG),
+    ]);
+
+  const servers: Record<string, McpStdioConfig> = {};
+
+  if (chromeEnabled === "true") {
+    const extraArgs = parseExtraArgs(chromeConfig);
+    servers["chrome-devtools"] = {
+      command: "npx",
+      args: ["-y", "chrome-devtools-mcp@latest", ...extraArgs],
+    };
+  }
+
+  if (playwrightEnabled === "true") {
+    const extraArgs = parseExtraArgs(playwrightConfig);
+    servers.playwright = {
+      command: "npx",
+      args: ["-y", "@playwright/mcp@latest", ...extraArgs],
+    };
+  }
+
+  return servers;
+}
+
+/**
+ * Build the allowedTools glob patterns for enabled browser MCP servers.
+ * Returns an empty array when no browser servers are enabled.
+ */
+export async function getBrowserAllowedToolPatterns(): Promise<string[]> {
+  const [chromeEnabled, playwrightEnabled] = await Promise.all([
+    getSetting(SETTINGS_KEYS.BROWSER_MCP_CHROME_DEVTOOLS_ENABLED),
+    getSetting(SETTINGS_KEYS.BROWSER_MCP_PLAYWRIGHT_ENABLED),
+  ]);
+
+  const patterns: string[] = [];
+  if (chromeEnabled === "true") patterns.push("mcp__chrome-devtools__*");
+  if (playwrightEnabled === "true") patterns.push("mcp__playwright__*");
+  return patterns;
+}
+
+// ── Exa Search MCP — semantic web search ────────────────────────────
+
+/** All Exa tools are read-only (search, similarity, content fetch) */
+export const EXA_READ_ONLY_TOOLS = new Set([
+  "mcp__exa__web_search_exa",
+  "mcp__exa__find_similar",
+  "mcp__exa__get_contents",
+]);
+
+export function isExaTool(toolName: string): boolean {
+  return toolName.startsWith("mcp__exa__");
+}
+
+export function isExaReadOnly(toolName: string): boolean {
+  return EXA_READ_ONLY_TOOLS.has(toolName);
+}
+
+/**
+ * Read external MCP server settings from DB and return configs
+ * for any enabled servers. Currently supports Exa Search.
+ *
+ * Returns `{}` when nothing is enabled — zero overhead.
+ */
+export async function getExternalMcpServers(): Promise<Record<string, AnyMcpServerConfig>> {
+  const exaEnabled = await getSetting(SETTINGS_KEYS.EXA_SEARCH_MCP_ENABLED);
+
+  const servers: Record<string, AnyMcpServerConfig> = {};
+
+  if (exaEnabled === "true") {
+    servers.exa = { type: "http", url: "https://mcp.exa.ai/mcp" };
+  }
+
+  return servers;
+}
+
+/**
+ * Build the allowedTools glob patterns for enabled external MCP servers.
+ */
+export async function getExternalAllowedToolPatterns(): Promise<string[]> {
+  const exaEnabled = await getSetting(SETTINGS_KEYS.EXA_SEARCH_MCP_ENABLED);
+
+  const patterns: string[] = [];
+  if (exaEnabled === "true") patterns.push("mcp__exa__*");
+  return patterns;
+}