@aria-cli/tools 1.0.0

package/src/definitions/core.ts

@@ -0,0 +1,106 @@
+/**
+ * Core tool definitions for ARIA
+ * Core tools across 10 definition groups:
+ * memory (5), web (3+1), filesystem (8), shell (7+1), arion (4), delegation (3), messaging (4+2), network (2), deploy (1), meta (11)
+ *
+ * Individual category definitions are in their respective files.
+ * This module assembles them into the unified CORE_TOOL_DEFINITIONS array.
+ * browser and process are forked from OpenClaw (MIT) and added directly here.
+ */
+
+import type { Tool, ToolCategory, RiskLevel } from "../types.js";
+import { MEMORY_TOOL_DEFINITIONS } from "./memory.js";
+import { WEB_TOOL_DEFINITIONS } from "./web.js";
+import { FILESYSTEM_TOOL_DEFINITIONS } from "./filesystem.js";
+import { SHELL_TOOL_DEFINITIONS } from "./shell.js";
+import { ARION_TOOL_DEFINITIONS } from "./arion.js";
+import { DELEGATION_TOOL_DEFINITIONS } from "./delegation.js";
+import { MESSAGING_TOOL_DEFINITIONS } from "./messaging.js";
+import { SLACK_TOOL_DEFINITIONS } from "./slack.js";
+import { OUTLOOK_TOOL_DEFINITIONS } from "./outlook.js";
+import { QUIP_TOOL_DEFINITIONS } from "./quip.js";
+import { NETWORK_TOOL_DEFINITIONS } from "./network.js";
+import { DEPLOY_TOOL_DEFINITIONS } from "./deploy.js";
+import { META_TOOL_DEFINITIONS } from "./meta.js";
+import { SESSION_HISTORY_TOOL_DEFINITIONS } from "./session-history.js";
+
+// OpenClaw forks (MIT) — Playwright browser automation and background process management
+import { browserTool } from "./browser/index.js";
+import { processTool } from "./process/index.js";
+
+// Re-export category arrays for direct access
+export { MEMORY_TOOL_DEFINITIONS } from "./memory.js";
+export { WEB_TOOL_DEFINITIONS } from "./web.js";
+export { FILESYSTEM_TOOL_DEFINITIONS } from "./filesystem.js";
+export { SHELL_TOOL_DEFINITIONS } from "./shell.js";
+export { ARION_TOOL_DEFINITIONS } from "./arion.js";
+export { DELEGATION_TOOL_DEFINITIONS } from "./delegation.js";
+export { MESSAGING_TOOL_DEFINITIONS } from "./messaging.js";
+export { SLACK_TOOL_DEFINITIONS } from "./slack.js";
+export { OUTLOOK_TOOL_DEFINITIONS } from "./outlook.js";
+export { QUIP_TOOL_DEFINITIONS } from "./quip.js";
+export { NETWORK_TOOL_DEFINITIONS } from "./network.js";
+export { DEPLOY_TOOL_DEFINITIONS } from "./deploy.js";
+export { META_TOOL_DEFINITIONS } from "./meta.js";
+export { SESSION_HISTORY_TOOL_DEFINITIONS } from "./session-history.js";
+
+/**
+ * All core tool definitions
+ */
+export const CORE_TOOL_DEFINITIONS: Tool[] = [
+  // Memory tools (5)
+  ...MEMORY_TOOL_DEFINITIONS,
+  // Web tools (3 + browser)
+  ...WEB_TOOL_DEFINITIONS,
+  browserTool,
+  // Filesystem tools (8, includes forked apply_patch with fuzzy matching)
+  ...FILESYSTEM_TOOL_DEFINITIONS,
+  // Shell tools (7 + process)
+  ...SHELL_TOOL_DEFINITIONS,
+  processTool,
+  // Arion tools (4)
+  ...ARION_TOOL_DEFINITIONS,
+  // Delegation tools (7): delegate_arion, spawn_worker, check_delegation, pause_delegation, resume_delegation, delegate_remote, quest_report
+  ...DELEGATION_TOOL_DEFINITIONS,
+  // Messaging tools (6): send_message, check_messages, search_messages, get_thread, check_slack_messages, send_slack_message
+  ...MESSAGING_TOOL_DEFINITIONS,
+  ...SLACK_TOOL_DEFINITIONS,
+  ...OUTLOOK_TOOL_DEFINITIONS,
+  ...QUIP_TOOL_DEFINITIONS,
+  // Network tools (2): manage_network + list_clients
+  ...NETWORK_TOOL_DEFINITIONS,
+  // Deploy tools (1): deploy (SSH remote deployment)
+  ...DEPLOY_TOOL_DEFINITIONS,
+  // Meta tools (10): ask_user/quest plus learning/meta capability tools
+  ...META_TOOL_DEFINITIONS,
+  // Session History tools (1): session_history (list/search/get/current/stats/delete/set_title)
+  ...SESSION_HISTORY_TOOL_DEFINITIONS,
+];
+
+/**
+ * Get all core tools
+ */
+export function getCoreTools(): Tool[] {
+  return CORE_TOOL_DEFINITIONS;
+}
+
+/**
+ * Get a core tool by name
+ */
+export function getCoreTool(name: string): Tool | undefined {
+  return CORE_TOOL_DEFINITIONS.find((tool) => tool.name === name);
+}
+
+/**
+ * Get all tools in a category
+ */
+export function getCoreToolsByCategory(category: ToolCategory): Tool[] {
+  return CORE_TOOL_DEFINITIONS.filter((tool) => tool.category === category);
+}
+
+/**
+ * Get all tools by risk level
+ */
+export function getCoreToolsByRiskLevel(riskLevel: RiskLevel): Tool[] {
+  return CORE_TOOL_DEFINITIONS.filter((tool) => tool.riskLevel === riskLevel);
+}

package/src/definitions/delegation.ts

@@ -0,0 +1,567 @@
+/**
+ * Delegation tool definitions
+ *
+ * Tools: delegate_arion, spawn_worker, check_delegation, pause_delegation, resume_delegation, delegate_remote, quest_report (7 tools)
+ *
+ * delegate_arion and spawn_worker call context.delegationExecutor (injected by runner).
+ * check_delegation uses context.delegationRegistry for status queries.
+ * When the executor/registry aren't wired, tools return a clear error.
+ */
+
+import { z } from "zod";
+import { NodeIdSchema } from "../network-runtime/index.js";
+import { tool } from "../tool-factory.js";
+import type { ToolContext, ToolResult } from "../types.js";
+
+/**
+ * Delegate a task to another arion in the room.
+ * The arion runs in parallel with its own memory and persona.
+ */
+const delegate_arion = tool({
+  name: "delegate_arion",
+  description:
+    "Delegate a task to another arion in the room. The arion runs in parallel with its own memory and persona. Use check_delegation to get results.",
+  parameters: z.object({
+    arion: z.string().min(1).max(100).describe("Name of the arion to delegate to"),
+    task: z.string().min(1).max(100_000).describe("The task description for the delegated arion"),
+    tier: z
+      .enum(["fast", "balanced", "powerful", "ensemble"])
+      .optional()
+      .describe("Model tier override (fast/balanced/powerful)"),
+  }),
+  category: "arion",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    if (!context.delegationExecutor) {
+      return {
+        success: false,
+        message:
+          "delegate_arion: Delegation executor not available. Ensure RunSession is configured with delegation support.",
+      };
+    }
+
+    try {
+      const id = await context.delegationExecutor.delegateToArion(
+        input.arion,
+        input.task,
+        input.tier,
+      );
+      return {
+        success: true,
+        message: `Delegation ${id} started. Arion "${input.arion}" is working on the task. Use check_delegation to monitor progress.`,
+        data: { id, arion: input.arion },
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: `delegate_arion failed: ${(e as Error).message}`,
+      };
+    }
+  },
+});
+
+/**
+ * Spawn a lightweight worker to execute a focused task in parallel.
+ * No memory or persona. Use for quick, isolated tasks.
+ */
+const spawn_worker = tool({
+  name: "spawn_worker",
+  description:
+    "Spawn a lightweight worker to execute a focused task in parallel. No memory or persona. Use for quick, isolated tasks. Use check_delegation to get results.",
+  parameters: z.object({
+    task: z.string().min(1).max(100_000).describe("The task for the worker"),
+    type: z
+      .enum(["worker", "cli_agent"])
+      .optional()
+      .default("worker")
+      .describe("Delegation type: lightweight worker (default) or external CLI agent"),
+    tools: z
+      .array(
+        z
+          .string()
+          .min(1)
+          .max(100)
+          .regex(/^[a-z0-9_]+$/),
+      )
+      .max(100)
+      .optional()
+      .describe("Restrict worker to these tools only"),
+    tier: z
+      .enum(["fast", "balanced", "powerful", "ensemble"])
+      .optional()
+      .default("fast")
+      .describe("Model tier"),
+    driver: z
+      .string()
+      .regex(/^[a-z0-9-]+$/)
+      .max(50)
+      .optional()
+      .describe("CLI agent driver ID (for type='cli_agent', e.g. claude-code/codex)"),
+    workspace: z
+      .enum(["cwd", "tempdir", "worktree"])
+      .optional()
+      .describe("Workspace strategy for CLI agent delegation"),
+    model: z.string().max(200).optional().describe("CLI model override (for type='cli_agent')"),
+    resume: z.string().max(200).optional().describe("Resume from an existing CLI session ID"),
+    timeout: z
+      .number()
+      .int()
+      .min(1000)
+      .max(3_600_000)
+      .optional()
+      .describe("CLI delegation timeout in ms"),
+  }),
+  category: "meta",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    if (!context.delegationExecutor) {
+      return {
+        success: false,
+        message:
+          "spawn_worker: Delegation executor not available. Ensure RunSession is configured with delegation support.",
+      };
+    }
+
+    try {
+      if (input.type === "cli_agent") {
+        const id = await context.delegationExecutor.spawnCliAgent({
+          task: input.task,
+          driver: input.driver ?? "claude-code",
+          workspace: input.workspace,
+          model: input.model,
+          resume: input.resume,
+          timeout: input.timeout,
+        });
+        return {
+          success: true,
+          message: "CLI agent delegation started",
+          data: { id },
+        };
+      }
+
+      const id = await context.delegationExecutor.spawnWorker(input.task, input.tools, input.tier);
+      return {
+        success: true,
+        message: `Worker ${id} spawned. Use check_delegation to monitor progress.`,
+        data: { id },
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: `spawn_worker failed: ${(e as Error).message}`,
+      };
+    }
+  },
+});
+
+/**
+ * Check the status of a delegated task or spawned worker.
+ * Uses typed DelegationRegistryRef from ToolContext.
+ */
+const check_delegation = tool({
+  name: "check_delegation",
+  description:
+    "Check the status of a delegated task. The ID is always a quest_xxx ID. Returns the result when complete.",
+  parameters: z.object({
+    id: z
+      .string()
+      .regex(/^quest_[a-z0-9]{6,20}$/)
+      .max(50)
+      .describe("Quest ID (quest_xxx)"),
+    wait: z.boolean().optional().default(false).describe("Wait for completion instead of polling."),
+    timeout: z
+      .number()
+      .int()
+      .min(1000)
+      .max(3_600_000)
+      .optional()
+      .describe("Max wait time in ms when wait=true (default 300000)"),
+  }),
+  category: "meta",
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    const registry = context.delegationRegistry;
+
+    if (!registry) {
+      return { success: false, message: "No delegation registry available" };
+    }
+
+    const entry = registry.get(input.id);
+
+    // If not in registry (evicted or process died), check quest store
+    if (!entry && context.questStore) {
+      const quest = context.questStore.getQuest(input.id);
+      if (quest) {
+        const questMessages = context.messageStore?.getByCorrelation(input.id) ?? [];
+        return {
+          success: quest.status === "done" || quest.status === "active",
+          message:
+            quest.status === "done"
+              ? quest.progress || "Quest completed"
+              : quest.status === "blocked"
+                ? quest.progress || "Quest blocked"
+                : `Quest is ${quest.status}`,
+          data: {
+            id: quest.id,
+            status: quest.status,
+            progress: quest.progress,
+            questMessages: questMessages.slice(-10),
+          },
+        };
+      }
+    }
+
+    if (!entry) {
+      return { success: false, message: `Delegation not found: ${input.id}` };
+    }
+
+    if (input.wait && entry.status === "running") {
+      try {
+        const completed = await registry.await(input.id, input.timeout ?? 300_000);
+        return buildCheckResponse(completed, context);
+      } catch (e) {
+        return { success: false, message: `Wait failed: ${(e as Error).message}` };
+      }
+    }
+
+    return buildCheckResponse(entry, context);
+  },
+});
+
+/** Build check_delegation response, enriching with quest store data when available. */
+function buildCheckResponse(
+  entry: {
+    id: string;
+    type: string;
+    status: string;
+    result?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+  },
+  context: ToolContext,
+): ToolResult {
+  let questProgress: string | undefined;
+  let questMessages: unknown[] | undefined;
+  if (context.questStore) {
+    const quest = context.questStore.getQuest(entry.id);
+    if (quest) questProgress = quest.progress;
+  }
+  if (context.messageStore) {
+    questMessages = context.messageStore.getByCorrelation(entry.id).slice(-10);
+  }
+
+  const isTerminalFailure = entry.status === "failed" || entry.status === "aborted";
+  return {
+    success: entry.status === "completed" || entry.status === "running",
+    message:
+      entry.status === "completed"
+        ? (entry.result ?? "Delegation completed")
+        : isTerminalFailure
+          ? (entry.error ?? `Delegation ${entry.status}`)
+          : `Delegation is ${entry.status}`,
+    data: {
+      id: entry.id,
+      type: entry.type,
+      status: entry.status,
+      result: entry.result,
+      error: entry.error,
+      questProgress,
+      questMessages,
+      metadata: entry.metadata,
+    },
+  };
+}
+
+/**
+ * Pause a running delegation.
+ * The agent stops after the AbortController signals cancellation.
+ * Can be resumed later with resume_delegation.
+ */
+const pause_delegation = tool({
+  name: "pause_delegation",
+  description:
+    "Pause a running delegation by terminating it. No in-flight state is preserved. Use resume_delegation to re-create the delegation with the original task.",
+  parameters: z.object({
+    id: z
+      .string()
+      .regex(/^quest_[a-z0-9]{6,20}$/)
+      .max(50)
+      .describe("Quest ID (quest_xxx) to pause"),
+    reason: z.string().max(1000).optional().describe("Reason for pausing"),
+  }),
+  category: "meta",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    const registry = context.delegationRegistry;
+    if (!registry) {
+      return { success: false, message: "No delegation registry available" };
+    }
+
+    const entry = registry.get(input.id);
+    if (!entry) {
+      return { success: false, message: `Delegation not found: ${input.id}` };
+    }
+
+    if (entry.status !== "running") {
+      return {
+        success: false,
+        message: `Cannot pause — delegation is ${entry.status}`,
+      };
+    }
+
+    registry.abort(input.id);
+
+    // Sync quest store so check_delegation's fallback path sees "blocked" after registry eviction
+    if (context.questStore) {
+      try {
+        context.questStore.updateQuest(input.id, {
+          status: "blocked",
+          progress: input.reason ?? "Paused by user",
+        });
+      } catch {
+        // Non-fatal — registry is authoritative while process lives
+      }
+    }
+
+    return {
+      success: true,
+      message: `Delegation ${input.id} aborted${input.reason ? `: ${input.reason}` : ""}. Use resume_delegation to re-create with the original task.`,
+      data: { id: input.id, status: "aborted" },
+    };
+  },
+});
+
+/**
+ * Resume a paused delegation from where it stopped.
+ * Creates a new delegation that continues the original task.
+ */
+const resume_delegation = tool({
+  name: "resume_delegation",
+  description:
+    "Resume a paused delegation by creating a new delegation with the original task. Does not restore in-flight state — the agent starts fresh with the original task description.",
+  parameters: z.object({
+    id: z
+      .string()
+      .regex(/^quest_[a-z0-9]{6,20}$/)
+      .max(50)
+      .describe("Quest ID (quest_xxx) to resume"),
+    additionalContext: z
+      .string()
+      .max(50_000)
+      .optional()
+      .describe("Additional context or instructions for the resumed agent"),
+  }),
+  category: "meta",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    const executor = context.delegationExecutor;
+    if (!executor) {
+      return {
+        success: false,
+        message: "Delegation executor not available",
+      };
+    }
+
+    const registry = context.delegationRegistry;
+    if (!registry) {
+      return { success: false, message: "No delegation registry available" };
+    }
+
+    const entry = registry.get(input.id);
+    if (!entry) {
+      return { success: false, message: `Delegation not found: ${input.id}` };
+    }
+
+    if (entry.status === "running") {
+      return {
+        success: false,
+        message: `Cannot resume — delegation ${input.id} is still running. Use pause_delegation first.`,
+      };
+    }
+
+    // Build a continuation task from the original task + optional additional context
+    const task = input.additionalContext
+      ? `Continue the previous task: ${entry.task}\n\nAdditional context: ${input.additionalContext}`
+      : `Continue the previous task: ${entry.task}`;
+
+    try {
+      let newId: string;
+      if (entry.type === "arion" && entry.arionName) {
+        newId = await executor.delegateToArion(entry.arionName, task);
+      } else if (entry.type === "cli_agent") {
+        if (entry.metadata?.driver) {
+          newId = await executor.spawnCliAgent({
+            task,
+            driver: entry.metadata.driver as string,
+            workspace: entry.metadata.workspace as "cwd" | "tempdir" | "worktree" | undefined,
+            model: entry.metadata.model as string | undefined,
+          });
+        } else {
+          return {
+            success: false,
+            message:
+              "Cannot resume CLI agent delegation — original driver metadata not preserved. Use spawn_worker with type='cli_agent' instead.",
+          };
+        }
+      } else {
+        newId = await executor.spawnWorker(task);
+      }
+      return {
+        success: true,
+        message: `Delegation resumed as ${newId}. Original: ${input.id}`,
+        data: { originalId: input.id, newId, type: entry.type },
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: `Resume failed: ${(e as Error).message}`,
+      };
+    }
+  },
+});
+
+/**
+ * Delegate a task to a remote ARIA node connected via WireGuard tunnel.
+ * The remote node receives the task as a quest message and executes it independently.
+ * Results come back via quest completion messages through the tunnel.
+ */
+const delegate_remote = tool({
+  name: "delegate_remote",
+  description:
+    "Delegate a task to a remote ARIA node connected via WireGuard tunnel. The node executes the task independently. Use check_delegation to get results.",
+  parameters: z.object({
+    node_id: NodeIdSchema.describe("Durable remote node id to delegate to"),
+    task: z.string().min(1).max(100_000).describe("Task description for the remote node"),
+    tier: z
+      .enum(["fast", "balanced", "powerful"])
+      .optional()
+      .describe("Model tier for the remote execution"),
+  }),
+  category: "messaging",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    if (!context.delegationExecutor?.delegateToRemote) {
+      return {
+        success: false,
+        message:
+          "delegate_remote: Remote delegation not available — no delegateToRemote configured. Ensure mailbox and network are wired.",
+      };
+    }
+
+    try {
+      const id = await context.delegationExecutor.delegateToRemote(
+        NodeIdSchema.parse(input.node_id),
+        input.task,
+        input.tier,
+      );
+      return {
+        success: true,
+        message: `Remote delegation ${id} sent to node "${input.node_id}". Use check_delegation to monitor progress.`,
+        data: { id, nodeId: input.node_id },
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: `delegate_remote failed: ${(e as Error).message}`,
+      };
+    }
+  },
+});
+
+/**
+ * View the structured completion report for a finished quest.
+ * Parses the JSON progress field to surface commits, files changed, commands run, and cost.
+ */
+const quest_report = tool({
+  name: "quest_report",
+  description:
+    "View the structured completion report for a finished quest, including commits, files changed, commands run, and cost",
+  parameters: z.object({
+    quest_id: z.string().min(1).max(100).describe("Quest ID to view report for"),
+  }),
+  category: "meta",
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: async (input, context: ToolContext): Promise<ToolResult> => {
+    const questId = input.quest_id;
+    if (!context.questStore) {
+      return { success: false, message: "Quest store not available" };
+    }
+    const quest = context.questStore.getQuest(questId);
+    if (!quest) {
+      return { success: false, message: `Quest not found: ${questId}` };
+    }
+    if (quest.status !== "done") {
+      return {
+        success: true,
+        message: `Quest not yet completed (status: ${quest.status})`,
+        data: { questId, status: quest.status },
+      };
+    }
+
+    // Try to parse structured progress JSON
+    try {
+      const report = JSON.parse(quest.progress);
+      return {
+        success: true,
+        message: "Quest completion report",
+        data: {
+          questId,
+          title: quest.title,
+          status: quest.status,
+          report: {
+            summary: report.summary ?? quest.progress.slice(0, 500),
+            commits: report.commits ?? [],
+            filesChanged: report.filesChanged ?? [],
+            commandsRun: report.commandsRun ?? [],
+            toolsUsed: report.toolsUsed ?? [],
+            turnCount: report.turnCount ?? 0,
+            tokensUsed: report.tokensUsed ?? 0,
+            costUsd: report.costUsd ?? 0,
+          },
+        },
+      };
+    } catch {
+      // Progress is plain text, not structured JSON
+      return {
+        success: true,
+        message: "Quest completion report (plain text)",
+        data: {
+          questId,
+          title: quest.title,
+          status: quest.status,
+          report: {
+            summary: quest.progress,
+            commits: [],
+            filesChanged: [],
+            commandsRun: [],
+          },
+        },
+      };
+    }
+  },
+});
+
+/** Delegation tool definitions (7) */
+export const DELEGATION_TOOL_DEFINITIONS = [
+  delegate_arion,
+  spawn_worker,
+  check_delegation,
+  pause_delegation,
+  resume_delegation,
+  delegate_remote,
+  quest_report,
+];