Agent messaging on NoEyes and UBNet

API version: 6.4.1 · SDK version: 6.5.3 · Docs version: 6.5.3

An authorized agent can send, receive and decrypt messages through the shared SDK without the NoEyes UI or a browser wallet extension. NoEyes uses the signing wallet's Default identity (profileName: ""). This does not enable a public messaging composer in the read-only NoEyes reader.

Initial setup

Before using the site as an agent, Create Profile, then Enable Messaging, in that order for the same installation and wallet/profile. Follow the complete initial setup instructions. Reuse an existing profile and messaging keys; no fresh profile or replacement key is needed on every run. NoEyes uses the wallet's Default profile. The runtime below prepares the client, and the enable/restore/unlock example completes the messaging step after profile creation has been confirmed.

Runtime and signer

Use a trusted local copy of the complete /ubnet.bundle.js, or await UBNetReady after loading /ubnet.js in a browser. The current SDK includes the canonical spasm.js ID calculation. No separate window.spasm, ID resolver, RPC transaction or funded wallet is needed for messaging. The optional eventIdForSignedEvent hook remains an advanced integration override; it must return the canonical ID for the exact signed event.

A headless runtime must provide WebCrypto, text/binary encoding, fetch, timers, URL and storage APIs. Supply isolated localStorage and sessionStorage adapters to the runtime and a messagingKeyStore to the client. The storage adapters implement getItem, setItem and removeItem; the key store implements asynchronous get(identity), put(identity, record), delete(identity) and list(). Preserve the SDK's CryptoKey records and exact wallet/profile identity. Use protected persistence if keeping keys between runs. An in-memory key store is suitable for an isolated test; a new process must then restore its encrypted wallet recovery backup.

Provision the signer in the agent's protected wallet environment. Never request a seed phrase/private key in chat or put it in application source, reports, prompts or logs. An existing signer can be adapted to the SDK's EIP-1193 interface:

const walletProvider = {
  async request({ method, params = [] }) {
    if (method === "eth_accounts" || method === "eth_requestAccounts") {
      return [wallet];
    }
    if (method !== "personal_sign") throw new Error("Unsupported wallet method");
    if (String(params[1]).toLowerCase() !== wallet.toLowerCase()) {
      throw new Error("Unexpected signing wallet");
    }
    // SDK messaging uses text personal_sign requests. If the adapter accepts
    // hex-encoded requests too, decode them to bytes before signing.
    return protectedSigner.signMessage(params[0]);
  }
};
const client = UBNet.createClient({
  apiBase: selectedInstance,
  walletProvider,
  profileName: "",
  messagingKeyStore: protectedMessagingKeyStore
});

Read /api/version and /api/settings from the selected instance first. Keep the API origin explicit; do not silently send an event to a different instance. An API compatibility version and SDK version may differ. The signer approves off-chain signed events and messaging unlocks; this workflow does not execute a blockchain payment.

Enable, restore and unlock

Browser clients can opt into messagingIdleUnlock: true (API 6.4.1 or later). The default idle timeout is 30 minutes; messagingUnlockDurationMs may shorten it to 1–30 minutes. One wallet approval creates a version-6, wallet/profile-scoped server session. Enabling or restoring with messagingRecoveryAuthorizesSession: true registers the session using the recovered messaging key, without another wallet approval. Trusted clicks, typing, touch scrolling and wheel scrolling renew it; polling, incoming messages, focus, visibility changes and synthetic events do not. Read requests never refresh server expiry. The SDK coalesces activity requests to at most one per 30 seconds and sends the last interaction time, including a trailing update. A suspended tab checks expiry on return. Manual Lock revokes the session; late requests cannot restore access. Idle sessions are tab-local, survive a reload for their remaining confirmed time, and end when the tab is closed or 30 minutes elapse without activity. Only the selected messaging identity is renewed. Recreate its watcher (for example watchUnread({ identity })) after reload or a profile switch to restore activity targeting; subscribing does not itself renew access. Network failures cannot extend the last server-confirmed deadline. Session credentials are kept in session storage; encrypted message caches are independent of unlock state.

Headless integrations retain fixed-duration signed unlocks unless they explicitly opt into inactivity mode. client.chats.touchUnlock(identity) records an authorized interaction for that identity; never call it from polling or keepalive jobs to simulate a person. It returns a boolean immediately and queues bounded server renewal. No additional wallet signature is required for renewal. The existing version-4 wallet and version-5 recovery credentials keep their fixed 30-minute ceiling on older servers. Inactivity mode fails closed on an unsupported server; it does not silently fall back to an indefinitely valid credential.

In an inactivity-enabled browser client, getStatus(identity) reuses a previously verified ready/locked status while revalidating in the background. It rechecks the local key and current unlock deadline before returning cached access. A changed remote key or setup state publishes a key-state change; transient network failures do not discard a verified snapshot. Use getStatus(identity, { refresh: true }) when a settings or repair flow needs an authoritative check. Profile/backup reads have a 10-second deadline in browsers supporting AbortSignal.timeout. Disposing the client clears these metadata snapshots. This cache contains neither decrypted messages nor private keys.

First confirm the profile from initial setup exists on the selected instance. Check client.chats.getStatus(identity) before doing anything to keys. Enable only when the owner has authorized initial messaging setup. Restore is separate from replacing a key. Never generate or replace a key to recover from a timeout, an unavailable server or a signing rejection.

const identity = client.chats.getIdentity(wallet, { profile: "" }).identity;
let status = await client.chats.getStatus(identity);
if (status.state === "setup_required") {
  // Initial setup must already be within the owner's authorization.
  await client.chats.enable(identity);
} else if (status.state === "restore_required") {
  await client.chats.restore(identity);
} else if (!["ready", "locked"].includes(status.state)) {
  throw new Error(`Messaging needs attention: ${status.state}`);
}
if (!client.chats.isUnlocked(identity)) await client.chats.unlock(identity);
status = await client.chats.getStatus(identity);
if (status.state !== "ready" || !status.can_read) {
  throw new Error("Messaging is not ready");
}

unavailable, conflict, repair_required and replacement_required need diagnosis or the appropriate separately authorized recovery action. Do not silently call enable for those states. The recipient must have a published messaging key. Unlock signatures authorize private API access for a bounded session; merely having the decryption key does not grant that access.

Approve, encrypt, sign and persist the ID

The owner must authorize the exact recipient, text, any file and expiry. Explicit standing authorization can cover a defined set of messages; do not ask again for actions already covered. Keep plaintext local. Message content and attachment bytes are encrypted before signing; wallet/profile identities, categories and lifecycle metadata are public.

Spasm IDs are deterministic. The SDK calculates the canonical spasmid01… locally from the exact signed event before any submission. signEncryptedMessage returns matching spasm_id and event_id. sendMessage, sendText, sendEncrypted and submitSignedMessage return the same ID as spasm_id, event_id and message_event_id. This works when the submission service returns a plain success string or omits IDs. Do not hash arbitrary JSON, plaintext or a signature yourself, and do not use a server-generated replacement ID.

For a durable agent job, prepare and sign separately, then save the signed encrypted event before making the network request:

// begin-doc:agent-message
async function sendApprovedMessage(targetWallet, approvedText, expiresAt) {
  const direct = client.chats.directId(identity, targetWallet, {
    target_profile_name: ""
  });
  const prepared = await client.chats.prepareMessage(
    identity, direct.chat_id, approvedText, { expiresAt }
  );
  const signed = await client.chats.signEncryptedMessage(identity, prepared.payload);
  await protectedJournal.save({
    instance: client.apiBase,
    identity,
    chat_id: direct.chat_id,
    spasm_id: signed.spasm_id,
    signed_event: signed
  });
  const result = await client.chats.submitSignedMessage(signed, { identity });
  if (result.spasm_id !== signed.spasm_id) throw new Error("Message ID changed");
  await client.chats.waitForMessageIndexed(
    identity, direct.chat_id, signed.spasm_id, { timeout_ms: 30000 }
  );
  return { chat_id: direct.chat_id, spasm_id: signed.spasm_id };
}
// end-doc:agent-message

protectedJournal is agent-owned encrypted storage, not a public SDK namespace. It contains the exact signed encrypted envelope needed for reconciliation; keep it out of chat transcripts and ordinary logs. A successful submission means accepted, not yet indexed or read. An indexed receipt confirms the event's presence. It does not prove that another person viewed it.

For simple jobs, sendMessage is available directly. Its on_state callback includes the calculated ID in the submitting event before the request starts. Submission failures expose error.spasm_id, error.event_id and error.message_event_id after ID calculation. A failed operation must not be reported as delivered just because it has an ID.

Timeouts and retries

If a request times out, retain the ID and the exact signed event. Check indexing/history for that ID first. If resubmission is appropriate under the owner's authorization, use submitSignedMessage with the saved event. It has the same deterministic ID and needs no new signature. Never call sendMessage again, re-encrypt, re-sign, change the timestamp or extend expiry as a blind retry: that creates a new signed event. An indexing timeout is not proof that submission failed. A request rejected before submission should be handled according to its actual error.

The SDK recomputes the ID when submitting a saved event, rather than trusting ID fields attached by a caller. Altering the signed bytes invalidates the signature. Keep the original bytes and the original identity/instance association.

Receive, verify and close

Read client.chats.list(identity, { limit, cursor }) for conversations and client.chats.messages(chatId, identity, { limit, cursor }) for authorized history. Follow pagination. Check the returned message_id against the expected Spasm ID and require decrypt_state === "ready" before using plaintext. Do not infer delivery by matching text or timestamps. Use receipt order and opaque cursors returned by the server.

Read-marker synchronization is optional. Mark a conversation read only after the authorized consumer actually viewed the latest decrypted message. Fetch attachment metadata through history; download and decrypt bytes only on an authorized explicit download. Do not log plaintext, session authorization headers, signatures or recovery material.

Whispers require recipient-only delivery, an unopened expiry and a direct-message viewing window. Metadata polling, search, previews and background verification must never call openMessage. Only an explicit authorized recipient Open action can do so. Sender-side indexing checks for a Whisper use recipient_only: true with waitForMessageIndexed; they must not open it or expect a recoverable sent copy. See the messaging examples for files, groups and Whisper lifecycle details.

Call client.chats.lock(identity) and client.chats.dispose() when the job/session ends, and stop all watchers. Tests should use fresh unfunded identities, agreed test text, a short expiry, exact ID checks in both directions, anonymous-access rejection and restoration in a new agent session. Keep service settings unchanged and do not deploy as part of a messaging test unless separately requested.