@aria-cli/tools 1.0.0

package/tests/network-runtime/wait-for-message-script.test.ts

@@ -0,0 +1,288 @@
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { once } from "node:events";
+import { spawn } from "node:child_process";
+
+const SCRIPT_PATH = fileURLToPath(
+  new URL("../../../../.comms/wait-for-message.cjs", import.meta.url),
+);
+
+type ChildResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+};
+
+async function createTempAriaHome() {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "wait-for-message-"));
+  const ariaHome = path.join(tempRoot, ".aria");
+  await fs.mkdir(path.join(ariaHome, "run"), { recursive: true });
+  return { tempRoot, ariaHome };
+}
+
+async function spawnWatcher(args: string[], env: NodeJS.ProcessEnv): Promise<ChildResult> {
+  const child = spawn(process.execPath, [SCRIPT_PATH, ...args], {
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += String(chunk);
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += String(chunk);
+  });
+
+  const [code] = (await once(child, "close")) as [number | null];
+  return { code, stdout, stderr };
+}
+
+async function listenOnSocket(
+  handler: (
+    request: {
+      id: string;
+      method: string;
+      payload?: unknown;
+      auth?: unknown;
+    },
+    socket: net.Socket,
+  ) => void | Promise<void>,
+): Promise<{ socketPath: string; close(): Promise<void> }> {
+  const socketPath = path.join(
+    await fs.mkdtemp(path.join(os.tmpdir(), "wait-for-message-sock-")),
+    "runtime.sock",
+  );
+
+  const server = net.createServer((socket) => {
+    let buffer = "";
+    socket.setEncoding("utf8");
+    socket.on("data", async (chunk) => {
+      buffer += chunk;
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = buffer.slice(0, newlineIndex);
+      buffer = buffer.slice(newlineIndex + 1);
+      const request = JSON.parse(line) as {
+        id: string;
+        method: string;
+        payload?: unknown;
+        auth?: unknown;
+      };
+      await handler(request, socket);
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  return {
+    socketPath,
+    async close() {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+      await fs.rm(path.dirname(socketPath), { recursive: true, force: true });
+    },
+  };
+}
+
+const cleanupPaths: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    cleanupPaths.splice(0).map((target) => fs.rm(target, { recursive: true, force: true })),
+  );
+});
+
+describe(".comms/wait-for-message.cjs", () => {
+  it("subscribes to the direct client inbox and prints the first message as JSON", async () => {
+    const bridgeHome = await createTempAriaHome();
+    cleanupPaths.push(bridgeHome.tempRoot);
+
+    const requests: Array<{ method: string; payload?: unknown; auth?: unknown }> = [];
+    const server = await listenOnSocket(async (request, socket) => {
+      requests.push({ method: request.method, payload: request.payload, auth: request.auth });
+      socket.write(
+        `${JSON.stringify({
+          id: request.id,
+          ok: true,
+          payload: {
+            id: "msg-1",
+            senderNodeId: "node-alpha",
+            senderDisplayNameSnapshot: "cc0",
+            inboxAddress: { kind: "client", clientId: "client-self" },
+            type: "finding",
+            content: "[cc0] quest complete",
+            priority: 1,
+            createdAt: 1,
+          },
+        })}\n`,
+      );
+      socket.end();
+    });
+
+    await fs.writeFile(
+      path.join(bridgeHome.ariaHome, "run", "agent-bridge.json"),
+      JSON.stringify(
+        {
+          socketPath: server.socketPath,
+          clientId: "client-self",
+          clientAuthToken: "proof-self",
+        },
+        null,
+        2,
+      ),
+    );
+
+    try {
+      const result = await spawnWatcher(["2"], {
+        ...process.env,
+        HOME: bridgeHome.tempRoot,
+        ARIA_HOME: bridgeHome.ariaHome,
+      });
+
+      expect(result.code).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        id: "msg-1",
+        senderDisplayNameSnapshot: "cc0",
+        content: "[cc0] quest complete",
+      });
+      expect(requests).toEqual([
+        {
+          method: "subscribeDirectClientInbox",
+          payload: undefined,
+          auth: {
+            clientId: "client-self",
+            clientAuthToken: "proof-self",
+          },
+        },
+      ]);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("waits past non-matching senders when --from is provided", async () => {
+    const bridgeHome = await createTempAriaHome();
+    cleanupPaths.push(bridgeHome.tempRoot);
+
+    const server = await listenOnSocket(async (request, socket) => {
+      socket.write(
+        `${JSON.stringify({
+          id: request.id,
+          ok: true,
+          payload: {
+            id: "msg-1",
+            senderNodeId: "node-alpha",
+            senderDisplayNameSnapshot: "cc2",
+            inboxAddress: { kind: "client", clientId: "client-self" },
+            type: "finding",
+            content: "[cc2] not for you",
+            priority: 1,
+            createdAt: 1,
+          },
+        })}\n`,
+      );
+
+      setTimeout(() => {
+        socket.write(
+          `${JSON.stringify({
+            id: request.id,
+            ok: true,
+            payload: {
+              id: "msg-2",
+              senderNodeId: "node-bravo",
+              senderDisplayNameSnapshot: "cc1",
+              inboxAddress: { kind: "client", clientId: "client-self" },
+              type: "finding",
+              content: "[cc1] target message",
+              priority: 1,
+              createdAt: 2,
+            },
+          })}\n`,
+        );
+        socket.end();
+      }, 25);
+    });
+
+    await fs.writeFile(
+      path.join(bridgeHome.ariaHome, "run", "agent-bridge.json"),
+      JSON.stringify(
+        {
+          socketPath: server.socketPath,
+          clientId: "client-self",
+          clientAuthToken: "proof-self",
+        },
+        null,
+        2,
+      ),
+    );
+
+    try {
+      const result = await spawnWatcher(["2", "--from", "cc1"], {
+        ...process.env,
+        HOME: bridgeHome.tempRoot,
+        ARIA_HOME: bridgeHome.ariaHome,
+      });
+
+      expect(result.code).toBe(0);
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        id: "msg-2",
+        senderDisplayNameSnapshot: "cc1",
+        content: "[cc1] target message",
+      });
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("exits with an error when the timeout elapses before a message arrives", async () => {
+    const bridgeHome = await createTempAriaHome();
+    cleanupPaths.push(bridgeHome.tempRoot);
+
+    const server = await listenOnSocket(async () => {
+      // Hold the connection open so the watcher's timeout path fires.
+    });
+
+    await fs.writeFile(
+      path.join(bridgeHome.ariaHome, "run", "agent-bridge.json"),
+      JSON.stringify(
+        {
+          socketPath: server.socketPath,
+          clientId: "client-self",
+          clientAuthToken: "proof-self",
+        },
+        null,
+        2,
+      ),
+    );
+
+    try {
+      const result = await spawnWatcher(["1"], {
+        ...process.env,
+        HOME: bridgeHome.tempRoot,
+        ARIA_HOME: bridgeHome.ariaHome,
+      });
+
+      expect(result.code).toBe(1);
+      expect(result.stdout).toBe("");
+      expect(result.stderr).toContain("Timed out waiting for a direct client inbox message");
+    } finally {
+      await server.close();
+    }
+  });
+});

package/tests/parallel.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { Tool, ToolContext, ToolResult } from '../src/types.js';
+
+// Helper to partition tool calls
+function partitionToolCalls(
+  toolCalls: Array<{ name: string }>,
+  getIsReadOnly: (name: string) => boolean
+): { readOnly: Array<{ name: string }>; mutating: Array<{ name: string }> } {
+  const readOnly: Array<{ name: string }> = [];
+  const mutating: Array<{ name: string }> = [];
+
+  for (const tc of toolCalls) {
+    if (getIsReadOnly(tc.name)) {
+      readOnly.push(tc);
+    } else {
+      mutating.push(tc);
+    }
+  }
+
+  return { readOnly, mutating };
+}
+
+describe('Tool Execution Parallelization', () => {
+  describe('partitionToolCalls', () => {
+    it('should partition read-only and mutating tools', () => {
+      const toolCalls = [
+        { name: 'read_file' },
+        { name: 'write_file' },
+        { name: 'grep' },
+        { name: 'bash' },
+      ];
+
+      const isReadOnly: Record<string, boolean> = {
+        read_file: true,
+        write_file: false,
+        grep: true,
+        bash: false,
+      };
+
+      const result = partitionToolCalls(toolCalls, (name) => isReadOnly[name] ?? false);
+
+      expect(result.readOnly).toHaveLength(2);
+      expect(result.readOnly.map(t => t.name)).toEqual(['read_file', 'grep']);
+      expect(result.mutating).toHaveLength(2);
+      expect(result.mutating.map(t => t.name)).toEqual(['write_file', 'bash']);
+    });
+
+    it('should handle all read-only tools', () => {
+      const toolCalls = [{ name: 'read_file' }, { name: 'grep' }];
+      const result = partitionToolCalls(toolCalls, () => true);
+
+      expect(result.readOnly).toHaveLength(2);
+      expect(result.mutating).toHaveLength(0);
+    });
+
+    it('should handle all mutating tools', () => {
+      const toolCalls = [{ name: 'write_file' }, { name: 'bash' }];
+      const result = partitionToolCalls(toolCalls, () => false);
+
+      expect(result.readOnly).toHaveLength(0);
+      expect(result.mutating).toHaveLength(2);
+    });
+
+    it('should default unknown tools to mutating', () => {
+      const toolCalls = [{ name: 'unknown_tool' }];
+      const result = partitionToolCalls(toolCalls, () => false);
+
+      expect(result.mutating).toHaveLength(1);
+    });
+  });
+});

package/tests/policy.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from "vitest";
+import { expandGroups, isToolAllowed, mergePolicies, TOOL_GROUPS } from "../src/policy.js";
+import { getCoreToolsByCategory, getCoreTools } from "../src/definitions/core.js";
+
+describe("expandGroups", () => {
+  it("resolves group names to tool arrays", () => {
+    const result = expandGroups(["group:memory"]);
+    expect(result).toEqual(
+      new Set([
+        "remember",
+        "recall",
+        "forget",
+        "recall_knowledge",
+        "reflect",
+        "search",
+        "learn",
+        "session_history",
+      ]),
+    );
+  });
+
+  it("passes through individual tool names", () => {
+    const result = expandGroups(["bash", "recall"]);
+    expect(result).toEqual(new Set(["bash", "recall"]));
+  });
+
+  it("handles mixed groups and names", () => {
+    const result = expandGroups(["group:shell", "recall"]);
+    expect(result).toEqual(
+      new Set([
+        "bash",
+        "exec",
+        "spawn",
+        "kill",
+        "list_processes",
+        "wait_process",
+        "write_stdin",
+        "process",
+        "recall",
+      ]),
+    );
+  });
+
+  it("shell group includes process observability tools", () => {
+    expect(TOOL_GROUPS["group:shell"]).toEqual(
+      expect.arrayContaining(["list_processes", "wait_process", "write_stdin"]),
+    );
+  });
+
+  it("ignores unknown groups", () => {
+    const result = expandGroups(["group:nonexistent", "bash"]);
+    expect(result).toEqual(new Set(["bash"]));
+  });
+});
+
+describe("isToolAllowed", () => {
+  it("allow-all when allow is empty or absent", () => {
+    expect(isToolAllowed("bash", {})).toBe(true);
+    expect(isToolAllowed("bash", { allow: [] })).toBe(true);
+  });
+
+  it("deny-all when allow is empty and restrictAllow is true", () => {
+    const denyAll = { allow: [], restrictAllow: true };
+    expect(isToolAllowed("bash", denyAll)).toBe(false);
+    expect(isToolAllowed("recall", denyAll)).toBe(false);
+  });
+
+  it("allow whitelist restricts access", () => {
+    expect(isToolAllowed("bash", { allow: ["recall", "remember"] })).toBe(false);
+    expect(isToolAllowed("recall", { allow: ["recall", "remember"] })).toBe(true);
+  });
+
+  it("deny overrides allow", () => {
+    expect(isToolAllowed("bash", { allow: ["group:shell"], deny: ["bash"] })).toBe(false);
+  });
+
+  it("group expansion in allow", () => {
+    expect(isToolAllowed("recall", { allow: ["group:memory"] })).toBe(true);
+    expect(isToolAllowed("bash", { allow: ["group:memory"] })).toBe(false);
+    expect(isToolAllowed("write_stdin", { allow: ["group:shell"] })).toBe(true);
+  });
+
+  it("group expansion in deny", () => {
+    expect(isToolAllowed("bash", { deny: ["group:shell"] })).toBe(false);
+    expect(isToolAllowed("write_stdin", { deny: ["group:shell"] })).toBe(false);
+    expect(isToolAllowed("recall", { deny: ["group:shell"] })).toBe(true);
+  });
+});
+
+describe("isToolAllowed — case insensitive (H-2 fix)", () => {
+  it("matches tool names case-insensitively", () => {
+    expect(isToolAllowed("Bash", { deny: ["bash"] })).toBe(false);
+    expect(isToolAllowed("BASH", { deny: ["bash"] })).toBe(false);
+    expect(isToolAllowed("bash", { deny: ["BASH"] })).toBe(false);
+  });
+
+  it("matches allow list case-insensitively", () => {
+    expect(isToolAllowed("Recall", { allow: ["recall"] })).toBe(true);
+    expect(isToolAllowed("recall", { allow: ["Recall"] })).toBe(true);
+  });
+
+  it("matches group expansion case-insensitively", () => {
+    // "BASH".toLowerCase() = "bash", which is in group:shell → allowed
+    expect(isToolAllowed("BASH", { allow: ["group:shell"] })).toBe(true);
+    // "Bash".toLowerCase() = "bash", which is in group:shell → denied
+    expect(isToolAllowed("Bash", { deny: ["group:shell"] })).toBe(false);
+  });
+});
+
+describe("mergePolicies", () => {
+  it("intersection: both allow lists", () => {
+    const merged = mergePolicies({ allow: ["bash", "recall"] }, { allow: ["recall", "remember"] });
+    expect(isToolAllowed("recall", merged)).toBe(true);
+    expect(isToolAllowed("bash", merged)).toBe(false);
+  });
+
+  it("intersection: disjoint allow lists deny all", () => {
+    const merged = mergePolicies({ allow: ["bash"] }, { allow: ["read_file"] });
+    expect(merged.restrictAllow).toBe(true);
+    expect(merged.allow).toEqual([]);
+    expect(isToolAllowed("bash", merged)).toBe(false);
+    expect(isToolAllowed("read_file", merged)).toBe(false);
+    expect(isToolAllowed("remember", merged)).toBe(false);
+  });
+
+  it("union of deny", () => {
+    const merged = mergePolicies({ deny: ["bash"] }, { deny: ["recall"] });
+    expect(isToolAllowed("bash", merged)).toBe(false);
+    expect(isToolAllowed("recall", merged)).toBe(false);
+  });
+
+  it("empty policy backward compat", () => {
+    const merged = mergePolicies({}, {});
+    expect(isToolAllowed("anything", merged)).toBe(true);
+  });
+});
+
+describe("TOOL_GROUPS alignment", () => {
+  const DYNAMIC_META_TOOLS = new Set<string>();
+  const sortNames = (names: string[]): string[] => [...names].sort();
+
+  it("contains only known core tools or approved dynamic tools", () => {
+    const knownTools = new Set(getCoreTools().map((tool) => tool.name));
+
+    for (const members of Object.values(TOOL_GROUPS)) {
+      for (const member of members) {
+        const isKnownCoreTool = knownTools.has(member);
+        const isApprovedDynamicTool = DYNAMIC_META_TOOLS.has(member);
+        expect(isKnownCoreTool || isApprovedDynamicTool).toBe(true);
+      }
+    }
+  });
+
+  it("tracks category memberships for core groups", () => {
+    // group:memory is a superset of memory-category tools (also includes search, learn from meta)
+    const memoryGroupTools = new Set(TOOL_GROUPS["group:memory"] ?? []);
+    for (const tool of getCoreToolsByCategory("memory")) {
+      expect(memoryGroupTools.has(tool.name)).toBe(true);
+    }
+
+    expect(sortNames(TOOL_GROUPS["group:web"] ?? [])).toEqual(
+      sortNames(getCoreToolsByCategory("web").map((tool) => tool.name)),
+    );
+
+    expect(sortNames(TOOL_GROUPS["group:filesystem"] ?? [])).toEqual(
+      sortNames(getCoreToolsByCategory("filesystem").map((tool) => tool.name)),
+    );
+
+    expect(sortNames(TOOL_GROUPS["group:shell"] ?? [])).toEqual(
+      sortNames(getCoreToolsByCategory("shell").map((tool) => tool.name)),
+    );
+
+    expect(sortNames(TOOL_GROUPS["group:arion"] ?? [])).toEqual(
+      sortNames(getCoreToolsByCategory("arion").map((tool) => tool.name)),
+    );
+
+    expect(sortNames(TOOL_GROUPS["group:meta"] ?? [])).toEqual(
+      sortNames([
+        ...getCoreToolsByCategory("meta").map((tool) => tool.name),
+        ...DYNAMIC_META_TOOLS,
+      ]),
+    );
+  });
+});

package/tests/print-default-test-lane.ts

@@ -0,0 +1,14 @@
+import { getToolsTestLaneFiles, loadToolsTestLaneManifest } from "./test-lane-manifest.js";
+
+const manifest = loadToolsTestLaneManifest();
+
+console.log(
+  JSON.stringify(
+    {
+      defaultLane: manifest.defaultLane,
+      files: getToolsTestLaneFiles(manifest.defaultLane),
+    },
+    null,
+    2,
+  ),
+);

package/tests/print-test-lane-manifest.ts

@@ -0,0 +1,22 @@
+import { loadToolsTestLaneManifest } from "./test-lane-manifest.js";
+
+const manifest = loadToolsTestLaneManifest();
+const counts = Object.fromEntries(
+  Object.entries(manifest.lanes).map(([lane, files]) => [lane, files.length]),
+);
+
+console.log(
+  JSON.stringify(
+    {
+      defaultLane: manifest.defaultLane,
+      setupFiles: manifest.setupFiles,
+      maxWorkers: manifest.maxWorkers,
+      pool: manifest.pool,
+      fileParallelism: manifest.fileParallelism,
+      counts,
+      unclassified: manifest.unclassified,
+    },
+    null,
+    2,
+  ),
+);