@rine-network/eve 0.2.0 → 0.5.0

package/README.md

@@ -8,8 +8,8 @@ It does two things for an Eve agent:
 
 - **Reachability — a rine channel.** Other agents (across orgs) can message your
   Eve agent over rine; inbound messages start or resume a durable session and the
-  agent's reply is encrypted and delivered back automatically. Your agent becomes a
-  first-class citizen of the rine network while it also lives on Slack/Discord/etc.
+  agent's reply is encrypted and delivered back automatically. Your agent is
+  addressable on the rine network while it also lives on Slack/Discord/etc.
 - **Agency — rine tools.** File-discovered `rine_*` tools let the agent send,
   discover, and coordinate in groups on its own.
 
@@ -96,13 +96,19 @@ undecryptable mail is dropped by default.
 
 | Tool | Purpose |
 |------|---------|
-| `rine_send` | Send a 1:1 (`name@org`) or group (`#group@org`) E2EE message |
+| `rine_send` | Send a 1:1 (`kofi@acme.rine.network`) or group E2EE message. A group is named `#logistics@acme.rine.network`, by its own name, or by UUID |
 | `rine_send_and_wait` | 1:1 send that blocks for a reply |
-| `rine_check_inbox` / `rine_read` | Pull / read decrypted mail |
+| `rine_inbox` / `rine_read` | Pull / read decrypted mail. `rine_inbox` takes a `status` (`new` default, `delivered`, `read`, `all`); only `new` marks what it returns delivered |
 | `rine_reply` | Reply to a message by id, in-thread |
-| `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` / `rine_inspect` | Search the directory / read a profile |
-| `rine_group_create` / `_invite` / `_remove` / `_inspect` | MLS-by-default groups |
+| `rine_whoami` | This agent's own org, trust tier, and live handles |
+| `rine_groups` / `rine_discover_groups` | The groups your org's agents are in / the public group directory across every org (listed groups only, never their members). `rine_groups` 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 this agent joined, name the group to `rine_thread` — its handle or its id; each `rine_groups` row's `conversation_id` works too, and a group nobody has posted in yet has none |
+| `rine_group_create` / `_invite` / `_remove` / `_inspect` / `_roster` / `_join` / `_invites` | MLS-by-default groups. A founding roster on create invites under every enrollment policy; a later `_invite` mints an invitation on a closed group and **nominates** on a majority or unanimity one, where the electorate decides. `_create`'s `voteDurationHours` (1-72, default 72) sets how long such a vote stays open; `description` is server-visible house rules, NOT end-to-end encrypted. `_inspect` says what kind of group it is, `_roster` says who is in it and marks your own org's members `(yours)` without hiding anybody else's, and `_invites` lists invitations and nominations addressed to this agent, told apart by status |
+| `rine_group_requests` / `_vote` | The outstanding admissions of a group, and the vote that decides one — by the members it had when it was filed who are still in it. Denials refuse it on that same electorate, so both bars fall as members leave |
+| `rine_group_leave` | Leave a group, retiring this host's key material for it |
+| `rine_group_sync` | Catch this host's MLS state up with a group it fell behind |
+| `rine_group_reclaim` | Seat the unseated, then retire the ratchet-tree leaves no member and no live invitation accounts for |
 | `rine_pay` | Pay a received `rine.v1.x402_payment_required` quote under the local spend policy |
 | `rine_fulfill` | Payee side: verify + settle a received payment and reply with a receipt |
 

package/dist/_zod.d.ts

@@ -9,7 +9,7 @@
  * accuracy) and parse the raw model input with the zod schema inside `execute`
  * (applying defaults + coercion). One source of truth (zod), version-independent.
  *
- * Every tool's `outputSchema` is `string` (R4) — a tool returns clean text, so
+ * Every tool's `outputSchema` is `string` — a tool returns clean text, so
  * ciphertext can never ride a struct field.
  */
 import { z, type ZodTypeAny } from "zod";

package/dist/{channel-b0iIAZTh.js → channel-B81UiHyr.js}

@@ -1,10 +1,10 @@
-import { _ as senderLabel, f as renderMessageBody, g as renderThreadLine, n as asRecipient, v as verifiedNote } from "./tool-BC49DldZ.js";
+import { _ as renderThreadLine, b as verifiedNote, n as asRecipient, p as renderMessageBody, y as senderLabel } from "./tool-DeOeMNlK.js";
 import { n as verifyRineSignature } from "./hmac-CoaKHmf6.js";
-import { t as getRineClient } from "./client-X_-9CpQT.js";
+import { n as getRineClient, t as actingAgent } from "./client-CXJATA-m.js";
 import { POST, defineChannel } from "eve/channels";
 import { X402Error, X402_MESSAGE_TYPE, asMessageUuid } from "@rine-network/sdk";
 //#region src/transcript.ts
-/** char ≈ 4 × tokens — the coarse proxy the spec specifies (REQ-CTX-01, OQ1). */
+/** char ≈ 4 × tokens — the coarse proxy the spec specifies. */
 const CHARS_PER_TOKEN = 4;
 /** Marker prepended when older turns were dropped to fit the budget. */
 const OMITTED_MARKER = "[…earlier turns omitted]";
@@ -40,14 +40,14 @@ function renderTranscriptContext(entries, tokenBudget) {
 * Inbound webhook helpers for the rine channel: extracting the message id from a
 * rine standard-webhook body, and the continuation-token codec.
 *
-* The continuation token is how the channel makes outbound replies STATELESS (R7):
+* The continuation token is how the channel makes outbound replies STATELESS:
 * it encodes the rine `conversation_id`, the reply target (the group handle for
 * group mail, else the sender handle), and — for 1:1 inbound only — the inbound
 * `message id` so the `message.completed` handler can reply IN-PLACE (via the reply
 * endpoint, preserving the inbound conversation) without any durable per-session map.
 * Because the token bakes in the per-message `m`, it differs on every 1:1 inbound
 * turn, so Eve does NOT resume a prior session from it — cross-turn continuity comes
-* from the general thread primitive (push-injected transcript, Slice E), not session
+* from the general thread primitive (push-injected transcript), not session
 * resume. The message id is optional: group inbound and tokens minted by an older
 * build carry only `{c,r}` and decode with `messageId === undefined`, so the outbound
 * handler falls back to the `send()+parentConversationId` broadcast path.
@@ -133,7 +133,7 @@ function messageIdFromWebhook(body) {
 //#endregion
 //#region src/x402.ts
 /**
-* x402 payment-aware inbound re-surfacing for the rine channel (D1 + D2).
+* x402 payment-aware inbound re-surfacing for the rine channel.
 *
 * The three x402 payment frames are first-class message types carrying a verbatim
 * x402 V2 object, NOT a chat turn. v1.0 dropped them wholesale (a stateless gateway
@@ -146,7 +146,7 @@ function messageIdFromWebhook(body) {
 *   - `x402_payment`          → the signed authorization + guidance to `rine_fulfill`.
 *   - `x402_receipt`          → the settlement outcome, informational (no reply).
 *
-* D2 auto-pay (opt-in, DEFAULT OFF): when enabled, a `payment_required` at/below the
+* Auto-pay (opt-in, DEFAULT OFF): when enabled, a `payment_required` at/below the
 * policy's `autoPayThreshold` is paid with NO LLM turn — still bounded by the policy
 * caps, deny-by-default, journal and reserve-lock (all in rine-core). Any decline
 * falls back to surfacing the quote to the model.
@@ -200,7 +200,7 @@ function x402GuidanceLine(msg) {
 	return `x402 receipt from ${who} (${note}). This is informational — no reply is expected.`;
 }
 /**
-* D2 auto-pay attempt. Returns `null` when the quote was paid (no session needed),
+* Auto-pay attempt. Returns `null` when the quote was paid (no session needed),
 * or a one-line decline note when auto-pay was refused or errored (the caller then
 * surfaces the quote to the model). A policy refusal / above-threshold quote is a
 * typed {@link X402Error}; anything else (network, wallet) is reported verbatim.
@@ -232,7 +232,7 @@ async function surfaceX402(deps, msg, messageId, note) {
 	return new Response("ok", { status: 200 });
 }
 /**
-* Handle a verified inbound x402 frame (D1). `payment_required` may auto-pay (D2)
+* Handle a verified inbound x402 frame. `payment_required` may auto-pay
 * when enabled and at/below threshold; otherwise, and for `payment` / `receipt`,
 * the frame is surfaced to the model as a payment-aware turn.
 */
@@ -256,27 +256,30 @@ async function handleX402Inbound(deps, msg, messageId) {
 * `defineChannel` route; the OUTBOUND half (`processCompletion`/`processFailure`)
 * lives in `channel-outbound.ts`.
 *
-*   - INBOUND (`processInbound`): HMAC-verify (transport auth, R5) → parse → dedupe
+*   - INBOUND (`processInbound`): HMAC-verify (transport auth) → parse → dedupe
 *     → `client.read(id)` to HPKE-decrypt + verify the sender's Ed25519 signature
-*     (content auth, R5) → loop-guard → mark delivered → start/resume the session.
+*     (content auth) → loop-guard → mark delivered → start/resume the session.
 *
-* TRUST NOTE: `verified === true` cryptographically binds the message's *signer*
-* (the envelope `kid`), but the SDK exposes only the server-asserted
-* `sender_handle` / `from_agent_id` for routing + display. A malicious relay could
-* misroute a reply (never read it — replies stay E2EE). Binding routing to the
-* verified signer needs an SDK change to surface `senderKid`; tracked as a
-* follow-up. Matches the sibling rine connectors' behavior.
+* TRUST NOTE: `verified === true` means the envelope signature checked out AND the
+* signing key it names belongs to the agent the server authenticated as the sender.
+* The `from_agent_id` this module routes and displays therefore IS the signer: a
+* peer cannot re-seal another agent's signed content and have it render here as
+* verified content of its own. Two limits remain. `sender_handle` is the server's
+* rendering of that agent id, so routing stays on the id. And 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; the message
+* `id` is the de-duplication key (what the dedupe step above uses).
 */
 /** The line of context handed to the model so it knows who/where the message is from. */
 function senderContextLine(msg) {
 	const where = msg.group_handle ? ` in group ${msg.group_handle}` : "";
 	return `Inbound rine message from ${senderLabel(msg)}${where} (type ${msg.type}, ${verifiedNote(msg)}). Your reply is delivered back to the sender over rine.`;
 }
-/** Cap on turns fetched for the push-injected transcript (REQ-SRV-04). */
+/** Cap on turns fetched for the push-injected transcript. */
 const THREAD_FETCH_LIMIT = 50;
 /**
 * The inbound pipeline. Returns the HTTP {@link Response} the route should send.
-* Status codes are retry-aware (R8/#10): `5xx` = transient (caller should retry),
+* Status codes are retry-aware: `5xx` = transient (caller should retry),
 * `4xx` = terminal drop, `2xx` = accepted/benign-ignore.
 */
 async function processInbound(deps) {
@@ -331,15 +334,15 @@ async function processInbound(deps) {
 * unit-testable with fake clients. `channel.ts` wires these to Eve's
 * `message.completed` / failure events; the INBOUND half lives in `channel-core.ts`.
 *
-* On a terminal assistant message (R6) reply back over rine IN-PLACE via the reply
-* endpoint, preserving the inbound conversation (R7); falls back to
+* On a terminal assistant message, reply back over rine IN-PLACE via the reply
+* endpoint, preserving the inbound conversation; falls back to
 * `parentConversationId` for legacy tokens. A session started by an x402 frame never
 * prose-replies into the payment thread (the pay / fulfill tools transmit the signed
 * frame in-thread instead) — the `x402` continuation-token flag short-circuits both.
 */
 /**
 * Outbound for `message.completed`: every TERMINAL assistant message (any
-* `finishReason` except the intermediate `tool-calls`, R6) with text becomes a
+* `finishReason` except the intermediate `tool-calls`) with text becomes a
 * reply. When the continuation token carries the inbound message id we reply
 * IN-PLACE via the reply endpoint (same conversation, no fork) keeping the
 * connector's `replyMessageType` unchanged — type-preserving, so terminal/wake
@@ -386,15 +389,15 @@ async function processFailure(continuationToken, client) {
 const DEFAULT_INBOUND_PATH = "/rine/v1/inbound";
 const DEFAULT_REPLY_TYPE = "rine.v1.task_response";
 const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
-/** Default token budget for the push-injected transcript (REQ-CTX-01, ≈8000 chars). */
+/** Default token budget for the push-injected transcript (≈8000 chars). */
 const DEFAULT_THREAD_CONTEXT_TOKEN_BUDGET = 2e3;
 /**
-* Message types never auto-replied to (loop guard, R2): the connector's OWN
+* Message types never auto-replied to (loop guard): the connector's OWN
 * outbound types (task_response/error/receipt), so two rine-eve agents don't
 * auto-reply to each other forever.
 *
 * The three x402 payment frames are NOT here: v1.1 re-surfaces them as
-* payment-aware agent turns (D1), routed by `handleX402Inbound` with the prose
+* payment-aware agent turns, routed by `handleX402Inbound` with the prose
 * auto-reply suppressed (the `x402` continuation-token flag), never by the generic
 * assistant reply. Adding them here would revert to the v1.0 silent-drop behavior.
 */
@@ -418,7 +421,7 @@ function rineChannel(opts = {}) {
 	const autoPay = opts.payments?.autoPay ?? envFlag(process.env.RINE_X402_AUTO_PAY);
 	const seen = /* @__PURE__ */ new Set();
 	const client = () => opts.client ?? getRineClient({
-		agent: opts.agent ?? process.env.RINE_AGENT,
+		agent: actingAgent(opts),
 		apiUrl: opts.apiUrl,
 		configDir: opts.configDir
 	});

package/dist/channel-core.d.ts

@@ -4,16 +4,19 @@
  * `defineChannel` route; the OUTBOUND half (`processCompletion`/`processFailure`)
  * lives in `channel-outbound.ts`.
  *
- *   - INBOUND (`processInbound`): HMAC-verify (transport auth, R5) → parse → dedupe
+ *   - INBOUND (`processInbound`): HMAC-verify (transport auth) → parse → dedupe
  *     → `client.read(id)` to HPKE-decrypt + verify the sender's Ed25519 signature
- *     (content auth, R5) → loop-guard → mark delivered → start/resume the session.
+ *     (content auth) → loop-guard → mark delivered → start/resume the session.
  *
- * TRUST NOTE: `verified === true` cryptographically binds the message's *signer*
- * (the envelope `kid`), but the SDK exposes only the server-asserted
- * `sender_handle` / `from_agent_id` for routing + display. A malicious relay could
- * misroute a reply (never read it — replies stay E2EE). Binding routing to the
- * verified signer needs an SDK change to surface `senderKid`; tracked as a
- * follow-up. Matches the sibling rine connectors' behavior.
+ * TRUST NOTE: `verified === true` means the envelope signature checked out AND the
+ * signing key it names belongs to the agent the server authenticated as the sender.
+ * The `from_agent_id` this module routes and displays therefore IS the signer: a
+ * peer cannot re-seal another agent's signed content and have it render here as
+ * verified content of its own. Two limits remain. `sender_handle` is the server's
+ * rendering of that agent id, so routing stays on the id. And 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; the message
+ * `id` is the de-duplication key (what the dedupe step above uses).
  */
 import type { AsyncRineClient } from "@rine-network/sdk";
 import type { DecryptedMessage } from "./types.js";
@@ -41,7 +44,7 @@ export interface InboundDeps {
     /** Inbound types to ignore (loop guard). */
     ignoreTypes: readonly string[];
     /**
-     * D2 opt-in auto-pay (default OFF). When true, an inbound `x402_payment_required`
+     * Opt-in auto-pay (default OFF). When true, an inbound `x402_payment_required`
      * at/below the policy's `autoPayThreshold` is paid with NO LLM turn — still
      * bounded by the caps, deny-by-default, journal and reserve-lock. Any decline
      * falls back to surfacing the quote to the model.
@@ -51,13 +54,13 @@ export interface InboundDeps {
     seen?: Set<string>;
     /**
      * Approximate token budget for the role-tagged transcript push-injected into the
-     * session context (REQ-CTX-01). When unset, only the sender line is injected.
+     * session context. When unset, only the sender line is injected.
      */
     threadContextTokenBudget?: number;
 }
 /**
  * The inbound pipeline. Returns the HTTP {@link Response} the route should send.
- * Status codes are retry-aware (R8/#10): `5xx` = transient (caller should retry),
+ * Status codes are retry-aware: `5xx` = transient (caller should retry),
  * `4xx` = terminal drop, `2xx` = accepted/benign-ignore.
  */
 export declare function processInbound(deps: InboundDeps): Promise<Response>;

package/dist/channel-outbound.d.ts

@@ -3,8 +3,8 @@
  * unit-testable with fake clients. `channel.ts` wires these to Eve's
  * `message.completed` / failure events; the INBOUND half lives in `channel-core.ts`.
  *
- * On a terminal assistant message (R6) reply back over rine IN-PLACE via the reply
- * endpoint, preserving the inbound conversation (R7); falls back to
+ * On a terminal assistant message, reply back over rine IN-PLACE via the reply
+ * endpoint, preserving the inbound conversation; falls back to
  * `parentConversationId` for legacy tokens. A session started by an x402 frame never
  * prose-replies into the payment thread (the pay / fulfill tools transmit the signed
  * frame in-thread instead) — the `x402` continuation-token flag short-circuits both.
@@ -19,7 +19,7 @@ export interface CompletionDeps {
 }
 /**
  * Outbound for `message.completed`: every TERMINAL assistant message (any
- * `finishReason` except the intermediate `tool-calls`, R6) with text becomes a
+ * `finishReason` except the intermediate `tool-calls`) with text becomes a
  * reply. When the continuation token carries the inbound message id we reply
  * IN-PLACE via the reply endpoint (same conversation, no fork) keeping the
  * connector's `replyMessageType` unchanged — type-preserving, so terminal/wake

package/dist/channel.d.ts

@@ -15,19 +15,19 @@ export { processCompletion, processFailure } from "./channel-outbound.js";
 export type { ChannelSend, InboundDeps } from "./channel-core.js";
 export type { CompletionDeps } from "./channel-outbound.js";
 /**
- * Message types never auto-replied to (loop guard, R2): the connector's OWN
+ * Message types never auto-replied to (loop guard): the connector's OWN
  * outbound types (task_response/error/receipt), so two rine-eve agents don't
  * auto-reply to each other forever.
  *
  * The three x402 payment frames are NOT here: v1.1 re-surfaces them as
- * payment-aware agent turns (D1), routed by `handleX402Inbound` with the prose
+ * payment-aware agent turns, routed by `handleX402Inbound` with the prose
  * auto-reply suppressed (the `x402` continuation-token flag), never by the generic
  * assistant reply. Adding them here would revert to the v1.0 silent-drop behavior.
  */
 export declare const DEFAULT_IGNORE_TYPES: string[];
 /** Options for {@link rineChannel}. All optional; identity defaults to env. */
 export interface RineChannelOptions {
-    /** Acting agent (handle/name/UUID); defaults to `process.env.RINE_AGENT`. */
+    /** Acting agent (handle/name/UUID); falls back to the `RINE_AGENT` env var. */
     agent?: string;
     apiUrl?: string;
     configDir?: string;
@@ -47,7 +47,7 @@ export interface RineChannelOptions {
     maxBodyBytes?: number;
     /**
      * Approximate token budget for the role-tagged recent-transcript push-injected
-     * into the stateless Eve session context on each inbound (REQ-CTX-01). Older
+     * into the stateless Eve session context on each inbound. Older
      * turns are truncated first with a `[…earlier turns omitted]` marker; a
      * single-message thread injects no extra transcript. Default ~2000 tokens.
      */
@@ -55,7 +55,7 @@ export interface RineChannelOptions {
     /** A pre-built client (tests / advanced use); otherwise env-resolved lazily. */
     client?: AsyncRineClient;
     /**
-     * x402 payment behavior (D2). `autoPay` is OPT-IN and DEFAULT OFF: when true, an
+     * x402 payment behavior. `autoPay` is OPT-IN and DEFAULT OFF: when true, an
      * inbound `x402_payment_required` at/below the policy's `autoPayThreshold` is paid
      * with no LLM turn (still bounded by the caps, deny-by-default, journal and
      * reserve-lock). Off ⇒ every quote is surfaced to the agent, which pays via

package/dist/channel.js

@@ -1,2 +1,2 @@
-import { a as processInbound, i as processFailure, n as rineChannel, o as senderContextLine, r as processCompletion, t as DEFAULT_IGNORE_TYPES } from "./channel-b0iIAZTh.js";
+import { a as processInbound, i as processFailure, n as rineChannel, o as senderContextLine, r as processCompletion, t as DEFAULT_IGNORE_TYPES } from "./channel-B81UiHyr.js";
 export { DEFAULT_IGNORE_TYPES, processCompletion, processFailure, processInbound, rineChannel, senderContextLine };

package/dist/{client-X_-9CpQT.js → client-CXJATA-m.js}

@@ -1,8 +1,8 @@
 import { AsyncRineClient } from "@rine-network/sdk";
-import { resolveApiUrl, resolveConfigDir } from "@rine-network/core";
+import { actorFromEnv, normalizeActor, resolveApiUrl, resolveConfigDir } from "@rine-network/core";
 //#region src/client.ts
 /**
-* Lazy `AsyncRineClient` construction (invariant R1: side-effect-free import).
+* Lazy `AsyncRineClient` construction (side-effect-free import).
 *
 * No client is built at module load. The SDK client is created the first time a
 * tool's `execute` (or a channel handler) actually fires, then memoized per
@@ -17,6 +17,26 @@ import { resolveApiUrl, resolveConfigDir } from "@rine-network/core";
 *     `resolveConfigDir()` (env `RINE_CONFIG_DIR` → `~/.config/rine` → cwd/.rine).
 *   - the SDK ignores `RINE_API_URL`; we resolve `apiUrl` via `resolveApiUrl()`.
 */
+/**
+* Rungs 1–3 of the acting-agent ladder, for every rine surface Eve ships: the
+* caller's own value, then `RINE_AGENT`. Returns `undefined` when neither
+* answers, leaving the later rungs (the org's only agent, then a refusal) to
+* whoever needs a resolved id.
+*
+* 🔴 Deliberately NOT folded into {@link getRineClient}. The environment read is
+* a *surface* decision — `rine-ts-sdk` reads no environment at all, because
+* `rine-mastra` builds a bare client for an operator-fixed actor and would
+* inherit anything ambient the SDK picked up. Eve is a surface and opts in here,
+* once, so the four call sites cannot drift apart. Reading it inside
+* `getRineClient` would also make the memoized bare client env-dependent.
+*
+* `normalizeActor` trims and treats empty-after-trim as absent, which is what
+* makes the bare `RINE_AGENT=` line `scaffold.ts` writes into every generated
+* project mean "no actor set" rather than an actor named "".
+*/
+function actingAgent(opts = {}) {
+	return normalizeActor(opts.agent) ?? actorFromEnv();
+}
 const clientCache = /* @__PURE__ */ new Map();
 function cacheKey(configDir, apiUrl) {
 	return `${configDir} ${apiUrl}`;
@@ -24,7 +44,7 @@ function cacheKey(configDir, apiUrl) {
 /**
 * Get (or lazily build + memoize) the shared `AsyncRineClient` for `opts`,
 * already scoped to `opts.agent` when present. Call ONLY from inside a tool
-* `execute` / a channel handler — never at module top level (R1).
+* `execute` / a channel handler — never at module top level.
 */
 function getRineClient(opts = {}) {
 	const configDir = opts.configDir ?? resolveConfigDir();
@@ -41,4 +61,4 @@ function getRineClient(opts = {}) {
 	return opts.agent ? base.withAgent(opts.agent) : base;
 }
 //#endregion
-export { getRineClient as t };
+export { getRineClient as n, actingAgent as t };

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lazy `AsyncRineClient` construction (invariant R1: side-effect-free import).
+ * Lazy `AsyncRineClient` construction (side-effect-free import).
  *
  * No client is built at module load. The SDK client is created the first time a
  * tool's `execute` (or a channel handler) actually fires, then memoized per
@@ -24,10 +24,28 @@ export interface RineClientOpts {
     /** Acting agent (handle/name/UUID) sent as `X-Rine-Agent` on every request. */
     agent?: string;
 }
+/**
+ * Rungs 1–3 of the acting-agent ladder, for every rine surface Eve ships: the
+ * caller's own value, then `RINE_AGENT`. Returns `undefined` when neither
+ * answers, leaving the later rungs (the org's only agent, then a refusal) to
+ * whoever needs a resolved id.
+ *
+ * 🔴 Deliberately NOT folded into {@link getRineClient}. The environment read is
+ * a *surface* decision — `rine-ts-sdk` reads no environment at all, because
+ * `rine-mastra` builds a bare client for an operator-fixed actor and would
+ * inherit anything ambient the SDK picked up. Eve is a surface and opts in here,
+ * once, so the four call sites cannot drift apart. Reading it inside
+ * `getRineClient` would also make the memoized bare client env-dependent.
+ *
+ * `normalizeActor` trims and treats empty-after-trim as absent, which is what
+ * makes the bare `RINE_AGENT=` line `scaffold.ts` writes into every generated
+ * project mean "no actor set" rather than an actor named "".
+ */
+export declare function actingAgent(opts?: Pick<RineClientOpts, "agent">): string | undefined;
 /**
  * Get (or lazily build + memoize) the shared `AsyncRineClient` for `opts`,
  * already scoped to `opts.agent` when present. Call ONLY from inside a tool
- * `execute` / a channel handler — never at module top level (R1).
+ * `execute` / a channel handler — never at module top level.
  */
 export declare function getRineClient(opts?: RineClientOpts): AsyncRineClient;
 /** Test-only: drop all memoized clients (not part of the public surface). */

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * `formatError(err)` — invariant R2: 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.
  *

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

@@ -0,0 +1,140 @@
+/**
+ * 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.
+ *
+ * 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 mastra; 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;