sentinelayer-cli 0.4.5 → 0.8.0

package/src/agents/shared-tools/dispatch-core.js

@@ -0,0 +1,320 @@
+import { randomUUID } from "node:crypto";
+import { evaluateBudget } from "../../cost/budget.js";
+import {
+  normalizeRunEvent,
+  appendRunEvent,
+} from "../../telemetry/ledger.js";
+import { createAgentEvent } from "../../events/schema.js";
+
+/**
+ * Shared tool dispatch infrastructure.
+ *
+ * Each persona builds its own TOOL_MAP (shared tools + domain tools)
+ * and creates a dispatcher via createToolDispatcher(). This avoids
+ * duplicating budget enforcement, telemetry, and result persistence.
+ */
+
+const RESULT_PERSIST_THRESHOLD = 5000;
+
+/**
+ * Create a tool dispatcher bound to a specific TOOL_MAP.
+ *
+ * @param {Record<string, Function>} toolMap - { ToolName: handler }
+ * @param {Set<string>} [readOnlyTools] - tool names safe for concurrent use
+ * @returns {{ dispatchTool, registerTool, isReadOnlyTool, listTools }}
+ */
+export function createToolDispatcher(toolMap, readOnlyTools) {
+  const TOOL_MAP = { ...toolMap };
+  const READ_ONLY_TOOLS = new Set(readOnlyTools || []);
+
+  async function dispatchTool(toolName, input, ctx) {
+    const handler = TOOL_MAP[toolName];
+    if (!handler) {
+      throw new ToolDispatchError(`Unknown tool: ${toolName}`);
+    }
+
+    // 1. Pre-flight budget check
+    const budgetCheck = evaluateBudget({
+      maxCostUsd: ctx.budget.maxCostUsd,
+      maxOutputTokens: ctx.budget.maxOutputTokens,
+      maxRuntimeMs: ctx.budget.maxRuntimeMs,
+      maxToolCalls: ctx.budget.maxToolCalls,
+      warningThresholdPercent: ctx.budget.warningThresholdPercent ?? 70,
+      maxNoProgress: 0,
+      sessionSummary: {
+        costUsd: ctx.usage.costUsd,
+        outputTokens: ctx.usage.outputTokens,
+        durationMs: Date.now() - ctx.startedAt,
+        toolCalls: ctx.usage.toolCalls + 1,
+        noProgressStreak: 0,
+      },
+    });
+
+    if (budgetCheck.blocking) {
+      const stopEvent = {
+        eventType: "run_stop",
+        sessionId: ctx.sessionId,
+        runId: ctx.runId,
+        stop: {
+          stopClass: budgetCheck.reasons[0]?.code || "MAX_TOOL_CALLS_EXCEEDED",
+          blocking: true,
+          reasonCodes: budgetCheck.reasons.map((r) => r.code),
+        },
+        usage: snapshotUsage(ctx),
+        metadata: { tool: toolName, phase: "pre_flight" },
+      };
+      await safeAppendEvent(ctx, stopEvent);
+
+      if (ctx.onEvent) {
+        ctx.onEvent(createAgentEvent({
+          event: "budget_stop",
+          agent: ctx.agentIdentity,
+          payload: {
+            stopClass: stopEvent.stop.stopClass,
+            reasons: budgetCheck.reasons,
+          },
+          usage: snapshotUsage(ctx),
+          sessionId: ctx.sessionId,
+          runId: ctx.runId,
+        }));
+      }
+
+      throw new BudgetExhaustedError(budgetCheck);
+    }
+
+    // Emit budget warnings
+    if (budgetCheck.warnings.length > 0 && ctx.onEvent) {
+      ctx.onEvent(createAgentEvent({
+        event: "budget_warning",
+        agent: ctx.agentIdentity,
+        payload: { warnings: budgetCheck.warnings },
+        usage: snapshotUsage(ctx),
+        sessionId: ctx.sessionId,
+        runId: ctx.runId,
+      }));
+    }
+
+    // 2. Emit tool_call event
+    const eventId = randomUUID();
+    const callEvent = {
+      eventType: "tool_call",
+      sessionId: ctx.sessionId,
+      runId: ctx.runId,
+      metadata: {
+        eventId,
+        tool: toolName,
+        input: sanitizeInput(toolName, input),
+        agentId: ctx.agentIdentity?.id,
+        persona: ctx.agentIdentity?.persona,
+      },
+    };
+    await safeAppendEvent(ctx, callEvent);
+
+    if (ctx.onEvent) {
+      ctx.onEvent(createAgentEvent({
+        event: "tool_call",
+        agent: ctx.agentIdentity,
+        payload: { tool: toolName, input: sanitizeInput(toolName, input) },
+        usage: snapshotUsage(ctx),
+        sessionId: ctx.sessionId,
+        runId: ctx.runId,
+      }));
+    }
+
+    // 3. Execute
+    const startMs = Date.now();
+    let result;
+    let error;
+    try {
+      result = handler(input);
+    } catch (err) {
+      error = err;
+    }
+    const durationMs = Date.now() - startMs;
+
+    // 4. Update accumulated usage
+    ctx.usage.toolCalls++;
+    ctx.usage.runtimeMs = Date.now() - ctx.startedAt;
+    ctx.lastToolCallAt = Date.now();
+    ctx.lastToolName = toolName;
+
+    // Track confirmed file reads for coverage accounting
+    if (!error && toolName === "FileRead") {
+      const readPath = input?.file_path || input?.filePath || input?.path || "";
+      if (readPath && ctx.usage.filesRead) ctx.usage.filesRead.add(readPath);
+    }
+
+    // 5. Emit tool_result event
+    const resultEvent = {
+      eventType: "tool_call",
+      sessionId: ctx.sessionId,
+      runId: ctx.runId,
+      usage: {
+        durationMs,
+        toolCalls: 1,
+      },
+      metadata: {
+        eventId,
+        phase: "result",
+        tool: toolName,
+        success: !error,
+        error: error?.message,
+        agentId: ctx.agentIdentity?.id,
+      },
+    };
+    await safeAppendEvent(ctx, resultEvent);
+
+    if (ctx.onEvent) {
+      ctx.onEvent(createAgentEvent({
+        event: "tool_result",
+        agent: ctx.agentIdentity,
+        payload: {
+          tool: toolName,
+          durationMs,
+          success: !error,
+          error: error?.message,
+        },
+        usage: snapshotUsage(ctx),
+        sessionId: ctx.sessionId,
+        runId: ctx.runId,
+      }));
+    }
+
+    if (error) throw error;
+
+    // 6. Large result persistence
+    const serialized = JSON.stringify(result);
+    if (serialized.length > RESULT_PERSIST_THRESHOLD && ctx.artifactDir) {
+      const refPath = `${ctx.artifactDir}/tool-results/${eventId}.json`;
+      const fsp = await import("node:fs/promises");
+      await fsp.mkdir(`${ctx.artifactDir}/tool-results`, { recursive: true });
+      await fsp.writeFile(refPath, serialized, "utf-8");
+      return {
+        _persisted: true,
+        _refPath: refPath,
+        _summary: summarizeResult(toolName, result),
+      };
+    }
+
+    return result;
+  }
+
+  function registerTool(name, handler, { readOnly = false } = {}) {
+    TOOL_MAP[name] = handler;
+    if (readOnly) READ_ONLY_TOOLS.add(name);
+  }
+
+  function isReadOnlyTool(toolName) {
+    return READ_ONLY_TOOLS.has(toolName);
+  }
+
+  function listTools() {
+    return Object.keys(TOOL_MAP);
+  }
+
+  return { dispatchTool, registerTool, isReadOnlyTool, listTools };
+}
+
+/**
+ * Create an agent context for tool dispatch.
+ */
+export function createAgentContext({
+  agentIdentity,
+  budget,
+  sessionId,
+  runId,
+  artifactDir,
+  onEvent,
+}) {
+  return {
+    agentIdentity,
+    budget: {
+      maxCostUsd: budget?.maxCostUsd ?? 5.0,
+      maxOutputTokens: budget?.maxOutputTokens ?? 12000,
+      maxRuntimeMs: budget?.maxRuntimeMs ?? 300000,
+      maxToolCalls: budget?.maxToolCalls ?? 150,
+      warningThresholdPercent: budget?.warningThresholdPercent ?? 70,
+    },
+    usage: {
+      costUsd: 0,
+      outputTokens: 0,
+      toolCalls: 0,
+      runtimeMs: 0,
+      filesRead: new Set(),
+    },
+    sessionId: sessionId || randomUUID(),
+    runId: runId || `agent-${Date.now()}-${randomUUID().slice(0, 8)}`,
+    artifactDir,
+    startedAt: Date.now(),
+    lastToolCallAt: Date.now(),
+    lastToolName: null,
+    onEvent,
+  };
+}
+
+function snapshotUsage(ctx) {
+  return {
+    costUsd: ctx.usage.costUsd,
+    outputTokens: ctx.usage.outputTokens,
+    toolCalls: ctx.usage.toolCalls,
+    durationMs: Date.now() - ctx.startedAt,
+    filesRead: [...(ctx.usage.filesRead || [])],
+  };
+}
+
+function sanitizeInput(toolName, input) {
+  const sanitized = { ...input };
+  if (sanitized.content && sanitized.content.length > 200) {
+    sanitized.content = `[${sanitized.content.length} chars]`;
+  }
+  return sanitized;
+}
+
+function summarizeResult(toolName, result) {
+  if (toolName === "FileRead") {
+    return `Read ${result.numLines} lines from ${result.filePath}`;
+  }
+  if (toolName === "Grep") {
+    return `${result.numMatches} matches in ${result.numFiles} files`;
+  }
+  if (toolName === "Glob") {
+    return `${result.numFiles} files matched`;
+  }
+  if (toolName === "Shell") {
+    return `Exit ${result.exitCode} in ${result.durationMs}ms`;
+  }
+  return `${toolName} completed`;
+}
+
+async function safeAppendEvent(ctx, eventData) {
+  try {
+    const normalized = normalizeRunEvent({
+      ...eventData,
+      sessionId: ctx.sessionId,
+      runId: ctx.runId,
+    });
+    if (ctx.artifactDir) {
+      await appendRunEvent(
+        { targetPath: ctx.artifactDir, outputDir: ctx.artifactDir },
+        normalized,
+      );
+    }
+  } catch {
+    // Telemetry failures must not block tool execution
+  }
+}
+
+export class ToolDispatchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ToolDispatchError";
+  }
+}
+
+export class BudgetExhaustedError extends Error {
+  constructor(budgetCheck) {
+    super(`Budget exhausted: ${budgetCheck.reasons.map((r) => r.code).join(", ")}`);
+    this.name = "BudgetExhaustedError";
+    this.budgetCheck = budgetCheck;
+  }
+}

package/src/agents/shared-tools/file-edit.js

@@ -0,0 +1,180 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { PathGuardError, resolveGuardedPath } from "./path-guards.js";
+
+/**
+ * String replacement in files with uniqueness enforcement and diff generation.
+ * Designed for use inside a worktree — validates path is within allowed directory.
+ *
+ * @param {object} input
+ * @param {string} input.file_path - Absolute path to the file to modify.
+ * @param {string} input.old_string - Exact text to replace.
+ * @param {string} input.new_string - Replacement text (must differ from old_string).
+ * @param {boolean} [input.replace_all] - Replace all occurrences (default: false).
+ * @param {string} [input.allowed_root] - Root directory edits are permitted in (worktree guard).
+ * @returns {{ filePath, diff, occurrencesFound, occurrencesReplaced, linesChanged }}
+ */
+export function fileEdit(input) {
+  if (!input.old_string && input.old_string !== "") {
+    throw new FileEditError("old_string is required.");
+  }
+  if (input.new_string === undefined || input.new_string === null) {
+    throw new FileEditError("new_string is required.");
+  }
+  if (input.old_string === input.new_string) {
+    throw new FileEditError("old_string and new_string must be different.");
+  }
+
+  let filePath;
+  try {
+    const guarded = resolveGuardedPath({
+      filePath: input.file_path,
+      allowedRoot: input.allowed_root || undefined,
+    });
+    filePath = guarded.resolvedPath;
+  } catch (error) {
+    if (error instanceof PathGuardError) {
+      throw new FileEditError(error.message);
+    }
+    if (error instanceof FileEditError) {
+      throw error;
+    }
+    throw new FileEditError(`Cannot access path: ${error.message}`);
+  }
+
+  // Read current content
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new FileEditError(`File not found: ${filePath}`);
+    }
+    throw new FileEditError(`Cannot read file: ${err.message}`);
+  }
+
+  // Count occurrences
+  const occurrences = countOccurrences(content, input.old_string);
+  if (occurrences === 0) {
+    throw new FileEditError(
+      `old_string not found in ${filePath}. Verify the exact text including whitespace and indentation.`,
+    );
+  }
+  if (occurrences > 1 && !input.replace_all) {
+    throw new FileEditError(
+      `old_string found ${occurrences} times in ${filePath}. Use replace_all: true to replace all, or provide more surrounding context to make it unique.`,
+    );
+  }
+
+  // Perform replacement
+  const replaceCount = input.replace_all ? occurrences : 1;
+  let newContent;
+  if (input.replace_all) {
+    newContent = content.split(input.old_string).join(input.new_string);
+  } else {
+    const idx = content.indexOf(input.old_string);
+    newContent =
+      content.slice(0, idx) +
+      input.new_string +
+      content.slice(idx + input.old_string.length);
+  }
+
+  // Generate unified diff for display
+  const diff = generateUnifiedDiff(filePath, content, newContent);
+
+  // Count changed lines
+  const oldLines = content.split("\n").length;
+  const newLines = newContent.split("\n").length;
+  const linesChanged = Math.abs(newLines - oldLines) +
+    countDiffLines(content, newContent);
+
+  // Write atomically: temp file + rename
+  const tmpPath = filePath + `.sl-edit-${Date.now()}`;
+  fs.writeFileSync(tmpPath, newContent, "utf-8");
+  fs.renameSync(tmpPath, filePath);
+
+  return {
+    filePath,
+    diff,
+    occurrencesFound: occurrences,
+    occurrencesReplaced: replaceCount,
+    linesChanged,
+    beforeHash: hashContent(content),
+    afterHash: hashContent(newContent),
+  };
+}
+
+function countOccurrences(haystack, needle) {
+  if (!needle) return 0;
+  let count = 0;
+  let idx = 0;
+  while ((idx = haystack.indexOf(needle, idx)) !== -1) {
+    count++;
+    idx += needle.length;
+  }
+  return count;
+}
+
+function generateUnifiedDiff(filePath, oldContent, newContent) {
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+  const diffLines = [];
+
+  diffLines.push(`--- a/${path.basename(filePath)}`);
+  diffLines.push(`+++ b/${path.basename(filePath)}`);
+
+  // Simple line-by-line diff (not full Myers — sufficient for review display)
+  const maxLines = Math.max(oldLines.length, newLines.length);
+  let chunkStart = -1;
+  let chunkOld = [];
+  let chunkNew = [];
+
+  for (let i = 0; i < maxLines; i++) {
+    const oldLine = i < oldLines.length ? oldLines[i] : undefined;
+    const newLine = i < newLines.length ? newLines[i] : undefined;
+
+    if (oldLine !== newLine) {
+      if (chunkStart === -1) chunkStart = i;
+      if (oldLine !== undefined) chunkOld.push(`-${oldLine}`);
+      if (newLine !== undefined) chunkNew.push(`+${newLine}`);
+    } else if (chunkStart !== -1) {
+      // Flush chunk
+      diffLines.push(`@@ -${chunkStart + 1},${chunkOld.length} +${chunkStart + 1},${chunkNew.length} @@`);
+      diffLines.push(...chunkOld, ...chunkNew);
+      chunkStart = -1;
+      chunkOld = [];
+      chunkNew = [];
+    }
+  }
+
+  // Flush final chunk
+  if (chunkStart !== -1) {
+    diffLines.push(`@@ -${chunkStart + 1},${chunkOld.length} +${chunkStart + 1},${chunkNew.length} @@`);
+    diffLines.push(...chunkOld, ...chunkNew);
+  }
+
+  return diffLines.join("\n");
+}
+
+function countDiffLines(oldContent, newContent) {
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+  let changed = 0;
+  const max = Math.min(oldLines.length, newLines.length);
+  for (let i = 0; i < max; i++) {
+    if (oldLines[i] !== newLines[i]) changed++;
+  }
+  return changed;
+}
+
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+export class FileEditError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FileEditError";
+  }
+}

package/src/agents/shared-tools/file-read.js

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PathGuardError, resolveGuardedPath } from "./path-guards.js";
+
+const MAX_RESULT_CHARS = 5000;
+const BINARY_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".svg",
+  ".woff", ".woff2", ".ttf", ".eot", ".otf",
+  ".mp3", ".mp4", ".ogg", ".webm", ".wav",
+  ".zip", ".tar", ".gz", ".br", ".zst",
+  ".pdf", ".wasm", ".node", ".exe", ".dll", ".so", ".dylib",
+]);
+
+/**
+ * Read a file with line numbers, offset/limit pagination, and binary detection.
+ * Returns { filePath, content, numLines, startLine, totalLines, truncated }.
+ */
+export function fileRead(input) {
+  const filePath = resolveAndValidatePath(input.file_path, input.allowed_root);
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (BINARY_EXTENSIONS.has(ext)) {
+    const stat = fs.statSync(filePath);
+    return {
+      filePath,
+      content: `[Binary file: ${ext}, ${stat.size} bytes. Use a specialized viewer.]`,
+      numLines: 0,
+      startLine: 0,
+      totalLines: 0,
+      truncated: false,
+      binary: true,
+    };
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new FileReadError(`File not found: ${filePath}`);
+    }
+    if (err.code === "EISDIR") {
+      throw new FileReadError(`Path is a directory, not a file: ${filePath}`);
+    }
+    throw new FileReadError(`Cannot read file: ${err.message}`);
+  }
+
+  const allLines = raw.split("\n");
+  const totalLines = allLines.length;
+  const offset = Math.max(0, input.offset ?? 0);
+  const limit = input.limit ?? 2000;
+  const sliced = allLines.slice(offset, offset + limit);
+  const startLine = offset + 1;
+
+  const numbered = sliced.map(
+    (line, i) => `${String(startLine + i).padStart(6)}\t${line}`,
+  );
+  let content = numbered.join("\n");
+  let truncated = false;
+
+  if (content.length > MAX_RESULT_CHARS) {
+    content = content.slice(0, MAX_RESULT_CHARS) + "\n[... truncated]";
+    truncated = true;
+  }
+
+  return {
+    filePath,
+    content,
+    numLines: sliced.length,
+    startLine,
+    totalLines,
+    truncated,
+    binary: false,
+  };
+}
+
+export class FileReadError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FileReadError";
+  }
+}
+
+function resolveAndValidatePath(filePath, allowedRoot) {
+  try {
+    const guarded = resolveGuardedPath({
+      filePath,
+      allowedRoot: allowedRoot || undefined,
+    });
+    return guarded.resolvedPath;
+  } catch (error) {
+    if (error instanceof PathGuardError) {
+      throw new FileReadError(error.message);
+    }
+    if (error instanceof FileReadError) {
+      throw error;
+    }
+    throw new FileReadError(`Cannot access path: ${error.message}`);
+  }
+}