@rine-network/openclaw 0.4.0 → 0.6.0

package/dist/src/runtime-dispatch.d.ts

@@ -2,15 +2,25 @@ import type { OpenClawConfig, PluginLogger, PluginRuntime } from "openclaw/plugi
 import { type DispatchFn } from "./dispatch.js";
 import type { RineClient } from "./rine-client.js";
 import type { RineInbound } from "./types.js";
+/** Where an agent's turn is delivered: to the whole group, or back to the sender. */
+type AnswerRoute = {
+    kind: "group" | "direct";
+    handle: string;
+};
 /**
  * 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.
  */
-export declare function pointerText(msg: RineInbound): string;
+export declare function pointerText(msg: RineInbound, route?: AnswerRoute): string;
 /**
  * Production dispatch fn: wakes an agent turn for one inbound rine message via the
  * canonical `dispatchInboundDirectDmWithRuntime` helper. `api.config` (cfg) and
@@ -26,3 +36,4 @@ export declare function makeRuntimeDispatcher(params: {
     agentId: string;
     logger: PluginLogger;
 }): DispatchFn;
+export {};

package/dist/src/service.d.ts

@@ -5,21 +5,11 @@ import type { TransportContext } from "./transports/context.js";
 import type { RineConfig } from "./types.js";
 /** Run the chosen transport. Exposed for testing with a stubbed transport map. */
 export declare function runTransport(tc: TransportContext): Promise<void>;
-/**
- * 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`).
- *
- * 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
- * every transport. Returns undefined (the service idles) on a network error or an ambiguous
- * 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.
- */
 export declare function resolveBoundAgentId(client: RineClient, config: RineConfig, logger: PluginLogger): Promise<string | undefined>;
 /**
  * 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`.
  */

package/dist/src/tool-actor.d.ts

@@ -0,0 +1,52 @@
+import type { ToolDef } from "@rine-network/mcp/tools";
+import type { EXPOSED_TOOLS } from "./tools.js";
+type ExposedTool = (typeof EXPOSED_TOOLS)[number];
+/**
+ * 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.
+ */
+export declare const ACTOR_TOOLS: ReadonlySet<ExposedTool>;
+/**
+ * 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`.
+ */
+export declare function withActingAgent(def: ToolDef, agentId: string | undefined): ToolDef;
+export {};

package/dist/src/tools.d.ts

@@ -2,8 +2,44 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { AnyAgentTool } from "openclaw/plugin-sdk";
 import type { ToolContext, ToolDef } from "@rine-network/mcp/tools";
 /** Tools exposed by the plugin (filtered from the mcp tool array). */
-export declare const EXPOSED_TOOLS: readonly ["rine_whoami", "rine_discover", "rine_send", "rine_read", "rine_inbox", "rine_thread", "rine_onboard", "rine_pay", "rine_fulfill"];
-/** Mutating tools gated behind the allowlist (manifest `toolMetadata.optional`). */
+export declare const EXPOSED_TOOLS: readonly ["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", "rine_onboard", "rine_pay", "rine_fulfill"];
+/**
+ * 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.
+ */
 export declare const OPTIONAL_TOOLS: Set<string>;
 /**
  * Strip raw ciphertext from any tool result before it reaches a transcript.
@@ -27,7 +63,7 @@ export declare function assertInternalTools(all?: ToolDef[]): void;
 /**
  * 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.)
  *
@@ -49,12 +85,19 @@ export declare function withAutoPayDefault(def: ToolDef, autoPay: boolean): Tool
 /** Options for {@link registerRineTools}. `tools` is a test seam (defaults to mcpTools). */
 export interface RegisterToolsOptions {
     autoPay?: boolean;
+    /** The agent this install acts as (`channels.rine.agentId`), named on every tool call that takes one. */
+    agentId?: string;
     tools?: ToolDef[];
 }
 /**
- * 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.
  */
 export declare function registerRineTools(api: OpenClawPluginApi, ctx: ToolContext, opts?: RegisterToolsOptions): void;

package/dist/src/types.d.ts

@@ -52,6 +52,14 @@ export interface RinePaymentsConfig {
 export interface RineConfig {
     transport: "expose" | "sse" | "poll";
     configDir?: string;
+    /**
+     * The agent this install acts as, exactly as the operator wrote it — a bare name, a
+     * handle or a UUID, never resolved here. Its two consumers are not the same notion:
+     * `resolveBoundAgentId` turns it into the UUID the notify service binds its inbox to,
+     * while `withActingAgent` threads the raw string onto every tool call as that call's
+     * acting-agent default and lets rine-mcp resolve it per call. Unset means "the org's
+     * only agent" on both paths, and nothing at all on an org that has several.
+     */
     agentId?: string;
     baseUrl?: string;
     pollIntervalMs: number;

package/dist/{sse-CL8OTrkL.js → sse-jRmQV4GZ.js}

@@ -1,5 +1,4 @@
-import { r as normalizeRineEvent } from "./inbound-DEe69mNL.js";
-import { n as sleep, t as backoff } from "./backoff-BMNABavv.js";
+import { a as normalizeRineEvent, n as sleep, t as backoff } from "./backoff-a3Dly8X4.js";
 import { n as saveCursor, t as loadCursor } from "./cursor-DPl6-dKW.js";
 //#region src/transports/sse.ts
 const MAX_ATTEMPTS_BEFORE_FALLBACK = 5;
@@ -57,7 +56,7 @@ async function runSseTransport(tc) {
 		logger.warn(`rine: SSE stream error (attempt ${attempt}): ${err instanceof Error ? err.message : String(err)}`);
 		if (attempt >= MAX_ATTEMPTS_BEFORE_FALLBACK) {
 			logger.warn("rine: SSE failed repeatedly — falling back to POLL transport");
-			const { runPollTransport } = await import("./poll-DKsUxQpG.js");
+			const { runPollTransport } = await import("./poll-BWvVevTN.js");
 			await runPollTransport(tc);
 			return;
 		}

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "kind": "channel",
   "name": "rine",
   "description": "Agent-to-agent E2EE messaging over the rine network (A2A relay / SSE / poll).",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "channels": ["rine"],
   "skills": ["skills/rine"],
   "activation": { "onStartup": true },
@@ -11,7 +11,23 @@
     "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",
@@ -22,9 +38,13 @@
   },
   "toolMetadata": {
     "rine_send": { "optional": true },
-    "rine_onboard": { "optional": true },
+    "rine_send_and_wait": { "optional": true },
     "rine_pay": { "optional": true },
-    "rine_fulfill": { "optional": true }
+    "rine_fulfill": { "optional": true },
+    "rine_group_invite": { "optional": true },
+    "rine_group_vote": { "optional": true },
+    "rine_group_remove": { "optional": true },
+    "rine_group_reclaim": { "optional": true }
   },
   "uiHints": {
     "exposeBaseUrl": {
@@ -55,7 +75,7 @@
           },
           "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",
@@ -64,7 +84,7 @@
           "pollIntervalMs": {
             "type": "number",
             "default": 60000,
-            "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",
@@ -135,7 +155,7 @@
       },
       "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",
@@ -144,7 +164,7 @@
       "pollIntervalMs": {
         "type": "number",
         "default": 60000,
-        "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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/openclaw",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Official OpenClaw plugin for rine.network \u2014 agent-to-agent E2EE messaging as a native channel, with A2A-relay / SSE / poll transports, tools, and the bundled rine skill.",
   "type": "module",
   "main": "dist/index.js",
@@ -60,12 +60,11 @@
     "build": "tsdown && tsc --emitDeclarationOnly -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "sync-skill": "node scripts/sync-skill.mjs",
     "prepublishOnly": "node scripts/check-no-file-deps.mjs"
   },
   "dependencies": {
-    "@rine-network/core": "^0.12.0",
-    "@rine-network/mcp": "^0.9.0"
+    "@rine-network/core": "^0.14.0",
+    "@rine-network/mcp": "^0.11.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.6.1"
@@ -80,7 +79,7 @@
   "homepage": "https://rine.network",
   "repository": {
     "type": "git",
-    "url": "https://codeberg.org/rine/openclaw"
+    "url": "https://codeberg.org/rine/rine-openclaw"
   },
   "publishConfig": {
     "access": "public"