sentinelayer-cli 0.1.0

package/src/agents/jules/tools/dispatch.js

@@ -0,0 +1,327 @@
+import { randomUUID } from "node:crypto";
+import { evaluateBudget } from "../../../cost/budget.js";
+import {
+  normalizeRunEvent,
+  appendRunEvent,
+} from "../../../telemetry/ledger.js";
+import { fileRead } from "./file-read.js";
+import { grep } from "./grep.js";
+import { glob } from "./glob.js";
+import { shell } from "./shell.js";
+import { fileEdit } from "./file-edit.js";
+import { frontendAnalyze } from "./frontend-analyze.js";
+import { runtimeAudit } from "./runtime-audit.js";
+import { authAudit } from "./auth-audit.js";
+
+/**
+ * Central tool dispatcher for Jules agents.
+ * Every tool call: budget check → telemetry emit → execute → telemetry result → return.
+ */
+
+const TOOL_MAP = {
+  FileRead: fileRead,
+  Grep: grep,
+  Glob: glob,
+  Shell: shell,
+  FileEdit: fileEdit,
+  FrontendAnalyze: frontendAnalyze,
+  RuntimeAudit: runtimeAudit,
+  AuthAudit: authAudit,
+};
+
+const READ_ONLY_TOOLS = new Set(["FileRead", "Grep", "Glob", "FrontendAnalyze", "RuntimeAudit", "AuthAudit"]);
+
+const RESULT_PERSIST_THRESHOLD = 5000;
+
+/**
+ * @param {string} toolName
+ * @param {object} input
+ * @param {AgentContext} ctx
+ * @returns {Promise<ToolResult>}
+ */
+export 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({
+        stream: "sl_event",
+        event: "budget_stop",
+        agent: ctx.agentIdentity,
+        payload: {
+          stopClass: stopEvent.stop.stopClass,
+          reasons: budgetCheck.reasons,
+        },
+        usage: snapshotUsage(ctx),
+      });
+    }
+
+    throw new BudgetExhaustedError(budgetCheck);
+  }
+
+  // Emit budget warnings
+  if (budgetCheck.warnings.length > 0 && ctx.onEvent) {
+    ctx.onEvent({
+      stream: "sl_event",
+      event: "budget_warning",
+      agent: ctx.agentIdentity,
+      payload: { warnings: budgetCheck.warnings },
+      usage: snapshotUsage(ctx),
+    });
+  }
+
+  // 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({
+      stream: "sl_event",
+      event: "tool_call",
+      agent: ctx.agentIdentity,
+      payload: { tool: toolName, input: sanitizeInput(toolName, input) },
+      usage: snapshotUsage(ctx),
+    });
+  }
+
+  // 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;
+
+  // 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({
+      stream: "sl_event",
+      event: "tool_result",
+      agent: ctx.agentIdentity,
+      payload: {
+        tool: toolName,
+        durationMs,
+        success: !error,
+        error: error?.message,
+      },
+      usage: snapshotUsage(ctx),
+    });
+  }
+
+  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;
+}
+
+/**
+ * Register an additional tool (e.g., FrontendAnalyze from PR J-2).
+ */
+export function registerTool(name, handler, { readOnly = false } = {}) {
+  TOOL_MAP[name] = handler;
+  if (readOnly) READ_ONLY_TOOLS.add(name);
+}
+
+/**
+ * Check if a tool is read-only (safe for concurrent execution).
+ */
+export function isReadOnlyTool(toolName) {
+  return READ_ONLY_TOOLS.has(toolName);
+}
+
+/**
+ * Get list of available tool names.
+ */
+export function listTools() {
+  return Object.keys(TOOL_MAP);
+}
+
+/**
+ * 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,
+    },
+    sessionId: sessionId || randomUUID(),
+    runId: runId || `jules-${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,
+  };
+}
+
+function sanitizeInput(toolName, input) {
+  // Strip file content from telemetry (only log metadata)
+  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/jules/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/jules/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}`);
+  }
+}