@aria-cli/tools 1.0.0

package/src/definitions/session-history.ts

@@ -0,0 +1,79 @@
+/**
+ * Session History tool definitions
+ *
+ * Tools: session_history (1 tool with multi-action pattern)
+ *
+ * Provides list, search, get, current, stats, delete, and set_title
+ * actions against the SessionHistory SQLite database.
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import type { Tool, ToolContext, ToolResult } from "../types.js";
+import { executeSessionHistory } from "../executors/session-history.js";
+
+const sessionHistory: Tool = {
+  name: "session_history",
+  description:
+    "List, search, and manage conversation session history. Actions: " +
+    "'list' shows recent sessions, 'search' finds sessions by message content (full-text search), " +
+    "'get' retrieves a full session transcript, 'current' shows current session info, " +
+    "'stats' shows session statistics, 'delete' removes a session, " +
+    "'set_title' renames a session.",
+  category: "memory",
+  parameters: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["list", "search", "get", "current", "stats", "delete", "set_title"],
+        description: "Action to perform",
+      },
+      query: {
+        type: "string",
+        description: "Search query (required for 'search' action)",
+      },
+      sessionId: {
+        type: "string",
+        description:
+          "Session ID or prefix — 8+ chars for prefix match, full UUID for exact match (required for 'get', 'delete', 'set_title')",
+      },
+      title: {
+        type: "string",
+        description: "New title (required for 'set_title' action)",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of results to return (default 20)",
+        default: 20,
+      },
+      offset: {
+        type: "number",
+        description: "Pagination offset (default 0)",
+        default: 0,
+      },
+      messageLimit: {
+        type: "number",
+        description: "Maximum messages to return per session for 'get' action (default 50)",
+        default: 50,
+      },
+    },
+    required: ["action"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "deferred",
+  // Only 'delete' needs confirmation — all other actions are safe
+  skipApprovalForInput: (input: unknown): boolean => {
+    const i = input as { action?: string } | undefined;
+    return i?.action !== "delete";
+  },
+  execute: (input: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> => {
+    return executeSessionHistory(
+      input as unknown as Parameters<typeof executeSessionHistory>[0],
+      ctx,
+    );
+  },
+};
+
+/** Session History tool definitions (1) */
+export const SESSION_HISTORY_TOOL_DEFINITIONS: Tool[] = [sessionHistory];

package/src/definitions/shell.ts

@@ -0,0 +1,202 @@
+/**
+ * Shell tool definitions
+ *
+ * Tools: bash, exec, spawn, kill, write_stdin, list_processes, wait_process (7 tools)
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import type { Tool } from "../types.js";
+import {
+  executeBash,
+  executeExec,
+  executeSpawn,
+  executeKill,
+  executeWriteStdin,
+} from "../executors/index.js";
+import { executeListProcesses, executeWaitProcess } from "../executors/shell.js";
+import { classifyCommand } from "../executors/shell-safety.js";
+
+const bash: Tool = {
+  name: "bash",
+  description: "Execute a shell command in a bash environment. Returns stdout and stderr.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "Command to execute" },
+      cwd: { type: "string", description: "Working directory" },
+      env: { type: "object", description: "Environment variables" },
+      timeout: { type: "number", description: "Timeout in milliseconds" },
+    },
+    required: ["command"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  requiresConfirmation: true,
+  isReadOnly: false,
+  loadingTier: "always",
+  skipApprovalForInput: (input: unknown) => {
+    const cmd = (input as { command?: string })?.command;
+    return typeof cmd === "string" && classifyCommand(cmd) === "safe";
+  },
+  execute: executeBash,
+};
+
+const exec: Tool = {
+  name: "exec",
+  description:
+    "Execute a program directly without shell interpretation. Safer than bash for untrusted input.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      program: { type: "string", description: "Program to execute" },
+      args: {
+        type: "array",
+        items: { type: "string" },
+        description: "Command arguments",
+      },
+      cwd: { type: "string", description: "Working directory" },
+      env: { type: "object", description: "Environment variables" },
+      timeout: { type: "number", description: "Timeout in milliseconds" },
+    },
+    required: ["program"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeExec,
+};
+
+const spawn: Tool = {
+  name: "spawn",
+  description:
+    "Start a long-running process in the background. Returns a process ID for management.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      program: { type: "string", description: "Program to spawn" },
+      args: {
+        type: "array",
+        items: { type: "string" },
+        description: "Command arguments",
+      },
+      cwd: { type: "string", description: "Working directory" },
+      env: { type: "object", description: "Environment variables" },
+      interactive: {
+        type: "boolean",
+        description: "Start as interactive PTY session (enables write_stdin). Default: false",
+        default: false,
+      },
+    },
+    required: ["program"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeSpawn,
+};
+
+const kill: Tool = {
+  name: "kill",
+  description: "Terminate a running process by its process ID.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      pid: { type: "number", description: "Process ID to kill" },
+      signal: {
+        type: "string",
+        description: "Signal to send",
+        default: "SIGTERM",
+      },
+    },
+    required: ["pid"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  requiresConfirmation: true,
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeKill,
+};
+
+const write_stdin: Tool = {
+  name: "write_stdin",
+  description:
+    "Send input to an interactive PTY session by PID. Use after spawning a process with interactive=true. Returns recent output from the session.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      pid: { type: "number", description: "PID of the interactive process" },
+      input: { type: "string", description: "Input string to send to the process" },
+      timeout: {
+        type: "number",
+        description: "Milliseconds to wait for output after writing (max 30000)",
+      },
+    },
+    required: ["pid", "input"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeWriteStdin,
+};
+
+const list_processes: Tool = {
+  name: "list_processes",
+  description:
+    "List tracked shell processes started in this session with metadata and runtime status.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      includeExited: {
+        type: "boolean",
+        description: "Include recently exited processes from registry history (default: false).",
+        default: false,
+      },
+    },
+    required: [],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeListProcesses,
+};
+
+const wait_process: Tool = {
+  name: "wait_process",
+  description: "Wait for a tracked process to exit and return exit metadata. Fails on timeout.",
+  category: "shell",
+  parameters: {
+    type: "object",
+    properties: {
+      pid: { type: "number", description: "PID of the process to wait for" },
+      timeoutMs: {
+        type: "number",
+        description: "Maximum milliseconds to wait (max 300000, default 30000).",
+      },
+      timeout: {
+        type: "number",
+        description: "Deprecated alias for timeoutMs.",
+      },
+    },
+    required: ["pid"],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeWaitProcess,
+};
+
+/** Shell tool definitions (7) */
+export const SHELL_TOOL_DEFINITIONS: Tool[] = [
+  bash,
+  exec,
+  spawn,
+  kill,
+  write_stdin,
+  list_processes,
+  wait_process,
+];

package/src/definitions/slack.ts

@@ -0,0 +1,211 @@
+import type { JSONSchema7 } from "json-schema";
+import type { Tool } from "../types.js";
+import { createSlackDesktopClient } from "../slack/desktop-session.js";
+
+type CheckSlackMessagesInput = {
+  teamId?: string;
+  channel?: string;
+  limit?: number;
+  threadTs?: string;
+};
+
+type SendSlackMessageInput = {
+  teamId?: string;
+  channel?: string;
+  text?: string;
+  threadTs?: string;
+};
+
+type ReactSlackMessageInput = {
+  teamId?: string;
+  channel?: string;
+  timestamp?: string;
+  name?: string;
+};
+
+const check_slack_messages: Tool = {
+  name: "check_slack_messages",
+  description:
+    "Read recent Slack messages from a channel or DM using the local Slack Desktop session on this machine.",
+  category: "messaging",
+  parameters: {
+    type: "object",
+    properties: {
+      teamId: {
+        type: "string",
+        description:
+          "Optional Slack team id to target when the local Slack Desktop app is signed into multiple workspaces.",
+      },
+      channel: {
+        type: "string",
+        description: "Slack conversation id (C/G/D...) or channel name.",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of messages to return (default 20, max 100).",
+        default: 20,
+      },
+      threadTs: {
+        type: "string",
+        description:
+          "Optional thread timestamp. When provided, reads thread replies instead of the root channel history.",
+      },
+    },
+    required: ["channel"],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: async (input: unknown) => {
+    const typedInput = input as CheckSlackMessagesInput;
+    const client = await createSlackDesktopClient({
+      teamId: typeof typedInput.teamId === "string" ? typedInput.teamId : undefined,
+    });
+    try {
+      const result = await client.listMessages({
+        channel: String(typedInput.channel ?? ""),
+        limit: typeof typedInput.limit === "number" ? typedInput.limit : 20,
+        threadTs: typeof typedInput.threadTs === "string" ? typedInput.threadTs : undefined,
+      });
+
+      return {
+        success: true,
+        message: `Fetched ${result.messages.length} Slack messages from ${result.channelId}.`,
+        data: result,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : "Slack read failed.",
+      };
+    } finally {
+      await client.close();
+    }
+  },
+};
+
+const send_slack_message: Tool = {
+  name: "send_slack_message",
+  description:
+    "Send a Slack message through the local Slack Desktop session on this machine. Requires confirmation because it posts externally.",
+  category: "messaging",
+  parameters: {
+    type: "object",
+    properties: {
+      teamId: {
+        type: "string",
+        description:
+          "Optional Slack team id to target when the local Slack Desktop app is signed into multiple workspaces.",
+      },
+      channel: {
+        type: "string",
+        description: "Slack conversation id (C/G/D...) or channel name.",
+      },
+      text: {
+        type: "string",
+        description: "Message text to send.",
+      },
+      threadTs: {
+        type: "string",
+        description: "Optional thread timestamp to reply inside an existing thread.",
+      },
+    },
+    required: ["channel", "text"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  requiresConfirmation: true,
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input: unknown) => {
+    const typedInput = input as SendSlackMessageInput;
+    const client = await createSlackDesktopClient({
+      teamId: typeof typedInput.teamId === "string" ? typedInput.teamId : undefined,
+    });
+    try {
+      const result = await client.sendMessage({
+        channel: String(typedInput.channel ?? ""),
+        text: String(typedInput.text ?? ""),
+        threadTs: typeof typedInput.threadTs === "string" ? typedInput.threadTs : undefined,
+      });
+
+      return {
+        success: true,
+        message: `Sent Slack message to ${result.channelId}.`,
+        data: result,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : "Slack send failed.",
+      };
+    } finally {
+      await client.close();
+    }
+  },
+};
+
+const react_slack_message: Tool = {
+  name: "react_slack_message",
+  description:
+    "Add an emoji reaction to a Slack message using the local Slack Desktop session on this machine. Requires confirmation because it modifies external state.",
+  category: "messaging",
+  parameters: {
+    type: "object",
+    properties: {
+      teamId: {
+        type: "string",
+        description:
+          "Optional Slack team id to target when the local Slack Desktop app is signed into multiple workspaces.",
+      },
+      channel: {
+        type: "string",
+        description: "Slack conversation id (C/G/D...) or channel name.",
+      },
+      timestamp: {
+        type: "string",
+        description: "Message timestamp to react to.",
+      },
+      name: {
+        type: "string",
+        description: "Emoji name without colons (e.g., thumbsup, eyes, white_check_mark).",
+      },
+    },
+    required: ["channel", "timestamp", "name"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  requiresConfirmation: true,
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: async (input: unknown) => {
+    const typedInput = input as ReactSlackMessageInput;
+    const client = await createSlackDesktopClient({
+      teamId: typeof typedInput.teamId === "string" ? typedInput.teamId : undefined,
+    });
+    try {
+      const result = await client.addReaction({
+        channel: String(typedInput.channel ?? ""),
+        timestamp: String(typedInput.timestamp ?? ""),
+        name: String(typedInput.name ?? ""),
+      });
+
+      return {
+        success: true,
+        message: `Added :${typedInput.name}: reaction in ${result.channelId}.`,
+        data: result,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : "Slack reaction failed.",
+      };
+    } finally {
+      await client.close();
+    }
+  },
+};
+
+export const SLACK_TOOL_DEFINITIONS = [
+  check_slack_messages,
+  send_slack_message,
+  react_slack_message,
+];

package/src/definitions/web.ts

@@ -0,0 +1,119 @@
+/**
+ * Web tool definitions
+ *
+ * Tools: web_search, web_fetch, browse (3 tools)
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import type { Tool } from "../types.js";
+import { executeWebSearch, executeWebFetch, executeBrowse } from "../executors/index.js";
+
+// web_search uses SearchProviderRouter with automatic provider selection
+const web_search: Tool = {
+  name: "web_search",
+  description:
+    "Search the web for information. Auto-selects the best available search provider (Brave, Firecrawl, Exa, Tavily, Jina, or DuckDuckGo). Works without any API key via Jina/DuckDuckGo fallback. Set ARIA_SEARCH_PROVIDER to override.",
+  category: "web",
+  parameters: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query" },
+      limit: {
+        type: "number",
+        description: "Maximum number of results",
+        default: 10,
+      },
+      domains: {
+        type: "array",
+        items: { type: "string" },
+        description: "Only include results from these domains",
+      },
+      excludeDomains: {
+        type: "array",
+        items: { type: "string" },
+        description: "Exclude results from these domains",
+      },
+      topic: {
+        type: "string",
+        enum: ["general", "news"],
+        description: "Search topic classification",
+      },
+      timeRange: {
+        type: "string",
+        enum: ["day", "week", "month", "year"],
+        description: "Restrict results to a recent time window",
+      },
+    },
+    required: ["query"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeWebSearch,
+};
+
+const web_fetch: Tool = {
+  name: "web_fetch",
+  description:
+    "Fetch the content of a web page. Returns the page content as text or structured data.",
+  category: "web",
+  parameters: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "URL to fetch" },
+      format: {
+        type: "string",
+        enum: ["text", "html", "json"],
+        description: "Output format",
+        default: "text",
+      },
+      headers: {
+        type: "object",
+        description: "Custom request headers",
+        additionalProperties: { type: "string" },
+      },
+      timeoutMs: {
+        type: "number",
+        description: "Request timeout in milliseconds",
+        default: 30_000,
+      },
+      maxSizeBytes: {
+        type: "number",
+        description: "Maximum response body size in bytes",
+        default: 1 * 1024 * 1024,
+      },
+    },
+    required: ["url"],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeWebFetch,
+};
+
+// browse uses Readability + Turndown for structured markdown extraction
+const browse: Tool = {
+  name: "browse",
+  description:
+    "Browse a web page and extract structured markdown content using Readability + Turndown. Returns the page title and markdown (up to 50K chars). Handles GitHub URL normalization and retry with backoff.",
+  category: "web",
+  parameters: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "URL to browse" },
+      timeoutMs: {
+        type: "number",
+        description: "Request timeout in milliseconds",
+        default: 30_000,
+      },
+    },
+    required: ["url"],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeBrowse,
+};
+
+/** Web tool definitions (3) */
+export const WEB_TOOL_DEFINITIONS: Tool[] = [web_search, web_fetch, browse];