@aria-cli/tools 1.0.0

package/src/definitions/meta.ts

@@ -0,0 +1,392 @@
+/**
+ * Meta tool definitions
+ *
+ * Tools:
+ * - ask_user, quest_update, quest_list
+ * - search, learn_tool, learn_skill
+ * - create_tool, create_skill, use_skill
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import type { Tool } from "../types.js";
+import {
+  executeAskUser,
+  executeQuestUpdate,
+  executeQuestList,
+  executeSearchKnowledge,
+  executeLearnTool,
+  executeLearnSkill,
+  executeLearnLegacy,
+  executeCreateTool,
+  executeCreateSkill,
+  executeUseSkill,
+  executeRestart,
+  executeSelfDiagnose,
+} from "../executors/index.js";
+
+const ask_user: Tool = {
+  name: "ask_user",
+  description:
+    "Ask the user clarifying questions. Supports optional multiple-choice answers. Use when you need user input to proceed.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      questions: {
+        type: "array",
+        description: "List of questions to ask the user",
+        items: {
+          type: "object",
+          properties: {
+            question: {
+              type: "string",
+              description: "The question to ask",
+            },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional multiple-choice answers",
+            },
+          },
+          required: ["question"],
+        },
+      },
+    },
+    required: ["questions"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  // Human interaction is a resumable barrier, not a parallel read-only batch item.
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeAskUser,
+};
+
+const quest_update: Tool = {
+  name: "quest_update",
+  description:
+    "Create, update, or complete quests (task tracking). Quests persist in a structured database across sessions.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      quests: {
+        type: "array",
+        description: "List of quests to create or update",
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              description: "Quest ID (omit to create a new quest)",
+            },
+            title: {
+              type: "string",
+              description: "Quest title",
+            },
+            status: {
+              type: "string",
+              enum: ["open", "active", "blocked", "done"],
+              description: "Quest status: open (ready), active (in progress), blocked, done",
+            },
+            priority: {
+              type: "number",
+              description: "Priority 0-4 (0 = highest, default 2)",
+              minimum: 0,
+              maximum: 4,
+            },
+            blocked_by: {
+              type: "string",
+              description: "ID of quest blocking this one",
+            },
+            notes: {
+              type: "string",
+              description: "Progress notes or context",
+            },
+          },
+          required: [],
+        },
+      },
+    },
+    required: ["quests"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeQuestUpdate,
+};
+
+const quest_list: Tool = {
+  name: "quest_list",
+  description: "List current quests with their status, priority, and dependencies.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        enum: ["all", "open", "active", "blocked", "done"],
+        description: "Filter by status (default: all)",
+        default: "all",
+      },
+    },
+    required: [],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeQuestList,
+};
+
+const search: Tool = {
+  name: "search",
+  description:
+    "Search for tools, skills, and capabilities across Memoria, local skill files, skill registries, and optional web/package sources.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "What to find — tool name, skill name, or capability description",
+      },
+      sources: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["memoria", "local", "registry", "web"],
+        },
+        default: ["memoria", "local", "registry"],
+        description:
+          "Where to search. memoria=learned tools/skills, local=SKILL.md files, registry=skills.sh+clawhub, web=npm/brew+general",
+      },
+      limit: { type: "number", minimum: 1, maximum: 50, default: 10 },
+    },
+    required: ["query"],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeSearchKnowledge,
+};
+
+const learn_tool: Tool = {
+  name: "learn_tool",
+  description:
+    "Learn a CLI tool from `<command> --help` and persist it as callable tool knowledge. (Deprecated — use learn instead)",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "CLI command name (supports subcommands)" },
+      name: { type: "string" },
+      description: { type: "string" },
+      category: {
+        type: "string",
+        enum: ["filesystem", "code", "shell", "web", "data", "memory", "meta", "arion"],
+      },
+    },
+    required: ["command"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: (input: Record<string, unknown>, ctx: import("../types.js").ToolContext) =>
+    executeLearnLegacy({ source: { type: "cli", command: String(input.command ?? "") } }, ctx),
+};
+
+const learn_skill: Tool = {
+  name: "learn_skill",
+  description:
+    "Learn a skill from a SKILL.md file or inline content and persist it in Memoria. (Deprecated — use learn instead)",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Path to SKILL.md (optional if using inline content)" },
+      name: { type: "string" },
+      description: { type: "string" },
+      content: { type: "string" },
+      tags: { type: "array", items: { type: "string" } },
+      toolIds: { type: "array", items: { type: "string" } },
+    },
+    required: [],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: (input: Record<string, unknown>, ctx: import("../types.js").ToolContext) =>
+    executeLearnLegacy({ source: { type: "file", path: String(input.path ?? "") } }, ctx),
+};
+
+const learn: Tool = {
+  name: "learn",
+  description:
+    "Backward-compatible learning tool. Delegates to learn_tool (CLI) or learn_skill (file).",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      source: {
+        type: "object",
+        properties: {
+          type: { type: "string", enum: ["cli", "file"] },
+          command: { type: "string" },
+          path: { type: "string" },
+        },
+        required: ["type"],
+      },
+    },
+    required: ["source"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeLearnLegacy,
+};
+
+const create_tool: Tool = {
+  name: "create_tool",
+  description:
+    "Create a reusable script-backed tool and save it to Memoria for future discovery/use.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      description: { type: "string" },
+      command: {
+        type: "string",
+        description: "Shell command to wrap (optional if script provided)",
+      },
+      script: {
+        type: "string",
+        description: "Script body to write (optional if command provided)",
+      },
+      argsSchema: { type: "object", additionalProperties: true },
+      tags: { type: "array", items: { type: "string" } },
+    },
+    required: ["name", "description"],
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeCreateTool,
+};
+
+const create_skill: Tool = {
+  name: "create_skill",
+  description:
+    "Create a reusable skill/procedure and optionally link it to the current arion profile.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      description: { type: "string" },
+      content: { type: "string" },
+      level: { type: "string", enum: ["beginner", "intermediate", "advanced", "expert"] },
+      tags: { type: "array", items: { type: "string" } },
+      toolIds: { type: "array", items: { type: "string" } },
+    },
+    required: ["name", "description", "content"],
+  } as JSONSchema7,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeCreateSkill,
+};
+
+const use_skill: Tool = {
+  name: "use_skill",
+  description: "Retrieve a learned skill by name/id and record its execution metrics.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      skillId: { type: "string" },
+      success: { type: "boolean", default: true },
+      durationMs: { type: "number" },
+      notes: { type: "string" },
+    },
+    required: [],
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: false,
+  loadingTier: "always",
+  execute: executeUseSkill,
+};
+
+const restart: Tool = {
+  name: "restart",
+  description:
+    "Restart ARIA through the RelaunchSupervisor. Use when you need to pick up code changes after a build, recover from a corrupted state, or when explicitly asked to restart. Fails closed when no supervisor is attached.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      reason: {
+        type: "string",
+        description: "Why the restart is needed (logged for diagnostics)",
+      },
+    },
+  } as JSONSchema7,
+  riskLevel: "dangerous",
+  requiresConfirmation: true,
+  loadingTier: "always",
+  execute: executeRestart,
+};
+
+const self_diagnose: Tool = {
+  name: "self_diagnose",
+  description:
+    "Gather comprehensive diagnostic context for debugging ARIA's own errors, crashes, and runtime issues. Returns structured data from configs, error logs, crash dumps, databases, active quests, sessions, network, and model state — all in one call. Use this as the first step when investigating any ARIA bug or unexpected behavior.",
+  category: "meta",
+  parameters: {
+    type: "object",
+    properties: {
+      focus: {
+        type: "string",
+        description:
+          "Optional keyword to filter errors/crashes (e.g. 'quest_update', 'OOM', 'crash')",
+      },
+      sections: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["runtime", "errors", "crashes", "databases", "daemon", "network"],
+        },
+        description: "Optional subset of sections to return (default: all 6)",
+      },
+      since: {
+        type: "string",
+        description: "ISO timestamp cutoff — only show events after this (default: last 1h)",
+      },
+      limit: {
+        type: "number",
+        description: "Max entries per section (default: 10)",
+        default: 10,
+      },
+    },
+  } as JSONSchema7,
+  riskLevel: "safe",
+  isReadOnly: true,
+  loadingTier: "always",
+  execute: executeSelfDiagnose,
+};
+
+/** Meta tool definitions */
+export const META_TOOL_DEFINITIONS: Tool[] = [
+  ask_user,
+  quest_update,
+  quest_list,
+  search,
+  learn,
+  learn_tool,
+  learn_skill,
+  create_tool,
+  create_skill,
+  use_skill,
+  restart,
+  self_diagnose,
+];

package/src/definitions/network.ts

@@ -0,0 +1,179 @@
+/**
+ * Network management tool definitions.
+ *
+ * Tools: manage_network, list_clients (2 tools)
+ *
+ * ARIA manages its own secure WireGuard network. The LLM uses this tool
+ * to invite peers, revoke access, list connections, and check status.
+ * No user configuration needed — the network auto-creates on first run.
+ */
+
+import { z } from "zod";
+import { tool } from "../tool-factory.js";
+import { NodeIdSchema } from "../network-runtime/index.js";
+import type { ToolResult, NetworkControlRef } from "../types.js";
+
+/**
+ * Network management — ARIA manages its own secure mesh network.
+ *
+ * Actions:
+ *   invite: Generate an invite token for a new peer
+ *   revoke: Remove a peer from the network
+ *   list_peers: List all connected Arions
+ *   status: Network health/connectivity status
+ */
+const manage_network = tool({
+  name: "manage_network",
+  description:
+    "Manage ARIA's secure WireGuard mesh network. Invite peers to the network, " +
+    "revoke access, list connected Arions, or check network status. " +
+    "The network auto-creates on first run — no user configuration needed.",
+  parameters: z.object({
+    action: z
+      .enum(["invite", "revoke", "list_peers", "status"])
+      .describe("Network management action"),
+    displayName: z.string().optional().describe("Optional local label for the invite"),
+    nodeId: NodeIdSchema.optional().describe("Durable remote node id (required for revoke)"),
+    duration: z.number().optional().describe("Invite token validity in ms (default: no expiry)"),
+  }),
+  category: "arion",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  execute: async (input, context): Promise<ToolResult> => {
+    // Network management requires the Memoria DB for peer registry
+    // The actual implementation lives in @aria/wireguard — we only call it here
+    // through the runtime-owned control surface when it is wired in.
+    const networkControl: NetworkControlRef | undefined = context.networkControl;
+
+    if (!networkControl) {
+      return {
+        success: false,
+        message:
+          "Network manager not available. Secure networking requires the @aria/wireguard package.",
+      };
+    }
+
+    switch (input.action) {
+      case "invite": {
+        try {
+          const result = networkControl.invite(input.displayName, input.duration);
+          const inviteLabel = input.displayName?.trim();
+          return {
+            success: true,
+            message:
+              `${inviteLabel ? `Invite token for "${inviteLabel}":\n\n` : "Invite token:\n\n"}${result.token}\n\n` +
+              `Token security model: bearer credential in plaintext payload form. ` +
+              `Share only via secure channels. They can join with: aria pairing join <token>`,
+            data: { token: result.token, ...(inviteLabel ? { displayName: inviteLabel } : {}) },
+          };
+        } catch (e) {
+          return { success: false, message: `invite failed: ${(e as Error).message}` };
+        }
+      }
+
+      case "revoke": {
+        if (!input.nodeId) {
+          return { success: false, message: "nodeId is required for revoke action" };
+        }
+        const revoked = networkControl.revokePeer(NodeIdSchema.parse(input.nodeId));
+        if (!revoked) {
+          return { success: false, message: `node "${input.nodeId}" not found` };
+        }
+        return {
+          success: true,
+          message: `Revoked access for "${input.nodeId}". They will be disconnected.`,
+          data: { nodeId: input.nodeId, revoked: true },
+        };
+      }
+
+      case "list_peers": {
+        const peers = networkControl.listPeers();
+        if (peers.length === 0) {
+          return {
+            success: true,
+            message: "No peers connected. Use manage_network(invite) to add peers.",
+            data: { peers: [] },
+          };
+        }
+        const networkSummary = peers
+          .map(
+            (p) =>
+              `${p.displayNameSnapshot ?? p.nodeId} (membership=${p.membershipStatus ?? p.status}, route=${p.routeOwnership ?? "current"}, session=${p.sessionState ?? "none"}, delivery=${p.deliveryReadiness ?? "cannot_address"}) — ${p.endpointHost ?? "unknown"}:${p.endpointPort ?? "?"}`,
+          )
+          .join("\n");
+        return {
+          success: true,
+          message: `${peers.length} peer(s):\n${networkSummary}`,
+          data: { peers },
+        };
+      }
+
+      case "status": {
+        const status = networkControl.status();
+        // Include signing public key for message signature verification
+        const signingPublicKey = status.signingPublicKey ?? null;
+        return {
+          success: true,
+          message: status.configured
+            ? `Network active. Node: ${status.nodeId?.slice(0, 12) ?? "unknown"}... ` +
+              `Transport: ${status.transportPublicKey?.slice(0, 12) ?? "unknown"}... ` +
+              `Port: ${status.listenPort}. ` +
+              `External: ${status.externalEndpoint ? `${status.externalEndpoint.address}:${status.externalEndpoint.port}` : "unknown"}. ` +
+              `Peers: ${status.activePeers} trusted / ${status.totalPeers} total. ` +
+              `Sessions: ${status.connectedPeers ?? 0} connected, ${status.handshakingPeers ?? 0} handshaking. ` +
+              `Delivery: ${status.queueOnlyPeers ?? 0} queue-only, ${status.supersededPeers ?? 0} superseded.` +
+              (signingPublicKey ? ` Signing key: ${signingPublicKey.slice(0, 12)}...` : "")
+            : "Network not configured. It will be created automatically on next startup.",
+          data: { ...status, signingPublicKey },
+        };
+      }
+
+      default:
+        return { success: false, message: `Unknown action: ${input.action}` };
+    }
+  },
+});
+
+/** Network tool definitions (1) */
+const list_clients = tool({
+  name: "list_clients",
+  description:
+    "List same-home attached clients that share this runtime. Use this before sending a direct local message to another attached terminal by exact clientId.",
+  parameters: z.object({}),
+  category: "arion",
+  riskLevel: "safe",
+  isReadOnly: true,
+  execute: async (_input, context): Promise<ToolResult> => {
+    const networkControl: NetworkControlRef | undefined = context.networkControl;
+    const listAttachedClients = networkControl?.listAttachedClients;
+    if (!listAttachedClients) {
+      return {
+        success: false,
+        message: "Same-home client directory is not available for this runtime.",
+      };
+    }
+
+    const clients = await Promise.resolve(listAttachedClients());
+    const selfClient = clients.find((client) => client.self) ?? null;
+    const otherClients = clients.filter((client) => !client.self);
+    if (clients.length === 0) {
+      return {
+        success: true,
+        message: "No same-home attached clients are currently available.",
+        data: { clients: [], otherClients: [], selfClient: null },
+      };
+    }
+
+    return {
+      success: true,
+      message:
+        otherClients.length > 0
+          ? `${otherClients.length} other same-home client(s) available`
+          : "No other same-home attached clients are currently available.",
+      data: { clients, otherClients, selfClient },
+    };
+  },
+});
+
+/** Network tool definitions (2) */
+export const NETWORK_TOOL_DEFINITIONS = [manage_network, list_clients];