@abot-ai/runtime 1.3.0 → 1.4.0

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

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { link, open, rename, rm } from "node:fs/promises";
+import { link, open, rename, rm, type FileHandle } from "node:fs/promises";
 import { posix } from "node:path";
 
 import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
@@ -10,16 +10,23 @@ import {
   type MutationTargetVersion,
 } from "./bounded-io.js";
 import { fail, isNodeErrorCode, rethrowFilesystemError } from "./errors.js";
-import { openMutationParent } from "./mutation-parent.js";
+import { closeMutationParent, openMutationParent } from "./mutation-parent.js";
+import { notifyCommittedFileOutput } from "./file-output-presentation.js";
+import { writeWithDirectoryAuthority } from "./directory-authority-write.js";
 
 export async function atomicWriteText(
   input: Readonly<{
     target: ResolvedRuntimeToolPath;
     content: string;
     expectedVersion: MutationTargetVersion;
+    onCommitted?: (root: FileHandle) => void;
   }>,
 ): 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({
@@ -65,13 +72,14 @@ export async function atomicWriteText(
       temporaryCreated = !removed;
     }
     await syncDirectoryBestEffort(parent.handle);
+    notifyCommittedFileOutput(parent.rootHandle, input.onCommitted);
   } catch (error: unknown) {
     rethrowFilesystemError(error, "write", input.target.logicalPath);
   } finally {
     if (temporaryCreated) {
       await rm(temporaryPath, { force: true }).catch(() => undefined);
     }
-    await parent.handle.close().catch(() => undefined);
+    await closeMutationParent(parent);
   }
 }
 
@@ -113,3 +121,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/dev-view.ts

@@ -146,7 +146,8 @@ async function viewFile(
   const lines = completeScannedLines(source.text, source.truncated);
   const availableLineCount = Math.max(lines.length, 1);
   const selection = selectWindow({
-    text: source.text,
+    path: input.target.logicalPath,
+    source,
     lines,
     startLine: input.startLine,
     endLine: input.endLine,

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

@@ -0,0 +1,68 @@
+import type { FileHandle } from "node:fs/promises";
+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 { notifyCommittedFileOutput } from "./file-output-presentation.js";
+import {
+  commitDirectoryWrite,
+  type DirectoryWriteInput,
+} from "./directory-write-task.js";
+
+export async function writeWithDirectoryAuthority(
+  input: Readonly<{
+    target: ResolvedRuntimeToolPath;
+    content: string;
+    expectedVersion: MutationTargetVersion;
+    onCommitted?: (root: FileHandle) => void;
+  }>,
+): 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,
+    });
+    notifyCommittedFileOutput(root, input.onCommitted);
+  } 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/edit-file.ts

@@ -14,6 +14,7 @@ import {
 import { buildMutationGrounding } from "./draft/grounding.js";
 import { prepareFileDraft } from "./draft/prepare.js";
 import { fail } from "./errors.js";
+import { reportCommittedFileOutput } from "./file-output-presentation.js";
 import type { FilesystemMutationCoordinator } from "./mutation-coordinator.js";
 import type { FilesystemPathService } from "./path-service.js";
 
@@ -139,6 +140,8 @@ export function createEditFileHandler(
         target,
         content: prepared.content,
         expectedVersion: snapshot.version,
+        onCommitted: (root) =>
+          reportCommittedFileOutput(context, target, "updated", root),
       });
       return result;
     });

package/plugins/filesystem/source/file-output-presentation.ts

@@ -0,0 +1,42 @@
+import { fstatSync } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type {
+  ResolvedRuntimeToolPath,
+  ToolExecutionContext,
+} from "../../../src/plugin-sdk/index.js";
+
+/** A presentation failure must never change an already committed mutation. */
+export function reportCommittedFileOutput(
+  context: ToolExecutionContext | undefined,
+  target: ResolvedRuntimeToolPath,
+  operation: "created" | "updated",
+  root: FileHandle,
+): void {
+  if (!context?.reportFileOutput) return;
+  try {
+    const identity = fstatSync(root.fd, { bigint: true });
+    context.reportFileOutput({
+      target,
+      operation,
+      rootIdentity: {
+        device: String(identity.dev),
+        inode: String(identity.ino),
+        birthtimeNs: String(identity.birthtimeNs),
+      },
+    });
+  } catch {
+    // The host may omit the optional card; the filesystem result stays true.
+  }
+}
+
+/** Called before releasing the mutation root; observers cannot undo a commit. */
+export function notifyCommittedFileOutput(
+  root: FileHandle,
+  onCommitted?: (root: FileHandle) => void,
+): void {
+  try {
+    onCommitted?.(root);
+  } catch {
+    // The committed tool result is independent of optional presentation.
+  }
+}