@xmtp/convos-cli 0.1.0

package/dist/commands/agent/serve.js

@@ -0,0 +1,662 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { createInterface } from "node:readline";
+import { Args, Flags } from "@oclif/core";
+import { encryptAttachment, } from "@xmtp/node-sdk";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import QRCode from "qrcode";
+import { ConvosBaseCommand } from "../../baseCommand.js";
+import { createClientForIdentity } from "../../utils/client.js";
+import { createIdentityStore } from "../../utils/identities.js";
+import { createInviteSlug, decryptConversationToken, parseInvite, verifyInvite, verifyInviteSignature, } from "../../utils/invite.js";
+import { getMimeType } from "../../utils/mime.js";
+import { parseAppData, serializeAppData, upsertProfile } from "../../utils/metadata.js";
+import { randomAlphanumeric } from "../../utils/random.js";
+import { getUploadProvider, INLINE_ATTACHMENT_MAX_BYTES, } from "../../utils/upload.js";
+import { buildProfileMap, getAccountAddress, isDisplayableMessage, jsonStringify, normalizeMessageContent, requireGroup, } from "../../utils/xmtp.js";
+export default class AgentServe extends ConvosBaseCommand {
+    static description = `Run an agent server for a conversation.
+
+Starts a long-running process that combines message streaming,
+join request processing, and stdin command handling into a single
+session — ideal for AI agents and bots.
+
+If no conversation ID is provided, creates a new conversation.
+Displays the QR code invite on stderr so agents can share it.
+
+Uses an ndjson (newline-delimited JSON) protocol:
+
+STDIN commands (one JSON object per line):
+  {"type":"send","text":"Hello"}                        Send a text message
+  {"type":"send","text":"Re","replyTo":"<id>"}          Reply to a message
+  {"type":"react","messageId":"<id>","emoji":"👍"}       React to a message
+  {"type":"react","messageId":"<id>","emoji":"👍","action":"remove"}
+  {"type":"attach","file":"./photo.jpg"}                Send a file attachment
+  {"type":"attach","file":"./img.jpg","replyTo":"<id>"} Reply with attachment
+  {"type":"remote-attach","url":"https://...","contentDigest":"...","secret":"...","salt":"...","nonce":"...","contentLength":123}
+  {"type":"stop"}                                       Graceful shutdown
+
+STDOUT events (one JSON object per line):
+  {"event":"ready",...}         Session started, includes invite URL
+  {"event":"message",...}       New message received
+  {"event":"member_joined",...} A member joined via invite
+  {"event":"sent",...}          Message sent confirmation
+  {"event":"error",...}         Error occurred
+
+STDERR: QR code, diagnostic logs (does not interfere with protocol)`;
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> --name "My Bot"',
+            description: "Create a new conversation and start serving",
+        },
+        {
+            command: "<%= config.bin %> <%= command.id %> <conversation-id>",
+            description: "Attach to an existing conversation",
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> --name "Agent" --profile-name "Assistant" --permissions admin-only',
+            description: "Create an admin-only conversation with a profile name",
+        },
+    ];
+    static args = {
+        id: Args.string({
+            description: "Existing conversation ID to attach to (omit to create new)",
+            required: false,
+        }),
+    };
+    static flags = {
+        ...ConvosBaseCommand.baseFlags,
+        name: Flags.string({
+            description: "Conversation name (when creating new)",
+            helpValue: "<name>",
+        }),
+        description: Flags.string({
+            description: "Conversation description (when creating new)",
+            helpValue: "<description>",
+        }),
+        permissions: Flags.option({
+            options: ["all-members", "admin-only"],
+            description: "Permission preset (when creating new)",
+            default: "all-members",
+        })(),
+        "profile-name": Flags.string({
+            description: "Profile display name for this conversation",
+            helpValue: "<name>",
+        }),
+        identity: Flags.string({
+            description: "Use an existing unlinked identity ID (when creating new)",
+            helpValue: "<id>",
+        }),
+        label: Flags.string({
+            description: "Local label for the identity",
+            helpValue: "<label>",
+        }),
+        "no-invite": Flags.boolean({
+            description: "Skip generating an invite (attach mode only)",
+            default: false,
+        }),
+    };
+    streams = [];
+    shutdownResolve;
+    /**
+     * Emit a JSON event to stdout (one line).
+     */
+    emit(event) {
+        process.stdout.write(jsonStringify(event) + "\n");
+    }
+    /**
+     * Emit an error event.
+     */
+    emitError(message, details) {
+        this.emit({ event: "error", message, ...details });
+    }
+    /**
+     * Process a single DM message as a potential join request.
+     */
+    async processJoinMessage(message, client, identity) {
+        if (message.senderInboxId === client.inboxId)
+            return;
+        const text = typeof message.content === "string" ? message.content : null;
+        if (!text)
+            return;
+        let invite;
+        try {
+            invite = parseInvite(text);
+        }
+        catch {
+            return;
+        }
+        const dmConversation = (await client.conversations.getConversationById(message.conversationId));
+        if (!(await verifyInvite(invite))) {
+            if (dmConversation)
+                dmConversation.updateConsentState(2 /* ConsentState.Denied */);
+            return;
+        }
+        if (!(await verifyInviteSignature(invite, identity.walletKey))) {
+            if (dmConversation)
+                dmConversation.updateConsentState(2 /* ConsentState.Denied */);
+            return;
+        }
+        if (invite.creatorInboxId !== client.inboxId) {
+            if (dmConversation)
+                dmConversation.updateConsentState(2 /* ConsentState.Denied */);
+            return;
+        }
+        if (invite.expiresAt && invite.expiresAt < new Date())
+            return;
+        let conversationId;
+        try {
+            conversationId = decryptConversationToken(invite.conversationToken, client.inboxId, Buffer.from(identity.walletKey.replace("0x", ""), "hex"));
+        }
+        catch {
+            if (dmConversation)
+                dmConversation.updateConsentState(2 /* ConsentState.Denied */);
+            return;
+        }
+        const conversation = await client.conversations.getConversationById(conversationId);
+        if (!conversation)
+            return;
+        const group = requireGroup(conversation);
+        try {
+            const appData = group.appData ?? "";
+            const metadata = parseAppData(appData);
+            if (metadata.tag && invite.tag !== metadata.tag)
+                return;
+        }
+        catch {
+            // skip tag check
+        }
+        await group.addMembers([message.senderInboxId]);
+        if (dmConversation)
+            dmConversation.updateConsentState(1 /* ConsentState.Allowed */);
+        return { conversationId, joinerInboxId: message.senderInboxId };
+    }
+    /**
+     * Process any pending DM join requests (batch, on startup).
+     */
+    async processPendingJoinRequests(client, identity) {
+        try {
+            await client.conversations.sync();
+            const dms = await client.conversations.list({
+                conversationType: 0 /* ConversationType.Dm */,
+                consentStates: [0 /* ConsentState.Unknown */],
+            });
+            for (const dm of dms) {
+                try {
+                    await dm.sync();
+                    const messages = await dm.messages({ limit: 10 });
+                    for (const message of messages) {
+                        try {
+                            const result = await this.processJoinMessage(message, client, identity);
+                            if (result) {
+                                this.emit({
+                                    event: "member_joined",
+                                    inboxId: result.joinerInboxId,
+                                    conversationId: result.conversationId,
+                                    timestamp: new Date().toISOString(),
+                                });
+                                break;
+                            }
+                        }
+                        catch {
+                            // skip individual message errors
+                        }
+                    }
+                }
+                catch {
+                    // skip individual DM errors
+                }
+            }
+        }
+        catch (error) {
+            this.emitError(`Failed to process pending join requests: ${error instanceof Error ? error.message : "unknown"}`);
+        }
+    }
+    /**
+     * Start streaming DM messages for join request processing.
+     */
+    async startJoinRequestStream(client, identity) {
+        try {
+            const stream = await client.conversations.streamAllDmMessages();
+            this.streams.push(stream);
+            (async () => {
+                try {
+                    for await (const message of stream) {
+                        try {
+                            const result = await this.processJoinMessage(message, client, identity);
+                            if (result) {
+                                this.emit({
+                                    event: "member_joined",
+                                    inboxId: result.joinerInboxId,
+                                    conversationId: result.conversationId,
+                                    timestamp: new Date().toISOString(),
+                                });
+                            }
+                        }
+                        catch {
+                            // skip individual message errors
+                        }
+                    }
+                }
+                catch {
+                    // stream ended
+                }
+            })();
+        }
+        catch (error) {
+            this.emitError(`Failed to start join request stream: ${error instanceof Error ? error.message : "unknown"}`);
+        }
+    }
+    /**
+     * Start streaming conversation messages.
+     */
+    async startMessageStream(conversation, client) {
+        try {
+            const stream = await conversation.stream();
+            this.streams.push(stream);
+            (async () => {
+                try {
+                    for await (const message of stream) {
+                        // Skip our own messages (they get a "sent" event instead)
+                        if (message.senderInboxId === client.inboxId)
+                            continue;
+                        // Skip content types we can't display cleanly
+                        if (!isDisplayableMessage(message))
+                            continue;
+                        // Rebuild profiles each time so newly-joined members are resolved
+                        const profiles = buildProfileMap(conversation.appData ?? "");
+                        this.emit({
+                            event: "message",
+                            id: message.id,
+                            senderInboxId: message.senderInboxId,
+                            contentType: message.contentType,
+                            content: normalizeMessageContent(message, profiles),
+                            sentAt: message.sentAt.toISOString(),
+                            deliveryStatus: message.deliveryStatus,
+                        });
+                    }
+                }
+                catch {
+                    // stream ended
+                }
+            })();
+        }
+        catch (error) {
+            this.emitError(`Failed to start message stream: ${error instanceof Error ? error.message : "unknown"}`);
+        }
+    }
+    /**
+     * Read and process stdin commands.
+     */
+    async startStdinReader(conversation) {
+        // If stdin is a TTY, skip the reader (no piped input)
+        if (process.stdin.isTTY)
+            return;
+        const rl = createInterface({
+            input: process.stdin,
+            terminal: false,
+        });
+        rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            let cmd;
+            try {
+                cmd = JSON.parse(trimmed);
+            }
+            catch {
+                this.emitError("Invalid JSON on stdin", { input: trimmed });
+                return;
+            }
+            void this.handleCommand(cmd, conversation);
+        });
+        rl.on("close", () => {
+            // stdin closed — trigger shutdown
+            this.shutdown();
+        });
+    }
+    /**
+     * Handle a parsed stdin command.
+     */
+    async handleCommand(cmd, conversation) {
+        try {
+            switch (cmd.type) {
+                case "send": {
+                    if (!cmd.text) {
+                        this.emitError("send command requires 'text' field");
+                        return;
+                    }
+                    let messageId;
+                    if (cmd.replyTo) {
+                        const { encodeText } = await import("@xmtp/node-sdk");
+                        messageId = await conversation.sendReply({
+                            reference: cmd.replyTo,
+                            content: encodeText(cmd.text),
+                        });
+                    }
+                    else {
+                        messageId = await conversation.sendText(cmd.text);
+                    }
+                    this.emit({
+                        event: "sent",
+                        id: messageId,
+                        text: cmd.text,
+                        ...(cmd.replyTo && { replyTo: cmd.replyTo }),
+                        timestamp: new Date().toISOString(),
+                    });
+                    break;
+                }
+                case "react": {
+                    if (!cmd.messageId || !cmd.emoji) {
+                        this.emitError("react command requires 'messageId' and 'emoji' fields");
+                        return;
+                    }
+                    const action = cmd.action === "remove" ? 2 /* ReactionAction.Removed */ : 1 /* ReactionAction.Added */;
+                    const reaction = {
+                        reference: cmd.messageId,
+                        referenceInboxId: "",
+                        action,
+                        content: cmd.emoji,
+                        schema: 1 /* ReactionSchema.Unicode */,
+                    };
+                    const reactionMessageId = await conversation.sendReaction(reaction);
+                    this.emit({
+                        event: "sent",
+                        id: reactionMessageId,
+                        type: "reaction",
+                        messageId: cmd.messageId,
+                        emoji: cmd.emoji,
+                        action: cmd.action ?? "add",
+                        timestamp: new Date().toISOString(),
+                    });
+                    break;
+                }
+                case "attach": {
+                    if (!cmd.file) {
+                        this.emitError("attach command requires 'file' field");
+                        return;
+                    }
+                    const content = await readFile(cmd.file);
+                    const filename = basename(cmd.file);
+                    const mimeType = cmd.mimeType ?? getMimeType(cmd.file);
+                    const attachment = { mimeType, content, filename };
+                    const needsRemote = content.length > INLINE_ATTACHMENT_MAX_BYTES;
+                    let messageId;
+                    let sendType;
+                    let url;
+                    if (needsRemote) {
+                        const config = this.getConvosConfig();
+                        const provider = getUploadProvider(config);
+                        if (!provider) {
+                            this.emitError(`File is ${content.length} bytes (>${INLINE_ATTACHMENT_MAX_BYTES}). ` +
+                                `Configure an upload provider (CONVOS_UPLOAD_PROVIDER) to send large files.`);
+                            return;
+                        }
+                        const encrypted = encryptAttachment(attachment);
+                        url = await provider.upload(encrypted.payload, filename, mimeType);
+                        if (cmd.replyTo) {
+                            const { encodeRemoteAttachment } = await import("@xmtp/node-sdk");
+                            messageId = await conversation.sendReply({
+                                reference: cmd.replyTo,
+                                content: encodeRemoteAttachment({
+                                    url,
+                                    contentDigest: encrypted.contentDigest,
+                                    secret: encrypted.secret,
+                                    salt: encrypted.salt,
+                                    nonce: encrypted.nonce,
+                                    scheme: "https",
+                                    contentLength: encrypted.payload.length,
+                                    filename,
+                                }),
+                            });
+                        }
+                        else {
+                            messageId = await conversation.sendRemoteAttachment({
+                                url,
+                                contentDigest: encrypted.contentDigest,
+                                secret: encrypted.secret,
+                                salt: encrypted.salt,
+                                nonce: encrypted.nonce,
+                                scheme: "https",
+                                contentLength: encrypted.payload.length,
+                                filename,
+                            }, false);
+                        }
+                        sendType = "remote";
+                    }
+                    else {
+                        if (cmd.replyTo) {
+                            const { encodeAttachment } = await import("@xmtp/node-sdk");
+                            messageId = await conversation.sendReply({
+                                reference: cmd.replyTo,
+                                content: encodeAttachment(attachment),
+                            });
+                        }
+                        else {
+                            messageId = await conversation.sendAttachment(attachment, false);
+                        }
+                        sendType = "inline";
+                    }
+                    this.emit({
+                        event: "sent",
+                        id: messageId,
+                        type: "attachment",
+                        filename,
+                        mimeType,
+                        size: content.length,
+                        sendType,
+                        ...(url && { url }),
+                        ...(cmd.replyTo && { replyTo: cmd.replyTo }),
+                        timestamp: new Date().toISOString(),
+                    });
+                    break;
+                }
+                case "remote-attach": {
+                    if (!cmd.url || !cmd.contentDigest || !cmd.secret || !cmd.salt || !cmd.nonce || !cmd.contentLength) {
+                        this.emitError("remote-attach command requires 'url', 'contentDigest', 'secret', 'salt', 'nonce', and 'contentLength' fields");
+                        return;
+                    }
+                    const remoteAttachment = {
+                        url: cmd.url,
+                        contentDigest: cmd.contentDigest,
+                        secret: new Uint8Array(Buffer.from(cmd.secret, "base64")),
+                        salt: new Uint8Array(Buffer.from(cmd.salt, "base64")),
+                        nonce: new Uint8Array(Buffer.from(cmd.nonce, "base64")),
+                        scheme: cmd.scheme ?? "https",
+                        contentLength: cmd.contentLength,
+                        filename: cmd.filename,
+                    };
+                    const remoteMessageId = await conversation.sendRemoteAttachment(remoteAttachment, false);
+                    this.emit({
+                        event: "sent",
+                        id: remoteMessageId,
+                        type: "remote-attachment",
+                        url: cmd.url,
+                        filename: cmd.filename,
+                        timestamp: new Date().toISOString(),
+                    });
+                    break;
+                }
+                case "stop":
+                    this.shutdown();
+                    break;
+                default:
+                    this.emitError(`Unknown command type: ${cmd.type}`);
+            }
+        }
+        catch (error) {
+            this.emitError(`Command failed: ${error instanceof Error ? error.message : "unknown"}`, { command: cmd });
+        }
+    }
+    /**
+     * Trigger graceful shutdown.
+     */
+    shutdown() {
+        if (this.shutdownResolve) {
+            this.shutdownResolve();
+        }
+    }
+    async run() {
+        const { args, flags } = await this.parse(AgentServe);
+        const config = this.getConvosConfig();
+        const store = createIdentityStore();
+        let identity;
+        let client;
+        let group;
+        let conversationId;
+        let inviteUrl;
+        let inviteSlug;
+        let inviteTag;
+        if (args.id) {
+            // ─── Attach to existing conversation ───
+            const existing = store.getByConversationId(args.id);
+            if (!existing) {
+                this.error(`No identity found for conversation: ${args.id}`);
+            }
+            identity = existing;
+            client = await createClientForIdentity(identity, config);
+            const conv = await client.conversations.getConversationById(args.id);
+            if (!conv) {
+                this.error(`Conversation not found: ${args.id}`);
+            }
+            group = requireGroup(conv);
+            conversationId = args.id;
+            // Generate invite unless --no-invite
+            if (!flags["no-invite"]) {
+                let appData = "";
+                try {
+                    appData = group.appData ?? "";
+                }
+                catch {
+                    // no appData
+                }
+                let metadata = parseAppData(appData);
+                inviteTag = metadata.tag;
+                if (!inviteTag) {
+                    inviteTag = randomAlphanumeric(10);
+                    metadata = { ...metadata, tag: inviteTag };
+                    await group.updateAppData(serializeAppData(metadata));
+                }
+                inviteSlug = await createInviteSlug(conversationId, client.inboxId, inviteTag, identity.walletKey, {
+                    name: group.name || undefined,
+                    description: group.description || undefined,
+                });
+                const env = config.env ?? "dev";
+                const baseUrl = env === "production"
+                    ? "https://popup.convos.org/v2"
+                    : "https://dev.convos.org/v2";
+                inviteUrl = `${baseUrl}?i=${encodeURIComponent(inviteSlug)}`;
+            }
+        }
+        else {
+            // ─── Create new conversation ───
+            if (flags.identity) {
+                const existing = store.get(flags.identity);
+                if (!existing)
+                    this.error(`Identity not found: ${flags.identity}`);
+                if (existing.conversationId) {
+                    this.error(`Identity ${flags.identity} is already linked to conversation ${existing.conversationId}`);
+                }
+                identity = existing;
+            }
+            else {
+                identity = store.create({
+                    label: flags.label ?? flags.name,
+                    profileName: flags["profile-name"],
+                });
+            }
+            client = await createClientForIdentity(identity, config);
+            const permissionsMap = {
+                "all-members": 0 /* GroupPermissionsOptions.Default */,
+                "admin-only": 1 /* GroupPermissionsOptions.AdminOnly */,
+            };
+            const options = {
+                groupName: flags.name,
+                groupDescription: flags.description,
+                permissions: permissionsMap[flags.permissions],
+            };
+            group = await client.conversations.createGroup([], options);
+            conversationId = group.id;
+            inviteTag = randomAlphanumeric(10);
+            store.update(identity.id, {
+                conversationId,
+                inboxId: client.inboxId,
+                inviteTag,
+                label: flags.label ?? flags.name ?? identity.label,
+                profileName: flags["profile-name"] ?? identity.profileName,
+            });
+            // Store invite tag + profile in appData
+            let metadata = {
+                tag: inviteTag,
+                profiles: [],
+            };
+            const profileName = flags["profile-name"];
+            if (profileName) {
+                metadata = upsertProfile(metadata, {
+                    inboxId: client.inboxId,
+                    name: profileName,
+                });
+            }
+            await group.updateAppData(serializeAppData(metadata));
+            // Generate invite
+            inviteSlug = await createInviteSlug(conversationId, client.inboxId, inviteTag, identity.walletKey, {
+                name: flags.name || undefined,
+                description: flags.description || undefined,
+            });
+            const env = config.env ?? "dev";
+            const baseUrl = env === "production"
+                ? "https://popup.convos.org/v2"
+                : "https://dev.convos.org/v2";
+            inviteUrl = `${baseUrl}?i=${encodeURIComponent(inviteSlug)}`;
+        }
+        // Generate QR code image (PNG) so agents can display it instantly
+        let qrCodePath;
+        if (inviteUrl) {
+            qrCodePath = join(tmpdir(), `convos-invite-${conversationId}.png`);
+            await QRCode.toFile(qrCodePath, inviteUrl, {
+                type: "png",
+                width: 512,
+                margin: 2,
+            });
+            process.stderr.write(`QR code saved to: ${qrCodePath}\n`);
+            process.stderr.write(`Invite URL: ${inviteUrl}\n`);
+        }
+        // Emit ready event
+        this.emit({
+            event: "ready",
+            conversationId,
+            identityId: identity.id,
+            inboxId: client.inboxId,
+            address: getAccountAddress(identity.walletKey),
+            name: group.name ?? "",
+            ...(inviteUrl && { inviteUrl }),
+            ...(inviteSlug && { inviteSlug }),
+            ...(inviteTag && { inviteTag }),
+            ...(qrCodePath && { qrCodePath }),
+            timestamp: new Date().toISOString(),
+        });
+        // Process any pending join requests from before we started
+        await this.processPendingJoinRequests(client, identity);
+        // Start all concurrent streams
+        await this.startMessageStream(group, client);
+        await this.startJoinRequestStream(client, identity);
+        this.startStdinReader(group);
+        // Keep running until shutdown
+        await new Promise((resolve) => {
+            this.shutdownResolve = resolve;
+            process.on("SIGINT", () => {
+                process.stderr.write("\nShutting down...\n");
+                resolve();
+            });
+            process.on("SIGTERM", () => {
+                process.stderr.write("\nShutting down...\n");
+                resolve();
+            });
+        });
+        // Clean up streams
+        for (const stream of this.streams) {
+            void stream.return();
+        }
+    }
+}

package/dist/commands/conversation/add-members.d.ts

@@ -0,0 +1,19 @@
+import { ConvosBaseCommand } from "../../baseCommand.js";
+export default class ConversationAddMembers extends ConvosBaseCommand {
+    static description: string;
+    static strict: boolean;
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        "log-level": import("@oclif/core/interfaces").OptionFlag<"off" | "error" | "warn" | "info" | "debug" | "trace" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "structured-logging": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "app-version": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "env-file": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<"local" | "dev" | "production" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "gateway-host": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}