@abot-ai/runtime 1.0.0

package/plugins/local-search/source/index.ts

@@ -0,0 +1,195 @@
+import { posix } from "node:path";
+
+import {
+  defineRuntimePlugin,
+  failureFromError,
+  failureResult,
+  readBoolean,
+  readBoundedInteger,
+  readOptionalString,
+  readRequiredString,
+  successResult,
+} from "../../../src/plugin-sdk/index.js";
+
+import { isLocalSearchError } from "./errors.js";
+import {
+  budgetSearchOutput,
+  type BudgetedSearchOutput,
+  type SearchEntry,
+} from "./output.js";
+import {
+  qualifyMatchPath,
+  resolveSearchRoot,
+  type SearchRoot,
+} from "./paths.js";
+import {
+  escapeRgGlobLiteral,
+  rgGlobArgs,
+  runRipgrepContentSearch,
+  runRipgrepPathSearch,
+} from "./ripgrep.js";
+
+const DEFAULT_MAX_RESULTS = 40;
+const MAX_RESULTS = 200;
+
+function fileNameMatches(
+  logicalPath: string,
+  query: string,
+  caseSensitive: boolean,
+): boolean {
+  const filename = posix.basename(logicalPath);
+  return caseSensitive
+    ? filename.includes(query)
+    : filename.toLowerCase().includes(query.toLowerCase());
+}
+
+export default defineRuntimePlugin((context) => ({
+  handlers: {
+    async local_search(params, executionContext) {
+      let root: SearchRoot | undefined;
+      try {
+        const query = readRequiredString(params.query, {
+          name: "query",
+          maxLength: 1_024,
+        });
+        const rawMode = readOptionalString(params.mode) ?? "both";
+        if (
+          !(["names", "content", "both"] as const).includes(rawMode as never)
+        ) {
+          return failureResult({
+            errorCode: "plugin_parameter_invalid",
+            message: "mode must be names, content, or both.",
+          });
+        }
+        const mode = rawMode as "names" | "content" | "both";
+        const caseSensitive = readBoolean(params.case_sensitive, {
+          defaultValue: false,
+        });
+        const maxResults = readBoundedInteger(params.max_results, {
+          defaultValue: DEFAULT_MAX_RESULTS,
+          minimum: 1,
+          maximum: MAX_RESULTS,
+          name: "max_results",
+        });
+        root = await resolveSearchRoot(context, params.path);
+        const candidates: SearchEntry[] = [];
+        let sourceTruncated = false;
+        if (mode === "names" || mode === "both") {
+          const names = root.isFile
+            ? Object.freeze({
+                items: Object.freeze(
+                  fileNameMatches(root.target.logicalPath, query, caseSensitive)
+                    ? [posix.basename(root.target.logicalPath)]
+                    : [],
+                ),
+                truncated: false,
+              })
+            : await runRipgrepPathSearch(
+                [
+                  "--files",
+                  "--null",
+                  "--hidden",
+                  ...rgGlobArgs(),
+                  caseSensitive ? "--glob" : "--iglob",
+                  `*${escapeRgGlobLiteral(query)}*`,
+                  "--",
+                  root.commandTarget,
+                ],
+                root.commandDirectory,
+                maxResults,
+                executionContext?.abortSignal,
+              );
+          sourceTruncated ||= names.truncated;
+          for (const rawPath of names.items) {
+            candidates.push({
+              kind: "name",
+              value: qualifyMatchPath(context, root, rawPath),
+            });
+          }
+        }
+        if ((mode === "content" || mode === "both") && !sourceTruncated) {
+          const remaining = maxResults - candidates.length;
+          const content = await runRipgrepContentSearch(
+            [
+              "--json",
+              "--with-filename",
+              "--fixed-strings",
+              "--line-number",
+              "--no-heading",
+              "--color",
+              "never",
+              "--max-columns",
+              "2048",
+              "--max-columns-preview",
+              "--hidden",
+              ...(caseSensitive ? [] : ["--ignore-case"]),
+              ...rgGlobArgs(),
+              "--",
+              query,
+              root.commandTarget,
+            ],
+            root.commandDirectory,
+            remaining,
+            executionContext?.abortSignal,
+            root.stdinFd,
+          );
+          sourceTruncated ||= content.truncated;
+          for (const match of content.items) {
+            candidates.push({
+              kind: "content",
+              value: {
+                ...match,
+                path: qualifyMatchPath(context, root, match.path),
+              },
+            });
+          }
+        }
+        const buildResult = (bounded: BudgetedSearchOutput) =>
+          successResult({
+            output: bounded.output,
+            producedNewInformation: true,
+            actions: [
+              {
+                type: "inspect_target",
+                target: root!.target.logicalPath,
+                details: "local_search",
+              },
+            ],
+            data: {
+              hasData: bounded.entries.length > 0,
+              itemCount: bounded.entries.length,
+              mode,
+              logicalRoot: root!.target.logicalPath,
+              truncation: bounded.metadata,
+              observationMeta: {
+                kind: "volatile_external",
+                carryPolicy: "never",
+              },
+            },
+          });
+        const bounded = budgetSearchOutput(
+          query,
+          mode,
+          candidates,
+          sourceTruncated,
+          (candidate) => buildResult(candidate).ok === true,
+        );
+        return buildResult(bounded);
+      } catch (error) {
+        if (isLocalSearchError(error)) {
+          return failureResult({
+            errorCode: error.code,
+            message: error.message,
+          });
+        }
+        return failureFromError(error, {
+          fallbackCode: "local_search_failed",
+          fallbackMessage: "Local search failed.",
+          operation: "local_search",
+        });
+      } finally {
+        await root?.close().catch(() => undefined);
+      }
+    },
+  },
+}));

package/plugins/local-search/source/output.ts

@@ -0,0 +1,101 @@
+import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
+
+import type { ContentMatch } from "./ripgrep.js";
+
+const MAX_OUTPUT_CHARS = 32_768;
+
+export type SearchEntry =
+  | Readonly<{ kind: "name"; value: string }>
+  | Readonly<{ kind: "content"; value: ContentMatch }>;
+
+export type BudgetedSearchOutput = Readonly<{
+  output: string;
+  entries: readonly SearchEntry[];
+  metadata: Readonly<{
+    truncated: boolean;
+    sourceTruncated: boolean;
+    candidateItems: number;
+    returnedItems: number;
+    outputMaxChars: number;
+  }>;
+}>;
+
+function display(value: string): string {
+  return JSON.stringify(value).slice(1, -1);
+}
+
+function render(params: {
+  query: string;
+  mode: string;
+  entries: readonly SearchEntry[];
+  truncated: boolean;
+}): string {
+  const names = params.entries
+    .filter(
+      (entry): entry is Extract<SearchEntry, { kind: "name" }> =>
+        entry.kind === "name",
+    )
+    .map(({ value }) => `- ${display(value)}`);
+  const content = params.entries
+    .filter(
+      (entry): entry is Extract<SearchEntry, { kind: "content" }> =>
+        entry.kind === "content",
+    )
+    .map(
+      ({ value }) =>
+        `- ${display(value.path)}:${value.lineNumber}:${sanitizeJsonText(value.text)}`,
+    );
+  return [
+    'Search scope: selected logical path; use "." for the current Worker root.',
+    `Query: ${sanitizeJsonText(params.query)}`,
+    `Mode: ${params.mode}`,
+    `Returned matches: ${params.entries.length}${params.truncated ? " (bounded)" : ""}`,
+    ...(names.length > 0 ? ["Filename matches:", ...names] : []),
+    ...(content.length > 0 ? ["Content matches:", ...content] : []),
+    ...(params.entries.length === 0 ? ["No matches found."] : []),
+    ...(params.truncated ? ["Additional matches were omitted."] : []),
+  ].join("\n");
+}
+
+export function budgetSearchOutput(
+  query: string,
+  mode: string,
+  candidates: readonly SearchEntry[],
+  sourceTruncated: boolean,
+  fitsSerializedResult: (candidate: BudgetedSearchOutput) => boolean,
+): BudgetedSearchOutput {
+  const build = (entries: readonly SearchEntry[]): BudgetedSearchOutput => {
+    const truncated = sourceTruncated || entries.length < candidates.length;
+    return Object.freeze({
+      output: render({ query, mode, entries, truncated }),
+      entries: Object.freeze([...entries]),
+      metadata: Object.freeze({
+        truncated,
+        sourceTruncated,
+        candidateItems: candidates.length,
+        returnedItems: entries.length,
+        outputMaxChars: MAX_OUTPUT_CHARS,
+      }),
+    });
+  };
+
+  const entries: SearchEntry[] = [];
+  for (const candidate of candidates) {
+    const tentative = [...entries, candidate];
+    const budgeted = build(tentative);
+    if (
+      budgeted.output.length > MAX_OUTPUT_CHARS ||
+      !fitsSerializedResult(budgeted)
+    ) {
+      break;
+    }
+    entries.push(candidate);
+  }
+  const result = build(entries);
+  if (!fitsSerializedResult(result)) {
+    throw new RangeError(
+      "The local-search result envelope exceeds its budget.",
+    );
+  }
+  return result;
+}

package/plugins/local-search/source/paths.ts

@@ -0,0 +1,194 @@
+import { constants, type BigIntStats } from "node:fs";
+import { open, realpath, stat, type FileHandle } from "node:fs/promises";
+import path from "node:path";
+
+import type {
+  ResolvedRuntimeToolPath,
+  RuntimePluginLoadContext,
+} from "../../../src/plugin-sdk/index.js";
+import { resolvePluginPath } from "../../../src/plugin-sdk/index.js";
+
+import { LocalSearchError } from "./errors.js";
+
+export type SearchRoot = Readonly<{
+  target: ResolvedRuntimeToolPath;
+  isFile: boolean;
+  commandDirectory: string;
+  commandTarget: string;
+  stdinFd?: number;
+  close(): Promise<void>;
+}>;
+
+function fsCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function sameIdentity(left: BigIntStats, right: BigIntStats): boolean {
+  return (
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.isFile() === right.isFile() &&
+    left.isDirectory() === right.isDirectory()
+  );
+}
+
+function isWithinRoot(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function authorityUnavailable(): LocalSearchError {
+  return new LocalSearchError(
+    "local_search_failed",
+    "Local search could not establish a safe read authority for the selected logical root.",
+  );
+}
+
+async function openSearchAuthority(
+  target: ResolvedRuntimeToolPath,
+): Promise<SearchRoot> {
+  if (
+    process.platform !== "linux" ||
+    !Number.isInteger(constants.O_NOFOLLOW) ||
+    !Number.isInteger(constants.O_NONBLOCK)
+  ) {
+    throw authorityUnavailable();
+  }
+
+  let handle: FileHandle | undefined;
+  let targetOpened = false;
+  try {
+    handle = await open(
+      target.absolutePath,
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+    );
+    targetOpened = true;
+    const observed = await handle.stat({ bigint: true });
+    if (!observed.isFile() && !observed.isDirectory()) {
+      throw new LocalSearchError(
+        "local_search_target_invalid",
+        "The selected search target must be a regular file or directory.",
+      );
+    }
+
+    const [canonicalRoot, canonicalTarget] = await Promise.all([
+      realpath(target.rootPath),
+      realpath(target.absolutePath),
+    ]);
+    if (
+      path.resolve(canonicalRoot) !== path.resolve(target.rootPath) ||
+      path.resolve(canonicalTarget) !== path.resolve(target.absolutePath) ||
+      !isWithinRoot(canonicalRoot, canonicalTarget)
+    ) {
+      throw authorityUnavailable();
+    }
+
+    const [pathIdentity, descriptorIdentity] = await Promise.all([
+      stat(canonicalTarget, { bigint: true }),
+      stat(`/proc/self/fd/${handle.fd}`, { bigint: true }),
+    ]);
+    if (
+      !sameIdentity(observed, pathIdentity) ||
+      !sameIdentity(observed, descriptorIdentity)
+    ) {
+      throw authorityUnavailable();
+    }
+
+    const authority = handle;
+    const isFile = observed.isFile();
+    let closed = false;
+    handle = undefined;
+    return Object.freeze({
+      target,
+      isFile,
+      commandDirectory: isFile ? "/" : `/proc/self/fd/${authority.fd}`,
+      commandTarget: isFile ? "-" : ".",
+      ...(isFile ? { stdinFd: authority.fd } : {}),
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        await authority.close();
+      },
+    });
+  } catch (error) {
+    await handle?.close().catch(() => undefined);
+    if (error instanceof LocalSearchError) throw error;
+    const code = fsCode(error);
+    if (!targetOpened && (code === "ENOENT" || code === "ENOTDIR")) {
+      throw new LocalSearchError(
+        "local_search_root_not_found",
+        "The selected logical search root does not exist.",
+      );
+    }
+    throw authorityUnavailable();
+  }
+}
+
+export async function resolveSearchRoot(
+  context: RuntimePluginLoadContext,
+  rawPath: unknown,
+): Promise<SearchRoot> {
+  const requested =
+    typeof rawPath === "string" && rawPath.trim() ? rawPath : ".";
+  const target = resolvePluginPath(context, requested, {
+    requirePath: true,
+    allowedLocations: ["agent_work", "workspace"],
+  });
+  return openSearchAuthority(target);
+}
+
+function normalizeRelativeResult(value: string): string {
+  const normalized = path.sep === "/" ? value : value.replaceAll(path.sep, "/");
+  if (
+    !normalized ||
+    normalized.includes("\\") ||
+    path.isAbsolute(normalized) ||
+    /^[A-Za-z]:[\\/]/u.test(normalized) ||
+    /^[\\/]{2}/u.test(normalized)
+  ) {
+    throw new LocalSearchError(
+      "local_search_path_roundtrip_unsafe",
+      "Local search found a path that cannot be reused as a logical path.",
+    );
+  }
+  return normalized.replace(/^\.\/+/, "");
+}
+
+export function qualifyMatchPath(
+  context: RuntimePluginLoadContext,
+  root: SearchRoot,
+  rawPath: string,
+): string {
+  const logical = root.isFile
+    ? root.target.logicalPath
+    : root.target.logicalPath === "."
+      ? normalizeRelativeResult(rawPath)
+      : path.posix.join(
+          root.target.logicalPath,
+          normalizeRelativeResult(rawPath),
+        );
+  const roundTrip = resolvePluginPath(context, logical, {
+    requirePath: true,
+    allowedLocations: ["agent_work", "workspace"],
+  });
+  const sourceAbsolutePath = root.isFile
+    ? root.target.absolutePath
+    : path.resolve(root.target.absolutePath, rawPath);
+  if (
+    roundTrip.logicalPath !== logical ||
+    path.resolve(roundTrip.absolutePath) !== path.resolve(sourceAbsolutePath)
+  ) {
+    throw new LocalSearchError(
+      "local_search_path_roundtrip_unsafe",
+      "Local search found a path that cannot be reused as a logical path.",
+    );
+  }
+  return logical;
+}