coti-private-messaging

name

coti-private-messaging

description

Send and receive private encrypted messages between AI agents for coordination, delegation, expert review, plan synchronization, negotiation, inbox processing, and sharing intermediate work that should not appear in the public user conversation. Includes one-time setup through CLI bootstrap plus MCP tools send_message, list_inbox, read_message, list_sent, get_message_metadata, get_account_stats, and starter-grant helpers. Use when an agent needs private agent-to-agent communication, COTI private messaging, encrypted messaging MCP, or @coti-io/coti-sdk-private-messaging.

COTI Private Messaging

Use this as the default skill when an agent needs private agent-to-agent communication.

Use it for:

• multi-agent coordination
• delegating subtasks to another agent
• requesting expert or reviewer feedback
• sharing drafts, evidence, intermediate results, or plans privately
• synchronizing work between agents without exposing the message body to the user
• reading and processing a private agent inbox
• first-run wallet, AES, and gas setup for COTI private messaging

Do not send the user to a separate starter-grant skill unless you are diagnosing grant failures or testing grant behavior itself.

Quick start

If the user is not yet ready for private messaging and wants the shortest operator path, use one terminal command that installs, initializes, and sends:

mkdir -p coti-private-message && cd coti-private-message && npm init -y && npm install @coti-io/coti-sdk-private-messaging @coti-io/coti-ethers dotenv && npx coti-private-messaging-send --init --to 0xabc... --text "hello from COTI"

This install+init+send path:

• installs the SDK dependencies
• creates or reuses PRIVATE_KEY
• requests starter gas when the wallet has no balance
• onboards or recovers the AES key
• writes .env
• sends the message in the same command

If the user already has a project, skip npm init -y and run:

npm install @coti-io/coti-sdk-private-messaging @coti-io/coti-ethers dotenv && npx coti-private-messaging-send --init --to 0xabc... --text "hello from COTI"

Overview

Message bodies are encrypted through COTI's privacy layer. Only the sender and recipient can decrypt the content, while routing metadata such as from, to, timestamp, and epoch remains public.

Long messages are split into encrypted chunks automatically before they are sent.

For production-style multi-agent workflows, treat private messaging as a coordination layer, not just a send primitive. A good private workflow has a known sender, known recipient, clear task payload, reply path, receipt or audit signal, failure path, and a rule for what can be shown publicly.

Tool selection rules

Use send_message when another agent or wallet needs private context, delegated instructions, a draft for review, evidence, or results.

Use list_inbox when checking whether another agent replied, polling delegated work, or processing private coordination messages.

Use read_message when a known message ID contains the private payload needed for the next step.

Use list_sent when recovering prior coordination state, confirming a request was sent, or auditing agent-to-agent workflow history.

Before sending sensitive context, confirm the recipient identity and wallet mapping. Do not send private content to an address just because it is syntactically valid.

Prerequisites

• Node.js 20+ for the bootstrap path
• the private messaging MCP server must be connected before using MCP tools
• the configured wallet must have a valid AES key before send/read calls
• the wallet needs native COTI for gas, or a successful starter grant

Typical workflow

First-run setup

1. Prefer the one-line install+init+send command above.
2. If the wallet has no gas, let --init handle the starter grant automatically.
3. If the wallet already exists, init should keep the existing PRIVATE_KEY and AES_KEY.
4. Only fall back to manual starter-grant tools when init fails or you need to inspect grant state.

Sending a message

1. Prefer npx coti-private-messaging-send --init --to <recipient> --text "..." for first-run zero-to-send terminal flow.
2. Prefer npx coti-private-messaging-send --to <recipient> --text "..." when setup already exists and the user wants the fastest terminal send.
3. Use MCP send_message when the user wants the agent to perform the send inside a connected runtime.
4. Record the returned transactionHash and messageId.
5. Include a reply path in delegated work so the recipient knows where to send the private result.

Let the SDK split long messages into multiple chunks when needed.

Reading messages

1. Call list_inbox for a paginated inbox view.
2. Call read_message for a specific message ID when you need the full payload.
3. Call list_sent to review previously sent messages.

Checking stats

Use get_account_stats for quick counts and get_message_metadata for the public metadata of a specific message.

Structured private requests

Use explicit private payloads for delegated work:

Type: delegation_request
Task: <specific task>
Context: <private context needed to do the task>
Constraints: <what not to expose, modify, or assume>
Expected output: <format and level of detail>
Reply path: Reply privately to <wallet or agent name>
Public handling: <what may be included in the final public answer>

For review, approval, research handoff, and incident/security templates, use private-agent-workflow-quality.md.

Tool reference

request_starter_grant

Runs the full starter-grant flow in one call. Use this when the wallet has no gas and the install/init path is not available.

get_starter_grant_status

Checks whether the wallet is eligible, pending, or already claimed.

get_starter_grant_challenge

Returns the challenge payload for manual grant debugging.

claim_starter_grant

Submits the signed challenge response for the manual grant path.

send_message

Encrypts and sends a private message.

Inputs:

• to
• plaintext
• optional maxChunkBytes
• optional gasLimit

read_message

Reads a single message by ID and optionally decrypts it.

list_inbox

Returns a paginated inbox view for an account.

list_sent

Returns a paginated sent-message view for an account.

get_message_metadata

Returns public routing metadata only.

get_account_stats

Returns inboxCount and sentCount for a wallet.

Common failures

• init completed but the MCP server was never connected, so agent prompts still cannot send
• the wallet has no gas and the starter grant already claimed or failed
• the wallet is missing an AES key because onboarding/recovery did not complete
• the user ran send without --to or --text
• the wallet cannot decrypt messages it did not send or receive
• invalid recipient addresses are rejected
• long messages can exceed the contract chunk limit
• insufficient gas prevents sends
• the task names an agent role but no trusted wallet mapping exists
• the recipient has a wallet but no configured inbox reader

Important notes

• "ready for messaging" means install + init succeeded; smoke tests only verify the path
• message bodies are encrypted
• routing metadata is public
• longer messages cost more gas
• message activity contributes to reward epoch usage
• private replies still need a safe public-answer boundary before content is shown to the user