@abot-ai/runtime 1.3.0 → 1.3.1

package/plugins/exec/src/index.cjs

@@ -558,11 +558,34 @@ function resolveExecScopedPath(pluginContext, executionContext, rawPath, cwd) {
 
 // plugins/exec/source/process-manager.ts
 var import_node_child_process = require("node:child_process");
-var import_node_fs2 = require("node:fs");
-var import_promises3 = require("node:fs/promises");
 var import_node_crypto2 = require("node:crypto");
 var import_node_string_decoder = require("node:string_decoder");
+
+// plugins/exec/source/shell-platform.ts
+var import_node_fs2 = require("node:fs");
+var import_promises3 = require("node:fs/promises");
 var EXEC_SHELL = "/bin/bash";
+function isSupportedExecPlatform(platform) {
+  return platform === "linux" || platform === "darwin";
+}
+async function assertSupportedShell(platform = process.platform) {
+  if (!isSupportedExecPlatform(platform)) {
+    throw new ExecPluginError(
+      "exec_platform_unsupported",
+      "The exec plugin requires Linux or macOS and executable /bin/bash."
+    );
+  }
+  try {
+    await (0, import_promises3.access)(EXEC_SHELL, import_node_fs2.constants.X_OK);
+  } catch {
+    throw new ExecPluginError(
+      "exec_shell_unavailable",
+      "The exec plugin cannot start because executable /bin/bash is unavailable."
+    );
+  }
+}
+
+// plugins/exec/source/process-manager.ts
 var COMPLETED_PROCESS_RETENTION_MS = 5 * 6e4;
 var MAX_ACTIVE_PROCESSES_PER_SCOPE = 4;
 var CappedTextBuffer = class {
@@ -602,22 +625,6 @@ var CappedTextBuffer = class {
     });
   }
 };
-async function assertSupportedShell() {
-  if (process.platform !== "linux") {
-    throw new ExecPluginError(
-      "exec_platform_unsupported",
-      "The exec plugin v1 requires Linux and /bin/bash."
-    );
-  }
-  try {
-    await (0, import_promises3.access)(EXEC_SHELL, import_node_fs2.constants.X_OK);
-  } catch {
-    throw new ExecPluginError(
-      "exec_shell_unavailable",
-      "The exec plugin cannot start because executable /bin/bash is unavailable."
-    );
-  }
-}
 function createExecProcessManager() {
   const processes = /* @__PURE__ */ new Map();
   const unknownProcess = () => new ExecPluginError(

package/plugins/filesystem/source/atomic-write.ts

@@ -11,6 +11,7 @@ import {
 } from "./bounded-io.js";
 import { fail, isNodeErrorCode, rethrowFilesystemError } from "./errors.js";
 import { openMutationParent } from "./mutation-parent.js";
+import { writeWithDirectoryAuthority } from "./directory-authority-write.js";
 
 export async function atomicWriteText(
   input: Readonly<{
@@ -20,6 +21,10 @@ export async function atomicWriteText(
   }>,
 ): Promise<void> {
   assertMutationContentSize(input.content);
+  if (requiresIsolatedDirectoryAuthority()) {
+    await writeWithDirectoryAuthority(input);
+    return;
+  }
   const parent = await openMutationParent(input.target);
   const targetPath = `${parent.procPath}/${parent.targetName}`;
   const anchoredTarget = Object.freeze({
@@ -113,3 +118,7 @@ async function syncDirectoryBestEffort(
     // The prepared file itself is always synced before the atomic install.
   }
 }
+
+function requiresIsolatedDirectoryAuthority(): boolean {
+  return process.platform === "darwin";
+}

package/plugins/filesystem/source/bounded-io.ts

@@ -1,12 +1,6 @@
 import { createHash } from "node:crypto";
 import { constants, type BigIntStats } from "node:fs";
-import {
-  opendir,
-  open,
-  realpath,
-  stat,
-  type FileHandle,
-} from "node:fs/promises";
+import { open, realpath, stat, type FileHandle } from "node:fs/promises";
 import { relative, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { TextDecoder } from "node:util";
@@ -19,7 +13,10 @@ export const MAX_MUTATION_BYTES = 1_048_576;
 export const READ_HEAD_BYTES = 24_576;
 export const READ_TAIL_BYTES = 12_288;
 export const DEV_SCAN_BYTES = 1_048_576;
-export const DIRECTORY_ENTRY_LIMIT = 160;
+export {
+  readDirectorySample,
+  DIRECTORY_ENTRY_LIMIT,
+} from "./directory-sample.js";
 
 export type BoundedText = Readonly<{
   text: string;
@@ -350,97 +347,6 @@ export function assertMutationContentSize(content: string): number {
   return byteCount;
 }
 
-export async function readDirectorySample(
-  target: ResolvedRuntimeToolPath,
-): Promise<Readonly<{ entries: readonly string[]; truncated: boolean }>> {
-  const entries: string[] = [];
-  let handle: FileHandle | undefined;
-  try {
-    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 operation required for a safe read.",
-      );
-    }
-    handle = await open(
-      target.absolutePath,
-      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
-    );
-    const before = await handle.stat({ bigint: true });
-    if (!before.isDirectory()) {
-      fail("not_a_directory", `Expected a directory: ${target.logicalPath}`);
-    }
-    const [canonicalRoot, canonicalTarget] = await Promise.all([
-      realpath(target.rootPath),
-      realpath(target.absolutePath),
-    ]);
-    const rootRelative = relative(canonicalRoot, canonicalTarget);
-    if (
-      rootRelative === ".." ||
-      rootRelative.startsWith(`..${sep}`) ||
-      rootRelative.startsWith(sep)
-    ) {
-      fail(
-        "filesystem_path_changed",
-        `Directory changed outside its configured root: ${target.logicalPath}`,
-      );
-    }
-    const pathIdentity = await stat(canonicalTarget, { bigint: true });
-    if (
-      !pathIdentity.isDirectory() ||
-      pathIdentity.dev !== before.dev ||
-      pathIdentity.ino !== before.ino
-    ) {
-      fail(
-        "filesystem_path_changed",
-        `Directory changed while it was being opened: ${target.logicalPath}`,
-      );
-    }
-    const directory = await opendir(`/proc/self/fd/${handle.fd}`);
-    for await (const entry of directory) {
-      if (entries.length >= DIRECTORY_ENTRY_LIMIT) {
-        await assertDirectoryStable(handle, before, target.logicalPath);
-        entries.sort((left, right) => left.localeCompare(right));
-        return Object.freeze({
-          entries: Object.freeze(entries),
-          truncated: true,
-        });
-      }
-      entries.push(`${entry.name}${entry.isDirectory() ? "/" : ""}`);
-    }
-    await assertDirectoryStable(handle, before, target.logicalPath);
-    entries.sort((left, right) => left.localeCompare(right));
-    return Object.freeze({ entries: Object.freeze(entries), truncated: false });
-  } catch (error: unknown) {
-    return rethrowFilesystemError(error, "inspect", target.logicalPath);
-  } finally {
-    await handle?.close().catch(() => undefined);
-  }
-}
-
-async function assertDirectoryStable(
-  handle: FileHandle,
-  before: BigIntStats,
-  logicalPath: string,
-): Promise<void> {
-  const after = await handle.stat({ bigint: true });
-  if (
-    !after.isDirectory() ||
-    after.dev !== before.dev ||
-    after.ino !== before.ino ||
-    after.mtimeNs !== before.mtimeNs ||
-    after.ctimeNs !== before.ctimeNs
-  ) {
-    fail(
-      "filesystem_read_changed",
-      `Directory changed while it was being read: ${logicalPath}`,
-    );
-  }
-}
-
 function rejectBinary(buffer: Buffer, logicalPath: string): void {
   if (buffer.includes(0)) {
     fail(

package/plugins/filesystem/source/directory-authority-write.ts

@@ -0,0 +1,64 @@
+import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
+import {
+  DirectoryAuthorityError,
+  runDirectoryAuthorityTask,
+} from "../../../src/shared/directory-authority/index.js";
+import type { MutationTargetVersion } from "./bounded-io.js";
+import { fail, rethrowFilesystemError } from "./errors.js";
+import { openMutationRoot } from "./mutation-parent.js";
+import {
+  commitDirectoryWrite,
+  type DirectoryWriteInput,
+} from "./directory-write-task.js";
+
+export async function writeWithDirectoryAuthority(
+  input: Readonly<{
+    target: ResolvedRuntimeToolPath;
+    content: string;
+    expectedVersion: MutationTargetVersion;
+  }>,
+): Promise<void> {
+  const root = await openMutationRoot(input.target);
+  const expected = input.expectedVersion;
+  const expectedVersion: DirectoryWriteInput["expectedVersion"] =
+    expected.kind === "absent"
+      ? { kind: "absent" }
+      : {
+          ...expected,
+          device: String(expected.device),
+          inode: String(expected.inode),
+          modifiedNs: String(expected.modifiedNs),
+          changedNs: String(expected.changedNs),
+        };
+  try {
+    await runDirectoryAuthorityTask({
+      directoryPath: input.target.rootPath,
+      directoryFd: root.fd,
+      input: {
+        relativePath: input.target.relativePath,
+        content: input.content,
+        expectedVersion,
+      },
+      task: commitDirectoryWrite,
+    });
+  } catch (error) {
+    if (error instanceof DirectoryAuthorityError) {
+      if (error.code.startsWith("filesystem_")) {
+        fail(
+          error.code,
+          `Safe write failed: ${input.target.logicalPath}`,
+          error.data,
+        );
+      }
+      if (error.code.startsWith("directory_authority_")) {
+        fail(
+          "filesystem_path_changed",
+          `Directory authority was lost: ${input.target.logicalPath}`,
+        );
+      }
+    }
+    rethrowFilesystemError(error, "write", input.target.logicalPath);
+  } finally {
+    await root.close().catch(() => undefined);
+  }
+}

package/plugins/filesystem/source/directory-sample-task.ts

@@ -0,0 +1,23 @@
+/** Self-contained trusted task, run with an already verified directory cwd. */
+export async function sampleDirectoryTask(
+  input: Readonly<{ maxEntries: number }>,
+): Promise<
+  Readonly<{
+    entries: readonly string[];
+    truncated: boolean;
+  }>
+> {
+  const { opendir } =
+    require("node:fs/promises") as typeof import("node:fs/promises");
+  const entries: string[] = [];
+  const directory = await opendir(".");
+  for await (const entry of directory) {
+    if (entries.length >= input.maxEntries) {
+      entries.sort((left, right) => left.localeCompare(right));
+      return { entries, truncated: true };
+    }
+    entries.push(`${entry.name}${entry.isDirectory() ? "/" : ""}`);
+  }
+  entries.sort((left, right) => left.localeCompare(right));
+  return { entries, truncated: false };
+}

package/plugins/filesystem/source/directory-sample.ts

@@ -0,0 +1,132 @@
+import { constants, type BigIntStats } from "node:fs";
+import {
+  open,
+  opendir,
+  realpath,
+  stat,
+  type FileHandle,
+} from "node:fs/promises";
+import { relative, sep } from "node:path";
+import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
+import {
+  DirectoryAuthorityError,
+  runDirectoryAuthorityTask,
+} from "../../../src/shared/directory-authority/index.js";
+import { fail, rethrowFilesystemError } from "./errors.js";
+import { sampleDirectoryTask } from "./directory-sample-task.js";
+
+export const DIRECTORY_ENTRY_LIMIT = 160;
+
+export async function readDirectorySample(
+  target: ResolvedRuntimeToolPath,
+): Promise<Readonly<{ entries: readonly string[]; truncated: boolean }>> {
+  const entries: string[] = [];
+  let handle: FileHandle | undefined;
+  try {
+    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 operation required for a safe read.",
+      );
+    }
+    handle = await open(
+      target.absolutePath,
+      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+    );
+    const before = await handle.stat({ bigint: true });
+    if (!before.isDirectory()) {
+      fail("not_a_directory", `Expected a directory: ${target.logicalPath}`);
+    }
+    const [canonicalRoot, canonicalTarget] = await Promise.all([
+      realpath(target.rootPath),
+      realpath(target.absolutePath),
+    ]);
+    const rootRelative = relative(canonicalRoot, canonicalTarget);
+    if (
+      rootRelative === ".." ||
+      rootRelative.startsWith(`..${sep}`) ||
+      rootRelative.startsWith(sep)
+    ) {
+      fail(
+        "filesystem_path_changed",
+        `Directory changed outside its configured root: ${target.logicalPath}`,
+      );
+    }
+    const pathIdentity = await stat(canonicalTarget, { bigint: true });
+    if (
+      !pathIdentity.isDirectory() ||
+      pathIdentity.dev !== before.dev ||
+      pathIdentity.ino !== before.ino
+    ) {
+      fail(
+        "filesystem_path_changed",
+        `Directory changed while it was being opened: ${target.logicalPath}`,
+      );
+    }
+    if (requiresIsolatedDirectorySample()) {
+      const sample = await runDirectoryAuthorityTask({
+        directoryPath: target.absolutePath,
+        directoryFd: handle.fd,
+        input: { maxEntries: DIRECTORY_ENTRY_LIMIT },
+        task: sampleDirectoryTask,
+      });
+      await assertDirectoryStable(handle, before, target.logicalPath);
+      return sample;
+    }
+    const directory = await opendir(`/proc/self/fd/${handle.fd}`);
+    for await (const entry of directory) {
+      if (entries.length >= DIRECTORY_ENTRY_LIMIT) {
+        await assertDirectoryStable(handle, before, target.logicalPath);
+        entries.sort((left, right) => left.localeCompare(right));
+        return Object.freeze({
+          entries: Object.freeze(entries),
+          truncated: true,
+        });
+      }
+      entries.push(`${entry.name}${entry.isDirectory() ? "/" : ""}`);
+    }
+    await assertDirectoryStable(handle, before, target.logicalPath);
+    entries.sort((left, right) => left.localeCompare(right));
+    return Object.freeze({ entries: Object.freeze(entries), truncated: false });
+  } catch (error: unknown) {
+    if (
+      error instanceof DirectoryAuthorityError &&
+      error.code.startsWith("directory_authority_")
+    ) {
+      fail(
+        "filesystem_path_changed",
+        `Directory authority was lost: ${target.logicalPath}`,
+      );
+    }
+    return rethrowFilesystemError(error, "inspect", target.logicalPath);
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+async function assertDirectoryStable(
+  handle: FileHandle,
+  before: BigIntStats,
+  logicalPath: string,
+): Promise<void> {
+  const after = await handle.stat({ bigint: true });
+  if (
+    !after.isDirectory() ||
+    after.dev !== before.dev ||
+    after.ino !== before.ino ||
+    after.mtimeNs !== before.mtimeNs ||
+    after.ctimeNs !== before.ctimeNs
+  ) {
+    fail(
+      "filesystem_read_changed",
+      `Directory changed while it was being read: ${logicalPath}`,
+    );
+  }
+}
+
+function requiresIsolatedDirectorySample(): boolean {
+  return process.platform === "darwin";
+}

package/plugins/filesystem/source/directory-write-task.ts

@@ -0,0 +1,160 @@
+export type DirectoryWriteInput = Readonly<{
+  relativePath: string;
+  content: string;
+  expectedVersion:
+    | Readonly<{ kind: "absent" }>
+    | Readonly<{
+        kind: "file";
+        device: string;
+        inode: string;
+        size: number;
+        mode: number;
+        modifiedNs: string;
+        changedNs: string;
+        digest: string;
+      }>;
+}>;
+
+/** Self-contained trusted task: serialized into an isolated Node process. */
+export async function commitDirectoryWrite(
+  input: DirectoryWriteInput,
+): Promise<void> {
+  const fs = require("node:fs/promises") as typeof import("node:fs/promises");
+  const { constants } = require("node:fs") as typeof import("node:fs");
+  const { createHash, randomUUID } =
+    require("node:crypto") as typeof import("node:crypto");
+  const expected = input.expectedVersion;
+
+  function failWrite(code: string): never {
+    throw Object.assign(new Error(code), { code });
+  }
+  function hasNodeCode(error: unknown, code: string): boolean {
+    return error instanceof Error && "code" in error && error.code === code;
+  }
+  function isSingleComponent(value: string): boolean {
+    if (!value || value === "." || value === "..") return false;
+    if (value.includes("/") || value.includes("\\")) return false;
+    return !value.includes("\0");
+  }
+  const segments = input.relativePath.split("/");
+  if (!segments.every(isSingleComponent)) failWrite("filesystem_path_changed");
+  const targetName = segments.pop()!;
+  if (Buffer.byteLength(input.content, "utf8") > 1_048_576) {
+    failWrite("filesystem_file_too_large");
+  }
+
+  async function enterChildDirectory(name: string): Promise<void> {
+    let handle: Awaited<ReturnType<typeof fs.open>>;
+    const flags =
+      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+    try {
+      handle = await fs.open(name, flags);
+    } catch (error) {
+      if (!hasNodeCode(error, "ENOENT")) throw error;
+      try {
+        await fs.mkdir(name);
+      } catch (creationError) {
+        if (!hasNodeCode(creationError, "EEXIST")) throw creationError;
+      }
+      handle = await fs.open(name, flags);
+    }
+    try {
+      const held = await handle.stat({ bigint: true });
+      if (!held.isDirectory()) failWrite("filesystem_path_changed");
+      process.chdir(name);
+      const entered = await fs.stat(".", { bigint: true });
+      if (held.dev !== entered.dev || held.ino !== entered.ino) {
+        failWrite("filesystem_path_changed");
+      }
+    } finally {
+      await handle.close();
+    }
+  }
+  for (const segment of segments) await enterChildDirectory(segment);
+
+  function hasExpectedMetadata(info: import("node:fs").BigIntStats): boolean {
+    if (expected.kind !== "file" || !info.isFile()) return false;
+    if (String(info.dev) !== expected.device) return false;
+    if (String(info.ino) !== expected.inode) return false;
+    if (Number(info.size) !== expected.size) return false;
+    if ((Number(info.mode) & 0o7777) !== expected.mode) return false;
+    if (String(info.mtimeNs) !== expected.modifiedNs) return false;
+    return String(info.ctimeNs) === expected.changedNs;
+  }
+  async function assertExpectedTarget(): Promise<void> {
+    let target: Awaited<ReturnType<typeof fs.open>>;
+    try {
+      target = await fs.open(
+        targetName,
+        constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+      );
+    } catch (error) {
+      if (hasNodeCode(error, "ENOENT") && expected.kind === "absent") return;
+      failWrite("filesystem_target_changed");
+    }
+    try {
+      const before = await target.stat({ bigint: true });
+      if (!hasExpectedMetadata(before)) failWrite("filesystem_target_changed");
+      if (expected.kind !== "file") failWrite("filesystem_target_changed");
+      const bytes = Buffer.alloc(expected.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const { bytesRead } = await target.read(
+          bytes,
+          offset,
+          bytes.length - offset,
+          offset,
+        );
+        if (bytesRead <= 0) failWrite("filesystem_target_changed");
+        offset += bytesRead;
+      }
+      const after = await target.stat({ bigint: true });
+      if (!hasExpectedMetadata(after)) failWrite("filesystem_target_changed");
+      const digest = createHash("sha256").update(bytes).digest("hex");
+      if (digest !== expected.digest) failWrite("filesystem_target_changed");
+    } finally {
+      await target.close();
+    }
+  }
+
+  const parent = await fs.open(
+    ".",
+    constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+  );
+  const temporaryName = `.abot-${targetName}-${randomUUID()}.tmp`;
+  let temporaryCreated = false;
+  try {
+    const temporary = await fs.open(temporaryName, "wx");
+    temporaryCreated = true;
+    try {
+      await temporary.writeFile(input.content, "utf8");
+      if (expected.kind === "file") await temporary.chmod(expected.mode);
+      await temporary.sync();
+    } finally {
+      await temporary.close();
+    }
+    await assertExpectedTarget();
+    if (expected.kind === "file") {
+      await fs.rename(temporaryName, targetName);
+      temporaryCreated = false;
+    } else {
+      try {
+        await fs.link(temporaryName, targetName);
+      } catch (error) {
+        if (hasNodeCode(error, "EEXIST"))
+          failWrite("filesystem_target_changed");
+        throw error;
+      }
+      const removed = await fs
+        .rm(temporaryName, { force: true })
+        .then(() => true)
+        .catch(() => false);
+      temporaryCreated = !removed;
+    }
+    await parent.sync().catch(() => undefined);
+  } finally {
+    if (temporaryCreated)
+      await fs.rm(temporaryName, { force: true }).catch(() => undefined);
+    await parent.close().catch(() => undefined);
+  }
+}

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

@@ -66,6 +66,7 @@ async function openDirectory(
         `Directory changed while it was being opened: ${logicalPath}`,
       );
     }
+    if (usesIsolatedDirectoryAuthority()) return handle;
     const procPath = `/proc/self/fd/${handle.fd}`;
     const procIdentity = await stat(procPath, { bigint: true });
     if (!procIdentity.isDirectory() || !sameIdentity(opened, procIdentity)) {
@@ -162,3 +163,13 @@ export async function openMutationParent(
     throw error;
   }
 }
+
+function usesIsolatedDirectoryAuthority(): boolean {
+  return process.platform === "darwin";
+}
+
+export function openMutationRoot(
+  target: ResolvedRuntimeToolPath,
+): Promise<FileHandle> {
+  return openDirectory(target.rootPath, target.rootPath, target.logicalPath);
+}