@abot-ai/runtime 1.6.0 → 1.8.0

package/plugins/filesystem/plugin.json

@@ -4,6 +4,10 @@
   "version": "0.1.0",
   "description": "Inspect and mutate files under the configured agent work directory and workspace roots.",
   "extensions": {
+    "ai.abot.compatibility": {
+      "version": 1,
+      "runtimePlatforms": ["linux", "darwin", "win32"]
+    },
     "ai.abot.runtime": {
       "version": 1,
       "entrypoint": "./src/index.cjs",
@@ -35,6 +39,7 @@
           "operations": {
             "inspect_target": {
               "summary": "Read a bounded line-numbered window from source code or another text file, or inspect a directory sample. Choose a locator or numeric lines; locator takes precedence. Results declare truncation explicitly.",
+              "outputChannels": {"text": "content", "data": "conditional"},
               "input": {
                 "type": "object",
                 "additionalProperties": false,
@@ -194,6 +199,7 @@
           "operations": {
             "read_one_file": {
               "summary": "Read one source-code or text file, including JS, TS, Python, HTML and CSS. Returns complete content within the read budget or an explicitly truncated head/tail view.",
+              "outputChannels": {"text": "content", "data": "metadata"},
               "input": {
                 "type": "object",
                 "additionalProperties": false,
@@ -213,7 +219,7 @@
         },
         "write_file": {
           "catalogGroups": ["write"],
-          "description": "Create one new file or perform an explicitly requested intentional full-file replacement. Use when the complete desired file is already known, especially for new or nearly empty files. Do not choose write_file for an ordinary addition or change to an existing file when an active existing-target editor can preserve current content. For an explicit existing-file replacement, inspect the complete current file first; prior conversation summaries do not count as current file content. Selection uses only the target path; runtime collects the raw file body over a separate payload channel.",
+          "description": "Write a file at the complete path, including its filename; missing parent directories are created automatically. For an empty directory, use an available SYSTEM or EXEC command tool. Use for a new file or explicitly requested full-file replacement whose complete content is known. Ordinary changes to an existing file belong to an available existing-target editor. Before full replacement, inspect the entire current file; conversation summaries are not current file content. Select only the path; the raw file body is authored separately.",
           "routingCapability": "filesystem_mutation",
           "controlsRefinement": "mechanical_when_complete",
           "developmentRoles": ["establish", "mutate"],
@@ -244,7 +250,7 @@
           "skills": [],
           "operations": {
             "write_complete_file": {
-              "summary": "Create a new file via a separate complete raw-text payload. Paths use the runtime-host namespace; relative paths use the call's working directory under the request's agent work root. Path syntax does not select a SYSTEM OS target. Establish source artifacts before consumers in a connected Worker call; bounded successful artifacts reach later payloads. Existing files require explicit full replacement; use edit_existing_file for ordinary edits. Do not create unrequested adjacent artifacts.",
+              "summary": "Write one file via separate complete raw payload; path includes its filename. Missing parents are auto-created; use an available SYSTEM or EXEC command for an empty directory. Paths use the runtime host; relative paths use call cwd under the agent work root, not a SYSTEM OS target. Establish sources before consumers in a Worker call; bounded successful artifacts reach later payloads. Existing files need explicit full replacement; use edit_existing_file for ordinary edits. No unrequested adjacent artifacts.",
               "input": {
                 "type": "object",
                 "additionalProperties": false,

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

@@ -1,3 +1,4 @@
+import { writeWindowsFile } from "./windows/operations.js";
 import { randomUUID } from "node:crypto";
 import { link, open, rename, rm, type FileHandle } from "node:fs/promises";
 import { posix } from "node:path";
@@ -23,6 +24,7 @@ export async function atomicWriteText(
   }>,
 ): Promise<void> {
   assertMutationContentSize(input.content);
+  if (process.platform === "win32") return writeWindowsFile(input);
   if (requiresIsolatedDirectoryAuthority()) {
     await writeWithDirectoryAuthority(input);
     return;

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

@@ -1,22 +1,20 @@
 import { createHash } from "node:crypto";
-import { constants, type BigIntStats } from "node:fs";
-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";
-
 import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
-
 import { fail, FilesystemToolError, rethrowFilesystemError } from "./errors.js";
+import { observeFileSlices } from "./file-observation.js";
+import { sameMetadata, type MutationFileMetadata } from "./file-version.js";
 
-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 { readExactBytes } from "./file-observation.js";
 export {
   readDirectorySample,
   DIRECTORY_ENTRY_LIMIT,
 } from "./directory-sample.js";
+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 type BoundedText = Readonly<{
   text: string;
@@ -25,73 +23,23 @@ export type BoundedText = Readonly<{
   omittedBytes: number;
   truncated: boolean;
 }>;
-
-type MutationFileMetadata = Readonly<{
-  device: bigint;
-  inode: bigint;
-  size: number;
-  mode: number;
-  modifiedNs: bigint;
-  changedNs: bigint;
-}>;
-
 export type MutationTargetVersion =
   | Readonly<{ kind: "absent" }>
   | Readonly<MutationFileMetadata & { kind: "file"; digest: string }>;
-
 export type MutationSnapshot = Readonly<{
   content: string | null;
   version: MutationTargetVersion;
 }>;
 
-type PositionalFileReader = Readonly<{
-  read(
-    buffer: Buffer,
-    offset: number,
-    length: number,
-    position: number,
-  ): Promise<Readonly<{ bytesRead: number }>>;
-}>;
-
-export async function readExactBytes(
-  reader: PositionalFileReader,
-  buffer: Buffer,
-  position: number,
-  logicalPath: string,
-): Promise<void> {
-  let offset = 0;
-  while (offset < buffer.length) {
-    const result = await reader.read(
-      buffer,
-      offset,
-      buffer.length - offset,
-      position + offset,
-    );
-    if (result.bytesRead <= 0 || result.bytesRead > buffer.length - offset) {
-      fail(
-        "filesystem_read_incomplete",
-        `File changed or ended before a complete read: ${logicalPath}`,
-      );
-    }
-    offset += result.bytesRead;
-  }
-}
-
 function decodeCompletePrefix(buffer: Buffer): string {
   return new StringDecoder("utf8").write(buffer);
 }
-
 function decodeSuffix(buffer: Buffer): string {
   let start = 0;
-  while (
-    start < Math.min(4, buffer.length) &&
-    (buffer[start]! & 0xc0) === 0x80
-  ) {
+  while (start < Math.min(4, buffer.length) && (buffer[start]! & 0xc0) === 0x80)
     start += 1;
-  }
   return buffer.subarray(start).toString("utf8");
 }
-
 function decodeMutationText(buffer: Buffer, logicalPath: string): string {
   try {
     return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
@@ -103,191 +51,83 @@ function decodeMutationText(buffer: Buffer, logicalPath: string): string {
   }
 }
 
-async function openRegularFile(target: ResolvedRuntimeToolPath): Promise<
-  Readonly<{
-    handle: FileHandle;
-    size: number;
-    metadata: MutationFileMetadata;
-  }>
-> {
-  let handle: FileHandle | undefined;
-  try {
-    if (typeof constants.O_NOFOLLOW !== "number") {
-      fail(
-        "filesystem_safe_io_unsupported",
-        "This platform does not provide the no-follow operation required for a safe read.",
-      );
-    }
-    handle = await open(
-      target.absolutePath,
-      constants.O_RDONLY | constants.O_NOFOLLOW,
-    );
-    const info = await handle.stat({ bigint: true });
-    if (!info.isFile()) {
-      fail("not_a_file", `Expected a regular file: ${target.logicalPath}`);
-    }
-    const metadata = metadataFromStat(info, 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",
-        `File changed outside its configured root: ${target.logicalPath}`,
-      );
-    }
-    const pathIdentity = await stat(canonicalTarget, { bigint: true });
-    if (
-      !pathIdentity.isFile() ||
-      pathIdentity.dev !== info.dev ||
-      pathIdentity.ino !== info.ino
-    ) {
-      fail(
-        "filesystem_path_changed",
-        `File changed while it was being opened: ${target.logicalPath}`,
-      );
-    }
-    return Object.freeze({ handle, size: metadata.size, metadata });
-  } catch (error: unknown) {
-    await handle?.close().catch(() => undefined);
-    rethrowFilesystemError(error, "inspect", target.logicalPath);
-  }
-}
-
 export async function readBoundedText(
   target: ResolvedRuntimeToolPath,
-  options: Readonly<{
-    headBytes?: number;
-    tailBytes?: number;
-  }> = {},
+  options: Readonly<{ headBytes?: number; tailBytes?: number }> = {},
 ): Promise<BoundedText> {
-  const file = await openRegularFile(target);
-  const headBytes = options.headBytes ?? READ_HEAD_BYTES;
-  const tailBytes = options.tailBytes ?? READ_TAIL_BYTES;
-  const byteBudget = headBytes + tailBytes;
-  try {
-    if (file.size <= byteBudget) {
-      const buffer = Buffer.alloc(file.size);
-      await readExactBytes(file.handle, buffer, 0, target.logicalPath);
-      await assertFileStable(file, target.logicalPath);
-      rejectBinary(buffer, target.logicalPath);
-      return Object.freeze({
-        text: decodeCompletePrefix(buffer),
-        byteCount: file.size,
-        bytesRead: file.size,
-        omittedBytes: 0,
-        truncated: false,
-      });
-    }
-    const head = Buffer.alloc(headBytes);
-    const tail = Buffer.alloc(tailBytes);
-    await Promise.all([
-      readExactBytes(file.handle, head, 0, target.logicalPath),
-      readExactBytes(
-        file.handle,
-        tail,
-        Math.max(0, file.size - tailBytes),
-        target.logicalPath,
-      ),
-    ]);
-    await assertFileStable(file, target.logicalPath);
-    rejectBinary(head, target.logicalPath);
-    rejectBinary(tail, target.logicalPath);
-    const omittedBytes = Math.max(0, file.size - head.length - tail.length);
-    return Object.freeze({
-      text: [
-        decodeCompletePrefix(head),
-        `[${omittedBytes} bytes omitted from the middle]`,
-        decodeSuffix(tail),
-      ].join("\n"),
-      byteCount: file.size,
-      bytesRead: head.length + tail.length,
-      omittedBytes,
-      truncated: true,
-    });
-  } catch (error: unknown) {
-    return rethrowFilesystemError(error, "read", target.logicalPath);
-  } finally {
-    await file.handle.close().catch(() => undefined);
-  }
+  const observed = await observeFileSlices(target, {
+    headBytes: options.headBytes ?? READ_HEAD_BYTES,
+    tailBytes: options.tailBytes ?? READ_TAIL_BYTES,
+  });
+  rejectBinary(observed.head, target.logicalPath);
+  rejectBinary(observed.tail, target.logicalPath);
+  const bytesRead = observed.head.length + observed.tail.length;
+  const omittedBytes = observed.metadata.size - bytesRead;
+  const text =
+    omittedBytes === 0
+      ? decodeCompletePrefix(observed.head)
+      : [
+          decodeCompletePrefix(observed.head),
+          `[${omittedBytes} bytes omitted from the middle]`,
+          decodeSuffix(observed.tail),
+        ].join("\n");
+  return Object.freeze({
+    text,
+    byteCount: observed.metadata.size,
+    bytesRead,
+    omittedBytes,
+    truncated: omittedBytes > 0,
+  });
 }
 
 export async function readPrefixText(
   target: ResolvedRuntimeToolPath,
   maxBytes: number = DEV_SCAN_BYTES,
 ): Promise<BoundedText> {
-  const file = await openRegularFile(target);
-  try {
-    const length = Math.min(file.size, maxBytes);
-    const buffer = Buffer.alloc(length);
-    await readExactBytes(file.handle, buffer, 0, target.logicalPath);
-    await assertFileStable(file, target.logicalPath);
-    rejectBinary(buffer, target.logicalPath);
-    return Object.freeze({
-      text: decodeCompletePrefix(buffer),
-      byteCount: file.size,
-      bytesRead: length,
-      omittedBytes: Math.max(0, file.size - length),
-      truncated: length < file.size,
-    });
-  } catch (error: unknown) {
-    rethrowFilesystemError(error, "read", target.logicalPath);
-  } finally {
-    await file.handle.close().catch(() => undefined);
-  }
+  const observed = await observeFileSlices(target, {
+    headBytes: maxBytes,
+    tailBytes: 0,
+  });
+  rejectBinary(observed.head, target.logicalPath);
+  return Object.freeze({
+    text: decodeCompletePrefix(observed.head),
+    byteCount: observed.metadata.size,
+    bytesRead: observed.head.length,
+    omittedBytes: observed.metadata.size - observed.head.length,
+    truncated: observed.head.length < observed.metadata.size,
+  });
 }
 
 export async function readMutationSnapshot(
   target: ResolvedRuntimeToolPath,
 ): Promise<MutationSnapshot> {
-  let file: Awaited<ReturnType<typeof openRegularFile>> | undefined;
   try {
-    file = await openRegularFile(target);
-    const byteCount = file.size;
-    if (byteCount > MAX_MUTATION_BYTES) {
-      fail(
-        "file_too_large",
-        `File exceeds the ${MAX_MUTATION_BYTES}-byte mutation limit: ${target.logicalPath}`,
-        { byteCount, maxBytes: MAX_MUTATION_BYTES },
-      );
-    }
-    const buffer = Buffer.alloc(byteCount);
-    await readExactBytes(file.handle, buffer, 0, target.logicalPath);
-    const afterRead = metadataFromStat(
-      await file.handle.stat({ bigint: true }),
-      target.logicalPath,
-    );
-    if (!sameMetadata(file.metadata, afterRead)) {
-      failTargetChanged(target.logicalPath, "file", "file");
-    }
-    rejectBinary(buffer, target.logicalPath);
+    const observed = await observeFileSlices(target, {
+      headBytes: MAX_MUTATION_BYTES,
+      tailBytes: 0,
+      maximumFileBytes: MAX_MUTATION_BYTES,
+    });
+    rejectBinary(observed.head, target.logicalPath);
     return Object.freeze({
-      content: decodeMutationText(buffer, target.logicalPath),
+      content: decodeMutationText(observed.head, target.logicalPath),
       version: Object.freeze({
         kind: "file",
-        ...file.metadata,
-        digest: digest(buffer),
+        ...observed.metadata,
+        digest: digest(observed.head),
       }),
     });
-  } catch (error: unknown) {
-    if (
-      error instanceof FilesystemToolError &&
-      error.code === "file_not_found"
-    ) {
+  } catch (error) {
+    if (error instanceof FilesystemToolError && error.code === "file_not_found")
       return Object.freeze({
         content: null,
         version: Object.freeze({ kind: "absent" }),
       });
-    }
+    if (
+      error instanceof FilesystemToolError &&
+      error.code === "filesystem_read_changed"
+    )
+      failTargetChanged(target.logicalPath, "file", "file");
     return rethrowFilesystemError(error, "read", target.logicalPath);
-  } finally {
-    await file?.handle.close().catch(() => undefined);
   }
 }
 
@@ -295,44 +135,29 @@ export async function assertMutationTargetUnchanged(
   target: ResolvedRuntimeToolPath,
   expected: MutationTargetVersion,
 ): Promise<void> {
-  let file: Awaited<ReturnType<typeof openRegularFile>> | undefined;
+  let current: MutationSnapshot;
   try {
-    file = await openRegularFile(target);
-  } catch (error: unknown) {
-    if (
+    current = await readMutationSnapshot(target);
+  } catch (error) {
+    const changedContents =
       error instanceof FilesystemToolError &&
-      error.code === "file_not_found"
-    ) {
-      if (expected.kind === "absent") return;
-      failTargetChanged(target.logicalPath, expected.kind, "absent");
-    }
+      [
+        "file_too_large",
+        "binary_file_unsupported",
+        "filesystem_invalid_encoding",
+      ].includes(error.code);
+    if (changedContents)
+      failTargetChanged(target.logicalPath, expected.kind, "file");
     throw error;
   }
-
-  try {
-    if (expected.kind === "absent") {
-      failTargetChanged(target.logicalPath, "absent", "file");
-    }
-    if (!sameMetadata(expected, file.metadata)) {
-      failTargetChanged(target.logicalPath, "file", "file");
-    }
-    const buffer = Buffer.alloc(file.size);
-    await readExactBytes(file.handle, buffer, 0, target.logicalPath);
-    const afterRead = metadataFromStat(
-      await file.handle.stat({ bigint: true }),
-      target.logicalPath,
-    );
-    if (
-      !sameMetadata(file.metadata, afterRead) ||
-      digest(buffer) !== expected.digest
-    ) {
-      failTargetChanged(target.logicalPath, "file", "file");
-    }
-  } catch (error: unknown) {
-    return rethrowFilesystemError(error, "inspect", target.logicalPath);
-  } finally {
-    await file.handle.close().catch(() => undefined);
-  }
+  if (current.version.kind !== expected.kind)
+    failTargetChanged(target.logicalPath, expected.kind, current.version.kind);
+  if (current.version.kind === "absent" || expected.kind === "absent") return;
+  if (
+    !sameMetadata(expected, current.version) ||
+    expected.digest !== current.version.digest
+  )
+    failTargetChanged(target.logicalPath, "file", "file");
 }
 
 export function assertMutationContentSize(content: string): number {
@@ -346,67 +171,16 @@ export function assertMutationContentSize(content: string): number {
   }
   return byteCount;
 }
-
 function rejectBinary(buffer: Buffer, logicalPath: string): void {
-  if (buffer.includes(0)) {
+  if (buffer.includes(0))
     fail(
       "binary_file_unsupported",
       `Binary file is not supported: ${logicalPath}`,
     );
-  }
-}
-
-function metadataFromStat(
-  info: BigIntStats,
-  logicalPath: string,
-): MutationFileMetadata {
-  if (info.size > BigInt(Number.MAX_SAFE_INTEGER)) {
-    fail("file_too_large", `File is too large to read safely: ${logicalPath}`);
-  }
-  return Object.freeze({
-    device: info.dev,
-    inode: info.ino,
-    size: Number(info.size),
-    mode: Number(info.mode) & 0o7777,
-    modifiedNs: info.mtimeNs,
-    changedNs: info.ctimeNs,
-  });
-}
-
-function sameMetadata(
-  left: MutationFileMetadata,
-  right: MutationFileMetadata,
-): boolean {
-  return (
-    left.device === right.device &&
-    left.inode === right.inode &&
-    left.size === right.size &&
-    left.mode === right.mode &&
-    left.modifiedNs === right.modifiedNs &&
-    left.changedNs === right.changedNs
-  );
-}
-
-async function assertFileStable(
-  file: Readonly<{ handle: FileHandle; metadata: MutationFileMetadata }>,
-  logicalPath: string,
-): Promise<void> {
-  const afterRead = metadataFromStat(
-    await file.handle.stat({ bigint: true }),
-    logicalPath,
-  );
-  if (!sameMetadata(file.metadata, afterRead)) {
-    fail(
-      "filesystem_read_changed",
-      `File changed while it was being read: ${logicalPath}`,
-    );
-  }
 }
-
 function digest(buffer: Buffer): string {
   return createHash("sha256").update(buffer).digest("hex");
 }
-
 function failTargetChanged(
   logicalPath: string,
   expectedState: MutationTargetVersion["kind"],

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

@@ -1,3 +1,4 @@
+import { sampleWindowsDirectory } from "./windows/operations.js";
 import { constants, type BigIntStats } from "node:fs";
 import {
   open,
@@ -20,6 +21,7 @@ export const DIRECTORY_ENTRY_LIMIT = 160;
 export async function readDirectorySample(
   target: ResolvedRuntimeToolPath,
 ): Promise<Readonly<{ entries: readonly string[]; truncated: boolean }>> {
+  if (process.platform === "win32") return sampleWindowsDirectory(target, DIRECTORY_ENTRY_LIMIT);
   const entries: string[] = [];
   let handle: FileHandle | undefined;
   try {

package/plugins/filesystem/source/errors.ts

@@ -34,6 +34,17 @@ export function isNodeErrorCode(error: unknown, code: string): boolean {
   );
 }
 
+export function isDirectoryTypeFailure(code: unknown): boolean {
+  return code === "not_a_directory" || code === "ENOTDIR";
+}
+
+export function failNotDirectory(): never {
+  fail(
+    "not_a_directory",
+    "A component of the requested path is not a directory. An existing file cannot contain child files. Inspect the path and choose a file target under a directory; do not repeat the same operation unchanged or overwrite the blocking file to turn it into a directory.",
+  );
+}
+
 export function rethrowFilesystemError(
   error: unknown,
   operation: "inspect" | "read" | "write",
@@ -45,6 +56,9 @@ export function rethrowFilesystemError(
   if (isNodeErrorCode(error, "ENOENT")) {
     fail("file_not_found", `Path does not exist: ${logicalPath}`);
   }
+  if (error instanceof Error && isDirectoryTypeFailure((error as NodeError).code)) {
+    failNotDirectory();
+  }
   if (isNodeErrorCode(error, "EACCES") || isNodeErrorCode(error, "EPERM")) {
     fail(
       "filesystem_access_denied",