@abot-ai/runtime 1.0.0

package/plugins/filesystem/source/edit-file.ts

@@ -0,0 +1,298 @@
+import {
+  boundText,
+  readRequiredString,
+  successResult,
+  type ToolImplementation,
+} from "../../../src/plugin-sdk/index.js";
+
+import { atomicWriteText } from "./atomic-write.js";
+import {
+  assertMutationContentSize,
+  assertMutationTargetUnchanged,
+  readMutationSnapshot,
+} from "./bounded-io.js";
+import { buildMutationGrounding } from "./draft/grounding.js";
+import { prepareFileDraft } from "./draft/prepare.js";
+import { fail } from "./errors.js";
+import type { FilesystemMutationCoordinator } from "./mutation-coordinator.js";
+import type { FilesystemPathService } from "./path-service.js";
+
+type EditSelection = Readonly<{
+  placement: "before" | "after" | "replace" | "delete";
+  startLine: number;
+  endLine: number;
+}>;
+
+export function createEditFileHandler(
+  paths: FilesystemPathService,
+  mutations: FilesystemMutationCoordinator,
+): ToolImplementation {
+  return async (params, context) => {
+    const requestedPath = readRequiredString(params.path, "path");
+    readRequiredString(params.instruction, "instruction");
+    const selection = parseSelection(params.selection);
+    const editContent = resolveEditContent(params.content, selection);
+    const target = paths.resolve(requestedPath, context);
+    return mutations.runExclusive(target.absolutePath, async () => {
+      const snapshot = await readMutationSnapshot(target);
+      const previousContent = snapshot.content;
+      if (previousContent === null) {
+        fail("file_not_found", `Path does not exist: ${target.logicalPath}`);
+      }
+      const applied = applyLineEdit(previousContent, selection, editContent);
+      const prepared = await prepareFileDraft({
+        targetPath: target.logicalPath,
+        candidate: applied.content,
+        ...(context ? { context } : {}),
+        repairScope: {
+          startLine: applied.changedStartLine,
+          endLine: applied.changedEndLine,
+        },
+      });
+      assertMutationContentSize(prepared.content);
+      if (prepared.structuralIntegrity !== "validated") {
+        const regressions = delimiterRegressions(
+          previousContent,
+          prepared.content,
+        );
+        if (regressions.length) {
+          fail(
+            "structural_regression",
+            [
+              `Edit would regress structural balance in ${target.logicalPath}.`,
+              ...regressions.map((entry) => `- ${entry}`),
+            ].join("\n"),
+          );
+        }
+      }
+      if (prepared.content === previousContent) {
+        await assertMutationTargetUnchanged(target, snapshot.version);
+        return successResult({
+          output: [`Path: ${target.logicalPath}`, "Edit: no-op"].join("\n"),
+          progress: true,
+          producedNewInformation: false,
+          actions: [
+            {
+              type: "state_already_satisfied",
+              target: target.logicalPath,
+              details: `line_edit:${selection.placement}`,
+            },
+          ],
+          data: {
+            mutationEvidence: false,
+            stateAlreadySatisfied: true,
+            currentStateEvidence: true,
+            path: target.logicalPath,
+          },
+        });
+      }
+
+      const grounding = buildMutationGrounding({
+        logicalPath: target.logicalPath,
+        content: prepared.content,
+        previousContent,
+        prepared,
+      });
+      const changedStartLine = Math.min(
+        applied.changedStartLine,
+        prepared.changedRange?.startLine ?? applied.changedStartLine,
+      );
+      const changedEndLine = Math.max(
+        applied.changedEndLine,
+        prepared.changedRange?.endLine ?? applied.changedEndLine,
+      );
+      const result = successResult({
+        output: [
+          `Path: ${target.logicalPath}`,
+          "Edit: success",
+          `Updated range: lines ${changedStartLine}-${changedEndLine}`,
+          renderWindow(prepared.content, changedStartLine, changedEndLine),
+        ].join("\n"),
+        progress: true,
+        actions: [
+          {
+            type: "refine_target",
+            target: target.logicalPath,
+            details: `line_edit:${selection.placement}:${selection.startLine}-${selection.endLine}`,
+          },
+        ],
+        data: {
+          mutationEvidence: true,
+          mutationGrounding: grounding.summary,
+          currentStateEvidence: true,
+          path: target.logicalPath,
+          changedRange: {
+            startLine: changedStartLine,
+            endLine: changedEndLine,
+          },
+          validation: prepared.validation,
+          eventMeta: {
+            path: target.logicalPath,
+            operation: selection.placement,
+            changedStartLine,
+            changedEndLine,
+          },
+        },
+      });
+      assertPreparedMutationResult(result);
+      await atomicWriteText({
+        target,
+        content: prepared.content,
+        expectedVersion: snapshot.version,
+      });
+      return result;
+    });
+  };
+}
+
+function assertPreparedMutationResult(
+  result: ReturnType<typeof successResult>,
+): asserts result is ReturnType<typeof successResult> & Readonly<{ ok: true }> {
+  if (result.ok) return;
+  fail(
+    result.errorCode ?? "plugin_result_invalid",
+    result.error ?? result.output,
+  );
+}
+
+function parseSelection(value: unknown): EditSelection {
+  if (typeof value !== "string" || !value.trim()) {
+    fail("invalid_edit_payload", "A structured edit selection is required.");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    fail("invalid_edit_payload", "Edit selection must be valid JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    fail("invalid_edit_payload", "Edit selection must be one object.");
+  }
+  const record = parsed as Record<string, unknown>;
+  const placement = record.placement;
+  const startLine = record.start_line;
+  const endLine = record.end_line;
+  if (
+    (placement !== "before" &&
+      placement !== "after" &&
+      placement !== "replace" &&
+      placement !== "delete") ||
+    typeof startLine !== "number" ||
+    !Number.isSafeInteger(startLine) ||
+    startLine < 1 ||
+    typeof endLine !== "number" ||
+    !Number.isSafeInteger(endLine) ||
+    endLine < startLine ||
+    ((placement === "before" || placement === "after") && startLine !== endLine)
+  ) {
+    fail("invalid_edit_payload", "Edit selection contains an invalid range.");
+  }
+  return Object.freeze({ placement, startLine, endLine });
+}
+
+function resolveEditContent(value: unknown, selection: EditSelection): string {
+  const deletePayloadEmpty =
+    value === undefined ||
+    (typeof value === "string" && value.trim().length === 0);
+  if (selection.placement === "delete") {
+    if (!deletePayloadEmpty) {
+      fail(
+        "invalid_edit_payload",
+        "Delete does not accept replacement content.",
+      );
+    }
+    return "";
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    fail("invalid_edit_payload", "A non-empty raw edit body is required.");
+  }
+  return value;
+}
+
+function applyLineEdit(
+  content: string,
+  selection: EditSelection,
+  editContent: string,
+): Readonly<{
+  content: string;
+  changedStartLine: number;
+  changedEndLine: number;
+}> {
+  const lines = content.split(/\r?\n/u);
+  if (selection.endLine > lines.length) {
+    fail(
+      "invalid_edit_location",
+      `Selected line range exceeds the current ${lines.length}-line file.`,
+    );
+  }
+  const editLines =
+    selection.placement === "delete" ? [] : splitPayload(editContent);
+  const spliceStart =
+    selection.placement === "after"
+      ? selection.endLine
+      : selection.startLine - 1;
+  const deleteCount =
+    selection.placement === "replace" || selection.placement === "delete"
+      ? selection.endLine - selection.startLine + 1
+      : 0;
+  lines.splice(spliceStart, deleteCount, ...editLines);
+  const startLine =
+    selection.placement === "delete"
+      ? Math.min(spliceStart + 1, Math.max(lines.length, 1))
+      : spliceStart + 1;
+  return Object.freeze({
+    content: lines.join(content.includes("\r\n") ? "\r\n" : "\n"),
+    changedStartLine: startLine,
+    changedEndLine: Math.max(startLine, startLine + editLines.length - 1),
+  });
+}
+
+function splitPayload(value: string): string[] {
+  const normalized = value.replace(/\r\n/gu, "\n").replace(/\n$/u, "");
+  return normalized ? normalized.split("\n") : [""];
+}
+
+function delimiterRegressions(previous: string, updated: string): string[] {
+  const delimiters = [
+    ["curly", "{", "}"],
+    ["square", "[", "]"],
+    ["paren", "(", ")"],
+  ] as const;
+  return delimiters.flatMap(([name, open, close]) => {
+    if (!previous.includes(open) || !previous.includes(close)) return [];
+    const before = balance(previous, open, close);
+    const after = balance(updated, open, close);
+    return before === 0 && after !== 0
+      ? [`${name} delimiter balance changed from 0 to ${after}`]
+      : [];
+  });
+}
+
+function balance(content: string, open: string, close: string): number {
+  let count = 0;
+  for (const character of content) {
+    if (character === open) count += 1;
+    else if (character === close) count -= 1;
+  }
+  return count;
+}
+
+function renderWindow(
+  content: string,
+  startLine: number,
+  endLine: number,
+): string {
+  const lines = content.split(/\r?\n/u);
+  const from = Math.max(1, startLine - 8);
+  const to = Math.min(lines.length, endLine + 8);
+  const rendered = [
+    `Updated content: lines ${from}-${to} of ${lines.length}`,
+    ...lines
+      .slice(from - 1, to)
+      .map((line, index) => `${from + index} | ${line}`),
+  ].join("\n");
+  return boundText(rendered, {
+    maxChars: 12_000,
+    marker: "\n[updated window output truncated]",
+  }).text;
+}

package/plugins/filesystem/source/errors.ts

@@ -0,0 +1,61 @@
+import { isRuntimeToolPathError } from "../../../src/plugin-sdk/index.js";
+
+type NodeError = Error & Readonly<{ code?: unknown }>;
+
+export class FilesystemToolError extends Error {
+  readonly code: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+
+  constructor(
+    code: string,
+    message: string = code,
+    data?: Readonly<Record<string, unknown>>,
+  ) {
+    super(message);
+    this.name = "FilesystemToolError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+export function fail(
+  code: string,
+  message: string = code,
+  data?: Readonly<Record<string, unknown>>,
+): never {
+  throw new FilesystemToolError(code, message, data);
+}
+
+export function isNodeErrorCode(error: unknown, code: string): boolean {
+  return (
+    error instanceof Error &&
+    typeof (error as NodeError).code === "string" &&
+    (error as NodeError).code === code
+  );
+}
+
+export function rethrowFilesystemError(
+  error: unknown,
+  operation: "inspect" | "read" | "write",
+  logicalPath: string,
+): never {
+  if (isRuntimeToolPathError(error) || error instanceof FilesystemToolError) {
+    throw error;
+  }
+  if (isNodeErrorCode(error, "ENOENT")) {
+    fail("file_not_found", `Path does not exist: ${logicalPath}`);
+  }
+  if (isNodeErrorCode(error, "EACCES") || isNodeErrorCode(error, "EPERM")) {
+    fail(
+      "filesystem_access_denied",
+      `Access was denied while attempting to ${operation}: ${logicalPath}`,
+    );
+  }
+  if (isNodeErrorCode(error, "EISDIR")) {
+    fail("not_a_file", `Expected a regular file: ${logicalPath}`);
+  }
+  fail(
+    `filesystem_${operation}_failed`,
+    `Filesystem ${operation} failed for ${logicalPath}.`,
+  );
+}

package/plugins/filesystem/source/index.ts

@@ -0,0 +1,59 @@
+import {
+  defineRuntimePlugin,
+  failureFromError,
+  failureResult,
+  type ToolImplementation,
+} from "../../../src/plugin-sdk/index.js";
+
+import { editFileAdapter, writeFileAdapter } from "./adapters.js";
+import { createDevViewHandler } from "./dev-view.js";
+import { createEditFileHandler } from "./edit-file.js";
+import { FilesystemToolError } from "./errors.js";
+import { getProcessFilesystemMutationCoordinator } from "./mutation-coordinator.js";
+import { createFilesystemPathService } from "./path-service.js";
+import { createReadFileHandler } from "./read-file.js";
+import { createWriteFileHandler } from "./write-file.js";
+
+function settle(
+  handler: ToolImplementation,
+  operation: string,
+): ToolImplementation {
+  return async (params, context) => {
+    try {
+      return await handler(params, context);
+    } catch (error: unknown) {
+      if (error instanceof FilesystemToolError) {
+        return failureResult({
+          errorCode: error.code,
+          message: error.message,
+          data: error.data,
+        });
+      }
+      return failureFromError(error, {
+        fallbackCode: `filesystem_${operation}_failed`,
+        fallbackMessage: `Filesystem ${operation} failed.`,
+        operation,
+      });
+    }
+  };
+}
+
+export default defineRuntimePlugin((context) => {
+  const paths = createFilesystemPathService(context.runtimePathResolver);
+  const mutations = getProcessFilesystemMutationCoordinator();
+  return Object.freeze({
+    handlers: Object.freeze({
+      dev_view: settle(createDevViewHandler(paths), "dev_view"),
+      edit_file: settle(createEditFileHandler(paths, mutations), "edit_file"),
+      read_file: settle(createReadFileHandler(paths), "read_file"),
+      write_file: settle(
+        createWriteFileHandler(paths, mutations),
+        "write_file",
+      ),
+    }),
+    adapters: Object.freeze({
+      edit_file: editFileAdapter,
+      write_file: writeFileAdapter,
+    }),
+  });
+});

package/plugins/filesystem/source/mutation-coordinator.ts

@@ -0,0 +1,37 @@
+export type FilesystemMutationCoordinator = Readonly<{
+  runExclusive<T>(targetKey: string, task: () => Promise<T>): Promise<T>;
+}>;
+
+function createFilesystemMutationCoordinator(): FilesystemMutationCoordinator {
+  const tails = new Map<string, Promise<void>>();
+
+  return Object.freeze({
+    async runExclusive<T>(
+      targetKey: string,
+      task: () => Promise<T>,
+    ): Promise<T> {
+      const previous = tails.get(targetKey) ?? Promise.resolve();
+      let release!: () => void;
+      const current = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      tails.set(targetKey, current);
+      await previous;
+      try {
+        return await task();
+      } finally {
+        release();
+        if (tails.get(targetKey) === current) tails.delete(targetKey);
+      }
+    },
+  });
+}
+
+// Coordination is owned by the filesystem plugin but shared by every plugin
+// instance loaded in this process so two handlers cannot mutate one target
+// from stale observations.
+const PROCESS_MUTATION_COORDINATOR = createFilesystemMutationCoordinator();
+
+export function getProcessFilesystemMutationCoordinator(): FilesystemMutationCoordinator {
+  return PROCESS_MUTATION_COORDINATOR;
+}

package/plugins/filesystem/source/mutation-parent.ts

@@ -0,0 +1,164 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath, stat, type FileHandle } from "node:fs/promises";
+import { relative, sep } from "node:path";
+
+import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
+
+import { fail, isNodeErrorCode, rethrowFilesystemError } from "./errors.js";
+
+export type MutationParent = Readonly<{
+  handle: FileHandle;
+  procPath: string;
+  targetName: string;
+}>;
+
+function isWithinRoot(target: string, root: string): boolean {
+  const rel = relative(root, target);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+function sameIdentity(
+  left: Readonly<{ dev: bigint; ino: bigint }>,
+  right: Readonly<{ dev: bigint; ino: bigint }>,
+): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function openDirectory(
+  path: string,
+  rootPath: string,
+  logicalPath: string,
+  allowMissing: boolean = false,
+): Promise<FileHandle> {
+  if (
+    typeof constants.O_DIRECTORY !== "number" ||
+    typeof constants.O_NOFOLLOW !== "number"
+  ) {
+    fail(
+      "filesystem_safe_io_unsupported",
+      "This platform does not provide the no-follow directory operations required for a safe write.",
+    );
+  }
+  let handle: FileHandle | undefined;
+  try {
+    handle = await open(
+      path,
+      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+    );
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isDirectory()) {
+      fail("not_a_directory", `Expected a directory: ${logicalPath}`);
+    }
+    const [canonicalRoot, canonicalDirectory] = await Promise.all([
+      realpath(rootPath),
+      realpath(path),
+    ]);
+    if (!isWithinRoot(canonicalDirectory, canonicalRoot)) {
+      fail(
+        "filesystem_path_changed",
+        `Directory changed outside its configured root: ${logicalPath}`,
+      );
+    }
+    const pathIdentity = await stat(canonicalDirectory, { bigint: true });
+    if (!pathIdentity.isDirectory() || !sameIdentity(opened, pathIdentity)) {
+      fail(
+        "filesystem_path_changed",
+        `Directory changed while it was being opened: ${logicalPath}`,
+      );
+    }
+    const procPath = `/proc/self/fd/${handle.fd}`;
+    const procIdentity = await stat(procPath, { bigint: true });
+    if (!procIdentity.isDirectory() || !sameIdentity(opened, procIdentity)) {
+      fail(
+        "filesystem_safe_io_unsupported",
+        "The process file-descriptor filesystem is unavailable for a safe write.",
+      );
+    }
+    return handle;
+  } catch (error: unknown) {
+    await handle?.close().catch(() => undefined);
+    if (allowMissing && isNodeErrorCode(error, "ENOENT")) throw error;
+    rethrowFilesystemError(error, "write", logicalPath);
+  }
+}
+
+async function openChildDirectory(
+  parent: FileHandle,
+  name: string,
+  logicalPath: string,
+): Promise<FileHandle> {
+  const anchoredPath = `/proc/self/fd/${parent.fd}/${name}`;
+  try {
+    return await openDirectory(
+      anchoredPath,
+      `/proc/self/fd/${parent.fd}`,
+      logicalPath,
+      true,
+    );
+  } catch (error: unknown) {
+    if (!isNodeErrorCode(error, "ENOENT")) throw error;
+  }
+  try {
+    await mkdir(anchoredPath);
+  } catch (error: unknown) {
+    if (!isNodeErrorCode(error, "EEXIST")) {
+      rethrowFilesystemError(error, "write", logicalPath);
+    }
+  }
+  return openDirectory(anchoredPath, `/proc/self/fd/${parent.fd}`, logicalPath);
+}
+
+/**
+ * Opens the mutation parent as a stable directory authority. Every descendant
+ * is traversed relative to an already-open descriptor, so swapping an
+ * intermediate pathname cannot redirect the eventual write outside the
+ * configured root.
+ */
+export async function openMutationParent(
+  target: ResolvedRuntimeToolPath,
+): Promise<MutationParent> {
+  const segments = target.relativePath.split("/").filter(Boolean);
+  const targetName = segments.pop();
+  if (!targetName || targetName === "." || targetName === "..") {
+    fail("not_a_file", `Expected a file path: ${target.logicalPath}`);
+  }
+  if (
+    segments.some(
+      (segment) =>
+        !segment ||
+        segment === "." ||
+        segment === ".." ||
+        segment.includes("/"),
+    )
+  ) {
+    fail(
+      "filesystem_path_changed",
+      `Path changed while preparing the write: ${target.logicalPath}`,
+    );
+  }
+
+  let current = await openDirectory(
+    target.rootPath,
+    target.rootPath,
+    target.logicalPath,
+  );
+  try {
+    for (const segment of segments) {
+      const next = await openChildDirectory(
+        current,
+        segment,
+        target.logicalPath,
+      );
+      await current.close();
+      current = next;
+    }
+    return Object.freeze({
+      handle: current,
+      procPath: `/proc/self/fd/${current.fd}`,
+      targetName,
+    });
+  } catch (error: unknown) {
+    await current.close().catch(() => undefined);
+    throw error;
+  }
+}

package/plugins/filesystem/source/path-service.ts

@@ -0,0 +1,73 @@
+import { posix } from "node:path";
+
+import type {
+  ResolvedRuntimeToolPath,
+  RuntimeToolPathResolver,
+  ToolExecutionContext,
+} from "../../../src/plugin-sdk/index.js";
+
+const FILESYSTEM_LOCATIONS = Object.freeze([
+  "agent_work",
+  "workspace",
+] as const);
+
+export type FilesystemPathService = Readonly<{
+  resolve(
+    rawPath: unknown,
+    context?: ToolExecutionContext,
+  ): ResolvedRuntimeToolPath;
+  parent(
+    target: ResolvedRuntimeToolPath,
+    context?: ToolExecutionContext,
+  ): ResolvedRuntimeToolPath;
+  sibling(
+    target: ResolvedRuntimeToolPath,
+    name: string,
+    context?: ToolExecutionContext,
+  ): ResolvedRuntimeToolPath;
+}>;
+
+function resolverFor(
+  fallback: RuntimeToolPathResolver,
+  context?: ToolExecutionContext,
+): RuntimeToolPathResolver {
+  return context?.runtimePathResolver ?? fallback;
+}
+
+function resolveWith(
+  resolver: RuntimeToolPathResolver,
+  rawPath: unknown,
+): ResolvedRuntimeToolPath {
+  return resolver.resolve(rawPath, {
+    requirePath: true,
+    allowedLocations: FILESYSTEM_LOCATIONS,
+  });
+}
+
+function logicalParent(logicalPath: string): string {
+  if (logicalPath === "." || logicalPath === "workspace") {
+    return logicalPath;
+  }
+  return posix.dirname(logicalPath);
+}
+
+export function createFilesystemPathService(
+  fallbackResolver: RuntimeToolPathResolver,
+): FilesystemPathService {
+  return Object.freeze({
+    resolve(rawPath, context) {
+      return resolveWith(resolverFor(fallbackResolver, context), rawPath);
+    },
+    parent(target, context) {
+      return resolveWith(
+        resolverFor(fallbackResolver, context),
+        logicalParent(target.logicalPath),
+      );
+    },
+    sibling(target, name, context) {
+      const parent = logicalParent(target.logicalPath);
+      const logicalPath = parent === "." ? name : posix.join(parent, name);
+      return resolveWith(resolverFor(fallbackResolver, context), logicalPath);
+    },
+  });
+}