@wowok/agent-mcp 3.0.4 → 3.0.6

package/dist/schemas/messenger_operation.output.json

@@ -62,9 +62,63 @@
                           "description": "Plaintext hash"
                         },
                         "plaintext": {
-                          "description": "Decrypted plaintext (optional)",
+                          "description": "Decrypted plaintext text. UNDEFINED for attachment messages (zipMetadata present) — their base64 envelope is stripped at the read boundary; read msg.attachment for metadata and use save_attachment for bytes",
                           "type": "string"
                         },
+                        "attachment": {
+                          "description": "Present when this message is an attachment (zipMetadata present). Byte-free descriptor; payload never embedded",
+                          "type": "object",
+                          "properties": {
+                            "kind": {
+                              "type": "string",
+                              "enum": [
+                                "image",
+                                "video",
+                                "audio",
+                                "voice",
+                                "file",
+                                "wts",
+                                "wip"
+                              ],
+                              "description": "Attachment business type: image/video/audio are inline-renderable media; 'voice' is an explicit voice message (webm cannot be auto-distinguished from video); 'file' is a generic document; wts/wip are evidence files"
+                            },
+                            "fileName": {
+                              "type": "string",
+                              "description": "Original file name (transport .zip suffix stripped)"
+                            },
+                            "mimeType": {
+                              "type": "string",
+                              "description": "MIME type inferred from extension or sender-provided"
+                            },
+                            "size": {
+                              "type": "number",
+                              "description": "Payload size in bytes (uncompressed)"
+                            },
+                            "caption": {
+                              "description": "Sender-provided caption (E2EE, inside the encrypted envelope)",
+                              "type": "string"
+                            },
+                            "durationMs": {
+                              "description": "Audio/video duration in milliseconds",
+                              "type": "number"
+                            },
+                            "width": {
+                              "description": "Media width in pixels",
+                              "type": "number"
+                            },
+                            "height": {
+                              "description": "Media height in pixels",
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "kind",
+                            "fileName",
+                            "mimeType",
+                            "size"
+                          ],
+                          "additionalProperties": false
+                        },
                         "replyTo": {
                           "description": "Quoted (replied-to) message reference, if this message replies to a previous one",
                           "type": "object",
@@ -230,9 +284,36 @@
                           "additionalProperties": false
                         },
                         "proof": {
-                          "description": "On-chain proof object address",
+                          "description": "Latest on-chain proof object address (projection of the last entry in proofs; derived at the read boundary for single-value consumers)",
                           "type": "string"
                         },
+                        "proofs": {
+                          "description": "All on-chain proofs anchored for this message, ascending by publish time (one-to-many; a message may be proofed multiple times)",
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "address": {
+                                "type": "string",
+                                "description": "On-chain Proof object address"
+                              },
+                              "network": {
+                                "description": "Network the proof was published on (testnet/mainnet/localnet); absent in legacy local records",
+                                "type": "string"
+                              },
+                              "createdAt": {
+                                "type": "number",
+                                "description": "Local record time (ms)"
+                              }
+                            },
+                            "required": [
+                              "address",
+                              "createdAt"
+                            ],
+                            "additionalProperties": false,
+                            "description": "One on-chain proof anchored for this message"
+                          }
+                        },
                         "decryptError": {
                           "description": "Decryption failure reason",
                           "type": "string"
@@ -295,20 +376,28 @@
               "properties": {
                 "messageId": {
                   "type": "string",
-                  "description": "Message ID"
+                  "description": "Message ID (empty on guard_authorization_required)"
                 },
                 "status": {
-                  "type": "string",
-                  "enum": [
-                    "pending",
-                    "confirmed",
-                    "read",
-                    "failed",
-                    "rejected",
-                    "decrypted",
-                    "decrypt_failed"
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "confirmed",
+                        "read",
+                        "failed",
+                        "rejected",
+                        "decrypted",
+                        "decrypt_failed"
+                      ]
+                    },
+                    {
+                      "type": "string",
+                      "const": "guard_authorization_required"
+                    }
                   ],
-                  "description": "Message status"
+                  "description": "Message status; 'guard_authorization_required' means smart send needs one-click authorization before delivery"
                 },
                 "merkleData": {
                   "description": "Merkle Tree proof data",
@@ -359,6 +448,38 @@
                 "lastReceivedLeafIndex": {
                   "description": "Last received leaf index (for message confirmation)",
                   "type": "number"
+                },
+                "authRequired": {
+                  "description": "True on the guard_authorization_required result shape — show the user ONE confirmation card, then resend via send_message with options.authorize=true",
+                  "type": "boolean"
+                },
+                "network": {
+                  "description": "Network the Passport must be created on (present on guard_authorization_required)",
+                  "type": "string",
+                  "enum": [
+                    "localnet",
+                    "testnet",
+                    "mainnet"
+                  ]
+                },
+                "reason": {
+                  "description": "Why silent passport reuse failed (present on guard_authorization_required)",
+                  "type": "string",
+                  "enum": [
+                    "no_local_passport",
+                    "local_passport_stale"
+                  ]
+                },
+                "hint": {
+                  "description": "Guidance text incl. the auto-friend hint — once the recipient replies, the sender is auto-friended and future messages need no verification",
+                  "type": "string"
+                },
+                "serverError": {
+                  "description": "Original server rejection message",
+                  "type": "string"
+                },
+                "submissions": {
+                  "description": "Guard submission requirements, when a guard demands answers before issuing a Passport (route through onchain_operations gen_passport with info)"
                 }
               },
               "required": [
@@ -387,20 +508,28 @@
               "properties": {
                 "messageId": {
                   "type": "string",
-                  "description": "Message ID"
+                  "description": "Message ID (empty on guard_authorization_required)"
                 },
                 "status": {
-                  "type": "string",
-                  "enum": [
-                    "pending",
-                    "confirmed",
-                    "read",
-                    "failed",
-                    "rejected",
-                    "decrypted",
-                    "decrypt_failed"
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "confirmed",
+                        "read",
+                        "failed",
+                        "rejected",
+                        "decrypted",
+                        "decrypt_failed"
+                      ]
+                    },
+                    {
+                      "type": "string",
+                      "const": "guard_authorization_required"
+                    }
                   ],
-                  "description": "Message status"
+                  "description": "Message status; 'guard_authorization_required' means smart send needs one-click authorization before delivery"
                 },
                 "merkleData": {
                   "description": "Merkle Tree proof data",
@@ -451,6 +580,38 @@
                 "lastReceivedLeafIndex": {
                   "description": "Last received leaf index (for message confirmation)",
                   "type": "number"
+                },
+                "authRequired": {
+                  "description": "True on the guard_authorization_required result shape — show the user ONE confirmation card, then resend via send_message with options.authorize=true",
+                  "type": "boolean"
+                },
+                "network": {
+                  "description": "Network the Passport must be created on (present on guard_authorization_required)",
+                  "type": "string",
+                  "enum": [
+                    "localnet",
+                    "testnet",
+                    "mainnet"
+                  ]
+                },
+                "reason": {
+                  "description": "Why silent passport reuse failed (present on guard_authorization_required)",
+                  "type": "string",
+                  "enum": [
+                    "no_local_passport",
+                    "local_passport_stale"
+                  ]
+                },
+                "hint": {
+                  "description": "Guidance text incl. the auto-friend hint — once the recipient replies, the sender is auto-friended and future messages need no verification",
+                  "type": "string"
+                },
+                "serverError": {
+                  "description": "Original server rejection message",
+                  "type": "string"
+                },
+                "submissions": {
+                  "description": "Guard submission requirements, when a guard demands answers before issuing a Passport (route through onchain_operations gen_passport with info)"
                 }
               },
               "required": [
@@ -479,20 +640,28 @@
               "properties": {
                 "messageId": {
                   "type": "string",
-                  "description": "Message ID"
+                  "description": "Message ID (empty on guard_authorization_required)"
                 },
                 "status": {
-                  "type": "string",
-                  "enum": [
-                    "pending",
-                    "confirmed",
-                    "read",
-                    "failed",
-                    "rejected",
-                    "decrypted",
-                    "decrypt_failed"
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "confirmed",
+                        "read",
+                        "failed",
+                        "rejected",
+                        "decrypted",
+                        "decrypt_failed"
+                      ]
+                    },
+                    {
+                      "type": "string",
+                      "const": "guard_authorization_required"
+                    }
                   ],
-                  "description": "Message status"
+                  "description": "Message status; 'guard_authorization_required' means smart send needs one-click authorization before delivery"
                 },
                 "merkleData": {
                   "description": "Merkle Tree proof data",
@@ -544,6 +713,38 @@
                   "description": "Last received leaf index (for message confirmation)",
                   "type": "number"
                 },
+                "authRequired": {
+                  "description": "True on the guard_authorization_required result shape — show the user ONE confirmation card, then resend via send_message with options.authorize=true",
+                  "type": "boolean"
+                },
+                "network": {
+                  "description": "Network the Passport must be created on (present on guard_authorization_required)",
+                  "type": "string",
+                  "enum": [
+                    "localnet",
+                    "testnet",
+                    "mainnet"
+                  ]
+                },
+                "reason": {
+                  "description": "Why silent passport reuse failed (present on guard_authorization_required)",
+                  "type": "string",
+                  "enum": [
+                    "no_local_passport",
+                    "local_passport_stale"
+                  ]
+                },
+                "hint": {
+                  "description": "Guidance text incl. the auto-friend hint — once the recipient replies, the sender is auto-friended and future messages need no verification",
+                  "type": "string"
+                },
+                "serverError": {
+                  "description": "Original server rejection message",
+                  "type": "string"
+                },
+                "submissions": {
+                  "description": "Guard submission requirements, when a guard demands answers before issuing a Passport (route through onchain_operations gen_passport with info)"
+                },
                 "sent_fields": {
                   "type": "array",
                   "items": {
@@ -596,9 +797,63 @@
                     "description": "Plaintext hash"
                   },
                   "plaintext": {
-                    "description": "Decrypted plaintext (optional)",
+                    "description": "Decrypted plaintext text. UNDEFINED for attachment messages (zipMetadata present) — their base64 envelope is stripped at the read boundary; read msg.attachment for metadata and use save_attachment for bytes",
                     "type": "string"
                   },
+                  "attachment": {
+                    "description": "Present when this message is an attachment (zipMetadata present). Byte-free descriptor; payload never embedded",
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "enum": [
+                          "image",
+                          "video",
+                          "audio",
+                          "voice",
+                          "file",
+                          "wts",
+                          "wip"
+                        ],
+                        "description": "Attachment business type: image/video/audio are inline-renderable media; 'voice' is an explicit voice message (webm cannot be auto-distinguished from video); 'file' is a generic document; wts/wip are evidence files"
+                      },
+                      "fileName": {
+                        "type": "string",
+                        "description": "Original file name (transport .zip suffix stripped)"
+                      },
+                      "mimeType": {
+                        "type": "string",
+                        "description": "MIME type inferred from extension or sender-provided"
+                      },
+                      "size": {
+                        "type": "number",
+                        "description": "Payload size in bytes (uncompressed)"
+                      },
+                      "caption": {
+                        "description": "Sender-provided caption (E2EE, inside the encrypted envelope)",
+                        "type": "string"
+                      },
+                      "durationMs": {
+                        "description": "Audio/video duration in milliseconds",
+                        "type": "number"
+                      },
+                      "width": {
+                        "description": "Media width in pixels",
+                        "type": "number"
+                      },
+                      "height": {
+                        "description": "Media height in pixels",
+                        "type": "number"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "fileName",
+                      "mimeType",
+                      "size"
+                    ],
+                    "additionalProperties": false
+                  },
                   "replyTo": {
                     "description": "Quoted (replied-to) message reference, if this message replies to a previous one",
                     "type": "object",
@@ -764,9 +1019,36 @@
                     "additionalProperties": false
                   },
                   "proof": {
-                    "description": "On-chain proof object address",
+                    "description": "Latest on-chain proof object address (projection of the last entry in proofs; derived at the read boundary for single-value consumers)",
                     "type": "string"
                   },
+                  "proofs": {
+                    "description": "All on-chain proofs anchored for this message, ascending by publish time (one-to-many; a message may be proofed multiple times)",
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "address": {
+                          "type": "string",
+                          "description": "On-chain Proof object address"
+                        },
+                        "network": {
+                          "description": "Network the proof was published on (testnet/mainnet/localnet); absent in legacy local records",
+                          "type": "string"
+                        },
+                        "createdAt": {
+                          "type": "number",
+                          "description": "Local record time (ms)"
+                        }
+                      },
+                      "required": [
+                        "address",
+                        "createdAt"
+                      ],
+                      "additionalProperties": false,
+                      "description": "One on-chain proof anchored for this message"
+                    }
+                  },
                   "decryptError": {
                     "description": "Decryption failure reason",
                     "type": "string"
@@ -811,14 +1093,11 @@
           "properties": {
             "operation": {
               "type": "string",
-              "const": "extract_zip_messages"
+              "const": "save_attachment"
             },
             "result": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "description": "Extracted file paths"
+              "type": "string",
+              "description": "Absolute path of the saved attachment file"
             }
           },
           "required": [
@@ -1556,7 +1835,7 @@
                   "type": "object",
                   "properties": {
                     "allowStrangerMessages": {
-                      "description": "Whether messages from strangers are allowed",
+                      "description": "Whether messages from strangers are allowed (ineffective while the guard list is non-empty)",
                       "type": "boolean"
                     },
                     "maxInboxSize": {
@@ -1642,229 +1921,648 @@
               "const": "pull_messages"
             },
             "result": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "messageId": {
-                    "type": "string",
-                    "description": "Message ID"
-                  },
-                  "fromAddress": {
-                    "type": "string",
-                    "description": "Sender address"
-                  },
-                  "toAddress": {
-                    "type": "string",
-                    "description": "Recipient address"
-                  },
-                  "plaintextHash": {
-                    "type": "string",
-                    "description": "Plaintext hash"
-                  },
-                  "plaintext": {
-                    "description": "Decrypted plaintext (optional)",
-                    "type": "string"
-                  },
-                  "replyTo": {
-                    "description": "Quoted (replied-to) message reference, if this message replies to a previous one",
+              "anyOf": [
+                {
+                  "type": "array",
+                  "items": {
                     "type": "object",
                     "properties": {
                       "messageId": {
                         "type": "string",
-                        "description": "Replied-to message ID (unique within the conversation)"
-                      }
-                    },
-                    "required": [
-                      "messageId"
-                    ],
-                    "additionalProperties": false
-                  },
-                  "guardAddress": {
-                    "description": "Guard address",
-                    "type": "string"
-                  },
-                  "passportAddress": {
-                    "description": "Passport address",
-                    "type": "string"
-                  },
-                  "lastReceivedLeafIndex": {
-                    "description": "Last received leaf index",
-                    "type": "number"
-                  },
-                  "direction": {
-                    "type": "string",
-                    "enum": [
-                      "sent",
-                      "received"
-                    ],
-                    "description": "Message direction"
-                  },
-                  "status": {
-                    "type": "string",
-                    "enum": [
-                      "pending",
-                      "confirmed",
-                      "read",
-                      "failed",
-                      "rejected",
-                      "decrypted",
-                      "decrypt_failed"
-                    ],
-                    "description": "Message status"
-                  },
-                  "msgType": {
-                    "anyOf": [
-                      {
-                        "type": "number",
-                        "const": 1
+                        "description": "Message ID"
                       },
-                      {
-                        "type": "number",
-                        "const": 3
-                      }
-                    ],
-                    "description": "Message type"
-                  },
-                  "leafIndex": {
-                    "description": "Leaf index",
-                    "type": "number"
-                  },
-                  "prevRoot": {
-                    "description": "Previous Merkle Root",
-                    "type": "string"
-                  },
-                  "newRoot": {
-                    "description": "Current Merkle Root",
-                    "type": "string"
-                  },
-                  "serverSignature": {
-                    "description": "Server signature",
-                    "type": "string"
-                  },
-                  "serverTimestamp": {
-                    "description": "Server confirmation timestamp",
-                    "type": "number"
-                  },
-                  "serverPublicKey": {
-                    "description": "Server public key",
-                    "type": "string"
-                  },
-                  "arkConfirmed": {
-                    "description": "ARK confirmation",
-                    "type": "object",
-                    "properties": {
-                      "recipient": {
+                      "fromAddress": {
+                        "type": "string",
+                        "description": "Sender address"
+                      },
+                      "toAddress": {
                         "type": "string",
                         "description": "Recipient address"
                       },
-                      "recipientPublicKey": {
+                      "plaintextHash": {
                         "type": "string",
-                        "description": "Recipient public key"
+                        "description": "Plaintext hash"
                       },
-                      "signature": {
+                      "plaintext": {
+                        "description": "Decrypted plaintext text. UNDEFINED for attachment messages (zipMetadata present) — their base64 envelope is stripped at the read boundary; read msg.attachment for metadata and use save_attachment for bytes",
+                        "type": "string"
+                      },
+                      "attachment": {
+                        "description": "Present when this message is an attachment (zipMetadata present). Byte-free descriptor; payload never embedded",
+                        "type": "object",
+                        "properties": {
+                          "kind": {
+                            "type": "string",
+                            "enum": [
+                              "image",
+                              "video",
+                              "audio",
+                              "voice",
+                              "file",
+                              "wts",
+                              "wip"
+                            ],
+                            "description": "Attachment business type: image/video/audio are inline-renderable media; 'voice' is an explicit voice message (webm cannot be auto-distinguished from video); 'file' is a generic document; wts/wip are evidence files"
+                          },
+                          "fileName": {
+                            "type": "string",
+                            "description": "Original file name (transport .zip suffix stripped)"
+                          },
+                          "mimeType": {
+                            "type": "string",
+                            "description": "MIME type inferred from extension or sender-provided"
+                          },
+                          "size": {
+                            "type": "number",
+                            "description": "Payload size in bytes (uncompressed)"
+                          },
+                          "caption": {
+                            "description": "Sender-provided caption (E2EE, inside the encrypted envelope)",
+                            "type": "string"
+                          },
+                          "durationMs": {
+                            "description": "Audio/video duration in milliseconds",
+                            "type": "number"
+                          },
+                          "width": {
+                            "description": "Media width in pixels",
+                            "type": "number"
+                          },
+                          "height": {
+                            "description": "Media height in pixels",
+                            "type": "number"
+                          }
+                        },
+                        "required": [
+                          "kind",
+                          "fileName",
+                          "mimeType",
+                          "size"
+                        ],
+                        "additionalProperties": false
+                      },
+                      "replyTo": {
+                        "description": "Quoted (replied-to) message reference, if this message replies to a previous one",
+                        "type": "object",
+                        "properties": {
+                          "messageId": {
+                            "type": "string",
+                            "description": "Replied-to message ID (unique within the conversation)"
+                          }
+                        },
+                        "required": [
+                          "messageId"
+                        ],
+                        "additionalProperties": false
+                      },
+                      "guardAddress": {
+                        "description": "Guard address",
+                        "type": "string"
+                      },
+                      "passportAddress": {
+                        "description": "Passport address",
+                        "type": "string"
+                      },
+                      "lastReceivedLeafIndex": {
+                        "description": "Last received leaf index",
+                        "type": "number"
+                      },
+                      "direction": {
                         "type": "string",
-                        "description": "Recipient signature"
+                        "enum": [
+                          "sent",
+                          "received"
+                        ],
+                        "description": "Message direction"
                       },
-                      "timestamp": {
+                      "status": {
+                        "type": "string",
+                        "enum": [
+                          "pending",
+                          "confirmed",
+                          "read",
+                          "failed",
+                          "rejected",
+                          "decrypted",
+                          "decrypt_failed"
+                        ],
+                        "description": "Message status"
+                      },
+                      "msgType": {
+                        "anyOf": [
+                          {
+                            "type": "number",
+                            "const": 1
+                          },
+                          {
+                            "type": "number",
+                            "const": 3
+                          }
+                        ],
+                        "description": "Message type"
+                      },
+                      "leafIndex": {
+                        "description": "Leaf index",
+                        "type": "number"
+                      },
+                      "prevRoot": {
+                        "description": "Previous Merkle Root",
+                        "type": "string"
+                      },
+                      "newRoot": {
+                        "description": "Current Merkle Root",
+                        "type": "string"
+                      },
+                      "serverSignature": {
+                        "description": "Server signature",
+                        "type": "string"
+                      },
+                      "serverTimestamp": {
+                        "description": "Server confirmation timestamp",
+                        "type": "number"
+                      },
+                      "serverPublicKey": {
+                        "description": "Server public key",
+                        "type": "string"
+                      },
+                      "arkConfirmed": {
+                        "description": "ARK confirmation",
+                        "type": "object",
+                        "properties": {
+                          "recipient": {
+                            "type": "string",
+                            "description": "Recipient address"
+                          },
+                          "recipientPublicKey": {
+                            "type": "string",
+                            "description": "Recipient public key"
+                          },
+                          "signature": {
+                            "type": "string",
+                            "description": "Recipient signature"
+                          },
+                          "timestamp": {
+                            "type": "number",
+                            "description": "ARK confirmation time"
+                          }
+                        },
+                        "required": [
+                          "recipient",
+                          "recipientPublicKey",
+                          "signature",
+                          "timestamp"
+                        ],
+                        "additionalProperties": false
+                      },
+                      "createdAt": {
                         "type": "number",
-                        "description": "ARK confirmation time"
+                        "description": "Message creation time (client)"
+                      },
+                      "receivedAt": {
+                        "description": "Local reception time",
+                        "type": "number"
+                      },
+                      "zipMetadata": {
+                        "description": "ZIP file metadata",
+                        "type": "object",
+                        "properties": {
+                          "fileName": {
+                            "type": "string",
+                            "description": "ZIP filename"
+                          },
+                          "fileSize": {
+                            "type": "number",
+                            "description": "File size in bytes"
+                          },
+                          "fileHash": {
+                            "type": "string",
+                            "description": "File SHA256 hash"
+                          },
+                          "contentType": {
+                            "type": "string",
+                            "enum": [
+                              "text",
+                              "zip",
+                              "wts",
+                              "wip"
+                            ],
+                            "description": "Content type"
+                          },
+                          "localCachePath": {
+                            "description": "Local cache path",
+                            "type": "string"
+                          },
+                          "downloadedAt": {
+                            "description": "Download timestamp",
+                            "type": "number"
+                          }
+                        },
+                        "required": [
+                          "fileName",
+                          "fileSize",
+                          "fileHash",
+                          "contentType"
+                        ],
+                        "additionalProperties": false
+                      },
+                      "proof": {
+                        "description": "Latest on-chain proof object address (projection of the last entry in proofs; derived at the read boundary for single-value consumers)",
+                        "type": "string"
+                      },
+                      "proofs": {
+                        "description": "All on-chain proofs anchored for this message, ascending by publish time (one-to-many; a message may be proofed multiple times)",
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "address": {
+                              "type": "string",
+                              "description": "On-chain Proof object address"
+                            },
+                            "network": {
+                              "description": "Network the proof was published on (testnet/mainnet/localnet); absent in legacy local records",
+                              "type": "string"
+                            },
+                            "createdAt": {
+                              "type": "number",
+                              "description": "Local record time (ms)"
+                            }
+                          },
+                          "required": [
+                            "address",
+                            "createdAt"
+                          ],
+                          "additionalProperties": false,
+                          "description": "One on-chain proof anchored for this message"
+                        }
+                      },
+                      "decryptError": {
+                        "description": "Decryption failure reason",
+                        "type": "string"
+                      },
+                      "decryptAttempts": {
+                        "description": "Number of decryption attempts",
+                        "type": "number"
+                      },
+                      "lastDecryptAttemptAt": {
+                        "description": "Last decryption attempt timestamp",
+                        "type": "number"
+                      },
+                      "viewedAt": {
+                        "description": "Timestamp when the current user viewed this message (local storage). If present, indicates the message has been viewed by the user. Only applicable to received messages (direction === 'received')",
+                        "type": "number"
                       }
                     },
                     "required": [
-                      "recipient",
-                      "recipientPublicKey",
-                      "signature",
-                      "timestamp"
+                      "messageId",
+                      "fromAddress",
+                      "toAddress",
+                      "plaintextHash",
+                      "direction",
+                      "status",
+                      "msgType",
+                      "createdAt"
                     ],
-                    "additionalProperties": false
-                  },
-                  "createdAt": {
-                    "type": "number",
-                    "description": "Message creation time (client)"
-                  },
-                  "receivedAt": {
-                    "description": "Local reception time",
-                    "type": "number"
+                    "additionalProperties": false,
+                    "description": "Message object"
                   },
-                  "zipMetadata": {
-                    "description": "ZIP file metadata",
+                  "description": "Single-account mode: messages pulled from server"
+                },
+                {
+                  "type": "array",
+                  "items": {
                     "type": "object",
                     "properties": {
-                      "fileName": {
+                      "account": {
                         "type": "string",
-                        "description": "ZIP filename"
+                        "description": "Account address"
                       },
-                      "fileSize": {
+                      "pulled": {
                         "type": "number",
-                        "description": "File size in bytes"
-                      },
-                      "fileHash": {
-                        "type": "string",
-                        "description": "File SHA256 hash"
+                        "description": "Number of messages pulled and decrypted in this round"
                       },
-                      "contentType": {
-                        "type": "string",
-                        "enum": [
-                          "text",
-                          "zip",
-                          "wts",
-                          "wip"
-                        ],
-                        "description": "Content type"
+                      "messages": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "messageId": {
+                              "type": "string",
+                              "description": "Message ID"
+                            },
+                            "fromAddress": {
+                              "type": "string",
+                              "description": "Sender address"
+                            },
+                            "toAddress": {
+                              "type": "string",
+                              "description": "Recipient address"
+                            },
+                            "plaintextHash": {
+                              "type": "string",
+                              "description": "Plaintext hash"
+                            },
+                            "plaintext": {
+                              "description": "Decrypted plaintext text. UNDEFINED for attachment messages (zipMetadata present) — their base64 envelope is stripped at the read boundary; read msg.attachment for metadata and use save_attachment for bytes",
+                              "type": "string"
+                            },
+                            "attachment": {
+                              "description": "Present when this message is an attachment (zipMetadata present). Byte-free descriptor; payload never embedded",
+                              "type": "object",
+                              "properties": {
+                                "kind": {
+                                  "type": "string",
+                                  "enum": [
+                                    "image",
+                                    "video",
+                                    "audio",
+                                    "voice",
+                                    "file",
+                                    "wts",
+                                    "wip"
+                                  ],
+                                  "description": "Attachment business type: image/video/audio are inline-renderable media; 'voice' is an explicit voice message (webm cannot be auto-distinguished from video); 'file' is a generic document; wts/wip are evidence files"
+                                },
+                                "fileName": {
+                                  "type": "string",
+                                  "description": "Original file name (transport .zip suffix stripped)"
+                                },
+                                "mimeType": {
+                                  "type": "string",
+                                  "description": "MIME type inferred from extension or sender-provided"
+                                },
+                                "size": {
+                                  "type": "number",
+                                  "description": "Payload size in bytes (uncompressed)"
+                                },
+                                "caption": {
+                                  "description": "Sender-provided caption (E2EE, inside the encrypted envelope)",
+                                  "type": "string"
+                                },
+                                "durationMs": {
+                                  "description": "Audio/video duration in milliseconds",
+                                  "type": "number"
+                                },
+                                "width": {
+                                  "description": "Media width in pixels",
+                                  "type": "number"
+                                },
+                                "height": {
+                                  "description": "Media height in pixels",
+                                  "type": "number"
+                                }
+                              },
+                              "required": [
+                                "kind",
+                                "fileName",
+                                "mimeType",
+                                "size"
+                              ],
+                              "additionalProperties": false
+                            },
+                            "replyTo": {
+                              "description": "Quoted (replied-to) message reference, if this message replies to a previous one",
+                              "type": "object",
+                              "properties": {
+                                "messageId": {
+                                  "type": "string",
+                                  "description": "Replied-to message ID (unique within the conversation)"
+                                }
+                              },
+                              "required": [
+                                "messageId"
+                              ],
+                              "additionalProperties": false
+                            },
+                            "guardAddress": {
+                              "description": "Guard address",
+                              "type": "string"
+                            },
+                            "passportAddress": {
+                              "description": "Passport address",
+                              "type": "string"
+                            },
+                            "lastReceivedLeafIndex": {
+                              "description": "Last received leaf index",
+                              "type": "number"
+                            },
+                            "direction": {
+                              "type": "string",
+                              "enum": [
+                                "sent",
+                                "received"
+                              ],
+                              "description": "Message direction"
+                            },
+                            "status": {
+                              "type": "string",
+                              "enum": [
+                                "pending",
+                                "confirmed",
+                                "read",
+                                "failed",
+                                "rejected",
+                                "decrypted",
+                                "decrypt_failed"
+                              ],
+                              "description": "Message status"
+                            },
+                            "msgType": {
+                              "anyOf": [
+                                {
+                                  "type": "number",
+                                  "const": 1
+                                },
+                                {
+                                  "type": "number",
+                                  "const": 3
+                                }
+                              ],
+                              "description": "Message type"
+                            },
+                            "leafIndex": {
+                              "description": "Leaf index",
+                              "type": "number"
+                            },
+                            "prevRoot": {
+                              "description": "Previous Merkle Root",
+                              "type": "string"
+                            },
+                            "newRoot": {
+                              "description": "Current Merkle Root",
+                              "type": "string"
+                            },
+                            "serverSignature": {
+                              "description": "Server signature",
+                              "type": "string"
+                            },
+                            "serverTimestamp": {
+                              "description": "Server confirmation timestamp",
+                              "type": "number"
+                            },
+                            "serverPublicKey": {
+                              "description": "Server public key",
+                              "type": "string"
+                            },
+                            "arkConfirmed": {
+                              "description": "ARK confirmation",
+                              "type": "object",
+                              "properties": {
+                                "recipient": {
+                                  "type": "string",
+                                  "description": "Recipient address"
+                                },
+                                "recipientPublicKey": {
+                                  "type": "string",
+                                  "description": "Recipient public key"
+                                },
+                                "signature": {
+                                  "type": "string",
+                                  "description": "Recipient signature"
+                                },
+                                "timestamp": {
+                                  "type": "number",
+                                  "description": "ARK confirmation time"
+                                }
+                              },
+                              "required": [
+                                "recipient",
+                                "recipientPublicKey",
+                                "signature",
+                                "timestamp"
+                              ],
+                              "additionalProperties": false
+                            },
+                            "createdAt": {
+                              "type": "number",
+                              "description": "Message creation time (client)"
+                            },
+                            "receivedAt": {
+                              "description": "Local reception time",
+                              "type": "number"
+                            },
+                            "zipMetadata": {
+                              "description": "ZIP file metadata",
+                              "type": "object",
+                              "properties": {
+                                "fileName": {
+                                  "type": "string",
+                                  "description": "ZIP filename"
+                                },
+                                "fileSize": {
+                                  "type": "number",
+                                  "description": "File size in bytes"
+                                },
+                                "fileHash": {
+                                  "type": "string",
+                                  "description": "File SHA256 hash"
+                                },
+                                "contentType": {
+                                  "type": "string",
+                                  "enum": [
+                                    "text",
+                                    "zip",
+                                    "wts",
+                                    "wip"
+                                  ],
+                                  "description": "Content type"
+                                },
+                                "localCachePath": {
+                                  "description": "Local cache path",
+                                  "type": "string"
+                                },
+                                "downloadedAt": {
+                                  "description": "Download timestamp",
+                                  "type": "number"
+                                }
+                              },
+                              "required": [
+                                "fileName",
+                                "fileSize",
+                                "fileHash",
+                                "contentType"
+                              ],
+                              "additionalProperties": false
+                            },
+                            "proof": {
+                              "description": "Latest on-chain proof object address (projection of the last entry in proofs; derived at the read boundary for single-value consumers)",
+                              "type": "string"
+                            },
+                            "proofs": {
+                              "description": "All on-chain proofs anchored for this message, ascending by publish time (one-to-many; a message may be proofed multiple times)",
+                              "type": "array",
+                              "items": {
+                                "type": "object",
+                                "properties": {
+                                  "address": {
+                                    "type": "string",
+                                    "description": "On-chain Proof object address"
+                                  },
+                                  "network": {
+                                    "description": "Network the proof was published on (testnet/mainnet/localnet); absent in legacy local records",
+                                    "type": "string"
+                                  },
+                                  "createdAt": {
+                                    "type": "number",
+                                    "description": "Local record time (ms)"
+                                  }
+                                },
+                                "required": [
+                                  "address",
+                                  "createdAt"
+                                ],
+                                "additionalProperties": false,
+                                "description": "One on-chain proof anchored for this message"
+                              }
+                            },
+                            "decryptError": {
+                              "description": "Decryption failure reason",
+                              "type": "string"
+                            },
+                            "decryptAttempts": {
+                              "description": "Number of decryption attempts",
+                              "type": "number"
+                            },
+                            "lastDecryptAttemptAt": {
+                              "description": "Last decryption attempt timestamp",
+                              "type": "number"
+                            },
+                            "viewedAt": {
+                              "description": "Timestamp when the current user viewed this message (local storage). If present, indicates the message has been viewed by the user. Only applicable to received messages (direction === 'received')",
+                              "type": "number"
+                            }
+                          },
+                          "required": [
+                            "messageId",
+                            "fromAddress",
+                            "toAddress",
+                            "plaintextHash",
+                            "direction",
+                            "status",
+                            "msgType",
+                            "createdAt"
+                          ],
+                          "additionalProperties": false,
+                          "description": "Message object"
+                        },
+                        "description": "Newly pulled messages (read boundary applied: attachment payloads stripped into descriptors)"
                       },
-                      "localCachePath": {
-                        "description": "Local cache path",
+                      "error": {
+                        "description": "Per-account pull error; absent on success. Other accounts are unaffected",
                         "type": "string"
-                      },
-                      "downloadedAt": {
-                        "description": "Download timestamp",
-                        "type": "number"
                       }
                     },
                     "required": [
-                      "fileName",
-                      "fileSize",
-                      "fileHash",
-                      "contentType"
+                      "account",
+                      "pulled",
+                      "messages"
                     ],
-                    "additionalProperties": false
-                  },
-                  "proof": {
-                    "description": "On-chain proof object address",
-                    "type": "string"
-                  },
-                  "decryptError": {
-                    "description": "Decryption failure reason",
-                    "type": "string"
-                  },
-                  "decryptAttempts": {
-                    "description": "Number of decryption attempts",
-                    "type": "number"
-                  },
-                  "lastDecryptAttemptAt": {
-                    "description": "Last decryption attempt timestamp",
-                    "type": "number"
+                    "additionalProperties": false,
+                    "description": "Per-account fan-out pull result"
                   },
-                  "viewedAt": {
-                    "description": "Timestamp when the current user viewed this message (local storage). If present, indicates the message has been viewed by the user. Only applicable to received messages (direction === 'received')",
-                    "type": "number"
-                  }
-                },
-                "required": [
-                  "messageId",
-                  "fromAddress",
-                  "toAddress",
-                  "plaintextHash",
-                  "direction",
-                  "status",
-                  "msgType",
-                  "createdAt"
-                ],
-                "additionalProperties": false,
-                "description": "Message object"
-              },
-              "description": "List of messages pulled from server"
+                  "description": "Fan-out mode (allAccounts/accounts set): one entry per account with isolated errors"
+                }
+              ]
             }
           },
           "required": [