@rine-network/mastra 0.4.0 → 0.6.0

package/dist/format-groups-list.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The plural group renderers: the caller's own groups, a directory search, and
+ * one group's roster. `format.ts`'s `renderGroup` renders exactly ONE group and
+ * is what `rine_group_inspect` returns; these render pages, one numbered row
+ * each, in the shape `renderInbox`/`renderDiscover` already use.
+ *
+ * A sibling of `format.ts` rather than part of it, for the same reason
+ * `format-groups.ts` is one — `format.ts` holds its ~200-LOC budget.
+ *
+ * Ciphertext cannot leak into the model's context through these renderers: a
+ * group, a directory entry and a roster row carry no message payload at all.
+ *
+ * The types come from `@rine-network/sdk` directly: the SDK exports them
+ * alongside their schemas, so there is nothing here to re-derive.
+ */
+import { type AgentHandleMap, type GroupMember, type GroupRead, type GroupSummary } from "@rine-network/sdk";
+/**
+ * What a group with no conversation renders instead of an id.
+ *
+ * A group's thread is created lazily on its first post, so a null
+ * `conversation_id` is the fact "nothing has been said in this group yet" — not
+ * an error, not a refusal, and not a missing field. The clause is never omitted
+ * on null: a model that sees it on some rows and not others reads the absence
+ * as a rendering fault rather than as a fact about the group.
+ *
+ * `format.ts`'s `renderGroup` imports it from here so the two renderers cannot
+ * tell a model two different things about the same group. The same sentence is
+ * printed by the CLI, crewai, langchain, hermes and eve; it is restated per
+ * package because there is no runtime module all of them import.
+ */
+export declare const NO_CONVERSATION = "(none \u2014 nothing has been said in this group yet)";
+/**
+ * What a group renders in place of an agent list when this org holds no seat.
+ *
+ * The group list is ORG-scoped — it reports every group any agent of this org
+ * is in — so a row on it was never proof that the agent this host is acting as
+ * may post there. The empty list is that proof's absence stated plainly: no
+ * agent of this org is seated, and a send into the group would be refused.
+ *
+ * Never omitted, for the reason `NO_CONVERSATION` gives above: a clause a model
+ * sees on some rows and not others reads as a rendering fault rather than as a
+ * fact about the group. Restated per package because there is no runtime module
+ * all seven rendering surfaces import — though this package and its twin do
+ * share one (`@rine-network/sdk`), so the day either reworded its row would be
+ * the day the sentence belongs there instead.
+ *
+ * Pinned meanwhile: `tests/test_client-server-contract_group0.py` compares the
+ * four declared copies against `rine.group_words.NO_OWN_AGENTS`, which the
+ * three Python surfaces import, so a reword in one package fails there rather
+ * than shipping two answers to one question.
+ */
+export declare const NO_OWN_AGENTS = "(none \u2014 no agent of your org is seated in this group)";
+/**
+ * The seated-agents clause, from the one place both renderers read it.
+ *
+ * `format.ts`'s `renderGroup` calls this too, so the row and the single-group
+ * view cannot tell a model two different things about the same group — the same
+ * reason `NO_CONVERSATION` is imported there rather than retyped.
+ *
+ * Each id renders as its HANDLE. The three cases, and why a name is never one
+ * of them, are stated once on `AgentHandleMap` in the SDK
+ * (`rine-ts-sdk/src/resources/agent-handles.ts`); this renderer is one of the
+ * four that follow them. In short: a known id prints its handle, an unknown one
+ * prints itself, an empty list prints {@link NO_OWN_AGENTS}. A model handed a
+ * UUID cannot tell which of its agents it names — that is the whole reason
+ * handle resolution exists here — but a UUID is still addressable, so an
+ * unresolved id is degraded, not lost.
+ *
+ * `handles` is omitted whenever the org's agent list could not be read; that is
+ * case 2 for every id, and it is why nothing here throws.
+ *
+ * `undefined` is accepted on purpose. `GroupReadSchema` defaults the field to
+ * `[]`, so a parsed row always has one — but a row that never went through that
+ * parse (a hand-built object, a fake) has nothing, and a renderer whose job is
+ * to state an absence must not throw on one.
+ */
+export declare function renderOwnAgents(ids: readonly string[] | undefined, handles?: AgentHandleMap): string;
+/**
+ * How this package names a group's regime in one field, for a LIST ROW.
+ *
+ * One definition for the row, and for the row only. It is NOT what the create
+ * confirmation head asks: what a freshly created group runs is decided from the
+ * create RESULT, by `createdGroupMls` in `@rine-network/core`, because the row
+ * alone cannot tell a founded group from an unfounded one. `renderGroup`'s
+ * `[OK]` line re-derives its first clause from the predicates directly and has
+ * never called this either. So a reword here reaches this row and nothing else,
+ * and a reword in either of those two does not reach this row.
+ *
+ * The init window is reported as MLS because sends into it already are MLS, and
+ * a field that said "sender-key" there would state the opposite of what is
+ * happening. The window's own distinction is `rine_group_inspect`'s to make.
+ *
+ * A group created to run MLS whose ratchet tree was never founded really does
+ * carry sender-key traffic, so it names sender keys — and says the rest of the
+ * answer, because that row is otherwise field-for-field an open group's and
+ * nothing else on the page can tell the two apart. The parenthesis carries NO
+ * comma: the row below is comma-separated, which is the same reason its last
+ * clause opens with `; `. The whole sentence lives in `rine_group_inspect`; a
+ * list row is not the place for it.
+ */
+export declare function groupModeLabel(g: GroupRead): string;
+/**
+ * A numbered list of the groups this org's agents are seated in, or the
+ * empty-state line.
+ *
+ * The list is org-scoped, and each row's `your agents` clause names which of
+ * this org's agents are seated in that group — an empty clause means none of
+ * them is, and a send into that group would be refused. The clause names them
+ * by handle because that is the spelling `rine_whoami` prints, so the two
+ * outputs can be read against each other — a UUID matched nothing this surface
+ * had ever shown the model. What neither tool says is which agent this host is
+ * acting AS: `WhoAmI` carries no such field and `renderWhoAmI` marks no row, so
+ * in a multi-agent org that still has to come from the host's own config (the
+ * `agent` this client was built with, which may itself have been given as a
+ * UUID).
+ */
+export declare function renderGroups(items: readonly GroupRead[], handles?: AgentHandleMap): string;
+/**
+ * A numbered list of publicly listed groups, or the empty-state line.
+ *
+ * The header says what the list IS. `GET /directory/groups` is an
+ * unauthenticated public-visibility scan across every org and carries no
+ * identity at all, so nothing on a row can say whether this agent holds a seat
+ * in that group — while `renderGroups` above prints near-identical rows that
+ * end with exactly that. Two numbered lists told apart by two words in a header
+ * is not enough, so this one says the difference outright.
+ *
+ * It names no verb: the header states what the caller is looking at, and which
+ * tool to reach for next is the tool description's sentence, not this one's.
+ */
+export declare function renderGroupSummaries(items: readonly GroupSummary[]): string;
+/**
+ * A numbered roster, or the empty-state line.
+ *
+ * The roster is members only. An invitation and a nomination hold a seat
+ * against the group's ceiling without appearing here — `rine_group_requests`
+ * is what reports those — so a roster shorter than the ceiling suggests is not
+ * a gap in this list.
+ *
+ * Every member is listed, from every org. Nothing here filters on whose agent
+ * a row is; `(yours)` marks this org's rows and takes none away.
+ */
+export declare function renderRoster(items: readonly GroupMember[]): string;

package/dist/format-groups.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The admission strings this package composes itself: the outstanding list
+ * `rine_group_requests` renders, the line `rine_group_vote` returns, the refusal
+ * a vote from outside the electorate reads as, and what `rine_group_reclaim`
+ * did to the ratchet tree.
+ *
+ * They sit beside `format.ts`'s group renderers rather than in the tool module,
+ * in a sibling of their own for the same reason `schemas-groups.ts` is one —
+ * `format.ts` holds its ~200-LOC budget. Their wording is fixed across every
+ * surface that ships these verbs, so a vote reads the same here, from the CLI,
+ * and from the Python connectors.
+ *
+ * Every other group verb returns a sentence composed once, further in: a removal
+ * and a leave return `result.message` from the SDK, a sync returns
+ * `describeMlsRecovery`, and the reclamation half below returns
+ * `describeMlsReclamation`. The rest have no such sentence to return.
+ */
+import { type MlsAdmissionResult } from "@rine-network/sdk";
+import type { JoinRequestRead, VoteResponse } from "./types.js";
+/**
+ * The outstanding admissions of one group under one filter, oldest first.
+ *
+ * Sorted here rather than trusted from the wire: the ordering is what every
+ * surface promises a voter, and the Python connectors sort too — so leaving it
+ * to the server would make the same list read differently by stack.
+ *
+ * `groupRef` is the reference the caller gave, not a UUID it never named.
+ */
+export declare function renderRequests(groupRef: string, outstanding: string, rows: readonly JoinRequestRead[]): string;
+/**
+ * The outcome of one vote.
+ *
+ * The leaf-and-Welcome sentence is conditioned on `mls_seated`, not on the
+ * server's `approved`. The seat the SDK attempts inside `vote()` is
+ * best-effort: a group running Sender Keys has no ratchet tree to mint a leaf
+ * in, and an add commit that fails is logged and swallowed so the vote can
+ * still be reported. On the status alone this claimed a Welcome for every vote
+ * that minted none — which is exactly the failure the seat exists to prevent,
+ * reported as a success.
+ *
+ * `invited` is the fourth answer a carried vote gives, and it is named rather
+ * than left to the bare status line. A member may nominate an agent into a
+ * `majority` or `unanimity` group, and the electorate can carry that nomination
+ * before the nominee has asked for anything; the request then resolves to a
+ * spendable invitation instead of a seat, so the agent that was never asked
+ * still decides for itself. Reporting it as "approved" would claim a membership
+ * that does not exist, and falling through to the bare line would leave a model
+ * reading a status word no other outcome uses.
+ */
+export declare function renderVote(groupRef: string, result: VoteResponse): string;
+/**
+ * A vote the electorate rule refused, as something the model can act on —
+ * or `undefined` for any other failure, which the shared `formatError` owns.
+ *
+ * Branching on the server's error CODE, never on its sentence: three 403s on
+ * this route mean different things, and the detail is written for an operator
+ * and is rewritten whenever the wording improves. `no vote was recorded` is
+ * stated first because that is the fact an agent would otherwise have to infer
+ * from a status code, and a retry of the same call cannot change any of them.
+ *
+ * There is deliberately no `BarUnreachable` arm. `bar_unreachable` and
+ * `electorate_empty` are one refusal and two facts about the row: the route
+ * raises `ElectorateEmptyError` for both, so an arm keyed on the other token
+ * could never run, and the `ElectorateEmpty` sentence is true of both cases.
+ * The two are told apart where they differ — on the row, by
+ * {@link renderRequests}.
+ */
+export declare function renderVoteRefusal(groupRef: string, err: unknown): string | undefined;
+/**
+ * What one reclamation pass seated and what it retired.
+ *
+ * The pass seats first and reclaims second, so the report carries both: a leaf
+ * belonging to an agent this run has just seated is not an orphan, and a
+ * reclamation reported without the seating that preceded it would read as
+ * though the tree had been trimmed against a roster nobody caught up.
+ *
+ * The reclamation half is `describeMlsReclamation` rather than a sentence of
+ * this package's own — one implementation for the four TypeScript surfaces that
+ * report a reclamation, sentence for sentence identical to the Python twin.
+ */
+export declare function renderReclamation(groupRef: string, result: MlsAdmissionResult): string;

package/dist/format.d.ts

@@ -5,11 +5,11 @@
  * with ONE inversion: the group MLS branch reads `[OK]` instead of `[WARN]`,
  * because the TS SDK fully reads/posts MLS + PQ traffic.
  *
- * Invariant I-2: these read ONLY `plaintext` / `decrypt_error` / verification
+ * These read ONLY `plaintext` / `decrypt_error` / verification
  * fields. They NEVER read `encrypted_payload` or any envelope/ciphertext field,
  * so ciphertext can never reach the LLM context through a rendered string.
  */
-import type { ThreadEntry } from "@rine-network/sdk";
+import type { AgentHandleMap, SenderKeyExplainer, ThreadEntry, WhoAmI } from "@rine-network/sdk";
 import type { AgentProfile, AgentSummary, DecryptedMessage, GroupRead, JoinRequestRead } from "./types.js";
 /**
  * Render a both-sided transcript (oldest→newest) for `rine_thread`. Each turn is a
@@ -27,29 +27,65 @@ export declare function verifiedNote(msg: DecryptedMessage): string;
  *   - anything else → compact JSON (last resort)
  */
 export declare function unwrapText(plaintext: unknown): string;
-/** Body of a message: decrypt error if unreadable, else the unwrapped plaintext. */
-export declare function renderMessageBody(msg: DecryptedMessage): string;
+/**
+ * Body of a message: decrypt error if unreadable, else the unwrapped plaintext.
+ *
+ * `explain` is the per-render tiering: pass it on a MULTI render (an inbox,
+ * one call per `renderInbox()`) so the no-sender-key cause explains itself in
+ * full on the first unreadable row and marks every subsequent one. Omit it on
+ * a SINGLE render (`rine_read`, a `rine_send_and_wait` reply) so the one row
+ * keeps the full sentence it already carries — there is nothing to tier when
+ * the caller asked for exactly one message. Every other decrypt-error cause is
+ * untouched either way; classification is the typed `decrypt_error_code`, never
+ * the words in `decrypt_error`.
+ */
+export declare function renderMessageBody(msg: DecryptedMessage, explain?: SenderKeyExplainer): string;
 /** A single message rendered across multiple labeled lines (for `rine_read`). */
 export declare function renderSingleMessage(msg: DecryptedMessage): string;
-/** A numbered inbox list, or the empty-state line. */
+/**
+ * A numbered inbox list, or the empty-state line.
+ *
+ * MULTI render: one explainer per `renderInbox()` call, so the
+ * no-sender-key cause explains itself once for this render and marks every
+ * later row with the same cause — never module-level, never per-row.
+ */
 export declare function renderInbox(items: readonly DecryptedMessage[]): string;
 /** A numbered discovery list, or the empty-state line. */
 export declare function renderDiscover(items: readonly AgentSummary[]): string;
 /** A full agent profile (for `rine_inspect`). */
 export declare function renderProfile(p: AgentProfile): string;
 /**
- * Self-diagnose a group's E2EE mode. Uses `mls_group_id !== null` (the source of
- * truth — the public `EncryptionVersion` enum is MISSING `mls-v1`/`hpke-hybrid-v1`
- * despite the SDK decrypting them), OR the explicit `mls_enabled`/`mls_pending`
- * flags. With MLS support present this is now a CAPABILITY flag, not a failure flag.
+ * This agent's own identity, for `rine_whoami`: the org it belongs to, the
+ * trust tier that org holds, and every handle it can act as.
+ *
+ * Revoked agents are dropped. The route returns them, and naming one here
+ * would offer the model a handle nothing can be sent from or to.
  */
-export declare function groupIsMls(g: GroupRead): boolean;
+export declare function renderWhoAmI(me: WhoAmI): string;
 /**
- * A group rendered for `rine_group_inspect`. THE INVERSION: both the MLS and
- * sender-key branches are `[OK]` — an MLS group is readable/postable here, not a
- * warned-about ceiling (the Python integration printed `[WARN] MLS — cannot
- * read/post`).
+ * A group rendered for `rine_group_inspect`. Every branch renders `[OK]`: an
+ * MLS group is fully readable and postable here.
+ *
+ * Four states, not two. The second is the MLS init window: the group has no
+ * `mls_group_id` to render yet, while the server already accepts nothing but
+ * MLS there, so sends from here are MLS sends. Rendering that window as either
+ * of the other states says the opposite of what is happening.
+ *
+ * The third is a group created to run MLS whose ratchet tree was never founded.
+ * It reads to every other question exactly like the fourth — an ordinary
+ * sender-key group — so it used to fall into it, and the agent was never told
+ * the group had not got the encryption it was created for. It stays `[OK]`:
+ * every claim that marker makes is true here, the group carries traffic, and
+ * only the regime is other than intended. The sentence is the SDK's, and this
+ * surface asks for the no-verb spelling because `rine_group_reclaim` refuses on
+ * mastra — naming a verb that will not act is worse than naming none.
+ *
+ * `your agents` closes the gap the `[OK]` lines leave open: they describe how
+ * the GROUP is run, not whether this org may act in it. A group can be perfectly
+ * readable in the abstract and hold no seat of this org's at all. It names them
+ * by handle when `handles` resolves them — the rule is stated once on
+ * `AgentHandleMap` in the SDK, and `renderOwnAgents` is where it is applied.
  */
-export declare function renderGroup(g: GroupRead): string;
+export declare function renderGroup(g: GroupRead, handles?: AgentHandleMap): string;
 /** A numbered list of the caller's pending group invites, or the empty-state line. */
 export declare function renderInvites(items: readonly JoinRequestRead[]): string;

package/dist/groups-admin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The 5 admission + membership-exit group tools: `rine_group_requests`,
+ * `rine_group_vote`, `rine_group_leave`, `rine_group_sync`,
+ * `rine_group_reclaim`.
+ *
+ * Split from `groups.ts` (which holds the six create/invite/inspect/join tools)
+ * so both files stay inside the ~200-LOC budget. Same idiom: one exported
+ * factory per tool, the SDK does the work, the tool renders.
+ *
+ * `rine_group_leave` is a distinct tool rather than a mode of
+ * `rine_group_remove`, which keeps its own "name your own agent to leave"
+ * behaviour: a leave destroys THIS host's key material, a removal acts on a
+ * third party, and one wrong argument should not turn one into the other.
+ */
+import { type RineToolOpts } from "./tool.js";
+/** `rine_group_requests` — list a group's outstanding admissions. */
+export declare function createRineGroupRequestsTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_requests", unknown>;
+/** `rine_group_vote` — approve or deny one pending join request. */
+export declare function createRineGroupVoteTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_vote", unknown>;
+/** `rine_group_leave` — leave a group this agent is a member of. */
+export declare function createRineGroupLeaveTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_leave", unknown>;
+/** `rine_group_sync` — catch this host's MLS state up with the group. */
+export declare function createRineGroupSyncTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_sync", unknown>;
+/** `rine_group_reclaim` — seat the unseated, then retire the orphaned leaves. */
+export declare function createRineGroupReclaimTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_reclaim", unknown>;

package/dist/groups-admission.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What an admission did, rendered for a model.
+ *
+ * A roster on `rine_group_create`, a batch on `rine_group_invite` and a single
+ * `agentToInvite` are the same operation at three entry points, so they answer
+ * in the same vocabulary. The two plural ones report one outcome per requested
+ * agent, in the order they were named: a batch never fails whole — naming 32
+ * agents and having one of them revoked costs that one agent its seat, not the
+ * other 31 theirs — which is only useful if the caller is told which one.
+ *
+ * Two reports, deliberately not merged. The server's says whether an
+ * **invitation** was minted; the MLS one says whether a ratchet-tree **leaf**
+ * was. An agent can be `invited` in the first and `no_key_package` in the
+ * second: it may join, and it will not be able to read a word until a leaf
+ * exists for it. Collapsing them into one number is how that goes unreported.
+ *
+ * On a `majority` or `unanimity` group the server's answer is `nominated`
+ * rather than `invited`: the invite files a join request the electorate
+ * decides, and no leaf is minted for it. So a nomination has no MLS report at
+ * all — the vote seats the member, and seating is what grants the key.
+ *
+ * The shapes and the reason→sentence maps are `@rine-network/core`'s, so this
+ * module is the rendering and nothing else. A skip used to print the raw wire
+ * token, which read as a refusal on exactly the groups it is not one for: an
+ * open group mints no invitation because it needs none, and `not_applicable`
+ * said nothing about that to a model deciding what to do next.
+ */
+import { type GroupAdmissionReport, type MlsAdmissionResult } from "@rine-network/core";
+/** The refusal when a caller names both invite targets, or neither. */
+export declare const INVITE_TARGET_REQUIRED = "Name exactly one of agentToInvite (one invitation) or agentsToInvite (a batch).";
+/**
+ * What one `agentToInvite` produced, told from the row's own status.
+ *
+ * The singular route answers one row rather than a per-agent report, so the
+ * status word is all a caller has to go on — and `Invited X (status pending)`
+ * both claims something that did not happen and hands a model a word no other
+ * outcome of this tool uses. `invited` and `pending` are therefore named, and
+ * any other status still prints itself rather than being read as one of them.
+ *
+ * `invited` covers two shapes and the sentence names both. A closed group mints
+ * a real invitation row that occupies a ratchet-tree seat until it is accepted
+ * or expires; an open group answers `invited` having minted nothing at all,
+ * because nobody needs an invitation to join one — and it runs sender keys, so
+ * there is no ratchet tree for a seat to sit in.
+ */
+export declare function renderSingularInvite(agentRef: string, groupRef: string, status: string): string;
+/** Per-agent invitation outcomes, one line each, in the order they were named. */
+export declare function renderAdmission(report: GroupAdmissionReport): string;
+/**
+ * What the MLS admission seated, and who is still without a leaf.
+ *
+ * `already_in_group` is filtered out of the unseated list: an agent that
+ * already holds a leaf is what a resumed admission looks like when it has
+ * nothing left to do, not a failure to report.
+ */
+export declare function renderMlsAdmission(mls: MlsAdmissionResult): string;

package/dist/groups-list.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The group domain's three READ tools: `rine_groups` (the groups this agent's
+ * ORG belongs to), `rine_discover_groups` (the public directory) and
+ * `rine_group_roster` (who is in one group).
+ *
+ * A third group module beside `groups.ts` (the six founding/admission tools)
+ * and `groups-admin.ts` (the five admission and exit verbs), so all three hold
+ * the ~200-LOC budget.
+ *
+ * None of them mutates anything, so none carries a `destructiveHint`.
+ * `rine_discover_groups` reads the public directory and needs no membership at
+ * all — it answers for `public`-visibility groups across every org, and returns
+ * no roster for any of them.
+ */
+import { type RineToolOpts } from "./tool.js";
+/** `rine_groups` — the groups this agent's ORG belongs to. */
+export declare function createRineGroupsTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_groups", unknown>;
+/** `rine_discover_groups` — search the public group directory. */
+export declare function createRineDiscoverGroupsTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_discover_groups", unknown>;
+/** `rine_group_roster` — who is in one group, and since when. */
+export declare function createRineGroupRosterTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_roster", unknown>;

package/dist/groups-resolve.d.ts

@@ -0,0 +1,81 @@
+/**
+ * AGENT handle → UUID resolution for the group tools, and the two group
+ * resolutions that are the SDK's rather than this package's.
+ *
+ * 🔴 **Group references are not resolved here any more.** This module
+ * used to answer them from `groups.list()` and a local three-branch match, a
+ * fourth copy of a ladder the SDK now owns: `client.groups.resolveRef` reads a
+ * UUID from the group's own indexed row, a handle from the server's own lookup,
+ * and a bare name from the org's list — and answers with the group's whole
+ * record, so a verb handed the record reads no group of its own. Every group
+ * tool in this package calls that seam directly; nothing re-derives a row at a
+ * call site, and nothing here restates the ladder.
+ *
+ * What is left is the resolution the SDK does NOT do for these tools:
+ *   - an agent → `resolveToUuid` (WebFinger) → its UUID (or pass a UUID
+ *     through). WebFinger — not the public directory — so unlisted agents
+ *     resolve too. This is the same resolution the SDK's own 1:1 send path uses.
+ *   - a group for `rine_group_join`, which is a DIFFERENT ladder and is
+ *     documented as such on {@link resolveJoinGroupUuid}.
+ *
+ * Split out of `groups.ts` so that file holds its six tool definitions and
+ * nothing else; the aggregator (`tools.ts`) never imports this module, so the
+ * shipped-surface gate's `id: "rine_*"` scan is unaffected by the move.
+ */
+import type { AsyncRineClient } from "@rine-network/sdk";
+/**
+ * A tool's answer, led by the item-18 completion notice when there is one.
+ *
+ * 🔴 `resolveToUuid` completes a short handle before it reaches WebFinger —
+ * `kofi@acme` is looked up as `kofi@acme.rine.network` — and answers with the
+ * resolved UUID, never the handle it resolved. The model named one agent and
+ * the call may have invited, removed or seated another, with nothing in the
+ * answer saying so.
+ *
+ * 🔴 A LINE, not a key, and that is this surface's shape rather than a choice:
+ * every tool here declares `strResult`, so there is no object to hang a field
+ * on. `@rine-network/mcp` returns objects and rides the same sentence as a
+ * `handle_completion` key; the CLI writes it to stderr. The BYTES are
+ * {@link handleCompletionNotes}' in `@rine-network/core` and are retyped by
+ * none of the three.
+ *
+ * It leads rather than trails because a model reads the head of a tool result
+ * and acts on it — a caveat about which agent was actually touched is worth
+ * nothing underneath the report of touching them.
+ */
+export declare function withHandleCompletionLine(answer: string, spellings: readonly string[]): string;
+/** Resolve an agent handle/UUID to its `AgentUuid` (UUIDs pass through). */
+export declare function resolveAgentUuid(apiUrl: string, target: string): Promise<import("@rine-network/sdk").AgentUuid>;
+/**
+ * Resolve a batch of agent handles/UUIDs, **in the order they were named**.
+ *
+ * Order is load-bearing: the server answers one admission entry per requested
+ * id in request order, so a report read against a re-ordered list names the
+ * wrong agents. Duplicates are dropped case-insensitively rather than sent
+ * twice, because the second copy of an id comes back `already_invited` and
+ * reads as a failure the caller did not cause.
+ */
+export declare function resolveAgentUuids(apiUrl: string, targets: string[]): Promise<import("@rine-network/sdk").AgentUuid[]>;
+/**
+ * Resolve a group handle/UUID to its `GroupUuid` for `rine_group_join`.
+ *
+ * 🔴 The SDK's own join ladder, not a copy of one, and NOT the ladder the other
+ * twelve group tools take. `client.groups.resolveRef` is scoped at every rung
+ * to a group the ORG already owns or is seated in — which for a join is the one
+ * set the target cannot be in — and this package
+ * used to answer instead from `groups.listInvites()` alone, so the commonest
+ * join there is, a handle read straight off `rine_discover_groups`, was refused
+ * here with the server never having been asked. `resolveRefForJoin` walks the
+ * org's seats, then this agent's invitations, then the public directory,
+ * matching the handle exactly at every rung. What this package could always do
+ * it still does: a BARE name resolves against this agent's own pending
+ * invitations — and against nothing else, because that list is the only set
+ * bounded to groups that have already asked for this agent, and a join cannot
+ * be taken back (`rine-core/src/resolve-group-join.ts` `resolveGroupUuidForJoin`).
+ *
+ * The refusals it throws lead with `Group not found`, which is the phrase
+ * `formatError` (`./errors.ts`) keys on to append this surface's own discover
+ * verbs — the old `No pending invite` wording matched none of its three
+ * spellings, so a refused join carried no remedy at all.
+ */
+export declare function resolveJoinGroupUuid(client: AsyncRineClient, target: string): Promise<import("@rine-network/sdk").GroupUuid>;

package/dist/groups.d.ts

@@ -1,18 +1,24 @@
 /**
- * The 6 group tools: `rine_group_create`, `rine_group_invite`,
+ * 6 of the group domain's 13 tools: `rine_group_create`, `rine_group_invite`,
  * `rine_group_remove`, `rine_group_inspect` (the INVERTED, MLS-capable
- * section), `rine_group_join`, `rine_group_invites`.
+ * section), `rine_group_join`, `rine_group_invites`. The four admission and
+ * exit verbs — `rine_group_requests`, `rine_group_vote`, `rine_group_leave`,
+ * `rine_group_sync` — live in `groups-admin.ts`, so both files hold the
+ * ~200-LOC budget.
  *
- * `group_create` exposes `enableMls` (default true) — the headline differentiator:
- * the SDK best-effort-inits an MLS group and the renderer reports
- * `[OK] MLS`, not a `[WARN]` ceiling.
+ * `group_create` exposes `enableMls` (default true): the SDK best-effort-inits
+ * an MLS group and the renderer reports `[OK] MLS`, not a `[WARN]` ceiling. It
+ * exposes no `visibility` default at all — see `schemas-groups.ts`.
  *
- * The TS SDK's `groups.invite`/`removeMember`/`get` take BRANDED UUIDs
- * positionally (unlike the Python SDK, which resolved handles internally), so
- * invite/remove/inspect/join PRE-RESOLVE handle→UUID here:
- *   - a group → `groups.list()` + local match (`findGroup`),
- *   - an agent → `resolveToUuid` (WebFinger) → its UUID (or pass a UUID through).
- *     WebFinger — not the public directory — so unlisted agents resolve too.
+ * Admission is plural on both write verbs. `members` on create and
+ * `agentsToInvite` on invite each take a batch and report one outcome per
+ * agent, because a batch drops what it cannot admit rather than refusing
+ * everyone, and on an MLS group it mints every new leaf in one commit instead
+ * of one commit each.
+ *
+ * Handle→UUID resolution lives in `groups-resolve.ts` and the admission
+ * rendering in `groups-admission.ts`, so this file is those six tool
+ * definitions and their bodies.
  *
  * `rine_group_join`/`rine_group_invites` close the accept-side gap: an agent
  * invited into a group previously had no tool to join it or see its pending
@@ -21,9 +27,9 @@
 import { type RineToolOpts } from "./tool.js";
 /** `rine_group_create` — create an MLS-by-default coordination group. */
 export declare function createRineGroupCreateTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_create", unknown>;
-/** `rine_group_invite` — invite an agent into a group (handle→UUID pre-resolved). */
+/** `rine_group_invite` — invite one agent or a batch (handle→UUID pre-resolved). */
 export declare function createRineGroupInviteTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_invite", unknown>;
-/** `rine_group_remove` — remove a member; group keys rotate (handle→UUID pre-resolved). */
+/** `rine_group_remove` — evict a member, or leave (handle→UUID pre-resolved). */
 export declare function createRineGroupRemoveTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_remove", unknown>;
 /** `rine_group_inspect` — report a group's E2EE mode + policy (`[OK] MLS` self-diagnosis). */
 export declare function createRineGroupInspectTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_inspect", unknown>;

package/dist/inbound.d.ts

@@ -10,13 +10,21 @@
  *      `createRun({runId})` would otherwise read an empty in-process run-map);
  *      a non-suspended / unknown run ⇒ skip, do NOT ack;
  *   3. build `resumeData` from `plaintext` / `verified` / `from` ONLY
- *      (I-2: JSON-serializable, never ciphertext or an SDK client) — a
+ *      (JSON-serializable, never ciphertext or an SDK client) — a
  *      decrypt-failed message ⇒ skip, do NOT ack;
  *   4. `createRun({runId}).resume({ step, resumeData })` to continue the run.
  *
  * **Lossless-by-default:** every skip path leaves the message in
  * the rine inbox (no `markDelivered`), so a later poll can retry after the run is
  * mapped / key recovery succeeds. The resumer NEVER acks.
+ *
+ * TRUST NOTE: `verified === true` on an inbound message means the envelope
+ * signature checked out AND the signing key it names belongs to the agent the
+ * server authenticated as the sender, so the `from` handed to the resumed step is
+ * the signer of that content. The signature covers the payload only — not this
+ * recipient, and no nonce — so an agent re-sending content it signed earlier
+ * produces a copy that verifies as its own. A workflow that must act on a payload
+ * once keys its own idempotency on `messageId`.
  */
 import type { ThreadMapStore } from "./threadmap.js";
 import type { DecryptedMessage } from "./types.js";
@@ -50,13 +58,13 @@ export interface ResumableRun {
     }): Promise<unknown>;
 }
 /**
- * The JSON-serializable payload handed to the suspended step on resume. I-2:
+ * The JSON-serializable payload handed to the suspended step on resume:
  * plaintext + signature facts ONLY — no ciphertext, no envelope, no SDK client.
  */
 export interface ResumeData {
     /** Unwrapped decrypted body (or a decrypt-error marker), never ciphertext. */
     plaintext: string;
-    /** Whether the inbound message's signature verified. */
+    /** Whether the signature verified as the server-authenticated sender's. */
     verified: boolean;
     /** Sender handle (or agent UUID fallback), for the resumed step's context. */
     from: string;

package/dist/index.d.ts

@@ -11,16 +11,18 @@
  * (client builder, error formatter, renderers, schemas) is exported now so
  * tests and downstream stages can consume it.
  *
- * Import is side-effect-free (I-1): nothing here constructs a client, reads a
+ * Import is side-effect-free: nothing here constructs a client, reads a
  * credential, or opens a socket at module load.
  */
 export { getRineClient } from "./client.js";
 export type { RineClientOpts } from "./client.js";
 export { formatError } from "./errors.js";
 export type { RinePaymentToolOpts, RineToolOpts } from "./tool.js";
-export { createRineCheckInboxTool, createRineReadTool, createRineReplyTool, createRineSendAndWaitTool, createRineSendTool, createRineThreadTool, } from "./messaging.js";
-export { createRineDiscoverTool, createRineInspectTool } from "./discovery.js";
+export { createRineInboxTool, createRineReadTool, createRineReplyTool, createRineSendAndWaitTool, createRineSendTool, createRineThreadTool, } from "./messaging.js";
+export { createRineDiscoverTool, createRineInspectTool, createRineWhoamiTool, } from "./discovery.js";
+export { createRineDiscoverGroupsTool, createRineGroupRosterTool, createRineGroupsTool, } from "./groups-list.js";
 export { createRineGroupCreateTool, createRineGroupInspectTool, createRineGroupInviteTool, createRineGroupInvitesTool, createRineGroupJoinTool, createRineGroupRemoveTool, } from "./groups.js";
+export { createRineGroupLeaveTool, createRineGroupReclaimTool, createRineGroupRequestsTool, createRineGroupSyncTool, createRineGroupVoteTool, } from "./groups-admin.js";
 export { createRineFulfillTool, createRinePayTool } from "./payments.js";
 export { rineToolkit } from "./tools.js";
 export type { RinePaymentsConfig, RineToolDomain, RineToolkitOptions, } from "./tools.js";