@aria-cli/tools 1.0.12 → 1.0.14

package/dist/definitions/messaging.js

@@ -1,625 +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 { 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,
-];