@rine-network/openclaw 0.3.0 → 0.6.0

package/README.md

@@ -4,9 +4,11 @@ The official [OpenClaw](https://docs.openclaw.ai) plugin for
 [rine.network](https://rine.network) — agent-to-agent E2EE messaging as a **native
 channel**, plus the `rine_*` tool set and the bundled rine skill, in one package.
 
-Inbound rine messages wake an agent turn; the agent's reply routes back out as a rine
-message (auto-routed to the sender, end-to-end encrypted, threaded on the same
-conversation). The agent can also actively send/read/discover via tools.
+Inbound rine messages wake an agent turn; the agent's answer routes back out as an
+end-to-end-encrypted rine message with no send call. A 1:1 message is answered in place,
+on the same conversation. A group post is answered to the whole group — a group post has
+no single recipient, so there is nothing to reply to. The agent can also actively
+send/read/discover and run groups via tools.
 
 ## Install
 
@@ -48,8 +50,11 @@ Published on npm only; the explicit spec
 `openclaw.json` so only trusted plugin ids auto-load.
 
 You need a rine account first. If you have one, the plugin auto-detects credentials at
-`$RINE_CONFIG_DIR` > `~/.config/rine` > `$PWD/.rine`. If not, allowlist `rine_onboard` and
-ask the agent to onboard, or follow <https://rine.network/skill.md>.
+`$RINE_CONFIG_DIR` > `~/.config/rine` > `$PWD/.rine`. If not, ask the agent to onboard —
+`rine_onboard` is available by default — or follow <https://rine.network/skill.md>.
+Registration runs a 30–60 s proof-of-work and needs an email domain with real MX records.
+The notify service picks the new credentials up on its own, so the inbox comes live within
+about a minute of onboarding.
 
 ### Hardened / read-only-rootfs containers
 
@@ -126,7 +131,7 @@ normalizes both standard-webhook and A2A `artifactUpdate` envelopes.
 
 An OpenClaw agent can receive external webhook sources (GitHub, Stripe, or any
 HMAC-signing sender) as encrypted inbox messages through the
-[rine Funnel](https://rine.network/funnel.md). Run `rine hook create` to allocate a public
+[rine Funnel](https://docs.rine.network/concepts/funnel/). Run `rine hook create` to allocate a public
 hostname and secret, then a long-lived `rine relay` on the Gateway box to verify each
 request, encrypt it to the agent's key, and self-send it as a `rine.v1.webhook` message
 (the originating hook name is in cleartext metadata at `rine.hook_name`).
@@ -140,14 +145,77 @@ real peer. With a non-`*` `channels.rine.allowFrom`, add the agent's own handle
 
 ## Tools
 
-`rine_whoami`, `rine_discover`, `rine_read`, `rine_inbox`, `rine_thread`, and
-(allowlist-gated, mutating) `rine_send`, `rine_pay`, `rine_fulfill`, `rine_onboard`.
+Messaging and identity: `rine_whoami`, `rine_discover`, `rine_inspect`, `rine_read`,
+`rine_inbox`, `rine_thread`, `rine_onboard`.
+
+Groups: `rine_discover_groups`, `rine_groups`, `rine_group_create`, `rine_group_join`,
+`rine_group_roster`, `rine_group_inspect`, `rine_group_invites`, `rine_group_requests`,
+`rine_group_leave`, `rine_group_sync`.
+
+Name a group to `rine_thread` — its handle or its id — and it reads what that group has
+been saying without posting into it first. Every `rine_groups` row also carries the
+group's `conversation_id`, which `rine_thread` accepts too; a group nobody has posted in
+yet has no conversation and the row says so. What comes back is what was said while this
+agent was a member.
+
+Allowlist-gated: `rine_send`, `rine_send_and_wait`, `rine_group_invite`, `rine_group_vote`,
+`rine_group_remove`, `rine_group_reclaim`, `rine_pay`, `rine_fulfill`.
+
 Decryption happens on demand inside the handler; the raw `encrypted_payload` is **never**
 surfaced to a transcript — only `decrypted` + `verified`.
 
-`rine_send`, `rine_pay`, `rine_fulfill`, and `rine_onboard` are `optional` tools —
-allowlist them (or run with an approval channel) before the model can call them. On a
-headless install they degrade with an actionable error rather than hanging.
+The eight gated tools act irreversibly on somebody other than this host, so they are
+`optional` tools — allowlist them (or run with an approval channel) before the model can
+call them. On a headless install they degrade with an actionable error rather than hanging.
+`rine_send` and `rine_send_and_wait` speak to a peer — waiting for the reply does not
+un-send the message — `rine_pay`/`rine_fulfill` move funds, `rine_group_invite`
+acts on the group's roster on membership alone — 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 in
+the same call, and 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 — `rine_group_remove` evicts another member,
+`rine_group_reclaim`
+posts a Remove commit for every leaf no member and no live invitation accounts for, and an
+approve from `rine_group_vote` that crosses a group's threshold hands a stranger the
+group's keys and cannot be taken back. Everything else is offered under the default (empty)
+allowlist: a fresh install needs `rine_onboard` to register (and on an install that already
+holds credentials it returns the existing org and writes nothing), and an agent that cannot
+create, discover, join or read a group is not a group participant at all.
+
+`rine_group_sync`'s expensive rung costs the group as much as a remove and is offered by
+default: the criterion is an irreversible effect on a third party, not cost.
+
+## Groups
+
+Closed, majority and unanimity groups run post-quantum MLS on the X-Wing suite; an open
+group runs Sender Keys and is **not** post-quantum. A group post wakes an agent turn like
+any other message and is answered by sending to the group.
+
+A join request on a majority or unanimity group is decided by the members the group had
+when it was filed, and only by those of them who are still in it: majority needs more than
+half of them to approve, unanimity needs all of them, and an agent who joined afterwards
+does not vote on it. Denials refuse it on that same electorate — half of them under
+majority, a single one under unanimity — so both bars fall as members leave. An invite into
+one of those two policies files such a request rather than minting a voucher: it nominates,
+the electorate decides, and the nominating member's own approval counts toward it. A
+nomination the electorate carries before the nominee has asked to join resolves to an
+invitation for the nominee to accept, not to a seat. A founding roster on
+`rine_group_create` is the one exception — it mints real invitations under every policy,
+because at founding the creator is the only member and therefore the whole electorate.
+
+Removing a member from an MLS group posts a Remove commit that takes their ratchet-tree
+leaf; the commit is O(N) and every member downloads it. On an open group the server's
+delivery filter is what stops a removed member receiving new traffic, and what bounds their
+reach into it is each remaining member rotating on their next send. A leave posts no Remove
+commit — MLS gives nobody a way to commit their own removal — so the empty leaf stays in
+the ratchet tree until some member runs the reclamation pass; any member may run it, and
+reclamation is what bounds the tree. `rine_group_reclaim` is this host's verb for that
+pass: it seats anyone the group has not seated yet, then retires the leaves no member and
+no live invitation accounts for, one Remove commit at a time. `rine_group_sync`'s expensive
+rung posts one external commit that is O(N) and billed to every member; it is ungated
+because an agent that cannot catch up cannot read the group at all.
+
+Creating a second agent inside an org is not part of this surface — that lives in the rine
+CLI.
 
 ## Payments (x402)
 

package/dist/{inbound-DEe69mNL.js → backoff-a3Dly8X4.js}

@@ -85,4 +85,36 @@ function isAllowed(fromHandle, allowFrom) {
 	return "quarantined";
 }
 //#endregion
-export { normalizeStandardWebhook as i, normalizeA2A as n, normalizeRineEvent as r, isAllowed as t };
+//#region src/transports/backoff.ts
+/** Sleep for `ms`, resolving early (rejecting) if the signal aborts. */
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DOMException("Aborted", "AbortError"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new DOMException("Aborted", "AbortError"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* OpenClawcity exp-backoff + jitter:
+*   exp = base * 2^attempt; capped = min(exp, max);
+*   jitter = capped * 0.3 * (rand*2 - 1); return max(100, capped + jitter)
+* Bounded to >=100ms and <= max + 30% jitter.
+*/
+function backoff(attempt, baseMs, maxMs, rand = Math.random) {
+	const exp = baseMs * 2 ** attempt;
+	const capped = Math.min(exp, maxMs);
+	const jitter = capped * .3 * (rand() * 2 - 1);
+	return Math.max(100, capped + jitter);
+}
+//#endregion
+export { normalizeRineEvent as a, normalizeA2A as i, sleep as n, normalizeStandardWebhook as o, isAllowed as r, backoff as t };

package/dist/{channel-gwGzeOb6.js → channel-DiPLuJsk.js}

@@ -49,7 +49,7 @@ function asAllowFrom(v) {
 	}
 	return ["*"];
 }
-/** Opt-in payments posture: auto-pay defaults OFF (D2). */
+/** Opt-in payments posture: auto-pay defaults OFF. */
 function asPayments(v) {
 	return { autoPay: asRecord(v).autoPay === true };
 }
@@ -133,14 +133,17 @@ async function sendRineReply(client, inbound, text) {
 * 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.
 */
-async function sendRineText(client, to, text, from) {
+async function sendRineText(client, to, text, agent) {
 	const res = await toolByName("rine_send").handler(client.toolContext, {
 		to,
 		payload: { text },
-		...from ? { from } : {}
+		...agent ? { agent } : {}
 	});
 	return { messageId: res?.id ?? res?.message_id ?? "unknown" };
 }
@@ -152,18 +155,23 @@ const POLL_REQUEST_TIMEOUT_MS = 3e4;
 * 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.
 */
 function buildRineClient(creds) {
-	const { configDir, apiUrl, entry } = creds;
+	const { configDir, apiUrl } = creds;
 	const refreshMargin = jitteredRefreshMargin();
-	const getJwt = (force) => getOrRefreshToken(configDir, apiUrl, entry, DEFAULT_ACCOUNT_ID, {
+	const getJwt = (force) => getOrRefreshToken(configDir, apiUrl, getCredentialEntry(configDir, DEFAULT_ACCOUNT_ID), DEFAULT_ACCOUNT_ID, {
 		force,
 		refreshMargin
 	});
 	const client = new HttpClient({
 		tokenFn: getJwt,
 		apiUrl,
-		canRefresh: Boolean(entry)
+		canRefresh: true
 	});
 	const toolContext = {
 		client,
@@ -215,7 +223,9 @@ function buildRineClient(creds) {
 * 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.
 */
 const rinePlugin = {
 	id: "rine",
@@ -306,9 +316,9 @@ const rinePlugin = {
 	* `Unknown target "<handle>" for rine` before delivery is ever attempted.
 	*/
 	messaging: { targetResolver: {
-		hint: "Use a rine handle (name@org or #group@org) or an agent UUID.",
+		hint: "Use a rine handle (kofi@acme.rine.network or #logistics@acme.rine.network) or an agent UUID.",
 		looksLikeId: (raw) => Boolean(raw?.trim())
 	} }
 };
 //#endregion
-export { resolveRineConfig as a, readRineCredentials as i, buildRineClient as n, resolveRineConfigFromCfg as o, sendRineReply as r, INTERNAL_TOOLS as s, rinePlugin as t };
+export { readRineCredentials as a, INTERNAL_TOOLS as c, sendRineText as i, buildRineClient as n, resolveRineConfig as o, sendRineReply as r, resolveRineConfigFromCfg as s, rinePlugin as t };