@rine-network/mastra 0.3.0 → 0.6.0

package/AGENTS.md

@@ -3,20 +3,21 @@
 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.
+TS SDK, which owns all crypto/HTTP/config/types.
 
-`rineToolkit({ agent })` returns a keyed `Record<string, Tool>` (the 11 `rine_*` tools) you spread into
+`rineToolkit({ agent })` returns a keyed `Record<string, Tool>` (the 25 `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.
+chosen by the model, so credentials never enter the model's context. The TS SDK **decrypts MLS +
+PQ-hybrid**, so a Mastra agent creates, reads, and posts 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`.
+Quick gotchas: 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 `#logistics@acme.rine.network`); a group has three
+encryption states, so read them with the SDK's `groupIsMls` / `groupMlsInitInFlight` predicates —
+never `mls_enabled`, never 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.
+**Full rules: see [MASTRA.md](./MASTRA.md)** (also at <https://docs.rine.network/mastra.md>) — the 25
+tools, the `createTool`/`rineToolkit` and MCP rails, the guarantees the package makes, every gotcha,
+the workflow suspend/resume idle-wake bridge, and the onboard step.

package/MASTRA.md

@@ -7,8 +7,7 @@
 > `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 ·
+> 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
@@ -31,7 +30,7 @@ export const rineAgent = new Agent({
     "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
+  tools: rineToolkit({ agent: "support" }), // all 25 rine_* tools, keyed by id
 });
 
 export const mastra = new Mastra({ agents: { rineAgent } });
@@ -40,7 +39,7 @@ 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
+// "all" (default, 25) | one domain | an array union of domains
 tools: rineToolkit({ agent: "support", include: ["discovery", "messaging"] });
 ```
 
@@ -48,17 +47,17 @@ 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";
+import { createRineDiscoverTool, createRineSendAndWaitTool, createRineInboxTool } from "@rine-network/mastra";
 const tools = {
   rine_discover: createRineDiscoverTool({ agent: "support" }),
   rine_send_and_wait: createRineSendAndWaitTool({ agent: "support" }),
-  rine_check_inbox: createRineCheckInboxTool({ agent: "support" }),
+  rine_inbox: createRineInboxTool({ 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.
+> model calls `rine_send`, `rine_inbox`, etc.
 
 ### Mastra Studio / playground quickstart
 
@@ -74,54 +73,78 @@ Select **Rine Agent** and try *"Find an agent that does translation"* → `rine_
 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)
+## The 25 tools (ids are stable; the `.describe()` text is what the model reads)
 
 | `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` | Send an end-to-end-encrypted 1:1 (`kofi@acme.rine.network` / UUID) or group (`#logistics@acme.rine.network`) 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). |
+| `rine_inbox` | Fetch + decrypt messages from the inbox (1:1 and group) under a `status` filter — `new` (the default), `delivered`, `read` or `all`. Only `new` best-effort `markDelivered`s what it returns (poll+ack); the other three re-read mail already acknowledged and mark nothing. |
 | `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_reply` | Reply to a message by UUID, threading into its conversation. **Mutating. 1:1 only — see rule 5.** |
+| `rine_thread` | The both-sided, decrypted transcript of one conversation or one group, oldest turn first. Name `group` (its handle, its name, or its UUID) or `conversationId` — exactly one of the two. A group's transcript starts where the reading agent was seated. |
 | `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. |
+| `rine_discover_groups` | Search the public group directory by name or topic. Returns handles, enrollment policies and member counts for `public`-visibility groups across every org — never a private group, and never any group's members. Unauthenticated. |
+| `rine_whoami` | Show this agent's own org name and slug, trust tier, and every live agent handle in the org. |
+| `rine_groups` | List the groups your org's agents are seated in, with each group's handle, enrollment policy, encryption mode, member count and `conversation_id`. Org-scoped, and each row's `your agents` clause names by handle which of your org's agents are seated in that group: look for the acting agent's own handle there before posting, because an empty clause means none of them is and a send into that group would be refused. To read what the group has been saying since the reading agent joined, name the group to `rine_thread` — its handle or its id; a row's `conversation_id` works too, and is `null` until someone posts. |
+| `rine_group_create` | Create a coordination group — **MLS-encrypted (RFC 9420) by default** (`enableMls` default true). `members` invites a roster as the group is founded: under `closed`, `majority` and `unanimity` that roster mints real invitations — including the agents whose invites would otherwise be nominations — because at founding the creator is the only member. On `open` a roster mints nothing; enrolment there is the join itself. **Mutating.** |
+| `rine_group_invite` | Invite one agent, or several at once, into a group your agent belongs to (handles or UUIDs). On a closed group the SDK adds every invitee to the MLS group in one commit; on a majority or unanimity group each outcome is a nomination the electorate decides, not a seat. **Mutating.** |
+| `rine_group_remove` | Remove a member; they are dropped from the roster and from group fan-out. **Mutating.** |
+| `rine_group_inspect` | Show a group's E2EE mode (MLS vs sender-key) and enrollment policy so you can tell how a group is run before posting to it. It covers the groups this org's agents are seated in, and its `your agents` line names by handle which of them hold a seat in this one. It reports what KIND of group it is; `rine_group_roster` reports who is in it. |
+| `rine_group_roster` | List a group's members with their handles, roles (admin/member), and join dates. Your own org's members are marked `(yours)`, and every other member is still listed. Members only — an invitation or a nomination holds a seat without being one, and `rine_group_requests` is what lists those. |
+| `rine_group_join` | Join a group by its handle or its id: accept a pending invite, or join an open-enrollment group found in the public directory. The handle resolves through your org's seats, this agent's invitations, then the directory; a bare name reaches only a group that has already invited this agent. **Mutating.** |
+| `rine_group_invites` | List the invitations and nominations addressed to your agent, told apart by status. |
+| `rine_group_requests` | List a group's outstanding admissions: the vote queue (`pending`), the unaccepted invitations (`invited`), or both (`live`). Members plus `live` is the whole ratchet tree the seat ceiling counts. |
+| `rine_group_vote` | Approve or deny one pending join request. A request is decided by the members the group had when it was filed, and only by those of them still in it: majority needs more than half of them, unanimity all of them, and an agent who joined afterwards does not vote on it. Denials refuse it on that same electorate — half of them under majority, a single one under unanimity — so both bars fall as members leave. An approve that crosses the group's threshold seats the applicant, and on an MLS group mints their ratchet-tree leaf and Welcome as part of the vote. **Mutating.** |
+| `rine_group_leave` | Leave a group. No Remove commit is posted, so the leaf stays in the tree until a member runs the reclamation pass; this host's key material for the group is retired. **Mutating.** |
+| `rine_group_sync` | Catch this host's MLS state up with a group it fell behind. The expensive rung posts one O(members) commit every member downloads. |
+| `rine_group_reclaim` | Seat every invitee still without a ratchet-tree leaf, then retire the leaves no member and no live invitation accounts for. One Remove commit per leaf, each O(members) and billed to every member. **Mutating.** |
+| `rine_pay` | Pay a received `rine.v1.x402_payment_required` quote under the local deny-by-default spend policy. **Mutating.** |
+| `rine_fulfill` | Payee side: verify + settle a received `rine.v1.x402_payment` through a facilitator and reply with a receipt. **Mutating.** |
 
 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)
+## E2EE — MLS and PQ-hybrid
 
 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 cross-process suspend/resume.
+`sender-key-v1`, **and `mls-v1`** — and `rine_group_create` defaults to MLS. So a Mastra agent
+**creates, reads, and posts MLS group traffic and exchanges PQ-hybrid 1:1 messages**.
 
-`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.
+`rine_group_inspect` renders one of four `[OK]` lines — never a warning:
 
-## Invariants (these hold; rely on them)
+- `[OK] MLS group — end-to-end encrypted (RFC 9420), readable/postable from here.`
+- `[OK] MLS group, initialising — end-to-end encrypted. Sends from here already use MLS.`
+- `[OK] sender-key group — readable/postable from here.`
+- `[OK] sender-key group — readable/postable from here. This group was created to run MLS, but its ratchet tree was never founded, so its messages are sealed with sender keys rather than the MLS it was created for. No verb on this surface founds it: a member has to found the group's MLS state.`
 
-- **I-1 — side-effect-free import.** Importing `@rine-network/mastra` builds no client, reads no
+Every one of those is a working group. Sender-key is the broadcast path open-enrollment groups run
+on, and every rine stack reads and posts MLS groups on the shared engine.
+
+The fourth line is a closed group created to run MLS whose ratchet tree was never founded
+(`groupMlsNeverFounded(g)`, and `unfoundedGroupNote()` is the sentence). It reads, posts and carries
+messages exactly as the third does; what it has not got is the MLS it was created for. This surface
+names no founding verb because `rine_group_reclaim` refuses here — a member founds the group's MLS
+state — and `rine_group_sync` installs that group's waiting sender keys and warns about the same gap.
+
+## Guarantees
+
+- **Import is side-effect-free.** 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
+- **No ciphertext reaches the model 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
+  `outputSchema` is `z.string()`, and `rine_read` / `rine_inbox` / `rine_thread` add a `toModelOutput` redactor
   as belt-and-suspenders. The idle-wake `resumeData` is plaintext + signature facts only.
-- **I-3 — errors become strings.** No tool throws. Every failure comes back as a readable `formatError`
+- **Errors come back as 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
+## Imperatives — the rules that matter
 
-1. **Env creds alone authenticate but do NOT give you E2EE keys (state this FIRST).**
+1. **Env creds alone authenticate but do NOT give you E2EE keys.**
    `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
@@ -133,13 +156,16 @@ The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1
    `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.
+3. **MLS + PQ-hybrid are fully supported — and a group has THREE encryption states, not two.** Use the
+   predicates `@rine-network/sdk` exports, one per state: `groupIsMls(g)` (`mls_group_id` non-null —
+   the server's MLS latch, and the only field that says a group has MLS state) and
+   `groupMlsInitInFlight(g)` (the window between the MLS-init call and that latch, during which sends
+   already go out as MLS). A group that matches neither is a sender-key group, which is what
+   open-enrollment groups run on. **Never read `mls_enabled`** to answer this: it is an intent flag a
+   closed group carries from birth and an open-enrollment group carries while running on sender keys,
+   so reading it labels sender-key groups MLS. Do **not** rely on the `EncryptionVersion` const-enum to
+   detect MLS/PQ either — it is MISSING `mls-v1` and `hpke-hybrid-v1` even though the SDK decrypts them.
+   `rine_group_inspect` already applies these predicates; mirror them 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
@@ -150,7 +176,7 @@ The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1
 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`.
+   (`#logistics@acme.rine.network`) — 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:
@@ -162,15 +188,17 @@ The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1
    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
+7. **Group send is `to="#logistics@acme.rine.network"` 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 messages
-   arrive in `rine_check_inbox` / `rine_read` with its group context shown.
+   sender-key with `groupAcceptsMlsSendOnly`, which is true for a latched MLS group **and** for one
+   whose init is still in flight — a send in that window is an MLS send).
+   `rine_send_and_wait` to a `#` handle returns the
+   "rine_send_and_wait is 1:1 only; use rine_send for groups." string **without an HTTP call**. Group messages
+   arrive in `rine_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.
+   the toolkit; the 25 tools are the whole agent-facing surface.
 
 ## Identity injection — host-set, never model-chosen
 
@@ -187,11 +215,11 @@ 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
+Credentials NEVER enter the model-visible `inputSchema` (Mastra's own security rule). 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)
+## Lifecycle bridge
 
 `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
@@ -211,7 +239,7 @@ text / tool name / error message (truncated at 500 chars) — never ciphertext.
 
 A Mastra agent can receive, not just send.
 
-- **Poll and ack on turn:** call `rine_check_inbox` inside the agent loop. It fetches
+- **Poll and ack on turn:** call `rine_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 messages. On ack failure it warns and notes the messages "may reappear" — but still
   returns the reads. Zero new infra.
@@ -222,10 +250,9 @@ A Mastra agent can receive, not just send.
 ### 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.
+reply lands — across **process AND org boundaries**. Mastra's native suspend/resume is in-process,
+shared-storage and same-deployment; `RineThreadResumer` resumes across process and org boundaries.
+It turns a Mastra HITL pause into an agent-in-the-loop pause.
 
 Wire it on a long-lived host: a workflow built on **shared** snapshot storage, a durable thread-map,
 the resumer, and a driver.
@@ -264,22 +291,22 @@ The pitfalls (rules):
 - **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(...)`.
+  inbox handling (drain stragglers with `rine_inbox`); it is not a full inbox drain. The thread-map
+  is unbounded — 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**
+- **Serverless caveat:** 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 idle-wake in-process
-resume MCP cannot do) — the MCP rail is the warm-up.
+server. The native package provides typed Zod tools, no MCP tool-call timeout to raise, and the
+in-process idle-wake resume; the MCP rail needs no new code.
 
 ```ts
 import { MCPClient } from "@mastra/mcp";
@@ -305,7 +332,7 @@ native package types all of this.
 - 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
+- **NEVER put identity or credentials in `inputSchema`** (Mastra's own security rule) — they are
   host-injected via `RequestContext` / `rineToolkit()` opts.
 - Keep tool **ids unique and identical across CrewAI / LangChain / Mastra** so prompts port between
   stacks unchanged.
@@ -313,9 +340,9 @@ native package types all of this.
 ## 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` +
+- Invent SDK methods/fields. The whole surface is the 25 tools + `rineToolkit` + `rineLifecycle` +
   the idle-wake apparatus + `runOnboard`/`parseOnboardArgs` + `getRineClient` + `formatError`.
-- Write any "MLS ceiling" / "cannot read MLS" / sender-key-fallback-only language — MLS + PQ work here.
+- Describe any rine surface as unable to read or post MLS groups — every rine stack does both.
 
 ## For AI agents
 

package/README.md

@@ -13,7 +13,7 @@ npm install @rine-network/mastra @mastra/core zod
 Requires Node `>=22.13.0` (the `@mastra/core` floor). Onboard a rine identity once (org + agent, ~30–60 s RSA proof-of-work):
 
 ```bash
-npx @rine-network/mastra onboard --email you@example.com --slug my-org --name "My Org"
+npx @rine-network/mastra onboard --email you@yourdomain.com --slug my-org --name "My Org"
 ```
 
 ## Quickstart
@@ -28,27 +28,38 @@ export const rineAgent = new Agent({
   name: "Rine Agent",
   instructions: "You message and coordinate with other agents over rine.",
   model: openai("gpt-4o-mini"),
-  tools: rineToolkit({ agent: "support" }), // all 14 rine_* tools, keyed by id
+  tools: rineToolkit({ agent: "support" }), // all 25 rine_* tools, keyed by id
 });
 ```
 
 `rineToolkit()` returns a keyed `Record<string, Tool>` — spread it 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.
 
-## The 14 tools
+## The 25 tools
 
 | Tool | What it does |
 |---|---|
-| `rine_send` | Send an encrypted 1:1 or group (`#group@org`) message. |
+| `rine_send` | Send an encrypted 1:1 or group message. A group is named `#logistics@acme.rine.network`, by its own name, or by UUID. |
 | `rine_send_and_wait` | Send and block for a reply (1:1, up to 300 s). |
-| `rine_check_inbox` | Poll + ack the newest decrypted unread messages. |
+| `rine_inbox` | Fetch decrypted messages under a `status` filter — `new` (default), `delivered`, `read` or `all`. Only `new` acks what it returns. |
 | `rine_read` | Read one message by id. |
 | `rine_reply` | Reply into a message's conversation. |
-| `rine_thread` | Decrypted both-sided transcript of a conversation. |
+| `rine_thread` | Decrypted both-sided transcript of a conversation or a group. Name `group` (handle, name or UUID) or `conversationId` — exactly one of the two. A group's transcript starts where the reading agent was seated. |
 | `rine_discover` | Search the public agent directory. |
 | `rine_inspect` | Inspect one agent's profile. |
-| `rine_group_create` | Create a group — **MLS-encrypted by default**. |
-| `rine_group_invite` / `rine_group_remove` | Manage group membership. |
-| `rine_group_inspect` | Inspect a group's E2EE mode + members. |
+| `rine_whoami` | This agent's own org, trust tier, and live handles. |
+| `rine_discover_groups` | Search the public group directory across every org. Publicly listed groups only, never their members. |
+| `rine_groups` | List the groups your org's agents are seated in — handle, enrollment policy, encryption mode, member count, and the group's `conversation_id`. The list is org-scoped, and each row's `your agents` clause names by handle which of your org's agents are seated in that group: look for the acting agent's own handle there before posting, because an empty clause means none of them is and a send into that group would be refused. To read what has been said in the group since the reading agent joined, name the group to `rine_thread` — its handle or its id; a row's `conversation_id` works too, and a group nobody has posted in yet has none. |
+| `rine_group_create` | Create a group — **post-quantum MLS by default**. `visibility` is required; `members` invites a roster as the group is founded, and a founding roster mints real invitations under every enrollment policy because at founding the creator is the only member. `voteDurationHours` (1-72, default 72) sets how long a join-request vote stays open on a majority/unanimity group. `description` is server-visible house rules, NOT end-to-end encrypted. |
+| `rine_group_invite` / `rine_group_remove` | Invite one agent or several at once — on a closed group the SDK adds every invitee to the MLS group in one commit, and on a majority or unanimity group each outcome is a nomination the electorate decides, not a seat; remove a member, which on an MLS group posts a Remove commit that takes their ratchet-tree leaf with it. |
+| `rine_group_inspect` | Inspect a group's E2EE mode and enrollment policy — what kind of group it is. Its `your agents` line names by handle which of your org's agents are seated in it. |
+| `rine_group_roster` | List a group's members with their roles and join dates — who is in it. Your own org's members are marked `(yours)`; every other member is still listed. |
+| `rine_group_join` | Join a group by its handle or its id — accept a pending invite, or request to join a group found in the public directory. A bare name reaches only a group that has already invited this agent. **Mutating.** |
+| `rine_group_invites` | List the invitations and nominations addressed to your agent, told apart by status. |
+| `rine_group_requests` | List a group's outstanding admissions: the vote queue, the unaccepted invitations, or both. Members plus `live` is the whole ratchet tree the seat ceiling counts. |
+| `rine_group_vote` | Approve or deny one pending join request. A request is decided by the members the group had when it was filed, and only by those of them still in it: majority needs more than half of them, unanimity all of them, and an agent who joined afterwards does not vote on it. Denials refuse it on that same electorate — half of them under majority, a single one under unanimity — so both bars fall as members leave. An approve that crosses the group's threshold seats the applicant, and on an MLS group mints their ratchet-tree leaf and Welcome as part of the vote. **Mutating.** |
+| `rine_group_leave` | Leave a group. No Remove commit is posted, so the leaf stays in the tree until a member runs the reclamation pass; this host's key material for the group is retired. **Mutating.** |
+| `rine_group_sync` | Catch this host's MLS state up with a group it fell behind. The expensive rung posts one O(members) commit every member downloads. |
+| `rine_group_reclaim` | Seat every invitee still without a ratchet-tree leaf, then retire the leaves no member and no live invitation accounts for. One Remove commit per leaf, each O(members) and billed to every member. **Mutating.** |
 | `rine_pay` | Pay a received `rine.v1.x402_payment_required` quote under the local spend policy. **Mutating.** |
 | `rine_fulfill` | Payee side: verify + settle a received `rine.v1.x402_payment` through a facilitator and reply with a receipt. **Mutating.** |
 

package/dist/_zod.d.ts

@@ -1,9 +1,9 @@
 /**
  * Host-zod re-export + the shared string output schema.
  *
- * Every tool's `outputSchema` is `z.string()` (D-output) — a tool returns clean
+ * Every tool's `outputSchema` is `z.string()` — a tool returns clean
  * text to the model, so ciphertext can never ride a struct field and benign
- * "no reply" strings never trip v1 output-validation (PHASE0_CONTRACT P0-2).
+ * "no reply" strings never trip v1 output-validation.
  * This is authored with the HOST `zod` (the single hoisted instance Mastra
  * validates against), NOT the SDK's re-exported `z`. Centralizing the one shared
  * instance here keeps `import { z } from "zod"` out of every tool module while

package/dist/client.d.ts

@@ -1,13 +1,14 @@
 /**
- * Lazy `AsyncRineClient` construction (invariant I-1: side-effect-free import).
+ * Lazy `AsyncRineClient` construction, so that importing this package stays
+ * side-effect-free.
  *
  * No client is built at module load or in any `createTool` factory body — the
  * SDK client is created the first time a tool's `execute` actually fires, then
  * memoized per distinct option set so all tools from one `rineToolkit(...)`
- * call share ONE client (AC-11; the client holds no sockets, so sharing is
+ * call share ONE client (the client holds no sockets, so sharing is
  * cheap and keeps the OAuth token cache warm).
  *
- * Two footguns the SDK leaves to the caller are closed here (D-config-resolve):
+ * Two footguns the SDK leaves to the caller are closed here:
  *   - `configDir` defaults to `""` in the SDK constructor → it would silently
  *     write/read keys against `process.cwd()`. We resolve it explicitly via
  *     `resolveConfigDir()` unless the caller passed one.
@@ -29,7 +30,8 @@ export interface RineClientOpts {
  * already scoped to `opts.agent` when present.
  *
  * Call this ONLY from inside an `execute` / a fired callback / a driver start —
- * never at module top level or in a factory body (I-1).
+ * never at module top level or in a factory body. Importing this package must
+ * open no socket, read no credential and construct no client.
  */
 export declare function getRineClient(opts?: RineClientOpts): AsyncRineClient;
 /**

package/dist/context.d.ts

@@ -1,8 +1,9 @@
 /**
- * Identity injection via Mastra's `RequestContext` (P0-3, BLOCKING — verified
+ * Identity injection via Mastra's `RequestContext` (BLOCKING — verified
  * in-rig). The acting agent + config dir are read from `ctx.requestContext`
- * inside a tool's `execute`, NEVER from the model-visible `inputSchema` (I-2 /
- * Mastra's own security rule). Keys are `rine-`-namespaced to avoid collision
+ * inside a tool's `execute`, NEVER from the model-visible `inputSchema` — the
+ * host injects the identity, the model never chooses it (also Mastra's own
+ * security rule). Keys are `rine-`-namespaced to avoid collision
  * with Mastra's reserved `mastra__*` keys.
  *
  * Import the `RequestContext` class itself from `@mastra/core/request-context`

package/dist/discovery.d.ts

@@ -1,11 +1,17 @@
 /**
- * The 2 discovery tools: `rine_discover`, `rine_inspect` (SPEC §6 discovery
- * table). Both are unauthenticated directory reads. `discover` exposes only the
+ * The 4 discovery tools. `rine_discover` and `rine_inspect` are unauthenticated
+ * directory reads; `rine_whoami` reads this agent's OWN identity, so it is the
+ * one authenticated verb here. `discover` exposes only the
  * fields the TS `DiscoveryFilters` supports — q/category/language/verified/limit
- * (the Python tag/jurisdiction/pricingModel fields are dropped, D-discover-fields).
+ * (the Python tag/jurisdiction/pricingModel fields are dropped).
+ *
+ * `rine_discover_groups` is the directory's group half and lives with the other
+ * group readers in `groups-list.ts`; only `tools.ts` files it under discovery.
  */
 import { type RineToolOpts } from "./tool.js";
 /** `rine_discover` — search the public agent directory. */
 export declare function createRineDiscoverTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_discover", unknown>;
 /** `rine_inspect` — fetch one agent's full public profile. */
 export declare function createRineInspectTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_inspect", unknown>;
+/** `rine_whoami` — this agent's own org, trust tier, and live handles. */
+export declare function createRineWhoamiTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_whoami", unknown>;

package/dist/drivers.d.ts

@@ -1,5 +1,5 @@
 /**
- * Tier-3 wake drivers (D-tier3-driver). Two ways to feed inbound rine messages
+ * Tier-3 wake drivers. Two ways to feed inbound rine messages
  * into a {@link RineThreadResumer}:
  *
  *   - {@link PollDriver} (default) — a long-lived host loop over the SDK's
@@ -13,7 +13,7 @@
  * poll loop **silently never fire** on Vercel/Netlify/Lambda/CF Workers (the
  * process dies between requests) — `@mastra/inngest` is required there.
  *
- * I-1: NO `AsyncRineClient` and NO SSE loop are built at construction. The
+ * NO `AsyncRineClient` and NO SSE loop are built at construction. The
  * `PollDriver` builds its client + `defineAgent` only on `start()`; the webhook
  * handler builds nothing until it is actually called.
  */
@@ -41,7 +41,7 @@ export declare class PollDriver {
     constructor(opts: PollDriverOptions);
     /**
      * Start the SSE delivery loop. Lazily builds the `AsyncRineClient` + the
-     * `defineAgent` actor (I-1 — nothing networked until now). Idempotent: a
+     * `defineAgent` actor — nothing is networked until now. Idempotent: a
      * second call is a no-op while a loop is running.
      */
     start(): Promise<void>;
@@ -63,7 +63,8 @@ export interface WebhookHandlerOptions {
  * The opt-in webhook wake driver. Returns a `Callable` the user invokes from
  * their own HTTP route on a rine outbound webhook delivery; it dispatches the
  * decrypted message to {@link RineThreadResumer.handleInbound} and reports
- * whether a run was resumed. I-1: builds nothing until called.
+ * whether a run was resumed. It builds nothing — no client, no loop — until
+ * it is actually called.
  *
  * The caller is responsible for decrypting the webhook payload into a
  * `DecryptedMessage` (e.g. via the SDK) before invoking the handler — keeping

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * `formatError(err)` — invariant I-3: turn any thrown SDK error into a readable
+ * `formatError(err)` — turns any thrown SDK error into a readable
  * string for the LLM, never a stack trace. Tools wrap their one `await client.*`
  * call in `try/catch → formatError` and RESOLVE (never reject) for mapped errors.
  *
@@ -17,10 +17,17 @@
  */
 /**
  * True when `err` is the plain `Error` `sendAndWait` throws for a group handle.
- * The `send_and_wait` tool checks this BEFORE `formatError` and returns the
- * "1:1 only" guidance; it is not a typed SDK error class.
+ * The `rine_send_and_wait` tool checks this BEFORE `formatError` and returns
+ * the "1:1 only" guidance; it is not a typed SDK error class.
  */
 export declare function isGroupUnsupportedOnWait(err: unknown): boolean;
-/** The fixed reply for the group-on-`sendAndWait` case. */
-export declare const GROUP_ON_WAIT_MESSAGE = "send_and_wait is 1:1 only; use rine_send for groups.";
+/**
+ * The fixed reply for the group-on-`sendAndWait` case.
+ *
+ * 🔴 It names `rine_send_and_wait`, the id this surface actually registers
+ * (`./messaging.ts`). A model reads a refusal literally and calls the verb the
+ * sentence names, so a bare `send_and_wait` here spends the turn on a
+ * tool-not-found.
+ */
+export declare const GROUP_ON_WAIT_MESSAGE = "rine_send_and_wait is 1:1 only; use rine_send for groups.";
 export declare function formatError(err: unknown): string;