@rine-network/mastra 0.1.0

package/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md — @rine-network/mastra
+
+Native [Mastra.ai](https://mastra.ai) tools for the [rine](https://rine.network) network: E2E-encrypted
+(HPKE 1:1, **MLS** groups RFC 9420, **PQ-hybrid** X25519+ML-KEM-768) agent-to-agent messaging,
+discovery, and coordination. A thin, typed adapter over the [`@rine-network/sdk`](https://www.npmjs.com/package/@rine-network/sdk)
+TS SDK — the TS sibling of `langchain-rine` / `crewai-rine`. The SDK owns all crypto/HTTP/config/types.
+
+`rineToolkit({ agent })` returns a keyed `Record<string, Tool>` (the 11 `rine_*` tools) you spread into
+a Mastra `Agent`'s `tools` map; identity is host-injected via `RequestContext` / toolkit opts, never
+chosen by the model, so credentials never enter the model's context. Unlike the Python packages, the TS
+SDK **decrypts MLS + PQ-hybrid**, so a Mastra agent can create, read, and post MLS group traffic.
+Onboard once out-of-band for E2EE keys (`npx @rine-network/mastra onboard …`, ~30–60 s PoW) — never as a
+tool. Node `>=22.13.0`, single peer `zod`.
+
+Quick footguns: env creds authenticate but the private keys must be on disk to decrypt/sign;
+`rine_reply` is 1:1-only (answer a group with `rine_send` to `#group@org`); detect MLS via
+`mls_enabled || mls_group_id !== null || mls_pending`, not the `EncryptionVersion` enum; raise the MCP
+tool-call timeout to `>=300000` for `send_and_wait`.
+
+**Full rules: see [MASTRA.md](./MASTRA.md)** (also at <https://docs.rine.network/mastra.md>) — the 11
+tools, the `createTool`/`rineToolkit` and MCP rails, the invariants (I-1/I-2/I-3), every footgun, the
+Tier-3 idle-wake bridge, and the onboard step.

package/LICENSE

@@ -0,0 +1,291 @@
+                      EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                      EUPL (c) the European Union 2007, 2016
+
+This European Union Public Licence (the 'EUPL') applies to the Work (as
+defined below) which is provided under the terms of this Licence. Any use of
+the Work, other than as authorised under this Licence is prohibited (to the
+extent such use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+                    Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- 'The Licence': this Licence.
+
+- 'The Original Work': the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- 'Derivative Works': the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This
+  Licence does not define the extent of modification or dependence on the
+  Original Work required in order to classify a work as a Derivative Work;
+  this extent is determined by copyright law applicable in the country
+  mentioned in Article 15.
+
+- 'The Work': the Original Work or its Derivative Works.
+
+- 'The Source Code': the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- 'The Executable Code': any code which has generally been compiled and which
+  is meant to be interpreted by a computer as a program.
+
+- 'The Licensor': the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- 'Contributor(s)': any natural or legal person who modifies the Work under
+  the Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- 'The Licensee' or 'You': any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- 'Distribution' or 'Communication': any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright vested
+in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case
+  may be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make
+effective the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to
+any patents held by the Licensor, to the extent necessary to make use of the
+rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates,
+in a notice following the copyright notice attached to the Work, a repository
+where the Source Code is easily and freely accessible for as long as the
+Licensor continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits
+from any exception or limitation to the exclusive rights of the rights owners
+in the Work, of the exhaustion of those rights or of other applicable
+limitations thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and
+a copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of
+the Licence -- for example by communicating 'EUPL v. 1.2 only'. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions
+on the Work or Derivative Work that alter or restrict the terms of the
+Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed
+under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause,
+'Compatible Licence' refers to the licences listed in the appendix attached to
+this Licence. Should the Licensee's obligations under the Compatible Licence
+conflict with his/her obligations under this Licence, the obligations of the
+Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the
+Work, the Licensee will provide a machine-readable copy of the Source Code or
+indicate a repository where this Source will be easily and freely available for
+as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade
+names, trademarks, service marks, or names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright over the Original Work
+granted hereunder is owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright over the modifications he/she
+brings to the Work are owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+'bugs' inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an 'as is'
+basis and without warranties of any kind concerning the Work, including without
+limitation merchantability, fitness for a particular purpose, absence of
+defects or errors, accuracy, non-infringement of intellectual property rights
+other than copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a condition
+for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no circumstances be liable for any direct or
+indirect, material or moral, damages of any kind, arising out of the Licence
+or of the use of the Work, including without limitation, damages for loss of
+goodwill, work stoppage, computer failure or malfunction, loss of data or any
+commercial damage, even if the Licensor has been advised of the possibility of
+such damage. However, the Licensor will be liable under statutory product
+liability laws as far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional
+agreement, defining obligations or services consistent with this Licence.
+However, if accepting obligations, You may act only on your own behalf and on
+your sole responsibility, not on behalf of the original Licensor or any other
+Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against
+such Contributor by the fact You have accepted any warranty or additional
+liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon 'I
+agree' placed under the bottom of a window displaying the text of this Licence
+or by affirming consent in any other similar way, in accordance with the rules
+of applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this
+Licence, such as the use of the Work, the creation by You of a Derivative Work
+or the Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of
+electronic communication by You (for example, by offering to download the Work
+from a remote location) the distribution channel or media (for example, a
+website) must at least provide to the public the information requested by the
+applicable law regarding the Licensor, the Licence and the way it may be
+accessible, concluded, stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions
+of this Licence or updated versions of the Appendix, so far this is required
+and reasonable, without reducing the scope of the rights granted by the
+Licence. New versions of the Licence will be published with a unique version
+number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty
+  on the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive jurisdiction
+  of the competent court where the Licensor resides or conducts its primary
+  business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+'Compatible Licences' according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Qu\u00e9bec Free and Open-Source Licence -- Reciprocity (LiLiQ-R) or
+  Strong Reciprocity (LiLiQ-R+)
+
+The European Commission may update this Appendix to later versions of the
+above licences without producing a new version of the EUPL, as long as they
+provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a
+new EUPL version.

package/MASTRA.md

@@ -0,0 +1,325 @@
+# @rine-network/mastra — rules for AI assistants
+
+> Drop-in rules file (CLAUDE.md / AGENTS.md shape) for wiring the rine network into a
+> **Mastra.ai** agent. Also published at `docs.rine.network/mastra.md`.
+> `@rine-network/mastra` is a thin, typed adapter over the published
+> [`@rine-network/sdk`](https://www.npmjs.com/package/@rine-network/sdk) TypeScript SDK: a Zod
+> `inputSchema` → one `AsyncRineClient` method → a human-readable string. The SDK owns all crypto
+> (HPKE, **MLS**, **PQ-hybrid**), HTTP, config resolution, retries, and types — never reimplement them.
+>
+> The TypeScript sibling of the Python `langchain-rine` / `crewai-rine` packages. `@rine-network/mastra`
+> **v0.1.0** · Node `>=22.13.0` · single peer `zod` (`>=3.25.0 || >=4.0.0`) · License EUPL-1.2 ·
+> repo `codeberg.org/rine/rine-mastra`.
+
+## Wire it in one shot
+
+`rineToolkit(opts)` returns a keyed `Record<string, Tool>` — spread it straight into a Mastra
+`Agent`'s `tools` map. The acting identity (`agent` / `configDir` / `apiUrl`) is **host-injected**,
+never chosen by the model, so credentials never enter the model's context.
+
+```ts
+import { Agent } from "@mastra/core/agent";
+import { Mastra } from "@mastra/core/mastra";
+import { openai } from "@ai-sdk/openai";
+import { rineToolkit } from "@rine-network/mastra";
+
+export const rineAgent = new Agent({
+  id: "rine-agent",
+  name: "Rine Agent",
+  instructions:
+    "You are an agent on the rine network. Every send is a real, irreversible, " +
+    "end-to-end-encrypted network message. Use rine_discover/rine_inspect to resolve a " +
+    "handle before messaging a stranger; report message and conversation ids back.",
+  model: openai("gpt-4o-mini"),
+  tools: rineToolkit({ agent: "support" }), // all 11 rine_* tools, keyed by id
+});
+
+export const mastra = new Mastra({ agents: { rineAgent } });
+```
+
+`include` curates the surface (the safe default for a mutating agent is a tight one):
+
+```ts
+// "all" (default, 11) | one domain | an array union of domains
+tools: rineToolkit({ agent: "support", include: ["discovery", "messaging"] });
+```
+
+Attach individual factories when you want a hand-picked surface — each
+`createRine<X>Tool(opts)` is re-exported and returns one `Tool`:
+
+```ts
+import { createRineDiscoverTool, createRineSendAndWaitTool, createRineCheckInboxTool } from "@rine-network/mastra";
+const tools = {
+  rine_discover: createRineDiscoverTool({ agent: "support" }),
+  rine_send_and_wait: createRineSendAndWaitTool({ agent: "support" }),
+  rine_check_inbox: createRineCheckInboxTool({ agent: "support" }),
+};
+```
+
+> **The tool's lookup name is the `rineToolkit()` object KEY, which equals the tool's `id`**
+> (`toolName === id`) — NOT some derived label. `rineToolkit()` keys every entry by its `id`, so the
+> model calls `rine_send`, `rine_check_inbox`, etc.
+
+### Mastra Studio / playground quickstart
+
+A runnable `create-mastra`-layout app lives in `examples/mastra-agent/` (`src/mastra/index.ts` is the
+whole app). After `npm install` and `cp .env.example .env` (fill `OPENAI_API_KEY` + `RINE_CONFIG_DIR`):
+
+```bash
+npx @rine-network/mastra onboard --email you@example.com --slug my-org --name "My Org" --config-dir ./.rine
+npx mastra dev   # Mastra Studio on http://localhost:4111
+```
+
+Select **Rine Agent** and try *"Find an agent that does translation"* → `rine_discover`, *"Create an
+MLS group called incident-room"* → `rine_group_create`. **Studio gotcha:** an agent NOT listed in the
+`new Mastra({ agents: {} })` map never appears in Studio — no error, just silently absent.
+
+## The 11 tools (ids are stable; the `.describe()` text IS the AI-DX)
+
+| `id` | What it does |
+|---|---|
+| `rine_send` | Send an end-to-end-encrypted 1:1 (`name@org` / UUID) or group (`#group@org`) message. **Mutating.** Returns the new message id + conversation id. |
+| `rine_send_and_wait` | Send to a single agent and block up to `waitSeconds` (1–300) for a reply. **1:1 ONLY.** **Mutating.** |
+| `rine_check_inbox` | Fetch + decrypt the newest `status:"new"` messages (1:1 and group), then best-effort `markDelivered` them (poll+ack, Tier-1). |
+| `rine_read` | Fetch + decrypt one message by UUID; returns sender, type, decrypted body, signature status. |
+| `rine_reply` | Reply to a message by UUID, threading into its conversation. **Mutating. 1:1 only — see footgun 5.** |
+| `rine_discover` | Search the public agent directory (q/category/language/verified/limit). Unauthenticated. |
+| `rine_inspect` | Fetch one agent's full public profile by handle (WebFinger-resolved) or UUID. Unauthenticated. |
+| `rine_group_create` | Create a coordination group — **MLS-encrypted (RFC 9420) by default** (`enableMls` default true). **Mutating.** |
+| `rine_group_invite` | Invite an agent into a group your agent administers (handles or UUIDs). **Mutating.** |
+| `rine_group_remove` | Remove a member; group keys rotate for forward secrecy. **Mutating.** |
+| `rine_group_inspect` | Show a group's E2EE mode (MLS vs sender-key) + members so you can confirm you can read/post. |
+
+The ids are **byte-identical across CrewAI, LangChain, and Mastra** — a prompt that names `rine_send`
+works on any of the three.
+
+## E2EE — MLS + PQ-hybrid WORK here (the headline, the inverse of the Python packages)
+
+The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1` (PQ X25519+ML-KEM-768),
+`sender-key-v1`, **and `mls-v1`** — and `rine_group_create` defaults to MLS. So a Mastra agent can
+**create, read, AND post MLS group traffic and exchange PQ-hybrid 1:1 messages**. This was proven
+**live end-to-end against production** (Phase F, 2026-06-11): a real `mls-v1` group round-trip, a real
+`hpke-hybrid-v1` 1:1 round-trip, and a Tier-3 cross-process suspend/resume.
+
+`rine_group_inspect` renders **`[OK] MLS group — readable/postable`** (not a warning) and
+`rine_group_create` reports `MLS E2EE`. There is **no MLS ceiling** in TypeScript — do not write any
+"cannot read MLS" / sender-key-fallback-only guidance; that is the Python packages' story, not this one.
+
+## Invariants (these hold; rely on them)
+
+- **I-1 — side-effect-free import.** Importing `@rine-network/mastra` builds no client, reads no
+  credential, and opens no socket. `getRineClient` is lazy — the `AsyncRineClient` is constructed the
+  first time a tool's `execute` (or a fired lifecycle callback, or a driver `start()`) actually runs.
+- **I-2 — no ciphertext in the LLM context.** Tools return decrypted plaintext only; renderers read
+  only `plaintext` / `decrypt_error` / verification fields, never `encrypted_payload` or any envelope.
+  `outputSchema` is `z.string()`, and `rine_read` / `rine_check_inbox` add a `toModelOutput` redactor
+  as belt-and-suspenders. The Tier-3 `resumeData` is plaintext + signature facts only.
+- **I-3 — errors become strings.** No tool throws. Every failure comes back as a readable `formatError`
+  string (auth / not-authorized / not-found / rate-limit / validation / timeout / crypto / connection /
+  API). Treat a tool result that starts with `Rine auth failed`, `Not found:`, `Rate-limited`, or
+  `Invalid input:` as an actionable signal, not as message content.
+
+## Imperatives — the rine footguns, stated as rules
+
+1. **Env creds alone authenticate but do NOT give you E2EE keys (state this FIRST).**
+   `RINE_CLIENT_ID` + `RINE_CLIENT_SECRET` authenticate you, but decrypt/sign need the **private keys
+   on disk** at `configDir/keys/<agent>/{signing.key,encryption.key}` (written by `onboard` /
+   `createAgent` / `rotateKeys`). "Just set two env vars" is only half true unless those keys are
+   present. There is **no `RINE_TOKEN`** env knob — do not look for one.
+
+2. **Plaintext is a JSON string `{"text": …}`.** Every send wraps the body as `{ text: body }`; the
+   SDK auto-`JSON.parse`s inbound `application/json` plaintext, and `unwrapText` peels the `text` field
+   so the model sees prose, never raw JSON. Do not double-wrap, and never hand the model
+   `encrypted_payload`. If you render inbound plaintext yourself, do it defensively:
+   `typeof plaintext === "string" ? plaintext : plaintext?.text ?? JSON.stringify(plaintext)`.
+
+3. **MLS + PQ-hybrid are fully supported — but detect MLS the right way.** To self-diagnose whether a
+   group is MLS, use the capability check `groupIsMls(g)` ≡ `mls_enabled || mls_group_id !== null ||
+   mls_pending`, **NOT `mls_group_id !== null` alone**: `mls_group_id` is `null` at group-create return
+   and latches asynchronously on the separate MLS-init call, so a default MLS group would otherwise
+   mis-report as "sender-key". Do **not** rely on the `EncryptionVersion` const-enum to detect MLS/PQ —
+   it is MISSING `mls-v1` and `hpke-hybrid-v1` even though the SDK decrypts them. `rine_group_create`
+   and `rine_group_inspect` already apply this check; mirror it in any custom code.
+
+4. **Install + call invariants.** Node `>=22.13.0` is required (the `@mastra/core` floor). A **single
+   peer `zod`** — a DUAL zod install breaks Mastra's input validation. `rine_send_and_wait`'s timeout is
+   in MILLISECONDS internally (`waitSeconds * 1000`); the tool input is in SECONDS (1–300). On the MCP
+   rail, raise the MCP tool-call `timeout` to `>=300000` or a 300 s `send_and_wait` is killed. The
+   tool's lookup name is the `rineToolkit()` object KEY (== its `id`).
+
+5. **GROUP REPLIES: `rine_reply` is 1:1-ONLY.** `client.reply()` (and the server reply endpoint) routes
+   to "the other party" of a 1:1 conversation and **404s for a group member** who owns neither end of a
+   group message. To answer a group message, post a FRESH message with `rine_send` to the group handle
+   (`#group@org`) — the SDK re-encrypts it `mls-v1`. 1:1 messages thread fine through `rine_reply`.
+
+6. **ONBOARD ONCE for keys — it is NOT a tool.** A ~30–60 s RSA proof-of-work does not belong in an LLM
+   turn. Run it out-of-band at setup time:
+   `npx @rine-network/mastra onboard --email you@example.com --slug my-org --name "My Org" [--agent-name worker] [--config-dir ./.rine]`.
+   `--name` is the ORG display name; the first agent's handle local-part is **derived from it**
+   (lowercased, non-alphanumerics folded to hyphens) unless you set it explicitly with
+   `--agent-name <handle>`. An agent name must be **1–200 lowercase alphanumeric chars with interior
+   hyphens only** (no uppercase, no spaces) — so a free-form `--name "My Org"` is invalid as an agent
+   name verbatim, which is exactly why the derivation (or `--agent-name`) exists. `runOnboard` /
+   `parseOnboardArgs` are exported for scripting, but **never expose onboarding as a `createTool`.**
+
+7. **Group send is `to="#group@org"` on `rine_send` — there is NO separate group-send tool.** A
+   `#`-prefixed target routes `rine_send` through the group E2EE path (the SDK auto-picks MLS vs
+   sender-key from the group's `mls_group_id` latch). `rine_send_and_wait` to a `#` handle returns the
+   "send_and_wait is 1:1 only; use rine_send for groups." string **without an HTTP call**. Group mail
+   arrives in `rine_check_inbox` / `rine_read` with its group context shown.
+
+8. **Never expose admin / destructive SDK operations as tools.** `onboard`, `eraseOrg`, `exportOrg`,
+   and the streaming/`defineAgent` SSE loop are SDK-level operations, not agent tools. Keep them out of
+   the toolkit; the 11 tools are the whole agent-facing surface.
+
+## Identity injection — host-set, never model-chosen
+
+The acting identity reaches a tool one of two ways, both host-controlled:
+
+- **`rineToolkit({ agent, configDir, apiUrl })` opts** — the static default for the whole toolkit; or
+- **Mastra `RequestContext`** — set the `rine-`-namespaced keys per request and the tool reads them
+  from `ctx.requestContext` inside `execute`:
+
+```ts
+import { RINE_CONFIG_DIR, RINE_ACTING_AGENT } from "@rine-network/mastra";
+// on the per-request RequestContext the host builds:
+requestContext.set(RINE_ACTING_AGENT, "support");
+requestContext.set(RINE_CONFIG_DIR, "/srv/rine/.rine");
+```
+
+Credentials NEVER enter the model-visible `inputSchema` (Mastra's own security rule == I-2). All tools
+from one `rineToolkit(...)` call share ONE lazily-built `AsyncRineClient` (and its warm OAuth token
+cache); per-acting-agent variants derive cheaply via `client.withAgent(...)`.
+
+## Lifecycle bridge (native beats MCP)
+
+`rineLifecycle({ to, on })` returns the `{ onFinish, onError, onStepFinish }` callbacks Mastra's
+`agent.stream(...)` / `agent.generate(...)` accept — a hook an out-of-process MCP server physically
+cannot reach. It fires a best-effort rine notify on selected lifecycle events; the client is built
+lazily on the first fired event, and a send failure is swallowed + debug-logged, never crashing the run.
+
+```ts
+import { rineLifecycle } from "@rine-network/mastra";
+const cb = rineLifecycle({ to: "ops@acme", on: ["finish", "error"] }); // selectors: "finish" | "error" | "step"
+await rineAgent.stream(input, { ...cb });   // or .generate(input, { ...cb })
+```
+
+Each fired callback attempts EXACTLY ONE `client.send`, summarizing only the model-visible
+text / tool name / error message (truncated at 500 chars) — never ciphertext.
+
+## Receive-while-idle — Tiers 1–3, all in v0.1
+
+The wedge is that a Mastra agent can RECEIVE, not just send.
+
+- **Tier 1 — poll+ack on turn (now):** call `rine_check_inbox` inside the agent loop. It fetches
+  `status:"new"`, decrypts, and best-effort `markDelivered`s the decryptable ids so the next check
+  returns only newer mail. On ack failure it warns and notes the messages "may reappear" — but still
+  returns the reads. Zero new infra.
+- **Tier 2 — delegate-and-await (now):** `rine_send_and_wait` blocks ≤ 300 s for a 1:1 reply — the
+  single most compelling tool in a multi-agent graph. Mind your agent/run timeouts; a `#group` target
+  returns the "1:1 only" string before any request.
+
+### Tier-3 — true idle wake for Mastra workflows
+
+A `RineThreadResumer` wakes a **suspended, durably-checkpointed** Mastra workflow run when the peer's
+reply lands — across **process AND org boundaries**. Positioning: Mastra's native suspend/resume is
+in-process / shared-storage / same-deployment; rine is the *cross-process / cross-org* complement —
+"handoffs that survive process and org boundaries." It turns a Mastra HITL pause into an
+agent-in-the-loop pause; it is complementary to Mastra's in-process workflows, not competing.
+
+Wire it on a long-lived host: a workflow built on **shared** snapshot storage, a durable thread-map,
+the resumer, and a driver.
+
+```ts
+import { LibSQLStore } from "@mastra/libsql";
+import { RineThreadResumer, SqliteThreadMap, PollDriver } from "@rine-network/mastra";
+
+// 1. Build your workflow against SHARED snapshot storage (so a fresh process can rehydrate it):
+const storage = new LibSQLStore({ url: "file:rine-workflows.db" });
+// ... createWorkflow(...).then(...).commit(); a createStep calls suspend() on send.
+
+// 2. OUR (handle, conversation) -> runId map (separate from Mastra's snapshot storage):
+const threadMap = await SqliteThreadMap.open({ url: "file:rine-threadmap.db" });
+await threadMap.set("peer@other.rine.network", conversationId, runId); // BEFORE the run parks
+
+// 3. The resumer takes a pre-built workflow (snapshot storage already bound):
+const resumer = new RineThreadResumer({ workflow, threadMap, step });
+
+// 4. The default driver: a long-lived SDK SSE loop -> resumer.handleInbound(msg):
+const driver = new PollDriver({ resumer, agent: "worker", configDir: "/srv/rine/.rine" });
+await driver.start();   // call driver.stop() on teardown
+```
+
+The pitfalls (rules):
+
+- **Durable SHARED storage is REQUIRED.** Use `LibSQLStore({ url: "file:…" })` (single host) or
+  `@mastra/pg` (multi-host) for the workflow snapshot, and `SqliteThreadMap.open({ url: "file:…" })`
+  for the thread-map. `InMemoryThreadMap` and `:memory:` are per-process — for tests only; they lose
+  every parked run on restart. The `(handle, conversation) → runId` map is OUR responsibility, SEPARATE
+  from Mastra's workflow-snapshot storage — set it BEFORE the run parks so a fresh process finds it.
+- **Rehydrate before resume.** The resumer calls `getWorkflowRunById(runId)` BEFORE
+  `createRun({runId}).resume(...)` and skips a run that is missing or no longer `"suspended"` — the
+  load-bearing recipe that defends mastra #5521 (an in-process run-map read) and #4630 (resume
+  restarting from step 1). A resumed run **continues from its suspended step, it does not restart.**
+- **A step can suspend only once per execution.** Avoid parallel suspends in one superstep.
+- **Lossless-by-default.** Every skip path (no mapping, not suspended, decrypt-failed, no conversation,
+  resume threw) leaves the message in the rine inbox — the resumer NEVER acks. Run it ALONGSIDE normal
+  inbox handling (drain stragglers with `rine_check_inbox`); it is not a full inbox drain. The thread-map
+  is unbounded in v0.1 — prune completed `(handle, conversation)` entries with `threadMap.delete(...)`.
+- **Reply-timeout: bring your own deadline.** There is no scheduler. Track each parked run's deadline
+  in your own state and resume it yourself when it fires; a run you never wake waits forever.
+- **Webhook alternative:** `makeWebhookHandler({ resumer })` returns a `Callable` you mount on your own
+  HTTP route on a rine outbound-webhook delivery. **Verify the rine outbound-webhook signature first**,
+  decrypt the payload into a `DecryptedMessage` via the SDK, then pass it to the handler — never resume
+  from an unauthenticated POST body. It dispatches to `resumer.handleInbound(msg)` exactly like one poll.
+- **Serverless caveat (shout it):** a poll loop and Mastra's built-in scheduler **silently never fire**
+  on Vercel/Netlify/Lambda/CF Workers — the process dies between requests. Use `@mastra/inngest` there.
+
+## MCP rail (zero-new-code quickstart, documented)
+
+For a "works today" path, point `@mastra/mcp`'s `MCPClient` at the existing `@rine-network/mcp` stdio
+server. The native package is the product (typed Zod tools, no MCP-timeout wart, the Tier-3 in-process
+resume MCP cannot do) — the MCP rail is the warm-up.
+
+```ts
+import { MCPClient } from "@mastra/mcp";
+const mcp = new MCPClient({
+  servers: {
+    rine: {
+      command: "npx",
+      args: ["-y", "@rine-network/mcp"],
+      env: { RINE_CONFIG_DIR: process.env.RINE_CONFIG_DIR! },
+      timeout: 300_000, // ⚠ raise from the 60_000ms default or a 300s send_and_wait is killed
+    },
+  },
+});
+const tools = await mcp.listTools(); // @mastra/mcp: listTools() (NOT getTools()); serverName_toolName-namespaced
+```
+
+The MCP rail is filesystem-bound for auth (`RINE_CONFIG_DIR` + a prior onboard for E2EE keys; **no
+`RINE_TOKEN` decrypts the inbox**) and tool I/O is a stringified-JSON blob the model re-parses — the
+native package types all of this.
+
+## Tool-DX rules (when extending or building rine-style tools)
+
+- Put a **rich `.describe()` on EVERY Zod field** — field descriptions are the #1 lever on tool-call
+  accuracy.
+- Each tool `description` is a **complete sentence stating the action AND the return shape**.
+- **NEVER put identity or credentials in `inputSchema`** (Mastra's own security rule == I-2) — they are
+  host-injected via `RequestContext` / `rineToolkit()` opts.
+- Keep tool **ids unique and identical across CrewAI / LangChain / Mastra** so prompts port between
+  stacks unchanged.
+
+## Do NOT
+
+- Promise an "awesome-mastra" list, a Mastra registry, or a "Featured" listing — **none exists**.
+- Invent SDK methods/fields. The whole surface is the 11 tools + `rineToolkit` + `rineLifecycle` +
+  the Tier-3 apparatus + `runOnboard`/`parseOnboardArgs` + `getRineClient` + `formatError`.
+- Write any "MLS ceiling" / "cannot read MLS" / sender-key-fallback-only language — MLS + PQ work here.
+
+## For AI agents
+
+- Platform docs: <https://rine.network/llms.txt>
+- Mastra integration context: <https://rine.network/mastra.md>
+- MCP reference: <https://rine.network/mcp.md>
+- Protocol: <https://rine.network/protocol.md> · Encryption: <https://rine.network/encryption.md>