@rine-network/eve 0.3.0 → 0.5.0

package/dist/tool-DeOeMNlK.js

@@ -0,0 +1,618 @@
+import { n as getRineClient, t as actingAgent } from "./client-CXJATA-m.js";
+import { APIConnectionError, AuthenticationError, AuthorizationError, ConfigError, CryptoError, GROUP_ROSTER_LEAD, NO_GROUPS_IN_ORG, NotFoundError, RateLimitError, RineApiError, RineTimeoutError, SchemaValidationError, ValidationError, groupIsMls, groupMlsInitInFlight, groupMlsNeverFounded, senderKeyExplainer, senderKeyExplanation, unfoundedGroupNote } from "@rine-network/sdk";
+import { resolveApiUrl } from "@rine-network/core";
+import { always, never, once } from "eve/tools/approval";
+import { ZodError } from "zod";
+/**
+* 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.
+*/
+const NO_OWN_AGENTS = "(none — 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.
+*/
+function renderOwnAgents(ids, handles) {
+	if (!ids || ids.length === 0) return NO_OWN_AGENTS;
+	return ids.map((id) => handles?.get(id.toLowerCase()) ?? id).join(", ");
+}
+/**
+* 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.
+*/
+function groupModeLabel(g) {
+	if (groupIsMls(g) || groupMlsInitInFlight(g)) return "MLS";
+	if (groupMlsNeverFounded(g)) return "sender-key (MLS never founded)";
+	return "sender-key";
+}
+/**
+* One row of the caller's own groups.
+*
+* The row carries `conversation_id` because this is the only place a model can
+* learn it without having already sent into the group or been handed a raw
+* message row: list the groups, take the id off the row, hand it to
+* `rine_thread`. The key is spelled as the wire field rather than as prose so
+* that the string the model reads and the argument it must fill match.
+*
+* It also names which of this org's agents hold a seat here. `member_count` is
+* the whole roster across every org; this clause is the caller's own share of
+* it, and it is the only thing on an org-scoped row that says whether this org
+* can act in the group at all.
+*
+* That clause closes the row with `; ` rather than `, ` because its VALUE is a
+* comma-joined list. Ending a comma-separated row with a comma-containing field
+* makes the row's field count depend on how many seats the org holds, so a
+* reader that split on `, ` would mis-read multi-seat rows only — and read
+* single-seat ones correctly, which is how that would ship.
+*/
+function renderGroupRow(g, handles) {
+	const mode = groupModeLabel(g);
+	const conversation = g.conversation_id ?? "(none — nothing has been said in this group yet)";
+	const yours = renderOwnAgents(g.member_agent_ids, handles);
+	return `${g.handle} (id ${g.id}) — ${mode}, enrollment ${g.enrollment_policy}, ${g.member_count} member(s), conversation_id=${conversation}; your agents: ${yours}`;
+}
+/**
+* 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).
+*/
+function renderGroups(items, handles) {
+	if (items.length === 0) return "This agent belongs to no groups.";
+	return items.map((g, i) => `${i + 1}. ${renderGroupRow(g, handles)}`).join("\n");
+}
+/**
+* One directory row.
+*
+* No encryption mode: a directory result carries no MLS latch at all, so
+* naming one here would be an invention. `rine_group_inspect` answers that
+* question, and only for a group an agent of this org is already in.
+*/
+function renderGroupSummaryRow(g) {
+	const desc = g.description ? ` — ${g.description}` : "";
+	return `${g.handle} (id ${g.id}) — enrollment ${g.enrollment_policy}, ${g.member_count} member(s)${desc}`;
+}
+/**
+* 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.
+*/
+function renderGroupSummaries(items) {
+	if (items.length === 0) return "No public groups matched.";
+	return [`${items.length} public group(s) found in the directory. A row here is a group that exists, not a group this agent is in:`, ...items.map((g, i) => `${i + 1}. ${renderGroupSummaryRow(g)}`)].join("\n");
+}
+/**
+* One roster row: who they are, what they may do, and since when.
+*
+* The join date renders date-only, and the same way on every surface that
+* renders a roster: `joined_at` is a validated ISO-8601 timestamp on the wire
+* (`GroupMemberSchema`), and a model reading seven surfaces should not have to
+* parse three renderings of the same field.
+*
+* A row of this org's own is suffixed `(yours)`. That is a MARKER, not a
+* filter: every member of the group is listed whichever org holds the seat, and
+* the suffix only says which of them this host could act as.
+*/
+function renderMemberRow(m) {
+	const joined = m.joined_at.slice(0, 10);
+	const own = m.is_own_org ? " (yours)" : "";
+	return `${m.agent_handle ?? m.agent_id} — ${m.role}, joined ${joined}${own}`;
+}
+/**
+* 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.
+*/
+function renderRoster(items) {
+	if (items.length === 0) return "No members reported for this group.";
+	return items.map((m, i) => `${i + 1}. ${renderMemberRow(m)}`).join("\n");
+}
+//#endregion
+//#region src/format.ts
+/**
+* Pure render functions: turn SDK return values into the human-readable strings
+* tools + the channel hand to the LLM / send back over rine.
+*
+* 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.
+*/
+/** One thread turn as a role-tagged line: `[sent] you: …` / `[received] alice@org: …`. */
+function renderThreadLine(e) {
+	const who = e.direction === "sent" ? "you" : e.senderHandle ?? "unknown";
+	return `[${e.direction}] ${who}: ${e.text}`;
+}
+/**
+* Render a both-sided transcript (oldest→newest) for `rine_thread`. Each turn is
+* a role-tagged line; `[unavailable]` text passes through unchanged.
+*/
+function renderThread(entries) {
+	if (entries.length === 0) return "No messages in this conversation.";
+	return entries.map(renderThreadLine).join("\n");
+}
+/** Honest signature note — never claims "verified" for an unverifiable message. */
+function verifiedNote(msg) {
+	return msg.verified ? "signature verified" : `signature ${msg.verification_status}`;
+}
+/**
+* THE PLAINTEXT-IS-JSON FOOTGUN. Outbound sends wrap `{ text: body }`, and the
+* SDK auto-`JSON.parse`s inbound `application/json` plaintext into a structured
+* value. Unwrap defensively so the model sees prose, never raw JSON:
+*   - a string → returned as-is
+*   - `{ text: "…" }` → the inner text
+*   - anything else → compact JSON (last resort)
+*/
+function unwrapText(plaintext) {
+	if (typeof plaintext === "string") return plaintext;
+	if (plaintext === null || plaintext === void 0) return "";
+	if (typeof plaintext === "object") {
+		const text = plaintext.text;
+		if (typeof text === "string") return text;
+	}
+	try {
+		return JSON.stringify(plaintext);
+	} catch {
+		return String(plaintext);
+	}
+}
+/**
+* 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, the webhook
+* channel's own inbound render) 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`.
+*/
+function renderMessageBody(msg, explain) {
+	if (msg.decrypt_error) {
+		const explanation = explain ? senderKeyExplanation(msg) : null;
+		return `[unreadable] ${explain && explanation ? explain(explanation).line : msg.decrypt_error}`;
+	}
+	return unwrapText(msg.plaintext);
+}
+/** Sender label: prefer the human handle, fall back to the agent UUID. */
+function senderLabel(msg) {
+	return msg.sender_handle ?? msg.from_agent_id ?? "unknown sender";
+}
+/** A single message rendered across multiple labeled lines (for `rine_read`). */
+function renderSingleMessage(msg) {
+	const lines = [
+		`Message ${msg.id}`,
+		`from: ${senderLabel(msg)}`,
+		`type: ${msg.type}`
+	];
+	if (msg.group_handle ?? msg.group_id) lines.push(`group: ${msg.group_handle ?? msg.group_id}`);
+	lines.push(`body: ${renderMessageBody(msg)}`);
+	lines.push(`(${verifiedNote(msg)})`);
+	return lines.join("\n");
+}
+/** One inbox row: compact single line keyed by id + sender + body preview. */
+function renderInboxRow(msg, explain) {
+	const from = senderLabel(msg);
+	const where = msg.group_handle ? ` in ${msg.group_handle}` : "";
+	return `${msg.id} from ${from}${where}: ${renderMessageBody(msg, explain)} (${verifiedNote(msg)})`;
+}
+/**
+* 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.
+*/
+function renderInbox(items) {
+	if (items.length === 0) return "No new messages.";
+	const explain = senderKeyExplainer();
+	return items.map((msg, i) => `${i + 1}. ${renderInboxRow(msg, explain)}`).join("\n");
+}
+/** One discovery row. */
+function renderAgentSummary(a) {
+	const verified = a.verified ? " [verified]" : "";
+	const desc = a.description ? ` — ${a.description}` : "";
+	const cat = a.category ? ` (${a.category})` : "";
+	return `${a.handle}${verified}${cat}${desc}`;
+}
+/** A numbered discovery list, or the empty-state line. */
+function renderDiscover(items) {
+	if (items.length === 0) return "No agents matched.";
+	return items.map((a, i) => `${i + 1}. ${renderAgentSummary(a)}`).join("\n");
+}
+/** A full agent profile (for `rine_inspect`). */
+function renderProfile(p) {
+	const lines = [
+		`${p.name} (${p.handle})`,
+		`id: ${p.id}`,
+		`verified: ${p.verified ? "yes" : "no"}`,
+		`human oversight: ${p.human_oversight ? "yes" : "no"}`
+	];
+	if (p.category) lines.push(`category: ${p.category}`);
+	if (p.description) lines.push(`description: ${p.description}`);
+	return lines.join("\n");
+}
+/**
+* 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.
+*/
+function renderWhoAmI(me) {
+	const slug = me.org.slug ? ` (${me.org.slug})` : "";
+	const live = me.agents.filter((a) => !a.revoked_at).map((a) => a.handle);
+	return [
+		`Org ${me.org.name}${slug}`,
+		`trust tier: ${me.trust_tier}`,
+		`agents: ${live.length > 0 ? live.join(", ") : "none live"}`
+	].join("\n");
+}
+/**
+* A group rendered for `rine_group_inspect`. Every branch is `[OK]` — an MLS
+* group is readable/postable from 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
+* eve — 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.
+*/
+function renderGroup(g, handles) {
+	const lines = [`Group ${g.handle} (id ${g.id})`];
+	if (groupIsMls(g)) {
+		lines.push("[OK] MLS group — end-to-end encrypted (RFC 9420), readable/postable from here.");
+		if (g.mls_group_id) lines.push(`mls_group_id: ${g.mls_group_id}`);
+	} else if (groupMlsInitInFlight(g)) lines.push("[OK] MLS group, initialising — end-to-end encrypted. Sends from here already use MLS.");
+	else if (groupMlsNeverFounded(g)) lines.push(`[OK] sender-key group — readable/postable from here. ${unfoundedGroupNote()}`);
+	else lines.push("[OK] sender-key group — readable/postable from here.");
+	lines.push(`enrollment: ${g.enrollment_policy}`);
+	lines.push(`visibility: ${g.visibility}`);
+	lines.push(`conversation_id: ${g.conversation_id ?? "(none — nothing has been said in this group yet)"}`);
+	lines.push(`your agents: ${renderOwnAgents(g.member_agent_ids, handles)}`);
+	return lines.join("\n");
+}
+/** `rine_group_join` outcome: immediate membership vs a pending vote. */
+function renderJoinResult(target, result) {
+	if (result.status === "joined") return `Joined ${target}.`;
+	return `Join request for ${target} submitted — pending approval (request ${result.request.id}).`;
+}
+/** One pending-invite row: group, inviter, status, and any message. */
+function renderInviteRow(inv) {
+	const group = inv.group_handle ?? inv.group_name ?? inv.group_id;
+	const from = inv.invited_by ? ` invited by ${inv.invited_by}` : "";
+	const msg = inv.message ? `: "${inv.message}"` : "";
+	return `${group} (status ${inv.status})${from}${msg}`;
+}
+/** A numbered list of the caller's pending group invites, or the empty-state line. */
+function renderInvites(items) {
+	if (items.length === 0) return "No pending group invites.";
+	return items.map((inv, i) => `${i + 1}. ${renderInviteRow(inv)}`).join("\n");
+}
+//#endregion
+//#region src/errors.ts
+/**
+* `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.
+*
+* Ordering matters: the TS SDK error classes form a hierarchy rooted at
+* `RineApiError`, so this maps MOST-SPECIFIC FIRST and lets `RineApiError` be the
+* catch-all for API errors.
+*/
+/** The synchronous message thrown by `sendAndWait` for a `#` group handle. */
+const GROUP_ON_WAIT_PREFIX = "sendAndWait() does not support group handles";
+/**
+* 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.
+*/
+function isGroupUnsupportedOnWait(err) {
+	return err instanceof Error && err.message.startsWith(GROUP_ON_WAIT_PREFIX);
+}
+/** The fixed reply for the group-on-`sendAndWait` case. */
+const GROUP_ON_WAIT_MESSAGE = "rine_send_and_wait is 1:1 only; use rine_send for groups.";
+/**
+* A group 404 has THREE producers on this stack, two spellings, and only one of
+* them is a `NotFoundError`.
+*
+*   - the **server** answers a bare `Group not found` (404 → `NotFoundError`);
+*   - the **TS SDK** resolves the handle itself before every group send and
+*     throws a PLAIN `Error`, `Group not found: <handle>`
+*     (`rine-ts-sdk/src/resources/messages.ts` `resolveGroup`;
+*     `rine-core`'s `getOrCreateSenderKey` throws the same shape);
+*   - the SDK's group **resolver** (`groups.resolveRef`) refuses the same way
+*     for every group verb on this surface, and its refusal is a plain `Error`
+*     carrying the same lead plus the caller's own roster.
+*
+* 🔴 `err instanceof NotFoundError` is therefore not the test. Keyed on the
+* class alone, the commonest group failure there is — a mistyped handle on
+* `rine_send` — fell past the branch to the bare `String(err.message)` arm with
+* no remedy at all. The predicate reads the MESSAGE, whichever class carried
+* it.
+*
+* This package used to mint a third spelling of its own — `No group '<x>' among
+* the groups your org's agents belong to`, thrown by a local `groups.list()`
+* match — and it went when that local match did. Nothing on this stack
+* produces that sentence any more, so nothing here reads for it: a predicate
+* kept for a producer that no longer exists is a claim that the surface can
+* still say something it cannot.
+*
+* A group needs the group half of the directory: `rine_discover` searches
+* AGENTS and can never resolve a group handle, so pointing a missing group at
+* it sends the caller to a search that structurally cannot answer.
+*/
+const GROUP_NOT_FOUND_LEAD = "Group not found";
+/**
+* The SECOND lead, and the one a BARE recipient name now carries.
+*
+* The bare-name miss stopped leading with a group verdict — both namespaces
+* have answered no by then, and the sentence says so — but the REMEDY below is
+* unchanged, and that is the whole reason this constant exists here. Dropping
+* the first lead without adding this one routes every bare-name miss to
+* `formatError`'s catch-all, which names `rine_discover`: the public AGENT
+* directory, which cannot resolve a group handle. That is exactly the
+* misdirection this constant exists to prevent, restored silently, with every
+* suite green.
+*
+* Pinned against `rine-core`, `rine-sdk` and the four other reading surfaces by
+* `NEITHER_NAMESPACE_LEAD_COPIES` (`tests/helpers_client_paths.py`).
+*/
+const NEITHER_NAMESPACE_LEAD = "names neither an agent nor a group you can reach";
+/**
+* True for any group-404 spelling, whatever class carried it.
+*
+* 🔴 The second lead is matched by CONTAINMENT, not prefix: its sentence opens
+* with the caller's own spelling (`'kofi' names neither …`), so `startsWith`
+* cannot see it and the arm would read as "not a group problem" forever.
+*/
+function isGroupNotFound(text) {
+	return text.startsWith(GROUP_NOT_FOUND_LEAD) || text.includes(NEITHER_NAMESPACE_LEAD);
+}
+/**
+* The one remedy all three take.
+*
+* `rine_groups` is named FIRST because it resolves a group the caller's org
+* holds a seat in, public or private. `rine_discover_groups` searches the
+* directory, which the server filters to `visibility == "public"`, so it
+* structurally cannot answer for a private group — it is named second because
+* it is the right tool for finding a public group you have never joined.
+*/
+const GROUP_NOT_FOUND_REMEDY = "Try rine_groups to find the right group handle, or rine_discover_groups to search the public directory.";
+/** The half of that remedy that is still worth naming once the roster is in hand. */
+const SEARCH_THE_DIRECTORY = "Try rine_discover_groups to search the public directory.";
+/**
+* A group refusal, plus the tool that can answer it — and one verb fewer when
+* the refusal has already answered itself.
+*
+* The SDK resolves a group reference against the caller's own groups and, on a
+* miss, hands back the list it was holding: {@link GROUP_ROSTER_LEAD} opens the
+* roster, {@link NO_GROUPS_IN_ORG} is the arm for an org that holds a seat
+* nowhere. Printing "run `rine_groups`" underneath either one tells a model to
+* go and fetch what it is already reading — the `rine_discover` defect
+* inverted, and measured to be worse than a wasted call: models parrot the hint
+* back as their answer instead of acting on it. `rine_discover_groups` is then
+* the only verb that can still find something new, so it is the only one named.
+* A **server** group 404 carries no roster and keeps both verbs.
+*
+* The roster arm ends on a LIST ROW, not on a sentence, so the clause joins
+* with a newline and the lead's own full stop is dropped: `(Planning).` reads
+* as part of that last group's entry, and a caller copying the row it was told
+* to name copies the period into the retry.
+*
+* Both sentences are imported from the SDK rather than retyped, so a reword
+* there cannot leave a stale literal here quietly restoring the loop.
+*/
+function groupNotFoundMessage(detail) {
+	if (detail.includes(GROUP_ROSTER_LEAD)) return `Not found: ${detail}\n${SEARCH_THE_DIRECTORY}`;
+	if (detail.includes(NO_GROUPS_IN_ORG)) return `Not found: ${detail} ${SEARCH_THE_DIRECTORY}`;
+	return `Not found: ${detail.replace(/\.+$/, "")}. ${GROUP_NOT_FOUND_REMEDY}`;
+}
+function formatError(err) {
+	if (err instanceof ZodError) {
+		const first = err.issues[0];
+		return `Invalid input: ${first?.path.length ? first.path.join(".") : "input"} — ${first?.message ?? "validation failed"}.`;
+	}
+	if (err instanceof AuthenticationError) return "rine auth failed — onboard with `npx @rine-network/eve onboard` or set RINE_CONFIG_DIR to your credentials directory.";
+	if (err instanceof AuthorizationError) return `Not authorized: ${err.detail}.`;
+	if (err instanceof NotFoundError) {
+		if (isGroupNotFound(err.detail)) return groupNotFoundMessage(err.detail);
+		return `Not found: ${err.detail}. Try rine_discover to find the right handle.`;
+	}
+	if (err instanceof RateLimitError) return `Rate-limited; retry after ${err.retryAfter ?? "a few"}s.`;
+	if (err instanceof ValidationError) return `Invalid input: ${err.detail}.`;
+	if (err instanceof SchemaValidationError) return `Invalid input: ${err.message}.`;
+	if (err instanceof RineTimeoutError) return "Request timed out; try again or raise the timeout.";
+	if (err instanceof ConfigError) return String(err.message);
+	if (err instanceof CryptoError) return `Encryption error: ${err.message} (check your agent keys are on disk).`;
+	if (err instanceof APIConnectionError) return `Could not reach rine: ${err.message}.`;
+	if (err instanceof RineApiError) return `${err.status}: ${err.detail}`;
+	const message = String(messageOf(err));
+	if (isGroupNotFound(message)) return groupNotFoundMessage(message);
+	return message;
+}
+function messageOf(err) {
+	if (err instanceof Error) return err.message;
+	return String(err ?? "unknown error");
+}
+//#endregion
+//#region src/tool.ts
+/**
+* Shared `defineTool` plumbing every rine tool reuses (no duplicated logic):
+* env-based identity resolution and the try/catch → `formatError` wrapper
+* (errors→strings, never a reject).
+*
+* Unlike the Mastra integration (which threads identity through a `RequestContext`),
+* Eve tools run in the app runtime with full `process.env` access, so identity is
+* resolved straight from the environment via `getRineClient` — no per-call context
+* plumbing, no credentials in the model-visible input schema.
+*
+* A tool's per-tool body is just `(client, input, apiUrl) => string`; this helper
+* supplies the surrounding contract. The concrete `defineTool({...})` (with the
+* model-facing description + schemas) lives in each domain module; this file only
+* builds the `execute` closure and the shared option/body types.
+*/
+/**
+* Resolve {@link RineToolOpts.needsApproval} to an Eve `needsApproval` callback,
+* or `undefined` (no gate) when unset. Only the mutating tool factories apply it.
+*/
+function approvalGate(opts) {
+	switch (opts.needsApproval) {
+		case "always": return always();
+		case "once": return once();
+		case "never": return never();
+		default: return;
+	}
+}
+/** Resolve the effective `AsyncRineClient` for one `execute` call (lazy). */
+function resolveClient(opts) {
+	if (opts.client) {
+		const agent = actingAgent(opts);
+		return agent ? opts.client.withAgent(agent) : opts.client;
+	}
+	return getRineClient({
+		configDir: opts.configDir,
+		apiUrl: opts.apiUrl,
+		agent: actingAgent(opts)
+	});
+}
+/**
+* The same resolved `apiUrl` the client is built against (factory override →
+* `RINE_API_URL` env → `resolveApiUrl()`). Exposed so handle→UUID pre-resolution
+* hits the SAME server WebFinger the client uses.
+*/
+function resolveApiUrlFor(opts) {
+	return opts.apiUrl ?? resolveApiUrl();
+}
+/** Brand a model-supplied recipient string for the SDK send surface. */
+function asRecipient(to) {
+	return to;
+}
+/**
+* Belt-and-suspenders ciphertext redactor for `read` / `inbox` / `thread`.
+* The renderers + `outputSchema: z.string()` already guarantee the `execute`
+* return is redacted text; this coerces ANY value to plain text before it can
+* reach the model, in Eve's `ToolModelOutput` shape.
+*/
+function redactToText(output) {
+	return {
+		type: "text",
+		value: typeof output === "string" ? output : ""
+	};
+}
+/**
+* Build an Eve-tool `execute(input, ctx)` from a zod schema + body, applying:
+*   1. zod `.parse(raw)` of the model input (defaults + coercion + validation),
+*   2. the lazy env-resolved client,
+*   3. the try/catch→formatError contract (resolves a string, never rejects).
+*
+* Eve hands `execute` the raw model input as `Record<string, unknown>`; we own the
+* parse because Eve receives a JSON Schema (not the zod schema) and may not apply
+* zod defaults. The Eve `ToolContext` is intentionally ignored — rine identity is
+* environment-resolved, not session-scoped.
+*/
+function makeExecute(schema, opts, body) {
+	return async (raw) => {
+		try {
+			const input = schema.parse(raw);
+			return await body(resolveClient(opts), input, resolveApiUrlFor(opts));
+		} catch (err) {
+			return formatError(err);
+		}
+	};
+}
+//#endregion
+export { renderRoster as C, renderGroups as S, renderThreadLine as _, GROUP_ON_WAIT_MESSAGE as a, verifiedNote as b, renderDiscover as c, renderInvites as d, renderJoinResult as f, renderThread as g, renderSingleMessage as h, redactToText as i, renderGroup as l, renderProfile as m, asRecipient as n, formatError as o, renderMessageBody as p, makeExecute as r, isGroupUnsupportedOnWait as s, approvalGate as t, renderInbox as u, renderWhoAmI as v, renderGroupSummaries as x, senderLabel as y };

package/dist/tool.d.ts

@@ -57,14 +57,14 @@ export declare function resolveClient(opts: RineToolOpts): AsyncRineClient;
 export declare function resolveApiUrlFor(opts: RineToolOpts): string;
 /**
  * The recipient union `client.send`/`sendAndWait` accept. The model supplies a
- * free-form `to` string (a `name@org` handle, a `#group@org` handle, or a UUID);
+ * free-form `to` string (a `name@org` handle, a `#logistics@acme.rine.network` handle, or a UUID);
  * the SDK normalizes + validates it at runtime, so this brands the string once.
  */
 type Recipient = AgentHandle | AgentUuid | GroupHandle | GroupUuid;
 /** Brand a model-supplied recipient string for the SDK send surface. */
 export declare function asRecipient(to: string): Recipient;
 /**
- * Belt-and-suspenders ciphertext redactor for `read` / `check_inbox`.
+ * Belt-and-suspenders ciphertext redactor for `read` / `inbox` / `thread`.
  * The renderers + `outputSchema: z.string()` already guarantee the `execute`
  * return is redacted text; this coerces ANY value to plain text before it can
  * reach the model, in Eve's `ToolModelOutput` shape.

package/dist/tools/discovery.d.ts

@@ -1,9 +1,15 @@
 /**
- * The 2 discovery tool factories: `rine_discover`, `rine_inspect`. Both are
- * unauthenticated directory reads.
+ * The 4 discovery tool factories. `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.
+ *
+ * `rine_discover_groups` is the directory's group half and lives with the other
+ * group readers in `groups-list.ts`; only its registry entry says `discovery`.
  */
 import { type RineToolOpts } from "../tool.js";
 /** `rine_discover` — search the public agent directory. */
 export declare function rineDiscoverTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
 /** `rine_inspect` — fetch one agent's full public profile. */
 export declare function rineInspectTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_whoami` — this agent's own org, trust tier, and live handles. */
+export declare function rineWhoamiTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;