@aria-cli/tools 1.0.0

package/src/definitions/messaging.ts

@@ -0,0 +1,734 @@
+/**
+ * Messaging tool definitions
+ *
+ * Tools: send_message, check_messages, search_messages, get_thread (4 tools)
+ *
+ * Inter-agent messaging for arions, workers, and leaders.
+ * All tools use context.messageStore (injected by runner when Memoria is available).
+ * When the message store isn't wired, tools return a clear error.
+ */
+
+import crypto from "node:crypto";
+import { z } from "zod";
+import { tool } from "../tool-factory.js";
+import type { ToolContext } from "../types.js";
+import { canonicalizeDeliveryReceipt, InboxAddressSchema } from "../network-runtime/index.js";
+import type {
+  AttachedClientView,
+  ClientId,
+  InboxAddress,
+  NodeId,
+} from "../network-runtime/index.js";
+
+const SENDER_INBOX_METADATA_KEY = "senderInbox";
+
+/**
+ * Resolve the local inbox address from ToolContext.
+ *
+ * Throws instead of returning null — a missing inbox address is a wiring bug
+ * (the entrypoint failed to set nodeId), not a user error. Silent message
+ * drops are structurally impossible: tools either route correctly or crash loudly.
+ */
+function resolveInboxAddress(context: ToolContext): InboxAddress {
+  if (context.inboxAddress) {
+    return context.inboxAddress;
+  }
+  if (context.nodeId) {
+    return { kind: "node", nodeId: context.nodeId };
+  }
+  throw new Error(
+    "Inbox address not available: neither context.inboxAddress nor context.nodeId is set. " +
+      "The entrypoint must wire nodeId into ToolContext (via RunOptions.nodeId or direct inboxAddress). " +
+      "This is a wiring bug — check tool-executor.ts and RunSession.toRunOptions().",
+  );
+}
+
+/**
+ * Resolve ALL inbox addresses the caller should see.
+ *
+ * When the runner is an attached client ({kind: "client", clientId}), remote
+ * peer messages still land in the node inbox ({kind: "node", nodeId}).  The TUI
+ * status bar already polls both — this helper lets the read tools do the same
+ * so the LLM sees everything the user sees.
+ */
+function resolveAllInboxAddresses(context: ToolContext): InboxAddress[] {
+  const primary = resolveInboxAddress(context);
+  if (primary.kind === "client" && context.nodeId) {
+    return [primary, { kind: "node", nodeId: context.nodeId }];
+  }
+  return [primary];
+}
+
+function resolveSenderIdentity(
+  context: ToolContext,
+  inboxAddress: InboxAddress,
+): { id: string; name: string; type: "arion" | "worker" | "leader" } {
+  const senderType: "arion" | "worker" | "leader" = context.arion
+    ? "arion"
+    : (context.senderType ?? "leader");
+
+  if (context.arion) {
+    return {
+      id: context.arion.id,
+      name: context.arion.name,
+      type: senderType,
+    };
+  }
+
+  return {
+    id:
+      context.nodeId ??
+      (inboxAddress.kind === "client" ? inboxAddress.clientId : inboxAddress.nodeId),
+    name: "ARIA",
+    type: senderType,
+  };
+}
+
+type ResolvedRecipient =
+  | {
+      kind: "remote";
+      nodeId: NodeId;
+      recipientName: string;
+    }
+  | {
+      kind: "local";
+      mailboxId: string;
+      recipientName: string;
+    }
+  | {
+      kind: "client";
+      clientId: ClientId;
+      recipientName: string;
+      self: boolean;
+    };
+
+async function listAttachedClients(context: ToolContext): Promise<AttachedClientView[]> {
+  return Promise.resolve(context.networkControl?.listAttachedClients?.() ?? []);
+}
+
+function buildUnknownRecipientError(context: ToolContext, recipientRef: string): string {
+  const localRecipientHint = context.manager
+    ? "registered local mailbox id or arion name"
+    : "registered local mailbox id or alias";
+  const sameHomeHint = context.networkControl?.listAttachedClients
+    ? "exact same-home clientId from list_clients"
+    : "exact same-home clientId";
+  return (
+    `Unknown recipient "${recipientRef}". ` +
+    `send_message requires an exact recipient identity: ${localRecipientHint}, exact remote nodeId, or ${sameHomeHint}.`
+  );
+}
+
+async function resolveManagedLocalRecipient(
+  context: ToolContext,
+  recipientRef: string,
+): Promise<ResolvedRecipient | null> {
+  const manager = context.manager;
+  if (!manager) {
+    return null;
+  }
+
+  const [directByName, listed] = await Promise.all([
+    manager.get(recipientRef).catch(() => null),
+    manager.list().catch(() => []),
+  ]);
+
+  const exactMatch =
+    directByName ??
+    listed.find((candidate) => candidate.id === recipientRef || candidate.name === recipientRef) ??
+    null;
+  if (!exactMatch) {
+    return null;
+  }
+
+  return {
+    kind: "local",
+    mailboxId: exactMatch.id,
+    recipientName: exactMatch.name,
+  };
+}
+
+function extractSenderInboxFromMetadata(
+  metadata: string | null | undefined,
+): InboxAddress | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(metadata) as Record<string, unknown>;
+    if (!(SENDER_INBOX_METADATA_KEY in parsed)) {
+      return undefined;
+    }
+    return InboxAddressSchema.parse(parsed[SENDER_INBOX_METADATA_KEY]);
+  } catch {
+    return undefined;
+  }
+}
+
+async function resolveRecipientFromReplyTarget(
+  context: ToolContext,
+  replyTo: string,
+  inboxAddress: InboxAddress,
+): Promise<{ ok: true; recipient: ResolvedRecipient } | { ok: false; error: string }> {
+  if (typeof context.messageStore?.getMessageForInbox !== "function") {
+    return {
+      ok: false,
+      error:
+        "Reply routing is unavailable: the message store cannot resolve inbox-scoped message ids.",
+    };
+  }
+
+  const original = context.messageStore.getMessageForInbox(inboxAddress, replyTo);
+  if (!original) {
+    return {
+      ok: false,
+      error: `Cannot reply to message "${replyTo}" because it is not present in the current inbox.`,
+    };
+  }
+
+  const senderInbox = extractSenderInboxFromMetadata(original.metadata);
+  if (senderInbox?.kind === "client") {
+    return {
+      ok: true,
+      recipient: {
+        kind: "client",
+        clientId: senderInbox.clientId,
+        recipientName: original.sender_name,
+        self: inboxAddress.kind === "client" && senderInbox.clientId === inboxAddress.clientId,
+      },
+    };
+  }
+
+  return resolveRecipientIdentity(context, original.sender_id, inboxAddress);
+}
+
+async function resolveRecipientIdentity(
+  context: ToolContext,
+  recipientRef: string,
+  inboxAddress: InboxAddress,
+): Promise<{ ok: true; recipient: ResolvedRecipient } | { ok: false; error: string }> {
+  const localMailbox = context.mailbox;
+  const peers = context.networkControl?.listPeers() ?? [];
+  const attachedClients = await listAttachedClients(context);
+  const exactClient = attachedClients.find((client) => client.clientId === recipientRef);
+  if (exactClient) {
+    return {
+      ok: true,
+      recipient: {
+        kind: "client",
+        clientId: exactClient.clientId,
+        recipientName: exactClient.displayLabel.trim() || exactClient.clientId,
+        self: exactClient.self,
+      },
+    };
+  }
+  const exactPeer = peers.find((peer) => peer.nodeId === recipientRef);
+  if (exactPeer) {
+    if (
+      exactPeer.routeOwnership === "superseded" ||
+      exactPeer.deliveryReadiness === "cannot_address"
+    ) {
+      return {
+        ok: false,
+        error:
+          `Peer "${recipientRef}" is not currently addressable` +
+          (exactPeer.routeOwnership === "superseded"
+            ? " because its direct route claim has been superseded."
+            : "."),
+      };
+    }
+    return {
+      ok: true,
+      recipient: {
+        kind: "remote",
+        nodeId: exactPeer.nodeId,
+        recipientName: exactPeer.displayNameSnapshot ?? exactPeer.nodeId,
+      },
+    };
+  }
+
+  const hasLocalRecipientId =
+    typeof localMailbox?.has === "function" && localMailbox.has(recipientRef);
+  if (hasLocalRecipientId) {
+    return {
+      ok: true,
+      recipient: {
+        kind: "local",
+        mailboxId: recipientRef,
+        recipientName: recipientRef,
+      },
+    };
+  }
+
+  const hasLocalRecipientAlias =
+    typeof localMailbox?.hasByName === "function" && localMailbox.hasByName(recipientRef);
+  if (hasLocalRecipientAlias) {
+    const canonicalLocalRecipientId =
+      typeof localMailbox?.resolveId === "function"
+        ? localMailbox.resolveId(recipientRef)
+        : undefined;
+    if (!canonicalLocalRecipientId) {
+      return {
+        ok: false,
+        error: `Registered local alias "${recipientRef}" is missing a canonical mailbox id`,
+      };
+    }
+    return {
+      ok: true,
+      recipient: {
+        kind: "local",
+        mailboxId: canonicalLocalRecipientId,
+        recipientName: recipientRef,
+      },
+    };
+  }
+
+  const managedLocalRecipient = await resolveManagedLocalRecipient(context, recipientRef);
+  if (managedLocalRecipient) {
+    return {
+      ok: true,
+      recipient: managedLocalRecipient,
+    };
+  }
+
+  // Resolve by display name — allows @mentioning peers by name instead of nodeId.
+  const recipientRefLower = recipientRef.toLowerCase().replace(/^@/, "");
+  const displayMatches = peers.filter(
+    (peer) =>
+      peer.displayNameSnapshot?.toLowerCase() === recipientRefLower ||
+      peer.displayNameSnapshot?.toLowerCase() === recipientRef.toLowerCase(),
+  );
+  if (displayMatches.length > 1) {
+    return { ok: false, error: `Ambiguous peer display name "${recipientRef}"` };
+  }
+  if (displayMatches.length === 1) {
+    const matchedPeer = displayMatches[0]!;
+    if (
+      matchedPeer.routeOwnership === "superseded" ||
+      matchedPeer.deliveryReadiness === "cannot_address"
+    ) {
+      return {
+        ok: false,
+        error: `Peer "${matchedPeer.displayNameSnapshot}" is not currently addressable.`,
+      };
+    }
+    return {
+      ok: true,
+      recipient: {
+        kind: "remote",
+        nodeId: matchedPeer.nodeId,
+        recipientName: matchedPeer.displayNameSnapshot ?? matchedPeer.nodeId,
+      },
+    };
+  }
+
+  const clientDisplayMatches = attachedClients.filter(
+    (client) =>
+      client.displayLabel?.toLowerCase() === recipientRefLower ||
+      client.displayLabel?.toLowerCase() === recipientRef.toLowerCase(),
+  );
+  if (clientDisplayMatches.length > 1) {
+    return { ok: false, error: `Ambiguous same-home client label "${recipientRef}"` };
+  }
+  if (clientDisplayMatches.length === 1) {
+    const matchedClient = clientDisplayMatches[0]!;
+    return {
+      ok: true,
+      recipient: {
+        kind: "client",
+        clientId: matchedClient.clientId,
+        recipientName: matchedClient.displayLabel?.trim() || matchedClient.clientId,
+        self: matchedClient.self,
+      },
+    };
+  }
+
+  if (inboxAddress.kind === "client") {
+    return {
+      ok: false,
+      error: buildUnknownRecipientError(context, recipientRef),
+    };
+  }
+
+  return {
+    ok: true,
+    recipient: {
+      kind: "local",
+      mailboxId: recipientRef,
+      recipientName: recipientRef,
+    },
+  };
+}
+
+/**
+ * Send a message to any agent (arion, worker, or leader).
+ * Messages are persisted and can be threaded via replyTo or correlated via correlationId.
+ */
+const send_message = tool({
+  name: "send_message",
+  description:
+    "Send a message to any agent (arion, worker, or leader). " +
+    "Use @name or display name to address peers and clients (e.g. @vm1, @local-machine), " +
+    "or use an exact nodeId/clientId for precision. " +
+    "When replying to a received message, prefer replyTo and omit to so the tool routes back to the original sender automatically. " +
+    "Messages are persisted and can be threaded via replyTo or correlated via correlationId.",
+  parameters: z
+    .object({
+      to: z
+        .string()
+        .optional()
+        .describe(
+          "Recipient: @name or display name of a peer/client (e.g. @vm1, @local-machine), " +
+            "or exact nodeId/clientId for precision",
+        ),
+      type: z
+        .enum([
+          "quest",
+          "quest_update",
+          "progress",
+          "finding",
+          "question",
+          "answer",
+          "review_request",
+          "review_result",
+          "approval",
+          "directive",
+          "context",
+          "announcement",
+          "error",
+        ])
+        .describe("Message type"),
+      content: z.string().describe("Message content"),
+      replyTo: z
+        .string()
+        .optional()
+        .describe(
+          "Message ID to reply to. When provided without to, the tool replies to the original sender automatically.",
+        ),
+      correlationId: z
+        .string()
+        .optional()
+        .describe("Correlation ID for sub-thread conversations within a quest"),
+      questId: z
+        .string()
+        .optional()
+        .describe("Quest ID this message belongs to (e.g. quest_abc123)"),
+      priority: z
+        .number()
+        .min(0)
+        .max(4)
+        .optional()
+        .describe("Priority: 0=critical, 2=normal (default), 4=backlog"),
+    })
+    .superRefine((input, ctx) => {
+      if (!input.to && !input.replyTo) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["to"],
+          message: 'Either "to" or "replyTo" is required.',
+        });
+      }
+    }),
+  category: "messaging",
+  riskLevel: "moderate",
+  isReadOnly: false,
+  execute: async (input, context) => {
+    if (!context.messageStore) {
+      return {
+        success: false,
+        message: "Message store not available. Messaging requires Memoria.",
+      };
+    }
+    const inboxAddress = resolveInboxAddress(context);
+    const recipient =
+      input.to && input.to.trim().length > 0
+        ? await resolveRecipientIdentity(context, input.to, inboxAddress)
+        : input.replyTo
+          ? await resolveRecipientFromReplyTarget(context, input.replyTo, inboxAddress)
+          : { ok: false as const, error: 'Either "to" or "replyTo" is required.' };
+    if (!recipient.ok) {
+      return {
+        success: false,
+        message: recipient.error,
+      };
+    }
+    if (recipient.recipient.kind === "client" && recipient.recipient.self) {
+      return {
+        success: false,
+        message: "Cannot send a same-home message to yourself.",
+      };
+    }
+    const recipientId =
+      recipient.recipient.kind === "remote"
+        ? recipient.recipient.nodeId
+        : recipient.recipient.kind === "client"
+          ? recipient.recipient.clientId
+          : recipient.recipient.mailboxId;
+    const sender = resolveSenderIdentity(context, inboxAddress);
+    const resolvedTargetLabel = input.to ?? recipient.recipient.recipientName;
+    const msg = {
+      id: crypto.randomUUID(),
+      version: 1 as const,
+      sender,
+      recipient: { id: recipientId, name: recipient.recipient.recipientName },
+      replyTo: input.replyTo,
+      correlationId: input.correlationId,
+      questId: input.questId,
+      type: input.type,
+      content: input.content,
+      metadata:
+        inboxAddress.kind === "client"
+          ? {
+              [SENDER_INBOX_METADATA_KEY]: inboxAddress,
+            }
+          : undefined,
+      timestamp: Date.now(),
+      priority: (input.priority ?? 2) as 0 | 1 | 2 | 3 | 4,
+      ...(recipient.recipient.kind === "client"
+        ? {
+            recipientInbox: {
+              kind: "client" as const,
+              clientId: recipient.recipient.clientId,
+            },
+          }
+        : {}),
+    };
+
+    // Route through Mailbox if available (handles delivery + persistence)
+    if (context.mailbox) {
+      try {
+        const receipt = canonicalizeDeliveryReceipt(await context.mailbox.sendDurable(msg));
+        const receiptSummary =
+          receipt.deliveryState === "queued_for_route"
+            ? `accepted and queued for route establishment`
+            : receipt.deliveryState === "dispatching"
+              ? `sent and awaiting remote acknowledgement`
+              : receipt.delivered
+                ? `delivered`
+                : `sent`;
+        const routeSummary = receipt.sessionState
+          ? ` session=${receipt.sessionState}, delivery=${receipt.deliveryReadiness ?? "unknown"}`
+          : "";
+        const reasonSummary = receipt.queuedReason ? ` reason=${receipt.queuedReason}` : "";
+        return {
+          success: true,
+          message:
+            `Message ${receiptSummary} for "${resolvedTargetLabel}" via ${receipt.transport}` +
+            `${routeSummary}${reasonSummary} (type: ${input.type}, id: ${msg.id})`,
+          data: {
+            id: msg.id,
+            to: recipientId,
+            type: input.type,
+            delivered: receipt.delivered,
+            queued: receipt.queued,
+            transport: receipt.transport,
+            accepted: receipt.accepted ?? true,
+            deliveryState: receipt.deliveryState,
+            sessionState: receipt.sessionState,
+            deliveryReadiness: receipt.deliveryReadiness,
+            queuedReason: receipt.queuedReason,
+          },
+        };
+      } catch (e) {
+        // Fail closed for known remote peers — a local fallback is not delivery.
+        if (recipient.recipient.kind === "remote") {
+          context.messageStore.store(msg, "sent", inboxAddress);
+          return {
+            success: false,
+            message: `Message delivery failed for "${resolvedTargetLabel}": ${(e as Error).message}`,
+            data: {
+              id: msg.id,
+              to: recipient.recipient.nodeId,
+              type: input.type,
+              delivered: false,
+            },
+          };
+        }
+
+        // Local fallback only makes sense when no remote peer principal was resolved.
+        context.messageStore.store(msg, "sent", inboxAddress);
+        return {
+          success: true,
+          message: `Message stored locally for "${resolvedTargetLabel}" but delivery failed: ${(e as Error).message}`,
+          data: { id: msg.id, to: recipientId, type: input.type, delivered: false },
+        };
+      }
+    }
+
+    // No Mailbox — store locally only (single-process mode)
+    context.messageStore.store(msg, "sent", inboxAddress);
+    return {
+      success: true,
+      message: `Message sent to "${resolvedTargetLabel}" (type: ${input.type}, id: ${msg.id})`,
+      data: { id: msg.id, to: recipientId, type: input.type, delivered: false },
+    };
+  },
+});
+
+/**
+ * Check your message inbox.
+ * Returns unread messages by default, with optional filters.
+ */
+const check_messages = tool({
+  name: "check_messages",
+  description:
+    "Check your message inbox. Returns unread messages by default, with optional filters.",
+  parameters: z.object({
+    unreadOnly: z.boolean().optional().describe("Only show unread messages (default: true)"),
+    from: z.string().optional().describe("Filter by sender name"),
+    type: z.string().optional().describe("Filter by message type"),
+    correlationId: z.string().optional().describe("Filter by correlation ID"),
+    limit: z.number().optional().describe("Max messages to return (default: 20)"),
+  }),
+  category: "messaging",
+  riskLevel: "safe",
+  isReadOnly: true,
+  execute: async (input, context) => {
+    if (!context.messageStore) {
+      return { success: false, message: "Message store not available." };
+    }
+    const inboxAddresses = resolveAllInboxAddresses(context);
+    const unreadOnly = input.unreadOnly ?? true;
+    const limit = input.limit ?? 20;
+
+    if (unreadOnly) {
+      const seen = new Set<string>();
+      const messages = inboxAddresses
+        .flatMap((addr) => context.messageStore!.getUnreadForInbox(addr, limit))
+        .filter((m) => {
+          if (seen.has(m.id)) return false;
+          seen.add(m.id);
+          return true;
+        })
+        .slice(0, limit);
+      if (messages.length === 0) {
+        return { success: true, message: "No unread messages.", data: { messages: [] } };
+      }
+      // Auto-mark as read
+      context.messageStore.markRead(messages.map((m) => m.id));
+      return {
+        success: true,
+        message: `${messages.length} message(s) received`,
+        data: { messages },
+      };
+    }
+
+    // Search with filters
+    const seen = new Set<string>();
+    const messages = inboxAddresses
+      .flatMap((addr) =>
+        context.messageStore!.searchInbox(addr, "", {
+          from: input.from,
+          type: input.type,
+          correlationId: input.correlationId,
+          limit,
+        }),
+      )
+      .filter((m) => {
+        if (seen.has(m.id)) return false;
+        seen.add(m.id);
+        return true;
+      })
+      .slice(0, limit);
+    return {
+      success: true,
+      message: `${messages.length} message(s) found`,
+      data: { messages },
+    };
+  },
+});
+
+/**
+ * Search message history by content with optional filters.
+ */
+const search_messages = tool({
+  name: "search_messages",
+  description: "Search message history by content with optional filters.",
+  parameters: z.object({
+    query: z.string().describe("Search text (matched against message content)"),
+    from: z.string().optional().describe("Filter by sender name"),
+    type: z.string().optional().describe("Filter by message type"),
+    correlationId: z.string().optional().describe("Filter by correlation ID"),
+    after: z.number().optional().describe("Only messages after this timestamp (epoch ms)"),
+    limit: z.number().optional().describe("Max results (default: 20)"),
+  }),
+  category: "messaging",
+  riskLevel: "safe",
+  isReadOnly: true,
+  execute: async (input, context) => {
+    if (!context.messageStore) {
+      return { success: false, message: "Message store not available." };
+    }
+    const inboxAddresses = resolveAllInboxAddresses(context);
+    const limit = input.limit ?? 20;
+    const seen = new Set<string>();
+    const messages = inboxAddresses
+      .flatMap((addr) =>
+        context.messageStore!.searchInbox(addr, input.query, {
+          from: input.from,
+          type: input.type,
+          correlationId: input.correlationId,
+          after: input.after,
+          limit,
+        }),
+      )
+      .filter((m) => {
+        if (seen.has(m.id)) return false;
+        seen.add(m.id);
+        return true;
+      })
+      .slice(0, limit);
+    return {
+      success: true,
+      message: `${messages.length} message(s) found`,
+      data: { messages },
+    };
+  },
+});
+
+/**
+ * Reconstruct a conversation thread from any message ID in the chain.
+ * Follows replyTo links to build the full thread.
+ */
+const get_thread = tool({
+  name: "get_thread",
+  description:
+    "Reconstruct a conversation thread from any message ID in the chain. Follows replyTo links to build the full thread.",
+  parameters: z.object({
+    messageId: z.string().describe("Any message ID in the thread"),
+  }),
+  category: "messaging",
+  riskLevel: "safe",
+  isReadOnly: true,
+  execute: async (input, context) => {
+    if (!context.messageStore) {
+      return { success: false, message: "Message store not available." };
+    }
+    const inboxAddresses = resolveAllInboxAddresses(context);
+    const seen = new Set<string>();
+    const thread = inboxAddresses
+      .flatMap((addr) => context.messageStore!.getThreadForInbox(addr, input.messageId))
+      .filter((m) => {
+        if (seen.has(m.id)) return false;
+        seen.add(m.id);
+        return true;
+      });
+    if (thread.length === 0) {
+      return { success: false, message: `No thread found for message ${input.messageId}` };
+    }
+    return {
+      success: true,
+      message: `Thread with ${thread.length} message(s)`,
+      data: { thread },
+    };
+  },
+});
+
+/** Messaging tool definitions (4) */
+export const MESSAGING_TOOL_DEFINITIONS = [
+  send_message,
+  check_messages,
+  search_messages,
+  get_thread,
+];