@rine-network/openclaw 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { i as readRineCredentials, n as buildRineClient, o as resolveRineConfigFromCfg, r as sendRineReply, s as INTERNAL_TOOLS, t as rinePlugin } from "./channel-DqxESY90.js";
-import { i as normalizeStandardWebhook, n as normalizeA2A, t as isAllowed } from "./inbound-DEe69mNL.js";
+import { a as readRineCredentials, c as INTERNAL_TOOLS, i as sendRineText, n as buildRineClient, r as sendRineReply, s as resolveRineConfigFromCfg, t as rinePlugin } from "./channel-DiPLuJsk.js";
+import { i as normalizeA2A, n as sleep, o as normalizeStandardWebhook, r as isAllowed } from "./backoff-a3Dly8X4.js";
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
-import { fetchAgents, resolveAgent } from "@rine-network/core";
-import { tools } from "@rine-network/mcp/tools";
+import { ACTOR_SURFACES, resolveActor } from "@rine-network/core";
+import { actorKeysFor, namesActor, tools } from "@rine-network/mcp/tools";
 import { dispatchInboundDirectDmWithRuntime } from "openclaw/plugin-sdk/channel-inbound";
 import { jsonResult } from "openclaw/plugin-sdk/channel-actions";
 //#region openclaw.plugin.json
@@ -35,7 +35,7 @@ var configSchema = {
 		},
 		"agentId": {
 			"type": "string",
-			"description": "rine agent id to bind (default: credentialed agent)."
+			"description": "The rine agent this install acts as — whose inbox the notify service reads, and the acting agent defaulted onto every tool call that takes one. Name, handle, or UUID. Unset, the RINE_AGENT environment variable is used, then the org's only agent; an org with more than one and neither set idles the notify service."
 		},
 		"baseUrl": {
 			"type": "string",
@@ -44,7 +44,7 @@ var configSchema = {
 		"pollIntervalMs": {
 			"type": "number",
 			"default": 6e4,
-			"description": "POLL only: interval between /poll checks."
+			"description": "Interval between /poll checks on the POLL transport, and how often an install without credentials re-checks for them on any transport."
 		},
 		"reconnectBaseMs": {
 			"type": "number",
@@ -150,44 +150,84 @@ function makeOnMessage(deps) {
 //#endregion
 //#region src/runtime-dispatch.ts
 /**
-* The Funnel relay self-sends this type (`from == to`); it is a one-way event the agent ACTS
-* on and must never auto-reply to (the reply is a self-send the server rejects). Compared as a
-* literal so the guard never depends on the installed SDK exporting a named constant — mirrors
-* the rine-hermes `_FUNNEL_WEBHOOK_TYPE` precedent.
-*/
-const WEBHOOK_TYPE = "rine.v1.webhook";
-/**
-* A one-way inbound: a Funnel webhook, or any self-addressed message (`from == to`). The agent
-* wakes to act via tools, but an auto-reply would target itself and be rejected.
+* Types the agent still WAKES for — it acts on them through its tools — but must never
+* auto-reply to, each mapped to the reason the operator reads in the log. Compared as
+* literals so a guard never depends on the installed SDK exporting a named constant
+* (mirrors the rine-hermes `_FUNNEL_WEBHOOK_TYPE` precedent).
+*
+* The Funnel webhook is relayed as the agent itself (`from == to`), so a reply targets the
+* agent and the server rejects it. The three x402 frames carry a payment handshake, and a
+* canned text reply injected into that thread corrupts it. The sender-key distribution and
+* group-invite envelopes are control frames whose payload the recipient parses as JSON:
+* a text answer to one is prose the peer's ingest path has to throw away, and because
+* `rine_reply` mirrors the inbound type the answer also goes on the wire wearing the
+* control frame's own label.
 */
-function isOneWayEvent(msg) {
-	return msg.type === WEBHOOK_TYPE || msg.selfSend === true;
+const NO_AUTO_REPLY_TYPES = new Map([
+	["rine.v1.webhook", "one-way Funnel webhook — act via tools; a reply would target self"],
+	["rine.v1.x402_payment_required", "x402 frame — act via the rine_pay tool; a text reply would corrupt the payment handshake"],
+	["rine.v1.x402_payment", "x402 frame — act via the rine_pay tool; a text reply would corrupt the payment handshake"],
+	["rine.v1.x402_receipt", "x402 frame — act via the rine_pay tool; a text reply would corrupt the payment handshake"],
+	["rine.v1.sender_key_distribution", "sender-key control frame — the peer parses it as JSON, and a text answer would be typed as one"],
+	["rine.v1.group_invite", "group-invite control frame — the peer parses it as JSON, and a text answer would be typed as one"]
+]);
+/** Why this inbound must not be auto-answered, or undefined when an answer is correct. */
+function noAutoReplyReason(msg, opts) {
+	if (msg.selfSend === true) return "self-addressed message — a reply would target self";
+	const byType = NO_AUTO_REPLY_TYPES.get(msg.type);
+	if (byType) return byType;
+	if (opts?.replayed) return "catch-up/replayed frame — live-phase frames only";
 }
 /**
-* The three x402 payment frames: the 402 quote, the signed authorization, and the settlement
-* receipt. Like a one-way event the agent still wakes to ACT (pay via the `rine_pay` tool, read
-* the receipt), but a canned TEXT auto-reply would be injected into the payment thread and
-* corrupt the x402 handshake. Compared as literals so the guard never depends on the installed
-* core SDK exporting `X402_MESSAGE_TYPE` — mirrors the WEBHOOK_TYPE precedent above.
+* How an answer to `msg` reaches its audience, or undefined when there is no route.
+*
+* A GROUP is answered by SENDING to the group, never by replying. `POST /messages/{id}/reply`
+* routes to the "other party" of a 1:1 pair and a group row carries `to_agent_id IS NULL` —
+* there is no other party, so the lifted `rine_reply` handler refuses one GET earlier
+* ("Cannot reply to a group post — it has no single recipient. Answer the group by sending
+* to " and then ONE OF TWO tails — `rine-mcp/src/tools/messaging.ts`,
+* `replyToGroupRefusal`) and the route behind it refuses too. The tail is the group's OWN
+* handle when the message it just fetched carries one, and otherwise "its own handle: " plus
+* how such a handle is spelled — `GROUP_HANDLE_PARTS`, rine-core's shared clause in
+* `handle-words.ts`, composed rather than retyped. Both tails keep the advice; the second is
+* for the row whose group has no handle to echo, which is the SAME missing handle
+* `answerRouteOf` below returns no route for. Its sibling refusal, "Cannot determine
+* recipient from message", is the NON-group case: a 1:1 row with no `to_agent_id` at all.
+*
+* `isGroup` is true whenever the inbound carries a group handle OR a bare group id, so a
+* group frame can arrive with no handle (a webhook body carrying only `group_id`). There is
+* no route in that case: a group UUID typechecks as a send target and is then encrypted 1:1
+* and rejected server-side, so refusing loudly beats sending something undeliverable.
 */
-const X402_FRAME_TYPES = new Set([
-	"rine.v1.x402_payment_required",
-	"rine.v1.x402_payment",
-	"rine.v1.x402_receipt"
-]);
-function isX402Frame(msg) {
-	return X402_FRAME_TYPES.has(msg.type);
+function answerRouteOf(msg) {
+	if (!msg.isGroup) return {
+		kind: "direct",
+		handle: msg.fromHandle
+	};
+	return msg.groupHandle ? {
+		kind: "group",
+		handle: msg.groupHandle
+	} : void 0;
 }
 /**
 * The inline pointer body — ciphertext stays out of the transcript; agent calls `rine_read`.
 *
-* The body also binds the reply target to the SENDER. Without this, a model that replies via the
-* optional `rine_send` tool can copy the message's own `to_agent_id` (= this agent's id, surfaced
-* by `rine_read`) and self-target, producing `Unknown target`. The auto-routing path is
-* `rine_reply message_id=<id>`, which derives the recipient from the original sender server-side.
+* The body names only tools this plugin exposes. It used to point at `rine_reply`, which is
+* an INTERNAL tool the host never registers, so every inbound spent a turn on tool calls the
+* runtime answered with `Tool rine_reply not found`. The plugin routes the turn's text out on
+* its own, so the correct instruction is to answer and call nothing.
+*
+* The body also states the audience. On a group post the old text named the poster twice and
+* the group never, i.e. it instructed the model to answer a group by privately DM'ing whoever
+* spoke last. `route` is resolved once by the dispatcher and passed in, so what the model is
+* told matches what `deliver` actually does — absent when the turn is not delivered at all.
 */
-function pointerText(msg) {
-	return `[rine ${msg.type} from ${msg.fromHandle}] message ${msg.id} (read with rine_read; reply with rine_reply message_id=${msg.id} — it auto-routes to ${msg.fromHandle}. If you use rine_send instead, set to=${msg.fromHandle}, never your own agent id.)`;
+function pointerText(msg, route) {
+	const inGroup = msg.isGroup && msg.groupHandle ? ` in group ${msg.groupHandle}` : "";
+	const head = `[rine ${msg.type} from ${msg.fromHandle}${inGroup}] message ${msg.id}`;
+	if (!route) return `${head} (read it with rine_read. Nothing you write this turn is sent — act on this message with your tools instead.)`;
+	if (route.kind === "group") return `${head} (read it with rine_read, then answer in your turn — your answer is posted to the whole group ${route.handle} automatically. Do not call a send tool, and never answer the sender privately.)`;
+	return `${head} (read it with rine_read, then answer in your turn — your answer is delivered back to ${route.handle} automatically. Do not call a send tool to answer.)`;
 }
 /**
 * Production dispatch fn: wakes an agent turn for one inbound rine message via the
@@ -203,6 +243,8 @@ function makeRuntimeDispatcher(params) {
 		signal.throwIfAborted();
 		const peerId = msg.isGroup ? msg.conversationId : msg.fromHandle;
 		const timestamp = msg.createdAt ? Date.parse(msg.createdAt) : void 0;
+		const suppressed = noAutoReplyReason(msg, opts);
+		const route = suppressed ? void 0 : answerRouteOf(msg);
 		let dispatchErr;
 		await dispatchInboundDirectDmWithRuntime({
 			cfg,
@@ -218,7 +260,7 @@ function makeRuntimeDispatcher(params) {
 			senderAddress: msg.fromHandle,
 			recipientAddress: agentId,
 			conversationLabel: msg.isGroup ? `rine group ${msg.conversationId}` : msg.fromHandle,
-			rawBody: pointerText(msg),
+			rawBody: pointerText(msg, route),
 			messageId: msg.id,
 			timestamp: Number.isFinite(timestamp) ? timestamp : void 0,
 			deliver: async (payload) => {
@@ -227,19 +269,15 @@ function makeRuntimeDispatcher(params) {
 					logger.warn(`rine: dropping non-text reply for ${msg.id} (rine replies are text-only)`);
 					return;
 				}
-				if (isOneWayEvent(msg)) {
-					logger.debug?.(`rine: no auto-reply for one-way ${msg.type} ${msg.id} (act via tools; reply would target self)`);
+				if (suppressed) {
+					logger.debug?.(`rine: no auto-reply for ${msg.type} ${msg.id} (${suppressed})`);
 					return;
 				}
-				if (isX402Frame(msg)) {
-					logger.debug?.(`rine: no auto-reply for x402 frame ${msg.type} ${msg.id} (act via the rine_pay tool; a text reply would corrupt the payment handshake)`);
+				if (!route) {
+					logger.error(`rine: cannot answer group message ${msg.id} — inbound carries no group handle`);
 					return;
 				}
-				if (opts?.replayed) {
-					logger.debug?.(`rine: no auto-reply for catch-up/replayed ${msg.id} (live-phase frames only)`);
-					return;
-				}
-				await replyToRine(client, msg, text, logger);
+				await deliverAnswer(client, msg, route, text, logger, agentId);
 			},
 			onRecordError: (err) => logger.warn(`rine: session-record error for ${msg.id}: ${msgOf(err)}`),
 			onDispatchError: (err) => {
@@ -249,9 +287,19 @@ function makeRuntimeDispatcher(params) {
 		if (dispatchErr) throw dispatchErr;
 	};
 }
-async function replyToRine(client, msg, text, logger) {
-	if (!text) return;
+/**
+* Route one agent turn back out to its audience. A group answer is a broadcast through the
+* lifted `rine_send` handler — the same call `channel.ts`'s outbound adapter already makes,
+* so no crypto or HTTP is reimplemented and the auto-answer does not become allowlist-gated
+* (the handler is invoked directly, never offered to the model). A 1:1 answer keeps the
+* reply-in-place path, which preserves the conversation.
+*/
+async function deliverAnswer(client, msg, route, text, logger, agentId) {
 	try {
+		if (route.kind === "group") {
+			await sendRineText(client, route.handle, text, agentId);
+			return;
+		}
 		await sendRineReply(client, msg, text);
 	} catch (err) {
 		logger.error(`rine: outbound reply failed for ${msg.id}: ${msgOf(err)}`);
@@ -387,7 +435,7 @@ async function deleteWebhook(client, webhookId, logger) {
 	}
 }
 async function fallbackToSse(tc) {
-	const { runSseTransport } = await import("./sse-CL8OTrkL.js");
+	const { runSseTransport } = await import("./sse-jRmQV4GZ.js");
 	await runSseTransport(tc);
 }
 function waitUntilAbort(signal) {
@@ -406,20 +454,23 @@ const SERVICE_ID = "rine-notify";
 async function runTransport(tc) {
 	switch (tc.config.transport) {
 		case "poll": {
-			const { runPollTransport } = await import("./poll-DKsUxQpG.js");
+			const { runPollTransport } = await import("./poll-BWvVevTN.js");
 			return runPollTransport(tc);
 		}
 		case "expose": return runExposeTransport(tc);
 		default: {
-			const { runSseTransport } = await import("./sse-CL8OTrkL.js");
+			const { runSseTransport } = await import("./sse-jRmQV4GZ.js");
 			return runSseTransport(tc);
 		}
 	}
 }
 /**
-* Resolve the rine agent id this install is bound to. `channels.rine.agentId` (a UUID,
-* handle, or bare name) wins; otherwise the org's sole agent is auto-selected — the same
-* resolution the CLI uses (`fetchAgents` + `resolveAgent`).
+* Resolve the UUID of the agent whose inbox the notify service reads. This is the
+* *transport* half of `channels.rine.agentId` — the tool half never comes here, because
+* `withActingAgent` hands rine-mcp the operator's string unresolved and it resolves once
+* per call. `channels.rine.agentId` (a UUID, handle, or bare name) wins, then `RINE_AGENT`,
+* then the org's sole agent — one ladder, `resolveActor`, the same one every other surface
+* climbs. Configuration beating the environment is precedence and stays silent.
 *
 * The OAuth `client_id` is NOT an agent id: credentials.json stores `client_id`/`client_secret`,
 * and binding the transport to it requests `/agents/{client_id}/stream|messages`, which 404s on
@@ -427,10 +478,28 @@ async function runTransport(tc) {
 * multi-agent org with no `agentId` set — both surface an actionable log; the gateway
 * health-monitor restarts the idle service, re-resolving once connectivity/config is fixed.
 */
+/**
+* How the TRANSPORT half spells the acting agent in a sentence it prints.
+*
+* `ACTOR_SURFACES.mcp` with the spelling replaced, on the precedent the core's own
+* `ACTOR_SURFACES` sets (`send --from` is `cli` with `alias` overridden — spread it,
+* do not mint a fourth entry): there is no `agent` parameter anywhere on this path.
+* The value came out of `openclaw.json`, so a warning telling the operator to "omit
+* agent" names a lever this surface does not have, and the one it does have —
+* `channels.rine.agentId` — is the one the catch branch below already names. No
+* `alias`: this surface never had a retired spelling, and it passes one value.
+*/
+const TRANSPORT_SURFACE = {
+	...ACTOR_SURFACES.mcp,
+	alias: void 0,
+	canonical: "channels.rine.agentId",
+	flagHint: "channels.rine.agentId"
+};
 async function resolveBoundAgentId(client, config, logger) {
 	try {
-		const agents = await fetchAgents(client.client);
-		return await resolveAgent(client.apiUrl, agents, config.agentId);
+		const resolved = await resolveActor(client.client, config.agentId, void 0, TRANSPORT_SURFACE);
+		if (resolved.warning !== void 0) logger.warn(`rine: ${resolved.warning}`);
+		return resolved.agentId;
 	} catch (err) {
 		logger.error(`rine: cannot resolve agent to bind (${err instanceof Error ? err.message : String(err)}). Set channels.rine.agentId (UUID or handle) or check connectivity — notify service idle.`);
 		return;
@@ -467,8 +536,57 @@ async function startNotifyLoop(params) {
 	await runTransport(tc);
 }
 /**
+* Whether `creds` carry everything the chosen transport needs. Onboarding writes
+* credentials.json in two steps — the OAuth entry first, `poll_url` seconds later once the
+* agent exists — so a POLL install waits for the second write. Picking credentials up in
+* between would freeze `pollUrl: undefined` into the transport context, and the poll loop
+* exits for good on a missing poll_url; it is also the bottom rung of the SSE fallback.
+*/
+function isTransportReady(creds, config) {
+	if (!creds.entry) return false;
+	return config.transport !== "poll" || Boolean(creds.pollUrl);
+}
+/**
+* Wait for rine credentials to appear, re-reading the config dir on the poll cadence.
+* A fresh install registers itself through `rine_onboard` mid-session; picking the new
+* credentials up here brings the inbox live without a gateway restart. Resolves undefined
+* when `stop()` aborts the wait.
+*/
+async function waitForCredentials(config, signal) {
+	while (!signal.aborted) {
+		try {
+			await sleep(config.pollIntervalMs, signal);
+		} catch {
+			return;
+		}
+		const creds = readRineCredentials(config);
+		if (isTransportReady(creds, config)) return creds;
+	}
+}
+/** Resolve credentials (waiting for them if the install has not onboarded), then run the loop. */
+async function startWhenCredentialed(params) {
+	const { api, config, signal, logger } = params;
+	let creds = readRineCredentials(config);
+	if (!creds.entry) {
+		logger.warn(`rine: no credentials.json at ${creds.configDir} — notify service idle until credentials appear (run rine_onboard or set RINE_CONFIG_DIR)`);
+		const found = await waitForCredentials(config, signal);
+		if (!found) return;
+		creds = found;
+		logger.info(`rine: credentials found at ${creds.configDir} — starting notify service`);
+	}
+	await startNotifyLoop({
+		api,
+		config,
+		creds,
+		client: buildRineClient(creds),
+		signal,
+		logger
+	});
+}
+/**
 * The single background notify service. `start(ctx)` resolves creds, owns the
-* AbortController (the service ctx has NO abort signal — see SDK_CONTRACT.md), then
+* AbortController — OpenClaw hands a service context that carries no abort signal, so
+* cancellation is ours to construct and ours to fire — then
 * hands off to `startNotifyLoop` which resolves the bound agent id and runs the transport.
 * `stop` aborts it. The long-lived loop lives here, not in a channel `gateway.startAccount`.
 */
@@ -479,22 +597,15 @@ function makeRineService(api) {
 		start(ctx) {
 			const logger = ctx.logger ?? api.logger;
 			const config = resolveRineConfigFromCfg(api.config);
-			const creds = readRineCredentials(config);
-			if (!creds.entry) {
-				logger.warn(`rine: no credentials.json at ${creds.configDir} — notify service idle (run rine_onboard or set RINE_CONFIG_DIR)`);
-				return;
-			}
-			const client = buildRineClient(creds);
 			controller = new AbortController();
 			const signal = controller.signal;
-			startNotifyLoop({
+			startWhenCredentialed({
 				api,
 				config,
-				creds,
-				client,
 				signal,
 				logger
 			}).catch((err) => {
+				if (signal.aborted) return;
 				logger.error(`rine: notify transport exited: ${err instanceof Error ? err.message : String(err)}`);
 			});
 		},
@@ -505,12 +616,116 @@ function makeRineService(api) {
 	};
 }
 //#endregion
+//#region src/tool-actor.ts
+/**
+* The exposed tools that take an acting agent.
+*
+* A set rather than a per-tool spelling: rine-mcp spells the concept `agent` on every one
+* of them, sends included, so the map's values had collapsed to one word and the only
+* thing left to record is membership. The retired spellings (`as`, and `from` on the two
+* sends) are still *read* by rine-mcp, but nothing here writes them — a wrapper that
+* defaulted a retired word would put it back in front of the model.
+*
+* A tool absent from this set takes no acting agent at all. Where such a tool has an
+* `agent`-shaped argument it means something else: `rine_inspect`'s `agent` is the
+* agent being looked up, `rine_onboard`'s `agent_name` names the agent being created,
+* and `rine_pay`/`rine_fulfill` derive the payee from the quote's own addressee.
+*
+* `rine_group_invite` is the tool the rename moved. Its `agent` used to be the
+* **invitee** and is now the actor, the invitee having taken its own `invitee` /
+* `invitees` slots. No presence check can tell those two readings apart — the property
+* exists either way — so the pair is pinned against the shipped schema by test, and
+* what makes that test meaningful is `invitee` existing at all: the invitee has
+* nowhere else to live. Swapping them would invite the installation's own agent and
+* report success.
+*/
+const ACTOR_TOOLS = new Set([
+	"rine_groups",
+	"rine_group_create",
+	"rine_group_join",
+	"rine_group_roster",
+	"rine_group_inspect",
+	"rine_group_invite",
+	"rine_group_invites",
+	"rine_group_requests",
+	"rine_group_vote",
+	"rine_group_leave",
+	"rine_group_remove",
+	"rine_group_sync",
+	"rine_group_reclaim",
+	"rine_send",
+	"rine_send_and_wait",
+	"rine_read",
+	"rine_inbox",
+	"rine_thread"
+]);
+/** The one word this plugin writes the acting agent into, as rine-mcp declares it. */
+const ACTOR_KEY = ACTOR_SURFACES.mcp.canonical;
+/** Throw on a tool in {@link ACTOR_TOOLS} that no longer declares `agent`. */
+function assertDeclaresActor(def) {
+	const props = def.inputSchema.properties;
+	if (props === void 0 || !(ACTOR_KEY in props)) throw new Error(`rine: mcp tool "${def.name}" no longer declares its acting-agent parameter "${ACTOR_KEY}" — version skew`);
+}
+/**
+* Bind the acting agent this install is configured for (`channels.rine.agentId`) as the
+* default of the tool's own acting-agent argument. Without it the plugin emits
+* `X-Rine-Agent` on no tool call at all, so a host running several agents acts as
+* whichever one the org's single-agent shortcut picks — or fails to resolve one.
+*
+* The operator's string travels **unresolved**: rine-mcp accepts a name, handle or UUID
+* and resolves it per call. This is the tool-facing half of `channels.rine.agentId`, and
+* it is not the same object as the notify service's binding — `resolveBoundAgentId`
+* turns the same setting into one UUID, up front, for the inbox the transports read.
+*
+* A model-supplied value still wins, so the operator's binding is a default and not a
+* cap — but an empty string names nobody, and letting one through would discard the
+* binding and hand the choice straight back to the server. 🔴 "Did the model name one?"
+* is rine-mcp's question to answer, not this file's: it reads retired spellings this
+* plugin never writes, and defaulting `agent` beside a model-supplied `from` would turn
+* one caller's choice into a two-values refusal. Configuration is a lower rung than the
+* call, and a lower rung loses silently.
+*
+* Mirrors {@link withAutoPayDefault}: one argument re-defaulted, nothing else touched. A
+* tool with no acting-agent argument is returned unchanged, and a tool whose argument has
+* disappeared upstream throws at load rather than silently dropping the actor — the
+* same version-skew posture as `requireTool`.
+*/
+function withActingAgent(def, agentId) {
+	if (agentId === void 0) return def;
+	if (!ACTOR_TOOLS.has(def.name)) return def;
+	assertDeclaresActor(def);
+	return {
+		...def,
+		handler: (ctx, params) => {
+			const args = { ...params ?? {} };
+			if (!namesActor(args, actorKeysFor(def.name))) args[ACTOR_KEY] = agentId;
+			return def.handler(ctx, args);
+		}
+	};
+}
+//#endregion
 //#region src/tools.ts
 /** Tools exposed by the plugin (filtered from the mcp tool array). */
 const EXPOSED_TOOLS = [
 	"rine_whoami",
 	"rine_discover",
+	"rine_inspect",
+	"rine_discover_groups",
+	"rine_groups",
+	"rine_group_create",
+	"rine_group_join",
+	"rine_group_roster",
+	"rine_group_inspect",
+	"rine_group_invite",
+	"rine_group_invites",
+	"rine_group_requests",
+	"rine_group_vote",
+	"rine_group_leave",
+	"rine_group_remove",
+	"rine_group_sync",
+	"rine_group_reclaim",
 	"rine_send",
+	"rine_send_and_wait",
 	"rine_read",
 	"rine_inbox",
 	"rine_thread",
@@ -518,12 +733,52 @@ const EXPOSED_TOOLS = [
 	"rine_pay",
 	"rine_fulfill"
 ];
-/** Mutating tools gated behind the allowlist (manifest `toolMetadata.optional`). */
+/**
+* Tools with an irreversible external effect ON A THIRD PARTY, gated behind the operator's
+* tool allowlist. The manifest's `toolMetadata.optional` carries the same set — OpenClaw ORs
+* the two, so both must agree. `rine_send` and `rine_send_and_wait` speak to a third party
+* over an encrypted channel — the second one is a send like any other, and the reply it waits
+* for does not make the message it already delivered take-backable;
+* `rine_pay` moves funds and `rine_fulfill` settles on-chain.
+*
+* `rine_group_invite`, `rine_group_vote`, `rine_group_remove` and `rine_group_reclaim` join
+* them for the same reason. An invite acts on the group's roster on membership alone: the
+* server authorises it with read access rather than admin on every policy but `closed`. On
+* a closed group it hands the named agent a seat it can redeem straight away, together with
+* a ratchet-tree leaf and Welcome minted inside the same call; on a majority or unanimity
+* group it files a join request in the group's name and spends this host's own approval on
+* it, and the electorate decides. An approve that crosses a group's threshold hands a
+* stranger the group's keys and cannot be taken back. A remove evicts somebody else — on an
+* MLS group it posts a Remove commit that takes their ratchet-tree leaf and that every
+* member downloads at O(N). Reclamation posts one Remove commit per orphaned leaf, and an
+* agent whose invitation lapsed and who is re-invited between the tree read and the commit
+* loses the fresh leaf with them.
+*
+* Note the asymmetry with the ungated `rine_group_sync`, whose expensive rung also costs
+* the group O(N): the criterion is an irreversible effect on a THIRD PARTY, not cost.
+*
+* Every other group verb is offered under the default empty allowlist, on the same reasoning
+* that keeps `rine_onboard` out of this set: gating a tool the plugin's core function depends
+* on leaves a fresh agent unable to work. An agent that cannot create, discover, join or read
+* a group is not a group participant at all, and an operator would have to edit the allowlist
+* before the plugin did anything with groups. Note the asymmetry with `rine_group_leave`,
+* which is irreversible but acts only on THIS host: gating it would leave an agent unable to
+* get out of a group somebody else put it in.
+*
+* `rine_onboard` is deliberately absent: registering the org is the first thing an
+* uncredentialed install does, and on an install that already holds credentials the tool
+* returns the existing org and writes nothing. Gating it leaves a fresh agent unable to
+* register itself.
+*/
 const OPTIONAL_TOOLS = new Set([
 	"rine_send",
-	"rine_onboard",
+	"rine_send_and_wait",
 	"rine_pay",
-	"rine_fulfill"
+	"rine_fulfill",
+	"rine_group_invite",
+	"rine_group_vote",
+	"rine_group_remove",
+	"rine_group_reclaim"
 ]);
 /**
 * Payee tools exposed only when the installed mcp actually provides them. `rine_fulfill`
@@ -531,6 +786,12 @@ const OPTIONAL_TOOLS = new Set([
 * `^`-range that includes it, so real installs always expose it. This lenience only covers
 * the version window where a locally-linked mcp predates the payee tool — it never masks a
 * skew of a tool openclaw's core function depends on (those stay strict via `requireTool`).
+*
+* The group verbs are deliberately NOT lenient. `publish-package.sh` rewrites the `file:`
+* mcp dep to a `^`-range on mcp's current version, so a published openclaw can never resolve
+* an mcp without them; lenience would only take effect against a locally-linked older mcp,
+* where it would let the plugin load with the group surface silently missing and every gate
+* still green. That fake-green is the failure this set exists to avoid, not to create.
 */
 const LENIENT_TOOLS = new Set(["rine_fulfill"]);
 const CIPHERTEXT_KEYS = ["encrypted_payload", "self_encrypted_payload"];
@@ -584,7 +845,7 @@ function assertInternalTools(all = tools) {
 /**
 * Adapt one mcp ToolDef into an OpenClaw AnyAgentTool with ciphertext stripping.
 * `parameters` is rine-mcp's JSON-schema `inputSchema`; `registerTool` stores it
-* verbatim (no TypeBox validation — see SDK_CONTRACT.md), so the whole tool object
+* verbatim and validates none of it against TypeBox, so the whole tool object
 * is cast to `AnyAgentTool` at one documented seam. (typebox is a transitive dep of
 * openclaw, not directly importable, so we never reference its `TSchema` type.)
 *
@@ -630,15 +891,20 @@ function withAutoPayDefault(def, autoPay) {
 	};
 }
 /**
-* Register the exposed rine tools on the plugin api. `rine_send`/`rine_onboard` and the
-* fund-moving `rine_pay`/`rine_fulfill` are registered `{ optional: true }` (allowlist
-* gating per manifest toolMetadata). Internal deps (`rine_reply`) are validated here too so
-* version skew fails at load. With `opts.autoPay`, `rine_pay` is threshold-gated by default.
+* Register the exposed rine tools on the plugin api. The {@link OPTIONAL_TOOLS} register
+* `{ optional: true }`, so OpenClaw offers them only when the agent's tool allowlist names
+* them; every other tool — `rine_onboard` included — is offered under the default empty
+* allowlist. Internal deps (`rine_reply`) are validated here too so version skew fails at
+* load. With `opts.autoPay`, `rine_pay` is threshold-gated by default; with `opts.agentId`,
+* every tool that declares an acting-agent argument defaults it to that agent (see
+* {@link withActingAgent}). What each tool then does with the argument is rine-mcp's:
+* nearly all of them send it as `X-Rine-Agent`, while `rine_read` reads it only to pick
+* the identity it decrypts as and sends no header of its own.
 */
 function registerRineTools(api, ctx, opts = {}) {
 	assertInternalTools(opts.tools);
 	for (const def of selectExposedTools(opts.tools)) {
-		const tuned = withAutoPayDefault(def, opts.autoPay === true);
+		const tuned = withActingAgent(withAutoPayDefault(def, opts.autoPay === true), opts.agentId);
 		const regOpts = OPTIONAL_TOOLS.has(def.name) ? {
 			name: def.name,
 			optional: true
@@ -665,7 +931,10 @@ var rine_openclaw_default = defineChannelPluginEntry({
 	},
 	registerFull(api) {
 		const config = resolveRineConfigFromCfg(api.config);
-		registerRineTools(api, buildRineClient(readRineCredentials(config)).toolContext, { autoPay: config.payments.autoPay });
+		registerRineTools(api, buildRineClient(readRineCredentials(config)).toolContext, {
+			autoPay: config.payments.autoPay,
+			agentId: config.agentId
+		});
 		registerExposeRoute(api);
 		api.registerService(makeRineService(api));
 	}

package/dist/{poll-DKsUxQpG.js → poll-BWvVevTN.js}

@@ -1,5 +1,4 @@
-import { r as normalizeRineEvent } from "./inbound-DEe69mNL.js";
-import { n as sleep } from "./backoff-BMNABavv.js";
+import { a as normalizeRineEvent, n as sleep } from "./backoff-a3Dly8X4.js";
 //#region src/transports/poll.ts
 /**
 * POLL transport — least token-intensive. Fixed-interval `GET /poll/{token}` (unauth);

package/dist/setup.js

@@ -1,4 +1,4 @@
-import { a as resolveRineConfig, i as readRineCredentials, t as rinePlugin } from "./channel-DqxESY90.js";
+import { a as readRineCredentials, o as resolveRineConfig, t as rinePlugin } from "./channel-DiPLuJsk.js";
 import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
 //#region setup.ts
 /** Auto-detect existing rine creds for the setup flow. Pure read; no writes. */

package/dist/src/channel.d.ts

@@ -9,6 +9,8 @@ export interface RineAccount {
  * the notify service + dispatch seam (the canonical reply path lives on the runtime
  * singleton, available to the service), so the channel object stays thin — it advertises
  * the `rine` channel so sessions key as `agent:<id>:rine:<kind>:<peer>` and the channel
- * surfaces in `plugins inspect`. See SDK_CONTRACT.md.
+ * surfaces in `plugins inspect`. Those four are what `ChannelPlugin` itself requires;
+ * everything else on this object is setup, reload and target resolution, plus the
+ * outbound adapter core needs before it will deliver to a rine handle at all.
  */
 export declare const rinePlugin: ChannelPlugin<RineAccount>;

package/dist/src/outbound.d.ts

@@ -13,9 +13,12 @@ export declare function sendRineReply(client: RineClient, inbound: RineInbound,
  * and delivers (without this the channel had no outbound surface — the agent's
  * generic send failed with `Unknown target … for rine`).
  *
- * `from` (the sending agent id) is passed only when configured; in a single-agent
- * org `rine_send` resolves the sole agent itself.
+ * `agent` (the sending agent, by name, handle or UUID) is passed only when configured;
+ * without it `rine_send` climbs its own ladder — `RINE_AGENT`, then the org's sole
+ * agent — and refuses in a multi-agent org rather than guessing. It was spelled `from`
+ * here until the rename; `rine_send` still reads that word from a stale caller, but
+ * nothing in this plugin writes it.
  */
-export declare function sendRineText(client: RineClient, to: string, text: string, from?: string): Promise<{
+export declare function sendRineText(client: RineClient, to: string, text: string, agent?: string): Promise<{
     messageId: string;
 }>;

package/dist/src/rine-client.d.ts

@@ -39,5 +39,10 @@ export interface RineClient {
  * Build the rine HTTP client + ToolContext from resolved creds. Mirrors
  * rine-mcp/src/server.ts bootstrap: tokenFn = getCredentialEntry + getOrRefreshToken;
  * new HttpClient({ tokenFn, apiUrl, canRefresh }).
+ *
+ * The credential entry is resolved on every token mint rather than captured once, so a
+ * client built before the install had credentials keeps working after `rine_onboard`
+ * writes them — without it the disk-cached onboarding token is the only thing the client
+ * ever has, and every call fails once that token reaches its refresh margin.
  */
 export declare function buildRineClient(creds: ResolvedCreds): RineClient;