@aria-cli/tools 1.0.0

package/tests/definitions/tool-inventory.test.ts

@@ -0,0 +1,207 @@
+/**
+ * @aria/tools - Tool inventory tests
+ *
+ * Validates the complete tool inventory: counts, names, categories,
+ * confirmation requirements, and loading tiers.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  CORE_TOOL_DEFINITIONS,
+  MEMORY_TOOL_DEFINITIONS,
+  WEB_TOOL_DEFINITIONS,
+  FILESYSTEM_TOOL_DEFINITIONS,
+  SHELL_TOOL_DEFINITIONS,
+  ARION_TOOL_DEFINITIONS,
+  DELEGATION_TOOL_DEFINITIONS,
+  META_TOOL_DEFINITIONS,
+} from "../../src/definitions/core.js";
+
+describe("Tool Inventory", () => {
+  describe("total tool count", () => {
+    it("should have exactly 64 core tools", () => {
+      expect(CORE_TOOL_DEFINITIONS).toHaveLength(64);
+    });
+  });
+
+  describe("tool names", () => {
+    const toolNames = () => CORE_TOOL_DEFINITIONS.map((t) => t.name);
+
+    it("should include new tools from refactoring", () => {
+      const names = toolNames();
+      expect(names).toContain("ask_user");
+      expect(names).toContain("quest_update");
+      expect(names).toContain("quest_list");
+      expect(names).toContain("apply_patch");
+      expect(names).toContain("write_stdin");
+      expect(names).toContain("ls");
+    });
+
+    it("should include OpenClaw-forked tools", () => {
+      const names = toolNames();
+      expect(names).toContain("browser");
+      expect(names).toContain("process");
+    });
+
+    it("should NOT include removed/consolidated tools", () => {
+      const names = toolNames();
+      expect(names).not.toContain("mkdir");
+      expect(names).not.toContain("cp");
+      expect(names).not.toContain("mv");
+      expect(names).not.toContain("rm");
+      expect(names).not.toContain("download");
+    });
+
+    it("should have unique tool names (no duplicates)", () => {
+      const names = toolNames();
+      expect(new Set(names).size).toBe(names.length);
+    });
+  });
+
+  describe("requiresConfirmation", () => {
+    const findTool = (name: string) => CORE_TOOL_DEFINITIONS.find((t) => t.name === name);
+
+    it("forget requires confirmation", () => {
+      expect(findTool("forget")?.requiresConfirmation).toBe(true);
+    });
+
+    it("kill requires confirmation", () => {
+      expect(findTool("kill")?.requiresConfirmation).toBe(true);
+    });
+
+    it("apply_patch requires confirmation", () => {
+      expect(findTool("apply_patch")?.requiresConfirmation).toBe(true);
+    });
+
+    it("bash requires confirmation", () => {
+      expect(findTool("bash")?.requiresConfirmation).toBe(true);
+    });
+
+    it("hatch_arion requires confirmation", () => {
+      expect(findTool("hatch_arion")?.requiresConfirmation).toBe(true);
+    });
+
+    it("retire_arion requires confirmation", () => {
+      expect(findTool("retire_arion")?.requiresConfirmation).toBe(true);
+    });
+
+    it("read-only tools do not require confirmation", () => {
+      const readOnlyTools = CORE_TOOL_DEFINITIONS.filter((t) => t.isReadOnly);
+      for (const tool of readOnlyTools) {
+        expect(
+          tool.requiresConfirmation,
+          `Read-only tool "${tool.name}" should not require confirmation`,
+        ).toBeFalsy();
+      }
+    });
+  });
+
+  describe("loadingTier", () => {
+    it("every tool has a loadingTier defined", () => {
+      for (const tool of CORE_TOOL_DEFINITIONS) {
+        expect(
+          tool.loadingTier,
+          `Tool "${tool.name}" should have loadingTier defined`,
+        ).toBeDefined();
+      }
+    });
+
+    it("all core tools have loadingTier 'always' or 'deferred'", () => {
+      const ALLOWED_DEFERRED = new Set(["session_history", "self_diagnose"]);
+      for (const tool of CORE_TOOL_DEFINITIONS) {
+        if (ALLOWED_DEFERRED.has(tool.name)) {
+          expect(tool.loadingTier, `Tool "${tool.name}" should have loadingTier "deferred"`).toBe(
+            "deferred",
+          );
+        } else {
+          expect(tool.loadingTier, `Tool "${tool.name}" should have loadingTier "always"`).toBe(
+            "always",
+          );
+        }
+      }
+    });
+  });
+
+  describe("category counts", () => {
+    const countByCategory = (category: string) =>
+      CORE_TOOL_DEFINITIONS.filter((t) => t.category === category).length;
+
+    it("filesystem: 7 tools", () => {
+      expect(countByCategory("filesystem")).toBe(7);
+    });
+
+    it("shell: 8 tools", () => {
+      expect(countByCategory("shell")).toBe(8);
+    });
+
+    it("web: 4 tools", () => {
+      expect(countByCategory("web")).toBe(4);
+    });
+
+    it("memory: 6 tools", () => {
+      expect(countByCategory("memory")).toBe(6);
+    });
+
+    it("arion: 8 tools (4 lifecycle + delegate_arion + network + same-home client directory + deploy)", () => {
+      expect(countByCategory("arion")).toBe(8);
+    });
+
+    it("meta: 17 tools (12 META_TOOL_DEFINITIONS + delegation tools)", () => {
+      expect(countByCategory("meta")).toBe(17);
+    });
+
+    it("messaging: 14 tools", () => {
+      expect(countByCategory("messaging")).toBe(14);
+    });
+
+    it("category counts sum to total", () => {
+      const total =
+        countByCategory("filesystem") +
+        countByCategory("shell") +
+        countByCategory("web") +
+        countByCategory("memory") +
+        countByCategory("arion") +
+        countByCategory("meta") +
+        countByCategory("messaging");
+      expect(total).toBe(CORE_TOOL_DEFINITIONS.length);
+    });
+  });
+
+  describe("category definition arrays", () => {
+    it("MEMORY_TOOL_DEFINITIONS has 5 tools", () => {
+      expect(MEMORY_TOOL_DEFINITIONS).toHaveLength(5);
+    });
+
+    it("WEB_TOOL_DEFINITIONS has 3 tools", () => {
+      expect(WEB_TOOL_DEFINITIONS).toHaveLength(3);
+    });
+
+    it("FILESYSTEM_TOOL_DEFINITIONS has 7 tools", () => {
+      expect(FILESYSTEM_TOOL_DEFINITIONS).toHaveLength(7);
+    });
+
+    it("SHELL_TOOL_DEFINITIONS has 7 tools", () => {
+      expect(SHELL_TOOL_DEFINITIONS).toHaveLength(7);
+    });
+
+    it("ARION_TOOL_DEFINITIONS has 4 tools", () => {
+      expect(ARION_TOOL_DEFINITIONS).toHaveLength(4);
+    });
+
+    it("DELEGATION_TOOL_DEFINITIONS has 7 tools", () => {
+      expect(DELEGATION_TOOL_DEFINITIONS).toHaveLength(7);
+    });
+
+    it("META_TOOL_DEFINITIONS has 12 tools", () => {
+      expect(META_TOOL_DEFINITIONS).toHaveLength(12);
+    });
+  });
+
+  describe("every tool has an execute function", () => {
+    it("all tools have execute as a function", () => {
+      for (const tool of CORE_TOOL_DEFINITIONS) {
+        expect(typeof tool.execute).toBe("function");
+      }
+    });
+  });
+});

package/tests/e2e/delegation-quest-orchestration.e2e.test.ts

@@ -0,0 +1,433 @@
+import { describe, expect, it } from "vitest";
+import { createToolRegistry } from "../../src/index.js";
+import type {
+  DelegationEntryRef,
+  DelegationExecutorRef,
+  DelegationRegistryRef,
+  QuestStoreItem,
+  QuestStoreRef,
+  QuestStoreStatus,
+  Tool,
+  ToolContext,
+} from "../../src/types.js";
+
+interface InternalDelegationEntry extends DelegationEntryRef {
+  waiters: Array<(entry: DelegationEntryRef) => void>;
+  resolve: (result: string) => void;
+  reject: (error: Error) => void;
+  abortController: AbortController;
+}
+
+class ControlledDelegationHarness implements DelegationExecutorRef, DelegationRegistryRef {
+  private readonly entries = new Map<string, InternalDelegationEntry>();
+  private sequence = 0;
+
+  get(id: string): DelegationEntryRef | undefined {
+    const entry = this.entries.get(id);
+    if (!entry) return undefined;
+    return this.toPublicEntry(entry);
+  }
+
+  list(): DelegationEntryRef[] {
+    return Array.from(this.entries.values(), (entry) => this.toPublicEntry(entry));
+  }
+
+  async await(id: string, timeoutMs = 30_000): Promise<DelegationEntryRef> {
+    const entry = this.entries.get(id);
+    if (!entry) {
+      throw new Error(`Delegation not found: ${id}`);
+    }
+
+    if (entry.status !== "running") {
+      return this.toPublicEntry(entry);
+    }
+
+    return new Promise<DelegationEntryRef>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        const idx = entry.waiters.indexOf(waiter);
+        if (idx !== -1) entry.waiters.splice(idx, 1);
+        reject(new Error("Delegation timed out"));
+      }, timeoutMs);
+
+      const waiter = (settled: DelegationEntryRef): void => {
+        clearTimeout(timeoutId);
+        resolve(settled);
+      };
+
+      entry.waiters.push(waiter);
+    });
+  }
+
+  async delegateToArion(
+    arionName: string,
+    task: string,
+    _maxTurns?: number,
+    _tier?: string,
+  ): Promise<string> {
+    return this.createEntry("arion", task, arionName);
+  }
+
+  async spawnWorker(
+    task: string,
+    _tools?: string[],
+    _maxTurns?: number,
+    _tier?: string,
+  ): Promise<string> {
+    return this.createEntry("worker", task);
+  }
+
+  async spawnCliAgent(params: {
+    task: string;
+    driver: string;
+    workspace?: "cwd" | "tempdir" | "worktree";
+    model?: string;
+    resume?: string;
+    timeout?: number;
+  }): Promise<string> {
+    return this.createEntry("cli_agent", params.task, undefined, { driver: params.driver });
+  }
+
+  complete(id: string, result: string): void {
+    const entry = this.requireEntry(id);
+    entry.resolve(result);
+  }
+
+  fail(id: string, error: string): void {
+    const entry = this.requireEntry(id);
+    entry.reject(new Error(error));
+  }
+
+  abort(id: string, error = "delegation aborted"): boolean {
+    const entry = this.entries.get(id);
+    if (!entry || entry.status !== "running") return false;
+    entry.abortController.abort();
+    entry.status = "aborted";
+    entry.error = error;
+    this.notify(entry);
+    return true;
+  }
+
+  private createEntry(
+    type: DelegationEntryRef["type"],
+    task: string,
+    arionName?: string,
+    metadata?: DelegationEntryRef["metadata"],
+  ): string {
+    const id = `quest_e2e${String(++this.sequence).padStart(6, "0")}`;
+    const abortController = new AbortController();
+    let resolve!: (result: string) => void;
+    let reject!: (error: Error) => void;
+    const promise = new Promise<string>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+
+    const entry: InternalDelegationEntry = {
+      id,
+      type,
+      arionName,
+      task,
+      status: "running",
+      metadata,
+      waiters: [],
+      resolve,
+      reject,
+      abortController,
+    };
+    this.entries.set(id, entry);
+
+    promise.then(
+      (result) => {
+        if (entry.status !== "running") return;
+        entry.status = "completed";
+        entry.result = result;
+        this.notify(entry);
+      },
+      (error: Error) => {
+        if (entry.status !== "running") return;
+        entry.status = "failed";
+        entry.error = error.message;
+        this.notify(entry);
+      },
+    );
+
+    return id;
+  }
+
+  private requireEntry(id: string): InternalDelegationEntry {
+    const entry = this.entries.get(id);
+    if (!entry) {
+      throw new Error(`Delegation not found: ${id}`);
+    }
+    return entry;
+  }
+
+  private notify(entry: InternalDelegationEntry): void {
+    const publicEntry = this.toPublicEntry(entry);
+    const waiters = entry.waiters.splice(0);
+    for (const waiter of waiters) {
+      waiter(publicEntry);
+    }
+  }
+
+  private toPublicEntry(entry: InternalDelegationEntry): DelegationEntryRef {
+    return {
+      id: entry.id,
+      type: entry.type,
+      arionName: entry.arionName,
+      task: entry.task,
+      status: entry.status,
+      result: entry.result,
+      error: entry.error,
+      metadata: entry.metadata,
+    };
+  }
+}
+
+class InMemoryQuestStore implements QuestStoreRef {
+  private readonly quests = new Map<string, QuestStoreItem>();
+
+  createQuest(input: {
+    id: string;
+    title: string;
+    description?: string;
+    priority?: number;
+    status?: QuestStoreStatus;
+    progress?: string;
+    blockedBy?: string;
+  }): QuestStoreItem {
+    const now = Date.now();
+    const quest: QuestStoreItem = {
+      id: input.id,
+      title: input.title,
+      description: input.description,
+      priority: input.priority ?? 2,
+      status: input.status ?? "open",
+      progress: input.progress ?? "",
+      blockedBy: input.blockedBy,
+      attempts: 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.quests.set(quest.id, quest);
+    return quest;
+  }
+
+  updateQuest(
+    id: string,
+    updates: Partial<{
+      title: string;
+      description: string;
+      priority: number;
+      status: QuestStoreStatus;
+      progress: string;
+      blockedBy: string;
+    }>,
+  ): QuestStoreItem {
+    const existing = this.quests.get(id);
+    if (!existing) {
+      throw new Error(`Quest not found: ${id}`);
+    }
+
+    const updated: QuestStoreItem = { ...existing, updatedAt: Date.now() };
+    if (updates.title !== undefined) updated.title = updates.title;
+    if (updates.description !== undefined) updated.description = updates.description;
+    if (updates.priority !== undefined) updated.priority = updates.priority;
+    if (updates.status !== undefined) updated.status = updates.status;
+    if (updates.progress !== undefined) updated.progress = updates.progress;
+    if (updates.blockedBy !== undefined) updated.blockedBy = updates.blockedBy;
+    this.quests.set(id, updated);
+    return updated;
+  }
+
+  getQuest(id: string): QuestStoreItem | null {
+    return this.quests.get(id) ?? null;
+  }
+
+  listQuests(filter?: { status?: string }): QuestStoreItem[] {
+    const all = Array.from(this.quests.values());
+    if (filter?.status) {
+      return all.filter((quest) => quest.status === filter.status);
+    }
+    return all;
+  }
+}
+
+function getTool(registry: ReturnType<typeof createToolRegistry>, name: string): Tool {
+  const tool = registry.get(name);
+  if (!tool) throw new Error(`Missing tool in registry: ${name}`);
+  return tool;
+}
+
+function createE2EContext(
+  questStore: QuestStoreRef,
+  delegationHarness: ControlledDelegationHarness,
+): ToolContext {
+  return {
+    workingDir: process.cwd(),
+    env: {},
+    confirm: async () => true,
+    questStore,
+    delegationExecutor: delegationHarness,
+    delegationRegistry: delegationHarness,
+  };
+}
+
+describe("Delegation + quest orchestration (E2E)", () => {
+  it("completes a delegated worker and closes the quest with the delegated result", async () => {
+    const registry = createToolRegistry();
+    const questStore = new InMemoryQuestStore();
+    const delegationHarness = new ControlledDelegationHarness();
+    const ctx = createE2EContext(questStore, delegationHarness);
+
+    const questUpdate = getTool(registry, "quest_update");
+    const questList = getTool(registry, "quest_list");
+    const spawnWorker = getTool(registry, "spawn_worker");
+    const checkDelegation = getTool(registry, "check_delegation");
+
+    const createQuestResult = await questUpdate.execute(
+      {
+        quests: [{ title: "Implement orchestration", status: "active" }],
+      },
+      ctx,
+    );
+    expect(createQuestResult.success).toBe(true);
+    const questId = (createQuestResult.data as { quests: Array<{ id: string }> }).quests[0]!.id;
+
+    const spawnResult = await spawnWorker.execute(
+      {
+        task: "Collect integration evidence",
+        maxTurns: 4,
+        tier: "fast",
+      },
+      ctx,
+    );
+    expect(spawnResult.success).toBe(true);
+    const delegationId = (spawnResult.data as { id: string }).id;
+
+    const waitResultPromise = checkDelegation.execute(
+      { id: delegationId, wait: true, timeout: 5_000 },
+      ctx,
+    );
+    delegationHarness.complete(delegationId, "Worker finished with validated report");
+    const waitResult = await waitResultPromise;
+
+    expect(waitResult.success).toBe(true);
+    const waitData = waitResult.data as { status: string; result?: string };
+    expect(waitData.status).toBe("completed");
+    expect(waitData.result).toContain("validated report");
+
+    const closeQuestResult = await questUpdate.execute(
+      {
+        quests: [
+          {
+            id: questId,
+            status: "done",
+            notes: waitData.result,
+          },
+        ],
+      },
+      ctx,
+    );
+    expect(closeQuestResult.success).toBe(true);
+
+    const doneList = await questList.execute({ status: "done" }, ctx);
+    expect(doneList.success).toBe(true);
+    const quests = (doneList.data as { quests: Array<{ id: string; notes: string }> }).quests;
+    const quest = quests.find((item) => item.id === questId);
+    expect(quest).toBeDefined();
+    expect(quest!.notes).toContain("validated report");
+  });
+
+  it("propagates delegated worker failures into quest status and notes", async () => {
+    const registry = createToolRegistry();
+    const questStore = new InMemoryQuestStore();
+    const delegationHarness = new ControlledDelegationHarness();
+    const ctx = createE2EContext(questStore, delegationHarness);
+
+    const questUpdate = getTool(registry, "quest_update");
+    const questList = getTool(registry, "quest_list");
+    const spawnWorker = getTool(registry, "spawn_worker");
+    const checkDelegation = getTool(registry, "check_delegation");
+
+    const createQuestResult = await questUpdate.execute(
+      {
+        quests: [{ title: "Run risky flow", status: "active" }],
+      },
+      ctx,
+    );
+    expect(createQuestResult.success).toBe(true);
+    const questId = (createQuestResult.data as { quests: Array<{ id: string }> }).quests[0]!.id;
+
+    const spawnResult = await spawnWorker.execute({ task: "Trigger failure path" }, ctx);
+    expect(spawnResult.success).toBe(true);
+    const delegationId = (spawnResult.data as { id: string }).id;
+
+    const waitResultPromise = checkDelegation.execute(
+      { id: delegationId, wait: true, timeout: 5_000 },
+      ctx,
+    );
+    delegationHarness.fail(delegationId, "synthetic worker failure");
+    const waitResult = await waitResultPromise;
+
+    expect(waitResult.success).toBe(false);
+    const waitData = waitResult.data as { status: string; error?: string };
+    expect(waitData.status).toBe("failed");
+    expect(waitData.error).toContain("synthetic worker failure");
+
+    const blockQuestResult = await questUpdate.execute(
+      {
+        quests: [
+          {
+            id: questId,
+            status: "blocked",
+            notes: waitData.error,
+          },
+        ],
+      },
+      ctx,
+    );
+    expect(blockQuestResult.success).toBe(true);
+
+    const blockedList = await questList.execute({ status: "blocked" }, ctx);
+    expect(blockedList.success).toBe(true);
+    const quests = (blockedList.data as { quests: Array<{ id: string; notes: string }> }).quests;
+    const quest = quests.find((item) => item.id === questId);
+    expect(quest).toBeDefined();
+    expect(quest!.notes).toContain("synthetic worker failure");
+  });
+
+  it("surfaces aborted delegation state when waiting on delegate_arion", async () => {
+    const registry = createToolRegistry();
+    const questStore = new InMemoryQuestStore();
+    const delegationHarness = new ControlledDelegationHarness();
+    const ctx = createE2EContext(questStore, delegationHarness);
+
+    const delegateArion = getTool(registry, "delegate_arion");
+    const checkDelegation = getTool(registry, "check_delegation");
+
+    const delegateResult = await delegateArion.execute(
+      {
+        arion: "Nova",
+        task: "Handle abort path",
+        maxTurns: 2,
+      },
+      ctx,
+    );
+    expect(delegateResult.success).toBe(true);
+    const delegationId = (delegateResult.data as { id: string }).id;
+
+    const waitResultPromise = checkDelegation.execute(
+      { id: delegationId, wait: true, timeout: 5_000 },
+      ctx,
+    );
+    delegationHarness.abort(delegationId, "parent session aborted");
+    const waitResult = await waitResultPromise;
+
+    expect(waitResult.success).toBe(false);
+    const waitData = waitResult.data as { status: string; error?: string };
+    expect(waitData.status).toBe("aborted");
+    expect(waitData.error).toContain("parent session aborted");
+    expect(waitResult.message).toContain("parent session aborted");
+  });
+});