@aria-cli/tools 1.0.9 → 1.0.11

package/src/definitions/messaging.ts

@@ -1,734 +0,0 @@
-/**
- * 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,
-];