@aria-cli/tools 1.0.19 → 1.0.31

package/dist/definitions/messaging.js

@@ -0,0 +1,626 @@
+/**
+ * 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 { canonicalizeDeliveryReceipt, InboxAddressSchema } 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) {
+    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) {
+    const primary = resolveInboxAddress(context);
+    if (primary.kind === "client" && context.nodeId) {
+        return [primary, { kind: "node", nodeId: context.nodeId }];
+    }
+    return [primary];
+}
+function resolveSenderIdentity(context, inboxAddress) {
+    const senderType = 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,
+    };
+}
+async function listAttachedClients(context) {
+    return Promise.resolve(context.networkControl?.listAttachedClients?.() ?? []);
+}
+function buildUnknownRecipientError(context, recipientRef) {
+    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, recipientRef) {
+    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) {
+    if (!metadata) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(metadata);
+        if (!(SENDER_INBOX_METADATA_KEY in parsed)) {
+            return undefined;
+        }
+        return InboxAddressSchema.parse(parsed[SENDER_INBOX_METADATA_KEY]);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolveRecipientFromReplyTarget(context, replyTo, inboxAddress) {
+    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, recipientRef, inboxAddress) {
+    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, 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,
+            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),
+            ...(recipient.recipient.kind === "client"
+                ? {
+                    recipientInbox: {
+                        kind: "client",
+                        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.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.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();
+            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();
+        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();
+        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();
+        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,
+];
+//# sourceMappingURL=messaging.js.map