@actagent/file-transfer 2026.6.2

package/actagent.plugin.json

@@ -0,0 +1,50 @@
+{
+  "id": "file-transfer",
+  "activation": {
+    "onStartup": true
+  },
+  "enabledByDefault": true,
+  "name": "File Transfer",
+  "description": "Fetch, list, and write files on paired nodes via dedicated node commands. Bypasses bash stdout truncation by using base64 over node.invoke for binaries up to 16 MB.",
+  "contracts": {
+    "tools": ["file_fetch", "dir_list", "dir_fetch", "file_write"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "nodes": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "ask": {
+              "type": "string",
+              "enum": ["off", "on-miss", "always"]
+            },
+            "allowReadPaths": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "allowWritePaths": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "denyPaths": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "maxBytes": {
+              "type": "number"
+            },
+            "followSymlinks": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/index.test.ts

@@ -0,0 +1,93 @@
+// File Transfer tests cover index plugin behavior.
+import { afterAll, describe, expect, it, vi } from "vitest";
+import pluginEntry from "./index.js";
+
+function rejectRuntimeImport(moduleName: string) {
+  return () => {
+    throw new Error(`${moduleName} imported during descriptor registration`);
+  };
+}
+
+vi.mock("./src/node-host/file-fetch.js", rejectRuntimeImport("node-host/file-fetch"));
+vi.mock("./src/node-host/dir-list.js", rejectRuntimeImport("node-host/dir-list"));
+vi.mock("./src/node-host/dir-fetch.js", rejectRuntimeImport("node-host/dir-fetch"));
+vi.mock("./src/node-host/file-write.js", rejectRuntimeImport("node-host/file-write"));
+vi.mock("./src/tools/file-fetch-tool.js", rejectRuntimeImport("tools/file-fetch-tool"));
+vi.mock("./src/tools/dir-list-tool.js", rejectRuntimeImport("tools/dir-list-tool"));
+vi.mock("./src/tools/dir-fetch-tool.js", rejectRuntimeImport("tools/dir-fetch-tool"));
+vi.mock("./src/tools/file-write-tool.js", rejectRuntimeImport("tools/file-write-tool"));
+vi.mock("./src/shared/node-invoke-policy.js", rejectRuntimeImport("shared/node-invoke-policy"));
+
+afterAll(() => {
+  vi.doUnmock("./src/node-host/file-fetch.js");
+  vi.doUnmock("./src/node-host/dir-list.js");
+  vi.doUnmock("./src/node-host/dir-fetch.js");
+  vi.doUnmock("./src/node-host/file-write.js");
+  vi.doUnmock("./src/tools/file-fetch-tool.js");
+  vi.doUnmock("./src/tools/dir-list-tool.js");
+  vi.doUnmock("./src/tools/dir-fetch-tool.js");
+  vi.doUnmock("./src/tools/file-write-tool.js");
+  vi.doUnmock("./src/shared/node-invoke-policy.js");
+  vi.resetModules();
+});
+
+describe("file-transfer plugin entry", () => {
+  it("registers static command and tool descriptors without importing runtime handlers", () => {
+    const registerNodeInvokePolicy = vi.fn();
+    const registerTool = vi.fn();
+
+    pluginEntry.register({
+      registerNodeInvokePolicy,
+      registerTool,
+    } as never);
+
+    expect(pluginEntry.nodeHostCommands?.map((entry) => entry.command)).toEqual([
+      "file.fetch",
+      "dir.list",
+      "dir.fetch",
+      "file.write",
+    ]);
+    expect(registerNodeInvokePolicy).toHaveBeenCalledTimes(1);
+    expect(registerNodeInvokePolicy.mock.calls[0]?.[0].commands).toEqual([
+      "file.fetch",
+      "dir.list",
+      "dir.fetch",
+      "file.write",
+    ]);
+    expect(registerTool.mock.calls.map(([tool]) => tool.name)).toEqual([
+      "file_fetch",
+      "dir_list",
+      "dir_fetch",
+      "file_write",
+    ]);
+  });
+
+  it("fails closed if the lazy policy module cannot load", async () => {
+    const registerNodeInvokePolicy = vi.fn();
+    const registerTool = vi.fn();
+    const invokeNode = vi.fn();
+
+    pluginEntry.register({
+      registerNodeInvokePolicy,
+      registerTool,
+    } as never);
+
+    const policy = registerNodeInvokePolicy.mock.calls[0]?.[0];
+    await expect(
+      policy.handle({
+        nodeId: "node-1",
+        command: "file.fetch",
+        params: { path: "/tmp/a.txt" },
+        config: {},
+        pluginConfig: {},
+        client: null,
+        invokeNode,
+      }),
+    ).resolves.toMatchObject({
+      ok: false,
+      code: "PLUGIN_POLICY_UNAVAILABLE",
+      unavailable: true,
+    });
+    expect(invokeNode).not.toHaveBeenCalled();
+  });
+});

package/index.ts

@@ -0,0 +1,121 @@
+// File Transfer plugin entrypoint registers its ACTAgent integration.
+import {
+  definePluginEntry,
+  type AnyAgentTool,
+  type ACTAgentPluginNodeHostCommand,
+} from "actagent/plugin-sdk/plugin-entry";
+import { createLazyFileTransferNodeInvokePolicy } from "./src/shared/lazy-node-invoke-policy.js";
+import {
+  DIR_FETCH_TOOL_DESCRIPTOR,
+  DIR_LIST_TOOL_DESCRIPTOR,
+  FILE_FETCH_TOOL_DESCRIPTOR,
+  FILE_WRITE_TOOL_DESCRIPTOR,
+} from "./src/tools/descriptors.js";
+
+type FileTransferToolDescriptor = Pick<
+  AnyAgentTool,
+  "label" | "name" | "description" | "parameters"
+>;
+
+function readNodeCommandParams(paramsJSON: string | null | undefined): unknown {
+  return paramsJSON ? JSON.parse(paramsJSON) : {};
+}
+
+function createLazyTool(
+  descriptor: FileTransferToolDescriptor,
+  loadTool: () => Promise<AnyAgentTool>,
+): AnyAgentTool {
+  let toolPromise: Promise<AnyAgentTool> | undefined;
+  const loadOnce = () => {
+    toolPromise ??= loadTool();
+    return toolPromise;
+  };
+  return {
+    ...descriptor,
+    async execute(toolCallId, args, signal, onUpdate) {
+      const tool = await loadOnce();
+      return await tool.execute(toolCallId, args, signal, onUpdate);
+    },
+  };
+}
+
+const fileTransferNodeHostCommands: ACTAgentPluginNodeHostCommand[] = [
+  {
+    command: "file.fetch",
+    cap: "file",
+    dangerous: true,
+    handle: async (paramsJSON) => {
+      const { handleFileFetch } = await import("./src/node-host/file-fetch.js");
+      const params = readNodeCommandParams(paramsJSON) as Parameters<typeof handleFileFetch>[0];
+      const result = await handleFileFetch(params);
+      return JSON.stringify(result);
+    },
+  },
+  {
+    command: "dir.list",
+    cap: "file",
+    dangerous: true,
+    handle: async (paramsJSON) => {
+      const { handleDirList } = await import("./src/node-host/dir-list.js");
+      const params = readNodeCommandParams(paramsJSON) as Parameters<typeof handleDirList>[0];
+      const result = await handleDirList(params);
+      return JSON.stringify(result);
+    },
+  },
+  {
+    command: "dir.fetch",
+    cap: "file",
+    dangerous: true,
+    handle: async (paramsJSON) => {
+      const { handleDirFetch } = await import("./src/node-host/dir-fetch.js");
+      const params = readNodeCommandParams(paramsJSON) as Parameters<typeof handleDirFetch>[0];
+      const result = await handleDirFetch(params);
+      return JSON.stringify(result);
+    },
+  },
+  {
+    command: "file.write",
+    cap: "file",
+    dangerous: true,
+    handle: async (paramsJSON) => {
+      const { handleFileWrite } = await import("./src/node-host/file-write.js");
+      const params = readNodeCommandParams(paramsJSON) as Parameters<typeof handleFileWrite>[0];
+      const result = await handleFileWrite(params);
+      return JSON.stringify(result);
+    },
+  },
+];
+
+export default definePluginEntry({
+  id: "file-transfer",
+  name: "File Transfer",
+  description: "Fetch, list, and write files on paired nodes via dedicated node commands.",
+  nodeHostCommands: fileTransferNodeHostCommands,
+  register(api) {
+    api.registerNodeInvokePolicy(createLazyFileTransferNodeInvokePolicy());
+    api.registerTool(
+      createLazyTool(FILE_FETCH_TOOL_DESCRIPTOR, async () => {
+        const { createFileFetchTool } = await import("./src/tools/file-fetch-tool.js");
+        return createFileFetchTool();
+      }),
+    );
+    api.registerTool(
+      createLazyTool(DIR_LIST_TOOL_DESCRIPTOR, async () => {
+        const { createDirListTool } = await import("./src/tools/dir-list-tool.js");
+        return createDirListTool();
+      }),
+    );
+    api.registerTool(
+      createLazyTool(DIR_FETCH_TOOL_DESCRIPTOR, async () => {
+        const { createDirFetchTool } = await import("./src/tools/dir-fetch-tool.js");
+        return createDirFetchTool();
+      }),
+    );
+    api.registerTool(
+      createLazyTool(FILE_WRITE_TOOL_DESCRIPTOR, async () => {
+        const { createFileWriteTool } = await import("./src/tools/file-write-tool.js");
+        return createFileWriteTool();
+      }),
+    );
+  },
+});

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@actagent/file-transfer",
+  "version": "2026.6.2",
+  "description": "ACTAgent file transfer plugin (file_fetch, dir_list, dir_fetch, file_write)",
+  "type": "module",
+  "dependencies": {
+    "minimatch": "10.2.5",
+    "typebox": "1.1.39"
+  },
+  "devDependencies": {
+    "@actagent/plugin-sdk": "workspace:*"
+  },
+  "actagent": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/node-host/dir-fetch.test.ts

@@ -0,0 +1,131 @@
+// File Transfer tests cover dir fetch plugin behavior.
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { handleDirFetch } from "./dir-fetch.js";
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+  // realpath: see file-fetch.test.ts for the macOS symlinked-tmpdir reason.
+  tmpRoot = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "dir-fetch-test-")));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+// dir-fetch shells out to /usr/bin/tar. Skip the body of these tests on
+// platforms without it (Windows CI). They still register, just no-op.
+const HAS_TAR = process.platform !== "win32";
+
+async function expectDirFetchError(input: Parameters<typeof handleDirFetch>[0], code: string) {
+  const result = await handleDirFetch(input);
+  if (result.ok) {
+    throw new Error("expected directory fetch error");
+  }
+  expect(result.code).toBe(code);
+}
+
+describe("handleDirFetch — input validation", () => {
+  it("rejects empty / non-string path", async () => {
+    await expectDirFetchError({ path: "" }, "INVALID_PATH");
+  });
+
+  it("rejects relative paths", async () => {
+    await expectDirFetchError({ path: "relative" }, "INVALID_PATH");
+  });
+
+  it("rejects paths with NUL bytes", async () => {
+    await expectDirFetchError({ path: "/tmp/foo\0bar" }, "INVALID_PATH");
+  });
+});
+
+describe("handleDirFetch — fs errors", () => {
+  it.runIf(HAS_TAR)("returns NOT_FOUND for a missing directory", async () => {
+    await expectDirFetchError({ path: path.join(tmpRoot, "missing") }, "NOT_FOUND");
+  });
+
+  it.runIf(HAS_TAR)("returns IS_FILE when path resolves to a file", async () => {
+    const f = path.join(tmpRoot, "f.txt");
+    await fs.writeFile(f, "x");
+    await expectDirFetchError({ path: f }, "IS_FILE");
+  });
+});
+
+describe("handleDirFetch — happy path", () => {
+  it("preflights directory entries without creating a tarball", async () => {
+    await fs.writeFile(path.join(tmpRoot, "a.txt"), "alpha\n");
+    await fs.mkdir(path.join(tmpRoot, ".ssh"));
+    await fs.writeFile(path.join(tmpRoot, ".ssh", "id_rsa"), "secret\n");
+    await fs.mkdir(path.join(tmpRoot, "sub"));
+    await fs.writeFile(path.join(tmpRoot, "sub", "b.txt"), "beta\n");
+
+    const r = await handleDirFetch({ path: tmpRoot, preflightOnly: true });
+    if (!r.ok) {
+      throw new Error(`expected ok, got ${r.code}: ${r.message}`);
+    }
+
+    expect(r.path).toBe(tmpRoot);
+    expect(r.tarBase64).toBe("");
+    expect(r.tarBytes).toBe(0);
+    expect(r.sha256).toBe("");
+    expect(r.preflightOnly).toBe(true);
+    expect(r.entries).toEqual([".ssh", ".ssh/id_rsa", "a.txt", "sub", "sub/b.txt"]);
+    expect(r.fileCount).toBe(r.entries?.length);
+  });
+
+  it.runIf(HAS_TAR)("returns a gzipped tar with byte count and sha256", async () => {
+    await fs.writeFile(path.join(tmpRoot, "a.txt"), "alpha\n");
+    await fs.writeFile(path.join(tmpRoot, "b.txt"), "beta\n");
+    await fs.mkdir(path.join(tmpRoot, "sub"));
+    await fs.writeFile(path.join(tmpRoot, "sub", "c.txt"), "gamma\n");
+
+    const r = await handleDirFetch({ path: tmpRoot });
+    if (!r.ok) {
+      throw new Error(`expected ok, got ${r.code}: ${r.message}`);
+    }
+
+    expect(r.tarBytes).toBeGreaterThan(0);
+    expect(r.tarBase64.length).toBeGreaterThan(0);
+
+    const buf = Buffer.from(r.tarBase64, "base64");
+    expect(buf.byteLength).toBe(r.tarBytes);
+
+    const expectedSha = crypto.createHash("sha256").update(buf).digest("hex");
+    expect(r.sha256).toBe(expectedSha);
+
+    // gzip magic bytes
+    expect(buf[0]).toBe(0x1f);
+    expect(buf[1]).toBe(0x8b);
+
+    // file count covers the regular files we created (3); BSD tar may also
+    // list directory entries, so be generous.
+    expect(r.fileCount).toBeGreaterThanOrEqual(3);
+    expect(r.entries).toContain("a.txt");
+    expect(r.entries).toContain("b.txt");
+    expect(r.entries).toContain("sub");
+    expect(r.entries).toContain("sub/c.txt");
+    expect(r.fileCount).toBe(r.entries?.length);
+  });
+});
+
+describe("handleDirFetch — size cap", () => {
+  it.runIf(HAS_TAR)(
+    "returns TREE_TOO_LARGE when content exceeds the cap mid-stream",
+    async () => {
+      // Write enough random content to exceed a small maxBytes. Random bytes
+      // don't compress, so gzip output is roughly the same size as input.
+      const big = crypto.randomBytes(512 * 1024);
+      await fs.writeFile(path.join(tmpRoot, "big1.bin"), big);
+      await fs.writeFile(path.join(tmpRoot, "big2.bin"), big);
+      await fs.writeFile(path.join(tmpRoot, "big3.bin"), big);
+
+      // 64KB cap should trip either the du preflight or the streaming SIGTERM.
+      await expectDirFetchError({ path: tmpRoot, maxBytes: 64 * 1024 }, "TREE_TOO_LARGE");
+    },
+    30_000,
+  );
+});