@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/agent/glob-match.ts

@@ -0,0 +1,146 @@
+/**
+ * Minimal glob matcher: `*`, `?`, and `**` only. Brace expansion is on by
+ * default and bounded (see `expandGlobBraces`); a host can turn it off. No
+ * regex, no dependency.
+ */
+
+export interface BraceExpansionOptions {
+  /** Max alternatives produced by expansion (default 128). */
+  maxAlternatives?: number;
+  /** Max total bytes across all expanded alternatives (default 4096). */
+  maxExpandedBytes?: number;
+}
+
+const DEFAULT_MAX_BRACE_ALTERNATIVES = 128;
+const DEFAULT_MAX_BRACE_EXPANDED_BYTES = 4_096;
+
+/**
+ * Expand `{a,b}` groups in a pattern (cartesian across multiple groups).
+ * Bounded: max alternatives and max total expanded bytes; unbalanced or nested
+ * braces fail closed. With no braces (or empty text), returns `[pattern]`.
+ */
+export function expandGlobBraces(pattern: string, options?: BraceExpansionOptions): string[] {
+  const maxAlternatives = options?.maxAlternatives ?? DEFAULT_MAX_BRACE_ALTERNATIVES;
+  const maxExpandedBytes = options?.maxExpandedBytes ?? DEFAULT_MAX_BRACE_EXPANDED_BYTES;
+  const results: string[] = [];
+
+  const go = (start: number, prefix: string): void => {
+    if (results.length >= maxAlternatives) {
+      throw new Error(`brace expansion exceeds ${maxAlternatives} alternative limit`);
+    }
+    const open = pattern.indexOf("{", start);
+    if (open === -1) {
+      const out = prefix + pattern.slice(start);
+      if (Buffer.byteLength(out, "utf8") > maxExpandedBytes) {
+        throw new Error(`brace expansion exceeds ${maxExpandedBytes} byte limit`);
+      }
+      results.push(out);
+      return;
+    }
+    let depth = 1;
+    let close = -1;
+    for (let i = open + 1; i < pattern.length; i++) {
+      const ch = pattern[i];
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          close = i;
+          break;
+        }
+      }
+    }
+    if (close === -1) throw new Error(`unbalanced brace expansion in pattern: ${pattern}`);
+    if (depth !== 0) throw new Error(`unbalanced brace expansion in pattern: ${pattern}`);
+    const body = pattern.slice(open + 1, close);
+    if (body.includes("{") || body.includes("}")) {
+      throw new Error(`nested brace expansion is not supported in pattern: ${pattern}`);
+    }
+    if (body.length === 0) throw new Error(`empty brace expansion in pattern: ${pattern}`);
+    for (const alt of body.split(",")) {
+      go(close + 1, prefix + pattern.slice(start, open) + alt);
+    }
+  };
+
+  go(0, "");
+  return results;
+}
+
+export function validateGlobPattern(pattern: string, maxPatternBytes: number, options?: { braceExpansion?: boolean }): void {
+  const patternBytes = Buffer.byteLength(pattern, "utf8");
+  if (patternBytes < 1) throw new Error("pattern must be non-empty");
+  if (patternBytes > maxPatternBytes) {
+    throw new Error(`pattern exceeds ${maxPatternBytes} byte pattern limit`);
+  }
+  if (pattern.includes("{") || pattern.includes("}")) {
+    if (options?.braceExpansion !== false) {
+      // Bounded expansion is validated by expandGlobBraces (alternatives + byte caps).
+      expandGlobBraces(pattern);
+      return;
+    }
+    throw new Error("brace expansion is disabled for this tool (host set braceExpansion: false)");
+  }
+}
+
+function matchSegment(pattern: string, segment: string): boolean {
+  function go(pi: number, si: number): boolean {
+    if (pi === pattern.length) return si === segment.length;
+    const pc = pattern[pi];
+    if (pc === "*") {
+      if (pi === pattern.length - 1) return true;
+      for (let k = si; k <= segment.length; k++) {
+        if (go(pi + 1, k)) return true;
+      }
+      return false;
+    }
+    if (pc === "?") {
+      if (si >= segment.length) return false;
+      return go(pi + 1, si + 1);
+    }
+    if (si >= segment.length || pc !== segment[si]) return false;
+    return go(pi + 1, si + 1);
+  }
+  return go(0, 0);
+}
+
+function splitPattern(pattern: string): string[] {
+  const normalized = pattern.replace(/\\/g, "/");
+  if (normalized === "") return [];
+  const parts = normalized.split("/");
+  if (parts.length > 0 && parts[0] === "") parts.shift();
+  if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
+  return parts;
+}
+
+function matchSegments(patternParts: readonly string[], pathParts: readonly string[], pi: number, pj: number): boolean {
+  while (pi < patternParts.length) {
+    const part = patternParts[pi];
+    if (part === "**") {
+      pi++;
+      if (pi === patternParts.length) return true;
+      for (let k = pj; k <= pathParts.length; k++) {
+        if (matchSegments(patternParts, pathParts, pi, k)) return true;
+      }
+      return false;
+    }
+    if (pj >= pathParts.length) return false;
+    if (!matchSegment(part, pathParts[pj])) return false;
+    pi++;
+    pj++;
+  }
+  return pj === pathParts.length;
+}
+
+/** Match a workspace-relative path against a glob pattern using `/` separators. */
+export function matchGlobPattern(pattern: string, path: string): boolean {
+  const patternParts = splitPattern(pattern);
+  const pathParts = splitPattern(path);
+  if (patternParts.length === 0) return pathParts.length === 0;
+  return matchSegments(patternParts, pathParts, 0, 0);
+}
+
+/** A path predicate for one pattern, brace-expanded (bounded) unless disabled. */
+export function compileGlob(pattern: string, braceExpansion = true): (path: string) => boolean {
+  const patterns = braceExpansion ? expandGlobBraces(pattern) : [pattern];
+  return (path) => patterns.some((alternative) => matchGlobPattern(alternative, path));
+}

package/coding/src/agent/glob.ts

@@ -0,0 +1,182 @@
+/**
+ * `glob` tool: bounded native pattern file finder.
+ */
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { CODING_OBSERVATION_EFFECT } from "./effects.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { HARD_MAX_REPO_DEPTH, HARD_MAX_REPO_RESULTS, validateCodingLimit, validateCodingLimitAllowZero } from "./limits.js";
+import {
+  createLocalRepositoryOperations,
+  RepositoryError,
+  type RepositoryGlobResult,
+  type RepositoryLimitOptions,
+  type RepositoryOperations,
+  resolveRepositoryLimits,
+} from "./repository.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+
+export interface GlobToolOptions {
+  executionPolicy?: ExecutionPolicy;
+  operations?: RepositoryOperations;
+  repository?: RepositoryLimitOptions;
+  maxDepth?: number;
+  maxResults?: number;
+  exclude?: readonly string[];
+  /** Bounded `{a,b}` brace expansion (default true); set `false` to reject braces. */
+  braceExpansion?: boolean;
+}
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: "glob",
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+function formatGlobText(result: RepositoryGlobResult): string {
+  if (result.paths.length === 0) {
+    return result.truncated ? `[truncated by ${result.truncatedBy ?? "limit"} before any matches]` : "(no matches)";
+  }
+  const lines = [...result.paths];
+  if (result.truncated) {
+    const next = result.nextOffset !== undefined ? ` Use offset=${result.nextOffset} to continue.` : "";
+    lines.push(`[truncated by ${result.truncatedBy ?? "limit"}.${next}]`);
+  }
+  return lines.join("\n");
+}
+
+export function createGlobTool(cwd: string, options?: GlobToolOptions): ToolDefinition {
+  const limits = resolveRepositoryLimits({
+    ...options?.repository,
+    maxDepth: options?.maxDepth ?? options?.repository?.maxDepth,
+    maxResults: options?.maxResults ?? options?.repository?.maxResults,
+    exclude: options?.exclude ?? options?.repository?.exclude,
+  });
+  const ops = options?.operations ?? createLocalRepositoryOperations(limits);
+
+  return {
+    name: "glob",
+    kind: "search",
+    effect: CODING_OBSERVATION_EFFECT,
+    effects: ["read"],
+    description: `Find workspace files by glob pattern without shell find. Supports * (segment), ? (one char), and ** (directories). Brace expansion is on: {a,b} expands (bounded to 128 alternatives / 4096 expanded bytes; unbalanced, nested, or empty braces are errors). Skips hidden names and excluded basenames (default: ${limits.exclude.join(", ")}) unless overridden. Does not follow symlinks. Results paginate with offset/maxResults (default ${limits.maxResults}). Depth default ${limits.maxDepth}. Prefer grep to find text inside files.`,
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: {
+          type: "string",
+          description: "Glob pattern matched against workspace-relative file paths (required)",
+        },
+        path: {
+          type: "string",
+          description: "Workspace-relative directory or file to search under (default: workspace root)",
+        },
+        includeHidden: {
+          type: "boolean",
+          description: "Include dotfile/dotdir names (default false). Excluded basenames still apply.",
+        },
+        maxDepth: {
+          type: "number",
+          description: `Maximum directory depth to descend (default ${limits.maxDepth}, hard ${HARD_MAX_REPO_DEPTH})`,
+        },
+        maxResults: {
+          type: "number",
+          description: `Maximum paths returned in this page (default ${limits.maxResults}, hard ${HARD_MAX_REPO_RESULTS})`,
+        },
+        offset: {
+          type: "number",
+          description: "Number of matching paths to skip before retaining results (default 0)",
+        },
+      },
+      required: ["pattern"],
+      additionalProperties: false,
+    } as JsonObject,
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+      if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+      const pattern = typeof args.pattern === "string" ? args.pattern : "";
+      if (!pattern) return errorResult(toolCallId, "pattern must be a non-empty string");
+
+      const path = typeof args.path === "string" ? args.path : undefined;
+      const includeHidden = args.includeHidden === true;
+      const braceExpansion = options?.braceExpansion !== false;
+      let maxDepth: number | undefined;
+      let maxResults: number | undefined;
+      let offset = 0;
+      try {
+        if (args.maxDepth !== undefined) {
+          maxDepth = validateCodingLimit("maxDepth", args.maxDepth as number, HARD_MAX_REPO_DEPTH);
+        }
+        if (args.maxResults !== undefined) {
+          maxResults = validateCodingLimit("maxResults", args.maxResults as number, HARD_MAX_REPO_RESULTS);
+        }
+        if (args.offset !== undefined) {
+          offset = validateCodingLimitAllowZero("offset", args.offset as number, limits.maxEntries);
+        }
+      } catch (error) {
+        return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+      }
+
+      const policyCheck = await enforceExecutionPolicy(
+        options?.executionPolicy,
+        {
+          kind: "glob",
+          operation: "glob",
+          paths: [path ? path : cwd],
+          risk: "low",
+          metadata: {
+            pattern,
+            includeHidden,
+            braceExpansion,
+            maxDepth,
+            maxResults,
+            offset,
+            sessionId: context.sessionId,
+            runId: context.runId,
+            signal: context.signal,
+          },
+        },
+        toolCallId,
+        "glob",
+      );
+      if (!policyCheck.allowed) return policyCheck.result;
+
+      try {
+        const result = await ops.glob({
+          root: cwd,
+          pattern,
+          path,
+          includeHidden,
+          braceExpansion,
+          exclude: limits.exclude,
+          maxDepth: maxDepth ?? limits.maxDepth,
+          maxResults: maxResults ?? limits.maxResults,
+          offset,
+          signal: context.signal,
+          deadlineMs: limits.maxTimeMs,
+        });
+        return {
+          toolCallId,
+          name: "glob",
+          content: [{ type: "text", text: formatGlobText(result) }],
+          metadata: {
+            truncated: result.truncated,
+            truncatedBy: result.truncatedBy,
+            offset: result.offset,
+            nextOffset: result.nextOffset,
+            returned: result.paths.length,
+            scannedEntries: result.scannedEntries,
+            scannedFiles: result.scannedFiles,
+            paths: result.paths,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof RepositoryError ? error.message : error instanceof Error ? error.message : String(error);
+        return errorResult(toolCallId, message);
+      }
+    },
+  };
+}