@rine-network/openclaw 0.1.5 → 0.2.1

package/README.md

@@ -12,7 +12,7 @@ conversation). The agent can also actively send/read/discover via tools.
 
 ```bash
 # 1. Install and enable the plugin
-openclaw plugins install npm:@rine-network/openclaw
+openclaw plugins install @rine-network/openclaw
 openclaw plugins enable rine
 ```
 
@@ -42,8 +42,8 @@ openclaw gateway restart
 openclaw plugins inspect rine --runtime --json   # verify channel + tools + service + route
 ```
 
-Published on npm only (`npm:@rine-network/openclaw`); the plain spec
-`openclaw plugins install @rine-network/openclaw` works too. The Gateway warns when
+Published on npm only; the explicit spec
+`openclaw plugins install npm:@rine-network/openclaw` works too. The Gateway warns when
 `plugins.allow` is empty — for a locked-down host, add `rine` to `plugins.allow` in
 `openclaw.json` so only trusted plugin ids auto-load.
 
@@ -122,10 +122,26 @@ Optional A2A per-task push (`CreateTaskPushNotificationConfig`) is a layer on to
 standard webhook (it needs an existing conversation/taskId); the `/rine/inbound` handler
 normalizes both standard-webhook and A2A `artifactUpdate` envelopes.
 
+## Inbound webhooks (the rine Funnel)
+
+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
+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`).
+
+A Funnel webhook is a **one-way event**: the relay sends it on the agent's behalf, so its
+sender is the agent's own handle. Act on the webhook — don't reply to its sender. A reply
+targets the agent itself, which rine rejects (OpenClaw logs a non-fatal
+`Cannot reply to your own message` and carries on); to follow up, send a new message to a
+real peer. With a non-`*` `channels.rine.allowFrom`, add the agent's own handle (or its
+`@org`) or the self-sent webhook is quarantined.
+
 ## Tools
 
-`rine_whoami`, `rine_discover`, `rine_read`, `rine_inbox`, and (allowlist-gated, mutating)
-`rine_send`, `rine_onboard`. Decryption happens on demand inside the handler; the raw
+`rine_whoami`, `rine_discover`, `rine_read`, `rine_inbox`, `rine_thread`, and
+(allowlist-gated, mutating) `rine_send`, `rine_onboard`. Decryption happens on demand inside the handler; the raw
 `encrypted_payload` is **never** surfaced to a transcript — only `decrypted` + `verified`.
 
 `rine_send` / `rine_onboard` are `optional` tools — allowlist them (or run with an approval
@@ -162,6 +178,12 @@ openclaw plugins doctor
 - **`npm ... ENOENT ... mkdir '…/.npm'` while installing:** read-only-rootfs host — npm can't
   write its default cache. See _Hardened / read-only-rootfs containers_ under **Install**.
 
+## For AI Agents
+
+- [Platform docs](https://rine.network/llms.txt)
+- [OpenClaw integration docs](https://rine.network/openclaw.md)
+- [Protocol](https://rine.network/protocol.md)
+
 ## License
 
 EUPL-1.2.

package/dist/{channel-DpHhVQ-n.js → channel-BPBnthxw.js}

@@ -12,6 +12,12 @@ import { tools } from "@rine-network/mcp/tools";
 */
 const DEFAULT_ACCOUNT_ID = "default";
 /**
+* The rine channel / plugin id. It is the key under both `channels.<id>` (activation +
+* effective config) and `plugins.entries.<id>` in openclaw.json, and the `id` this plugin
+* registers under. Shared so the config resolver reads the same block the channel activates.
+*/
+const CHANNEL_ID = "rine";
+/**
 * Internal mcp tools the plugin depends on at runtime but does NOT expose to the agent.
 * Validated at startup (alongside `selectExposedTools`) so a rename of an mcp tool fails
 * fast at load, not at first reply. `rine_reply` backs the inbound→reply dispatch path;
@@ -43,7 +49,7 @@ function asAllowFrom(v) {
 	}
 	return ["*"];
 }
-/** Resolve the typed config from a raw `api.pluginConfig` (or `{}`), applying defaults. */
+/** Resolve the typed config from a raw config record (or `{}`), applying defaults. */
 function resolveRineConfig(raw = {}) {
 	return {
 		transport: asTransport(raw.transport),
@@ -58,6 +64,28 @@ function resolveRineConfig(raw = {}) {
 		allowFrom: asAllowFrom(raw.allowFrom)
 	};
 }
+function asRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
+}
+/**
+* Resolve the typed config from a live OpenClawConfig (`api.config` / an outbound `ctx.cfg`).
+*
+* `channels.rine` is the documented, activation-required home for `transport`/`allowFrom`/etc.,
+* so it is authoritative; `plugins.entries.rine.config` is merged underneath as a fallback for
+* installs that placed config there (both are validated against the same manifest schema). This
+* is the single source of truth for the notify service, the tool client, and the outbound
+* adapter — before, the service/tools read `api.pluginConfig` (`plugins.entries.rine.config`)
+* while outbound read `channels.rine`, so `channels.rine.transport` was silently ignored.
+*/
+function resolveRineConfigFromCfg(cfg) {
+	const root = asRecord(cfg);
+	const channelCfg = asRecord(asRecord(root.channels)[CHANNEL_ID]);
+	const entryCfg = asRecord(asRecord(asRecord(root.plugins).entries)[CHANNEL_ID]).config;
+	return resolveRineConfig({
+		...asRecord(entryCfg),
+		...channelCfg
+	});
+}
 /**
 * Resolve rine credentials using core's 3-level config-dir fallback
 * ($RINE_CONFIG_DIR > ~/.config/rine > $PWD/.rine). An explicit `cfg.configDir`
@@ -136,11 +164,18 @@ function buildRineClient(creds) {
 	async function pollCount(pollUrl, signal) {
 		try {
 			const res = await fetch(pollUrl, { signal: signal ?? AbortSignal.timeout(POLL_REQUEST_TIMEOUT_MS) });
-			if (!res.ok) return 0;
+			if (res.status === 401 || res.status === 403) return {
+				kind: "auth-error",
+				status: res.status
+			};
+			if (!res.ok) return { kind: "error" };
 			const body = await res.json();
-			return typeof body.count === "number" ? body.count : 0;
+			return {
+				kind: "count",
+				count: typeof body.count === "number" ? body.count : 0
+			};
 		} catch {
-			return 0;
+			return { kind: "error" };
 		}
 	}
 	async function fetchNewMessages(agentId, limit = 50) {
@@ -165,13 +200,6 @@ function buildRineClient(creds) {
 		markDelivered
 	};
 }
-//#endregion
-//#region src/channel.ts
-/** Re-derive the typed rine config from the `channels.rine` block of a live OpenClawConfig. */
-function rineConfigFromCfg(cfg) {
-	const channels = cfg.channels;
-	return resolveRineConfig(channels?.rine ?? {});
-}
 /**
 * Minimal but type-valid `ChannelPlugin` for rine. Required fields only:
 * id / meta / capabilities / config. Inbound delivery + outbound replies are owned by
@@ -252,7 +280,7 @@ const rinePlugin = {
 			};
 		},
 		sendText: async (ctx) => {
-			const config = rineConfigFromCfg(ctx.cfg);
+			const config = resolveRineConfigFromCfg(ctx.cfg);
 			const creds = readRineCredentials(config);
 			if (!creds.entry) throw new Error("rine: no credentials at the resolved config dir — run rine_onboard or set RINE_CONFIG_DIR.");
 			const { messageId } = await sendRineText(buildRineClient(creds), ctx.to, ctx.text, config.agentId);
@@ -274,4 +302,4 @@ const rinePlugin = {
 	} }
 };
 //#endregion
-export { resolveRineConfig as a, readRineCredentials as i, buildRineClient as n, INTERNAL_TOOLS as o, sendRineReply as r, rinePlugin as t };
+export { resolveRineConfig as a, readRineCredentials as i, buildRineClient as n, resolveRineConfigFromCfg as o, sendRineReply as r, INTERNAL_TOOLS as s, rinePlugin as t };

package/dist/{inbound-G0JD7YmI.js → inbound-DEe69mNL.js}

@@ -10,11 +10,14 @@ function normalizeRineEvent(raw) {
 	const groupHandle = str(raw.group_handle);
 	const groupId = str(raw.group_id);
 	const isGroup = Boolean(groupHandle ?? groupId);
+	const fromAgentId = str(raw.from_agent_id);
+	const toAgentId = str(raw.to_agent_id);
 	return {
 		id: raw.id,
 		conversationId: raw.conversation_id,
 		fromHandle: str(raw.sender_handle) ?? str(raw.from_agent_id) ?? "unknown",
 		type: raw.type,
+		selfSend: Boolean(fromAgentId && fromAgentId === toAgentId),
 		isGroup,
 		groupHandle,
 		groupId,

package/dist/index.js

@@ -1,5 +1,5 @@
-import { a as resolveRineConfig, i as readRineCredentials, n as buildRineClient, o as INTERNAL_TOOLS, r as sendRineReply, t as rinePlugin } from "./channel-DpHhVQ-n.js";
-import { i as normalizeStandardWebhook, n as normalizeA2A, t as isAllowed } from "./inbound-G0JD7YmI.js";
+import { i as readRineCredentials, n as buildRineClient, o as resolveRineConfigFromCfg, r as sendRineReply, s as INTERNAL_TOOLS, t as rinePlugin } from "./channel-BPBnthxw.js";
+import { i as normalizeStandardWebhook, n as normalizeA2A, t as isAllowed } from "./inbound-DEe69mNL.js";
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 import { fetchAgents, resolveAgent } from "@rine-network/core";
 import { tools } from "@rine-network/mcp/tools";
@@ -85,6 +85,20 @@ var configSchema = {
 };
 //#endregion
 //#region src/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 (REQ-FSH-02).
+*/
+function isOneWayEvent(msg) {
+	return msg.type === WEBHOOK_TYPE || msg.selfSend === true;
+}
 function msgOf(err) {
 	return err instanceof Error ? err.message : String(err);
 }
@@ -120,7 +134,7 @@ function makeOnMessage(deps) {
 			lastClear = Date.now();
 		}
 	}
-	return async function onMessage(msg) {
+	return async function onMessage(msg, opts) {
 		maybeClear();
 		if (seen.has(msg.id)) return true;
 		if (isAllowed(msg.fromHandle, config.allowFrom) === "quarantined") {
@@ -133,7 +147,7 @@ function makeOnMessage(deps) {
 		logger.info(`rine: inbound ${msg.type} ${msg.id} from ${msg.fromHandle} → dispatching`);
 		seen.add(msg.id);
 		try {
-			await dispatch(msg, signal);
+			await dispatch(msg, signal, opts);
 		} catch (err) {
 			seen.delete(msg.id);
 			logger.error(`rine: dispatch failed for ${msg.id}: ${msgOf(err)}`);
@@ -157,7 +171,7 @@ function makeOnMessage(deps) {
 */
 function makeRuntimeDispatcher(params) {
 	const { cfg, runtime, client, agentId, logger } = params;
-	return async function dispatch(msg, signal) {
+	return async function dispatch(msg, signal, opts) {
 		signal.throwIfAborted();
 		const peerId = msg.isGroup ? msg.conversationId : msg.fromHandle;
 		const timestamp = msg.createdAt ? Date.parse(msg.createdAt) : void 0;
@@ -185,6 +199,14 @@ 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)`);
+					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);
 			},
 			onRecordError: (err) => logger.warn(`rine: session-record error for ${msg.id}: ${msgOf(err)}`),
@@ -333,7 +355,7 @@ async function deleteWebhook(client, webhookId, logger) {
 	}
 }
 async function fallbackToSse(tc) {
-	const { runSseTransport } = await import("./sse-CLGVjmVC.js");
+	const { runSseTransport } = await import("./sse-BEULwHS1.js");
 	await runSseTransport(tc);
 }
 function waitUntilAbort(signal) {
@@ -352,12 +374,12 @@ const SERVICE_ID = "rine-notify";
 async function runTransport(tc) {
 	switch (tc.config.transport) {
 		case "poll": {
-			const { runPollTransport } = await import("./poll-BvmG87ve.js");
+			const { runPollTransport } = await import("./poll-bXndKyw3.js");
 			return runPollTransport(tc);
 		}
 		case "expose": return runExposeTransport(tc);
 		default: {
-			const { runSseTransport } = await import("./sse-CLGVjmVC.js");
+			const { runSseTransport } = await import("./sse-BEULwHS1.js");
 			return runSseTransport(tc);
 		}
 	}
@@ -424,7 +446,7 @@ function makeRineService(api) {
 		id: SERVICE_ID,
 		start(ctx) {
 			const logger = ctx.logger ?? api.logger;
-			const config = resolveRineConfig(api.pluginConfig ?? {});
+			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)`);
@@ -459,11 +481,12 @@ const EXPOSED_TOOLS = [
 	"rine_send",
 	"rine_read",
 	"rine_inbox",
+	"rine_thread",
 	"rine_onboard"
 ];
 /** Mutating tools gated behind the allowlist (manifest `toolMetadata.optional`). */
 const OPTIONAL_TOOLS = new Set(["rine_send", "rine_onboard"]);
-const CIPHERTEXT_KEYS = ["encrypted_payload"];
+const CIPHERTEXT_KEYS = ["encrypted_payload", "self_encrypted_payload"];
 /**
 * Strip raw ciphertext from any tool result before it reaches a transcript.
 * Recurses through objects/arrays so `rine_read`/`rine_inbox` (which spread the
@@ -564,7 +587,7 @@ var rine_openclaw_default = defineChannelPluginEntry({
 		uiHints
 	},
 	registerFull(api) {
-		registerRineTools(api, buildRineClient(readRineCredentials(resolveRineConfig(api.pluginConfig ?? {}))).toolContext);
+		registerRineTools(api, buildRineClient(readRineCredentials(resolveRineConfigFromCfg(api.config))).toolContext);
 		registerExposeRoute(api);
 		api.registerService(makeRineService(api));
 	}

package/dist/poll-bXndKyw3.js

@@ -0,0 +1,61 @@
+import { r as normalizeRineEvent } from "./inbound-DEe69mNL.js";
+import { n as sleep } from "./backoff-BMNABavv.js";
+//#region src/transports/poll.ts
+/**
+* POLL transport — least token-intensive. Fixed-interval `GET /poll/{token}` (unauth);
+* only on `count > 0` does it mint a JWT, fetch `/messages?status=new`, and dispatch.
+*
+* Graceful fallback: the loop never crashes. A revoked/expired token (`401`/`403`) is
+* surfaced as an actionable error exactly once (REQ-FSH-06 — not masked as an empty inbox);
+* a transient network/HTTP error warns once; a healthy count of 0 is silent no-work. Every
+* failure keeps the loop alive at the fixed interval, and a healthy poll re-arms the warnings.
+*/
+async function runPollTransport(tc) {
+	const { client, config, agentId, logger, onMessage, signal, pollUrl } = tc;
+	if (!pollUrl) {
+		logger.error("rine: POLL transport requires a poll_url in credentials.json (.default.poll_url) — run `rine poll-token`");
+		return;
+	}
+	let warnedKind;
+	while (!signal.aborted) {
+		const result = await client.pollCount(pollUrl, signal);
+		if (result.kind === "auth-error") {
+			if (warnedKind !== "auth") {
+				warnedKind = "auth";
+				logger.error(`rine: POLL token rejected (HTTP ${result.status}) — inbox is silently dead until you run \`rine poll-token\` and update credentials.json (.default.poll_url)`);
+			}
+			await wait(config.pollIntervalMs, signal);
+			continue;
+		}
+		if (result.kind === "error") {
+			if (warnedKind !== "network") {
+				warnedKind = "network";
+				logger.warn("rine: POLL count request failed (network/transient) — keeping loop alive");
+			}
+			await wait(config.pollIntervalMs, signal);
+			continue;
+		}
+		warnedKind = void 0;
+		if (result.count <= 0) {
+			await wait(config.pollIntervalMs, signal);
+			continue;
+		}
+		try {
+			const items = await client.fetchNewMessages(agentId);
+			for (const raw of items) {
+				if (signal.aborted) break;
+				await onMessage(normalizeRineEvent(raw));
+			}
+		} catch (err) {
+			logger.warn(`rine: POLL fetch/dispatch error (keeping loop alive): ${err instanceof Error ? err.message : String(err)}`);
+		}
+		await wait(config.pollIntervalMs, signal);
+	}
+}
+async function wait(ms, signal) {
+	try {
+		await sleep(ms, signal);
+	} catch {}
+}
+//#endregion
+export { runPollTransport };

package/dist/setup.js

@@ -1,4 +1,4 @@
-import { a as resolveRineConfig, i as readRineCredentials, t as rinePlugin } from "./channel-DpHhVQ-n.js";
+import { a as resolveRineConfig, i as readRineCredentials, t as rinePlugin } from "./channel-BPBnthxw.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/config.d.ts

@@ -1,7 +1,18 @@
 import type { CredentialEntry } from "@rine-network/core";
 import type { RineConfig } from "./types.js";
-/** Resolve the typed config from a raw `api.pluginConfig` (or `{}`), applying defaults. */
+/** Resolve the typed config from a raw config record (or `{}`), applying defaults. */
 export declare function resolveRineConfig(raw?: Record<string, unknown>): RineConfig;
+/**
+ * Resolve the typed config from a live OpenClawConfig (`api.config` / an outbound `ctx.cfg`).
+ *
+ * `channels.rine` is the documented, activation-required home for `transport`/`allowFrom`/etc.,
+ * so it is authoritative; `plugins.entries.rine.config` is merged underneath as a fallback for
+ * installs that placed config there (both are validated against the same manifest schema). This
+ * is the single source of truth for the notify service, the tool client, and the outbound
+ * adapter — before, the service/tools read `api.pluginConfig` (`plugins.entries.rine.config`)
+ * while outbound read `channels.rine`, so `channels.rine.transport` was silently ignored.
+ */
+export declare function resolveRineConfigFromCfg(cfg: unknown): RineConfig;
 export interface ResolvedCreds {
     configDir: string;
     apiUrl: string;

package/dist/src/constants.d.ts

@@ -7,6 +7,12 @@
  * channel. Both are `"default"` by convention.
  */
 export declare const DEFAULT_ACCOUNT_ID = "default";
+/**
+ * The rine channel / plugin id. It is the key under both `channels.<id>` (activation +
+ * effective config) and `plugins.entries.<id>` in openclaw.json, and the `id` this plugin
+ * registers under. Shared so the config resolver reads the same block the channel activates.
+ */
+export declare const CHANNEL_ID = "rine";
 /**
  * Internal mcp tools the plugin depends on at runtime but does NOT expose to the agent.
  * Validated at startup (alongside `selectExposedTools`) so a rename of an mcp tool fails

package/dist/src/dispatch.d.ts

@@ -7,7 +7,19 @@ import type { RineConfig, RineInbound } from "./types.js";
  * (`openclaw/plugin-sdk/channel-inbound`), the canonical inbound→agent-turn helper that
  * routes, finalizes the PascalCase ctx, records the session, and dispatches.
  */
-export type DispatchFn = (msg: RineInbound, signal: AbortSignal) => Promise<void>;
+export type DispatchFn = (msg: RineInbound, signal: AbortSignal, opts?: DispatchOpts) => Promise<void>;
+/**
+ * Per-message dispatch modifiers set by the transport (not part of the message itself).
+ */
+export interface DispatchOpts {
+    /**
+     * This frame was replayed during the SSE catch-up phase (before the stream reached the
+     * live/heartbeat state) — wake the agent to ACT, but never auto-reply. A restart against
+     * an undelivered backlog would otherwise fan out one canned reply per replayed message
+     * (REQ-FSH-01). Live-phase frames (opts absent / `replayed:false`) still auto-reply.
+     */
+    replayed?: boolean;
+}
 export interface OnMessageDeps {
     client: RineClient;
     config: RineConfig;
@@ -23,7 +35,7 @@ export interface OnMessageDeps {
  * or quarantined) so the SSE cursor may advance past it; `false` only when dispatch FAILED —
  * a transient error that must be retried, so the cursor must stay behind it.
  */
-export type OnMessage = (msg: RineInbound) => Promise<boolean>;
+export type OnMessage = (msg: RineInbound, opts?: DispatchOpts) => Promise<boolean>;
 /**
  * The inline pointer body — ciphertext stays out of the transcript; agent calls `rine_read`.
  *

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

@@ -2,6 +2,21 @@ import { HttpClient } from "@rine-network/core";
 import type { MessageRead } from "@rine-network/core";
 import type { ToolContext } from "@rine-network/mcp/tools";
 import type { ResolvedCreds } from "./config.js";
+/**
+ * Outcome of a `/poll` count probe. A revoked/expired poll token (`401`/`403`) is
+ * distinguished from a healthy count and from a transient network/HTTP error so the poll
+ * loop can surface an actionable auth warning instead of masking it as an empty inbox
+ * (REQ-FSH-06).
+ */
+export type PollResult = {
+    kind: "count";
+    count: number;
+} | {
+    kind: "auth-error";
+    status: number;
+} | {
+    kind: "error";
+};
 export interface RineClient {
     /** Shared `ToolContext` for the lifted mcp tool handlers. */
     toolContext: ToolContext;
@@ -10,8 +25,12 @@ export interface RineClient {
     apiUrl: string;
     /** Mint/refresh the OAuth JWT via core's token cache (auto-refresh on 401). */
     getJwt: (force?: boolean) => Promise<string>;
-    /** Unauthenticated poll: `GET {pollUrl}` → count. Returns 0 on any failure. */
-    pollCount: (pollUrl: string, signal?: AbortSignal) => Promise<number>;
+    /**
+     * Unauthenticated poll: `GET {pollUrl}` → a {@link PollResult}. Reports `auth-error` on a
+     * `401`/`403` (revoked token) and `error` on any transient network/HTTP failure, so the
+     * caller never confuses a dead token for an empty inbox (REQ-FSH-06).
+     */
+    pollCount: (pollUrl: string, signal?: AbortSignal) => Promise<PollResult>;
     /** Fetch new messages for an agent (auth). */
     fetchNewMessages: (agentId: string, limit?: number) => Promise<MessageRead[]>;
     /** Mark messages delivered (auth) — at-least-once after successful dispatch. */

package/dist/src/tools.d.ts

@@ -2,7 +2,7 @@ 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_onboard"];
+export declare const EXPOSED_TOOLS: readonly ["rine_whoami", "rine_discover", "rine_send", "rine_read", "rine_inbox", "rine_thread", "rine_onboard"];
 /** Mutating tools gated behind the allowlist (manifest `toolMetadata.optional`). */
 export declare const OPTIONAL_TOOLS: Set<string>;
 /**

package/dist/src/transports/poll.d.ts

@@ -3,9 +3,9 @@ import type { TransportContext } from "./context.js";
  * POLL transport — least token-intensive. Fixed-interval `GET /poll/{token}` (unauth);
  * only on `count > 0` does it mint a JWT, fetch `/messages?status=new`, and dispatch.
  *
- * Graceful fallback: on `/poll` failure (e.g. revoked token) it logs an actionable
- * message and keeps the loop alive at the fixed interval — never crashes the service.
- * (`pollCount` returns 0 on any error; a transient zero is indistinguishable from an
- * empty inbox, which is the desired no-work behavior.)
+ * Graceful fallback: the loop never crashes. A revoked/expired token (`401`/`403`) is
+ * surfaced as an actionable error exactly once (REQ-FSH-06 — not masked as an empty inbox);
+ * a transient network/HTTP error warns once; a healthy count of 0 is silent no-work. Every
+ * failure keeps the loop alive at the fixed interval, and a healthy poll re-arms the warnings.
  */
 export declare function runPollTransport(tc: TransportContext): Promise<void>;

package/dist/src/types.d.ts

@@ -15,6 +15,13 @@ export interface RineInbound {
     fromHandle: string;
     /** rine message type, e.g. `rine.v1.dm`. */
     type: string;
+    /**
+     * `from_agent_id == to_agent_id` — a self-addressed message. A Funnel `rine.v1.webhook`
+     * is the canonical case (the relay sends on the agent's behalf), and the server rejects a
+     * reply to it ("Cannot reply to your own message"). Drives the one-way no-auto-reply guard
+     * (REQ-FSH-02). Absent when the transport can't determine both agent ids (e.g. A2A push).
+     */
+    selfSend?: boolean;
     /** Whether this is a group/broadcast message. */
     isGroup: boolean;
     /** Group handle `#name@org` when `isGroup`. */

package/dist/{sse-CLGVjmVC.js → sse-BEULwHS1.js}

@@ -1,4 +1,4 @@
-import { r as normalizeRineEvent } from "./inbound-G0JD7YmI.js";
+import { r as normalizeRineEvent } from "./inbound-DEe69mNL.js";
 import { n as sleep, t as backoff } from "./backoff-BMNABavv.js";
 import { n as saveCursor, t as loadCursor } from "./cursor-DPl6-dKW.js";
 //#region src/transports/sse.ts
@@ -49,7 +49,7 @@ async function runSseTransport(tc) {
 			onReset: () => {
 				attempt = 0;
 			},
-			onRaw: async (raw) => onMessage(normalizeRineEvent(raw))
+			onRaw: async (raw, opts) => onMessage(normalizeRineEvent(raw), opts)
 		});
 		attempt = 0;
 	} catch (err) {
@@ -57,7 +57,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-BvmG87ve.js");
+			const { runPollTransport } = await import("./poll-bXndKyw3.js");
 			await runPollTransport(tc);
 			return;
 		}
@@ -89,6 +89,7 @@ async function streamOnce(params) {
 	const decoder = new TextDecoder();
 	let buffer = "";
 	let gapSeen = false;
+	let live = lastEventId !== void 0;
 	while (!signal.aborted) {
 		const { done, value } = await readWithIdleWatchdog(reader);
 		if (done) return;
@@ -98,10 +99,15 @@ async function streamOnce(params) {
 			const block = buffer.slice(0, sep);
 			buffer = buffer.slice(sep + 2);
 			const evt = parseSseBlock(block);
-			if (!evt || evt.event !== "message" || !evt.data) continue;
+			if (!evt) continue;
+			if (evt.event === "heartbeat" || evt.event === "status") {
+				live = true;
+				continue;
+			}
+			if (evt.event !== "message" || !evt.data) continue;
 			let delivered = false;
 			try {
-				delivered = await onRaw(JSON.parse(evt.data));
+				delivered = await onRaw(JSON.parse(evt.data), { replayed: !live });
 			} catch {
 				if (evt.id) gapSeen = true;
 				continue;

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.1.5",
+  "version": "0.2.1",
   "channels": ["rine"],
   "skills": ["skills/rine"],
   "activation": { "onStartup": true },
@@ -14,6 +14,7 @@
       "rine_send",
       "rine_read",
       "rine_inbox",
+      "rine_thread",
       "rine_onboard"
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/openclaw",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "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",
@@ -64,8 +64,8 @@
     "prepublishOnly": "node scripts/check-no-file-deps.mjs"
   },
   "dependencies": {
-    "@rine-network/core": "^0.5.1",
-    "@rine-network/mcp": "^0.4.2"
+    "@rine-network/core": "^0.8.1",
+    "@rine-network/mcp": "^0.6.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.6.1"

package/skills/rine/SKILL.md

@@ -52,6 +52,9 @@ rine read <message-id> [--agent <name>]
 # Reply to a message (type defaults to original message's type)
 rine reply <message-id> --payload '{"result": "Thanks!"}'
 
+# Show a conversation's full decrypted transcript (both sides, role-tagged)
+rine thread <conversation-id> [--agent <name>] [--limit 50]
+
 # Discover agents
 rine discover agents --query "invoice processing"
 rine discover categories
@@ -60,10 +63,14 @@ rine discover categories
 rine agent describe <id> --description "I process invoices"
 rine agent set-categories <id> --categories "finance,invoicing"
 
-# Webhooks
+# Webhooks (outbound — rine POSTs to your URL)
 rine webhook create --url https://your-server.com/hook  # --agent auto-resolved
 rine webhook list
 
+# Inbound webhook funnel (GitHub/Stripe/custom → your encrypted inbox)
+rine hook create --name github   # prints Hostname, Payload URL, secret (shown once)
+rine relay --hook github         # long-lived daemon on your box: TLS + HMAC verify + encrypt
+
 # Real-time streaming
 rine stream [--agent <uuid>] [--json]
 ```
@@ -74,7 +81,7 @@ Common message types: `rine.v1.task_request`, `rine.v1.task_response`, `rine.v1.
 
 **MCP tools** (equivalent to CLI commands above):
 `rine_onboard` (register + create agent), `rine_agent_create`,
-`rine_send`, `rine_inbox`, `rine_read`, `rine_reply`,
+`rine_send`, `rine_inbox`, `rine_read`, `rine_reply`, `rine_thread`,
 `rine_discover`, `rine_inspect`, `rine_discover_groups`,
 `rine_groups`, `rine_group_create`, `rine_group_join`, `rine_group_members`, `rine_group_invite`,
 `rine_whoami`, `rine_poll`.
@@ -238,6 +245,20 @@ rine webhook create --url https://your-server.com/hook
 ```
 Push delivery, HMAC-signed, 5 automatic retries on failure.
 
+To receive an external webhook source (GitHub, Stripe, custom) as encrypted inbox
+messages on a NAT'd box — the inbound direction — use the Funnel instead:
+```bash
+rine hook create --name github   # prints Hostname, Payload URL, X-Hub-Signature-256 secret (once)
+rine relay --hook github         # terminate TLS + verify HMAC + encrypt, all on your box
+```
+The relay self-sends each verified webhook as a signed `rine.v1.webhook` message with the
+originating hook in cleartext metadata at `rine.hook_name`. rine never sees the cleartext body,
+the HMAC secret, or the TLS key.
+
+A `rine.v1.webhook` is a one-way event: its sender is your own agent's handle (the relay
+sends on the agent's behalf), so act on it — don't reply to the sender. A reply targets the
+agent itself, which rine rejects. To follow up, send a new message to a real peer.
+
 ---
 
 ### Triage rules (once you've read the inbox)

package/dist/poll-BvmG87ve.js

@@ -1,42 +0,0 @@
-import { r as normalizeRineEvent } from "./inbound-G0JD7YmI.js";
-import { n as sleep } from "./backoff-BMNABavv.js";
-//#region src/transports/poll.ts
-/**
-* POLL transport — least token-intensive. Fixed-interval `GET /poll/{token}` (unauth);
-* only on `count > 0` does it mint a JWT, fetch `/messages?status=new`, and dispatch.
-*
-* Graceful fallback: on `/poll` failure (e.g. revoked token) it logs an actionable
-* message and keeps the loop alive at the fixed interval — never crashes the service.
-* (`pollCount` returns 0 on any error; a transient zero is indistinguishable from an
-* empty inbox, which is the desired no-work behavior.)
-*/
-async function runPollTransport(tc) {
-	const { client, config, agentId, logger, onMessage, signal, pollUrl } = tc;
-	if (!pollUrl) {
-		logger.error("rine: POLL transport requires a poll_url in credentials.json (.default.poll_url) — run `rine poll-token`");
-		return;
-	}
-	while (!signal.aborted) {
-		if (await client.pollCount(pollUrl, signal) <= 0) {
-			await wait(config.pollIntervalMs, signal);
-			continue;
-		}
-		try {
-			const items = await client.fetchNewMessages(agentId);
-			for (const raw of items) {
-				if (signal.aborted) break;
-				await onMessage(normalizeRineEvent(raw));
-			}
-		} catch (err) {
-			logger.warn(`rine: POLL fetch/dispatch error (keeping loop alive): ${err instanceof Error ? err.message : String(err)}`);
-		}
-		await wait(config.pollIntervalMs, signal);
-	}
-}
-async function wait(ms, signal) {
-	try {
-		await sleep(ms, signal);
-	} catch {}
-}
-//#endregion
-export { runPollTransport };