@rine-network/eve 0.1.0 → 0.2.0

package/README.md

@@ -103,11 +103,33 @@ undecryptable mail is dropped by default.
 | `rine_thread` | Decrypted both-sided transcript of a conversation |
 | `rine_discover` / `rine_inspect` | Search the directory / read a profile |
 | `rine_group_create` / `_invite` / `_remove` / `_inspect` | MLS-by-default groups |
+| `rine_pay` | Pay a received `rine.v1.x402_payment_required` quote under the local spend policy |
+| `rine_fulfill` | Payee side: verify + settle a received payment and reply with a receipt |
 
 Identity is resolved from the environment (`RINE_CONFIG_DIR`, `RINE_AGENT`,
 `RINE_API_URL`) — never from a tool's model-visible input. Tools return plain text
 and never surface ciphertext.
 
+## Payments (x402)
+
+`rine_pay` and `rine_fulfill` carry [x402](https://docs.rine.network/concepts/x402-payments/)
+stablecoin payments as signed messages in the same encrypted thread; both wrap
+`client.payments`. An inbound x402 frame **wakes a payment-aware turn** — a
+`payment_required` points the agent at `rine_pay`, a `payment` at `rine_fulfill`, a
+`receipt` is informational — and the terminal assistant prose into a payment thread stays
+suppressed. `init --tools payments` scaffolds both tools. The wallet key stays on the host
+and is never returned to the model, and a deny-by-default spend policy bounds every
+signature. `rine_pay` returns one of the shared payer statuses (`payment-submitted`,
+`no-wallet`, `not-payment-required`, `policy-refused`, `above-auto-pay-threshold`,
+`already-paid`, `wallet-busy`); `rine_fulfill` reports `settled` / `settlement-failed` /
+`verification-failed` / `facilitator-error` / `no-facilitator`.
+
+Auto-pay is **opt-in, off by default**: `rineChannel({ payments: { autoPay: true } })` or
+`RINE_X402_AUTO_PAY=1` lets an inbound quote at/below the wallet policy's auto-pay threshold
+be paid with no LLM turn; a quote above the threshold falls back to surfacing it to the
+model. `rine_fulfill`'s facilitator comes from `RINE_FACILITATOR` (a preset — `cdp` /
+`payai` / `x402-rs` — or an `https://` base URL) or the tool's `facilitator` option.
+
 **Human-in-the-loop (optional).** The mutating tools (`send`, `send_and_wait`,
 `reply`, `group_*`) accept an opt-in approval gate — `rineSendTool({ needsApproval:
 "once" })` (or `"always"`) — wired to Eve's approval flow. It's off by default, since
@@ -127,6 +149,8 @@ forever. Configure via `rineChannel({ ignoreTypes: [...] })`.
 | `RINE_WEBHOOK_SECRET` | HMAC secret the channel verifies inbound with |
 | `RINE_WEBHOOK_ID` | registered webhook id (for `webhook --delete`) |
 | `RINE_INBOUND_PATH` | channel route path (default `/rine/v1/inbound`) |
+| `RINE_X402_AUTO_PAY` | set `1` to auto-pay quotes at/below the policy's auto-pay threshold (default off) |
+| `RINE_FACILITATOR` | `rine_fulfill` facilitator: a preset (`cdp` / `payai` / `x402-rs`) or an `https://` base URL |
 
 ## License
 

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

@@ -2,7 +2,7 @@ import { _ as senderLabel, f as renderMessageBody, g as renderThreadLine, n as a
 import { n as verifyRineSignature } from "./hmac-CoaKHmf6.js";
 import { t as getRineClient } from "./client-X_-9CpQT.js";
 import { POST, defineChannel } from "eve/channels";
-import { asMessageUuid } from "@rine-network/sdk";
+import { X402Error, X402_MESSAGE_TYPE, asMessageUuid } from "@rine-network/sdk";
 //#region src/transcript.ts
 /** char ≈ 4 × tokens — the coarse proxy the spec specifies (REQ-CTX-01, OQ1). */
 const CHARS_PER_TOKEN = 4;
@@ -54,6 +54,17 @@ function renderTranscriptContext(entries, tokenBudget) {
 */
 /** Sentinel marking our token payload, robust to Eve's `<channel>:` namespacing. */
 const TOKEN_MARKER = "r1.";
+/**
+* Record a handled message id in the bounded per-runtime dedupe set. The set is
+* cleared wholesale when it reaches {@link SEEN_CAP} (a coarse but allocation-free
+* eviction — the server-side `delivered_at` ack is the durable dedupe). A no-op
+* when no set is provided.
+*/
+function rememberSeen(seen, id) {
+	if (!seen) return;
+	if (seen.size >= 5e3) seen.clear();
+	seen.add(id);
+}
 /** base64url (no padding) encode of a UTF-8 string. */
 function b64urlEncode(s) {
 	return Buffer.from(s, "utf-8").toString("base64url");
@@ -67,12 +78,13 @@ function b64urlDecode(s) {
 * (`rine:`); we additionally fence our payload with {@link TOKEN_MARKER} so the
 * decoder can recover it regardless of any prefix the framework adds.
 */
-function encodeReplyToken(conversationId, replyTarget, messageId) {
+function encodeReplyToken(conversationId, replyTarget, messageId, opts = {}) {
 	const payload = {
 		c: conversationId,
 		r: replyTarget
 	};
 	if (messageId) payload.m = messageId;
+	if (opts.x402) payload.x = 1;
 	return `${TOKEN_MARKER}${b64urlEncode(JSON.stringify(payload))}`;
 }
 /**
@@ -94,7 +106,8 @@ function decodeReplyToken(token) {
 		return {
 			conversationId,
 			replyTarget,
-			messageId: typeof m === "string" && m.length > 0 ? m : void 0
+			messageId: typeof m === "string" && m.length > 0 ? m : void 0,
+			x402: payload?.x === 1 ? true : void 0
 		};
 	} catch {
 		return null;
@@ -118,18 +131,134 @@ function messageIdFromWebhook(body) {
 	return typeof id === "string" && id.length > 0 ? id : void 0;
 }
 //#endregion
+//#region src/x402.ts
+/**
+* x402 payment-aware inbound re-surfacing for the rine channel (D1 + D2).
+*
+* The three x402 payment frames are first-class message types carrying a verbatim
+* x402 V2 object, NOT a chat turn. v1.0 dropped them wholesale (a stateless gateway
+* that auto-replied prose into a payment handshake would corrupt it). v1.1 re-surfaces
+* them as an agent turn with STRUCTURED payment context so the model can act via the
+* dedicated pay / fulfill tools — while the terminal assistant prose stays suppressed
+* in EVERY case (the `x402` continuation-token flag; the guard hazard never re-arms):
+*
+*   - `x402_payment_required` → the quote + guidance to pay via `rine_pay`.
+*   - `x402_payment`          → the signed authorization + guidance to `rine_fulfill`.
+*   - `x402_receipt`          → the settlement outcome, informational (no reply).
+*
+* D2 auto-pay (opt-in, DEFAULT OFF): when enabled, a `payment_required` at/below the
+* policy's `autoPayThreshold` is paid with NO LLM turn — still bounded by the policy
+* caps, deny-by-default, journal and reserve-lock (all in rine-core). Any decline
+* falls back to surfacing the quote to the model.
+*/
+/** The three x402 frame types this module re-surfaces. */
+const X402_FRAME_TYPES = [
+	X402_MESSAGE_TYPE.PAYMENT_REQUIRED,
+	X402_MESSAGE_TYPE.PAYMENT,
+	X402_MESSAGE_TYPE.RECEIPT
+];
+const X402_FRAME_SET = new Set(X402_FRAME_TYPES);
+/** Whether a message type is one of the three x402 payment frames. */
+function isX402Frame(type) {
+	return X402_FRAME_SET.has(type);
+}
+/** Atomic-unit amount of a requirement (x402 V2 `amount`, else V1 spelling). */
+function requirementAmount(r) {
+	return r.amount ?? r.maxAmountRequired ?? "?";
+}
+/** One `accepts[]` requirement as a compact model-readable line. */
+function requirementLine(r) {
+	return `${requirementAmount(r)} of ${r.asset} on ${r.network} → ${r.payTo}`;
+}
+/**
+* The structured payment body handed to the model as the turn's primary message.
+* Reads only the decrypted plaintext (the verbatim x402 object) — never ciphertext.
+*/
+function renderX402Body(msg) {
+	const p = msg.plaintext;
+	if (msg.type === X402_MESSAGE_TYPE.PAYMENT_REQUIRED) {
+		const pr = p ?? {};
+		const accepts = Array.isArray(pr.accepts) ? pr.accepts : [];
+		const opts = accepts.length > 0 ? accepts.map((r) => `  - ${requirementLine(r)}`).join("\n") : "  (no acceptable requirements advertised)";
+		const res = pr.resource?.description ?? pr.resource?.url;
+		return `x402 payment request. Accepted ways to pay:\n${opts}${res ? `\nfor: ${res}` : ""}`;
+	}
+	if (msg.type === X402_MESSAGE_TYPE.PAYMENT) {
+		const pp = p ?? {};
+		const acc = pp.accepted;
+		return `x402 signed payment authorization from ${pp.payload?.authorization?.from ?? "unknown payer"}${acc ? ` for ${requirementLine(acc)}` : ""}.`;
+	}
+	const sr = p ?? {};
+	return `x402 settlement receipt — ${sr.success ? "settled" : "failed"} (${sr.success ? `tx ${sr.transaction} on ${sr.network}` : `reason: ${sr.errorReason ?? "unknown"}`}).`;
+}
+/** The routing-guidance line: what the model should do, and the do-not-reply rule. */
+function x402GuidanceLine(msg) {
+	const who = senderLabel(msg);
+	const note = verifiedNote(msg);
+	if (msg.type === X402_MESSAGE_TYPE.PAYMENT_REQUIRED) return `x402 quote from ${who} (${note}). To pay, call rine_pay with message_id ${msg.id} — the spend is bounded by your local policy (deny-by-default, caps). Do NOT send a text reply into this payment thread.`;
+	if (msg.type === X402_MESSAGE_TYPE.PAYMENT) return `x402 payment from ${who} (${note}). To verify, settle, and send a receipt, call rine_fulfill with message_id ${msg.id}. Do NOT send a text reply into this payment thread.`;
+	return `x402 receipt from ${who} (${note}). This is informational — no reply is expected.`;
+}
+/**
+* D2 auto-pay attempt. Returns `null` when the quote was paid (no session needed),
+* or a one-line decline note when auto-pay was refused or errored (the caller then
+* surfaces the quote to the model). A policy refusal / above-threshold quote is a
+* typed {@link X402Error}; anything else (network, wallet) is reported verbatim.
+*/
+async function tryAutoPay(deps, msg) {
+	try {
+		await deps.client.payments.pay(msg, { autoPay: true });
+		return null;
+	} catch (err) {
+		if (err instanceof X402Error) return `[auto-pay declined (${err.code}): ${err.message}]`;
+		return `[auto-pay failed: ${err instanceof Error ? err.message : String(err)}]`;
+	}
+}
+/** Surface an x402 frame to the model without arming the prose auto-reply. */
+async function surfaceX402(deps, msg, messageId, note) {
+	const replyTarget = msg.group_handle ?? msg.sender_handle ?? senderLabel(msg);
+	await deps.client.markDelivered([msg.id]).catch(() => {});
+	rememberSeen(deps.seen, messageId);
+	const context = [x402GuidanceLine(msg)];
+	if (note) context.push(note);
+	const token = encodeReplyToken(msg.conversation_id, replyTarget, void 0, { x402: true });
+	await deps.send({
+		message: renderX402Body(msg),
+		context
+	}, {
+		auth: null,
+		continuationToken: token
+	});
+	return new Response("ok", { status: 200 });
+}
+/**
+* Handle a verified inbound x402 frame (D1). `payment_required` may auto-pay (D2)
+* when enabled and at/below threshold; otherwise, and for `payment` / `receipt`,
+* the frame is surfaced to the model as a payment-aware turn.
+*/
+async function handleX402Inbound(deps, msg, messageId) {
+	if (msg.type === X402_MESSAGE_TYPE.PAYMENT_REQUIRED && deps.autoPay) {
+		const decline = await tryAutoPay(deps, msg);
+		if (decline === null) {
+			await deps.client.markDelivered([msg.id]).catch(() => {});
+			rememberSeen(deps.seen, messageId);
+			return new Response("auto-paid", { status: 200 });
+		}
+		return surfaceX402(deps, msg, messageId, decline);
+	}
+	return surfaceX402(deps, msg, messageId, null);
+}
+//#endregion
 //#region src/channel-core.ts
 /**
-* Pure inbound/outbound pipeline for the rine channel — no `eve` import, so it is
-* unit-testable with fake clients/sends. `channel.ts` wires these to Eve's
-* `defineChannel` routes + events.
+* INBOUND half of the pure rine channel pipeline — no `eve` import, so it is
+* unit-testable with fake clients/sends. `channel.ts` wires this to Eve's
+* `defineChannel` route; the OUTBOUND half (`processCompletion`/`processFailure`)
+* lives in `channel-outbound.ts`.
 *
 *   - INBOUND (`processInbound`): HMAC-verify (transport auth, R5) → parse → dedupe
 *     → `client.read(id)` to HPKE-decrypt + verify the sender's Ed25519 signature
 *     (content auth, R5) → loop-guard → mark delivered → start/resume the session.
-*   - OUTBOUND (`processCompletion`): on a terminal assistant message (R6) reply
-*     back over rine IN-PLACE via the reply endpoint, preserving the inbound
-*     conversation (R7); falls back to `parentConversationId` for legacy tokens.
 *
 * TRUST NOTE: `verified === true` cryptographically binds the message's *signer*
 * (the envelope `kid`), but the SDK exposes only the server-asserted
@@ -138,7 +267,6 @@ function messageIdFromWebhook(body) {
 * verified signer needs an SDK change to surface `senderKid`; tracked as a
 * follow-up. Matches the sibling rine connectors' behavior.
 */
-const SEEN_CAP = 5e3;
 /** The line of context handed to the model so it knows who/where the message is from. */
 function senderContextLine(msg) {
 	const where = msg.group_handle ? ` in group ${msg.group_handle}` : "";
@@ -173,17 +301,15 @@ async function processInbound(deps) {
 	if (msg.decrypt_error) return new Response("undecryptable", { status: 422 });
 	if (!msg.verified && !deps.acceptUnverified) return new Response("unverified sender signature", { status: 422 });
 	if (deps.ignoreTypes.includes(msg.type)) {
-		deps.seen?.add(messageId);
+		rememberSeen(deps.seen, messageId);
 		return new Response("ignored type", { status: 202 });
 	}
+	if (isX402Frame(msg.type)) return handleX402Inbound(deps, msg, messageId);
 	const replyTarget = msg.group_handle ?? msg.sender_handle;
 	if (!replyTarget) return new Response("no reply target", { status: 422 });
 	const token = msg.group_handle ? encodeReplyToken(msg.conversation_id, replyTarget) : encodeReplyToken(msg.conversation_id, replyTarget, msg.id);
 	await deps.client.markDelivered([msg.id]).catch(() => {});
-	if (deps.seen) {
-		if (deps.seen.size >= SEEN_CAP) deps.seen.clear();
-		deps.seen.add(messageId);
-	}
+	rememberSeen(deps.seen, messageId);
 	const context = [senderContextLine(msg)];
 	if (deps.threadContextTokenBudget != null) {
 		const priorTurns = (await deps.client.thread(msg.conversation_id, { limit: THREAD_FETCH_LIMIT }).catch(() => [])).slice(0, -1);
@@ -198,6 +324,19 @@ async function processInbound(deps) {
 	});
 	return new Response("ok", { status: 200 });
 }
+//#endregion
+//#region src/channel-outbound.ts
+/**
+* OUTBOUND half of the pure rine channel pipeline — no `eve` import, so it is
+* unit-testable with fake clients. `channel.ts` wires these to Eve's
+* `message.completed` / failure events; the INBOUND half lives in `channel-core.ts`.
+*
+* On a terminal assistant message (R6) reply back over rine IN-PLACE via the reply
+* endpoint, preserving the inbound conversation (R7); falls back to
+* `parentConversationId` for legacy tokens. A session started by an x402 frame never
+* prose-replies into the payment thread (the pay / fulfill tools transmit the signed
+* frame in-thread instead) — the `x402` continuation-token flag short-circuits both.
+*/
 /**
 * Outbound for `message.completed`: every TERMINAL assistant message (any
 * `finishReason` except the intermediate `tool-calls`, R6) with text becomes a
@@ -213,6 +352,7 @@ async function processCompletion(deps) {
 	if (!deps.message) return;
 	const rc = decodeReplyToken(deps.continuationToken);
 	if (!rc) return;
+	if (rc.x402) return;
 	if (rc.messageId) {
 		await deps.client.reply(asMessageUuid(rc.messageId), { text: deps.message }, { type: deps.replyMessageType });
 		return;
@@ -230,6 +370,7 @@ async function processCompletion(deps) {
 async function processFailure(continuationToken, client) {
 	const rc = decodeReplyToken(continuationToken);
 	if (!rc) return;
+	if (rc.x402) return;
 	const text = "Sorry — I hit an internal error handling your request.";
 	if (rc.messageId) {
 		await client.reply(asMessageUuid(rc.messageId), { text }, { type: "rine.v1.error" });
@@ -247,12 +388,25 @@ const DEFAULT_REPLY_TYPE = "rine.v1.task_response";
 const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
 /** Default token budget for the push-injected transcript (REQ-CTX-01, ≈8000 chars). */
 const DEFAULT_THREAD_CONTEXT_TOKEN_BUDGET = 2e3;
-/** Message types the connector itself emits — never auto-replied to (loop guard, R2). */
+/**
+* Message types never auto-replied to (loop guard, R2): the connector's OWN
+* outbound types (task_response/error/receipt), so two rine-eve agents don't
+* auto-reply to each other forever.
+*
+* The three x402 payment frames are NOT here: v1.1 re-surfaces them as
+* payment-aware agent turns (D1), routed by `handleX402Inbound` with the prose
+* auto-reply suppressed (the `x402` continuation-token flag), never by the generic
+* assistant reply. Adding them here would revert to the v1.0 silent-drop behavior.
+*/
 const DEFAULT_IGNORE_TYPES = [
 	"rine.v1.task_response",
 	"rine.v1.error",
 	"rine.v1.receipt"
 ];
+/** Whether an env flag is truthy (`1` / `true`, case-insensitive). */
+function envFlag(value) {
+	return value === "1" || value?.toLowerCase() === "true";
+}
 /** Build the rine channel. Default-export the result from `agent/channels/rine.ts`. */
 function rineChannel(opts = {}) {
 	const path = opts.path ?? process.env.RINE_INBOUND_PATH ?? DEFAULT_INBOUND_PATH;
@@ -261,6 +415,7 @@ function rineChannel(opts = {}) {
 	const acceptUnverified = opts.acceptUnverified ?? false;
 	const ignoreTypes = opts.ignoreTypes ?? DEFAULT_IGNORE_TYPES;
 	const threadContextTokenBudget = opts.threadContextTokenBudget ?? DEFAULT_THREAD_CONTEXT_TOKEN_BUDGET;
+	const autoPay = opts.payments?.autoPay ?? envFlag(process.env.RINE_X402_AUTO_PAY);
 	const seen = /* @__PURE__ */ new Set();
 	const client = () => opts.client ?? getRineClient({
 		agent: opts.agent ?? process.env.RINE_AGENT,
@@ -278,7 +433,8 @@ function rineChannel(opts = {}) {
 			maxBodyBytes,
 			ignoreTypes,
 			seen,
-			threadContextTokenBudget
+			threadContextTokenBudget,
+			autoPay
 		}))],
 		events: {
 			"message.completed": async (data, channel) => {
@@ -301,4 +457,4 @@ function rineChannel(opts = {}) {
 	});
 }
 //#endregion
-export { senderContextLine as a, messageIdFromWebhook as c, processInbound as i, processCompletion as n, decodeReplyToken as o, processFailure as r, encodeReplyToken as s, rineChannel as t };
+export { processInbound as a, handleX402Inbound as c, x402GuidanceLine as d, decodeReplyToken as f, processFailure as i, isX402Frame as l, messageIdFromWebhook as m, rineChannel as n, senderContextLine as o, encodeReplyToken as p, processCompletion as r, X402_FRAME_TYPES as s, DEFAULT_IGNORE_TYPES as t, renderX402Body as u };

package/dist/channel-core.d.ts

@@ -1,14 +1,12 @@
 /**
- * Pure inbound/outbound pipeline for the rine channel — no `eve` import, so it is
- * unit-testable with fake clients/sends. `channel.ts` wires these to Eve's
- * `defineChannel` routes + events.
+ * INBOUND half of the pure rine channel pipeline — no `eve` import, so it is
+ * unit-testable with fake clients/sends. `channel.ts` wires this to Eve's
+ * `defineChannel` route; the OUTBOUND half (`processCompletion`/`processFailure`)
+ * lives in `channel-outbound.ts`.
  *
  *   - INBOUND (`processInbound`): HMAC-verify (transport auth, R5) → parse → dedupe
  *     → `client.read(id)` to HPKE-decrypt + verify the sender's Ed25519 signature
  *     (content auth, R5) → loop-guard → mark delivered → start/resume the session.
- *   - OUTBOUND (`processCompletion`): on a terminal assistant message (R6) reply
- *     back over rine IN-PLACE via the reply endpoint, preserving the inbound
- *     conversation (R7); falls back to `parentConversationId` for legacy tokens.
  *
  * TRUST NOTE: `verified === true` cryptographically binds the message's *signer*
  * (the envelope `kid`), but the SDK exposes only the server-asserted
@@ -42,6 +40,13 @@ export interface InboundDeps {
     maxBodyBytes: number;
     /** Inbound types to ignore (loop guard). */
     ignoreTypes: readonly string[];
+    /**
+     * D2 opt-in auto-pay (default OFF). When true, an inbound `x402_payment_required`
+     * at/below the policy's `autoPayThreshold` is paid with NO LLM turn — still
+     * bounded by the caps, deny-by-default, journal and reserve-lock. Any decline
+     * falls back to surfacing the quote to the model.
+     */
+    autoPay?: boolean;
     /** Bounded set of already-handled message ids (dedupe across retries/replays). */
     seen?: Set<string>;
     /**
@@ -56,27 +61,3 @@ export interface InboundDeps {
  * `4xx` = terminal drop, `2xx` = accepted/benign-ignore.
  */
 export declare function processInbound(deps: InboundDeps): Promise<Response>;
-export interface CompletionDeps {
-    finishReason: string;
-    message: string | null;
-    continuationToken: string;
-    client: AsyncRineClient;
-    replyMessageType: string;
-}
-/**
- * Outbound for `message.completed`: every TERMINAL assistant message (any
- * `finishReason` except the intermediate `tool-calls`, R6) with text becomes a
- * reply. When the continuation token carries the inbound message id we reply
- * IN-PLACE via the reply endpoint (same conversation, no fork) keeping the
- * connector's `replyMessageType` unchanged — type-preserving, so terminal/wake
- * semantics are exactly as before. Legacy tokens (no message id) fall back to the
- * historical `send()+parentConversationId` path. No-ops for non-rine sessions
- * (token not ours) or empty messages.
- */
-export declare function processCompletion(deps: CompletionDeps): Promise<void>;
-/**
- * Best-effort error notice back to the sender on a terminal session failure.
- * Replies IN-PLACE (reply endpoint, same conversation) keeping the `rine.v1.error`
- * type; falls back to `send()+parentConversationId` for legacy tokens.
- */
-export declare function processFailure(continuationToken: string, client: AsyncRineClient): Promise<void>;

package/dist/channel-outbound.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OUTBOUND half of the pure rine channel pipeline — no `eve` import, so it is
+ * unit-testable with fake clients. `channel.ts` wires these to Eve's
+ * `message.completed` / failure events; the INBOUND half lives in `channel-core.ts`.
+ *
+ * On a terminal assistant message (R6) reply back over rine IN-PLACE via the reply
+ * endpoint, preserving the inbound conversation (R7); falls back to
+ * `parentConversationId` for legacy tokens. A session started by an x402 frame never
+ * prose-replies into the payment thread (the pay / fulfill tools transmit the signed
+ * frame in-thread instead) — the `x402` continuation-token flag short-circuits both.
+ */
+import type { AsyncRineClient } from "@rine-network/sdk";
+export interface CompletionDeps {
+    finishReason: string;
+    message: string | null;
+    continuationToken: string;
+    client: AsyncRineClient;
+    replyMessageType: string;
+}
+/**
+ * Outbound for `message.completed`: every TERMINAL assistant message (any
+ * `finishReason` except the intermediate `tool-calls`, R6) with text becomes a
+ * reply. When the continuation token carries the inbound message id we reply
+ * IN-PLACE via the reply endpoint (same conversation, no fork) keeping the
+ * connector's `replyMessageType` unchanged — type-preserving, so terminal/wake
+ * semantics are exactly as before. Legacy tokens (no message id) fall back to the
+ * historical `send()+parentConversationId` path. No-ops for non-rine sessions
+ * (token not ours) or empty messages.
+ */
+export declare function processCompletion(deps: CompletionDeps): Promise<void>;
+/**
+ * Best-effort error notice back to the sender on a terminal session failure.
+ * Replies IN-PLACE (reply endpoint, same conversation) keeping the `rine.v1.error`
+ * type; falls back to `send()+parentConversationId` for legacy tokens.
+ */
+export declare function processFailure(continuationToken: string, client: AsyncRineClient): Promise<void>;

package/dist/channel.d.ts

@@ -10,8 +10,21 @@
  * `channel-core.ts` (pure, testable); this file is the `defineChannel` wiring.
  */
 import type { AsyncRineClient } from "@rine-network/sdk";
-export { processInbound, processCompletion, processFailure, senderContextLine, } from "./channel-core.js";
-export type { ChannelSend, InboundDeps, CompletionDeps } from "./channel-core.js";
+export { processInbound, senderContextLine } from "./channel-core.js";
+export { processCompletion, processFailure } from "./channel-outbound.js";
+export type { ChannelSend, InboundDeps } from "./channel-core.js";
+export type { CompletionDeps } from "./channel-outbound.js";
+/**
+ * Message types never auto-replied to (loop guard, R2): the connector's OWN
+ * outbound types (task_response/error/receipt), so two rine-eve agents don't
+ * auto-reply to each other forever.
+ *
+ * The three x402 payment frames are NOT here: v1.1 re-surfaces them as
+ * payment-aware agent turns (D1), routed by `handleX402Inbound` with the prose
+ * auto-reply suppressed (the `x402` continuation-token flag), never by the generic
+ * assistant reply. Adding them here would revert to the v1.0 silent-drop behavior.
+ */
+export declare const DEFAULT_IGNORE_TYPES: string[];
 /** Options for {@link rineChannel}. All optional; identity defaults to env. */
 export interface RineChannelOptions {
     /** Acting agent (handle/name/UUID); defaults to `process.env.RINE_AGENT`. */
@@ -41,6 +54,16 @@ export interface RineChannelOptions {
     threadContextTokenBudget?: number;
     /** A pre-built client (tests / advanced use); otherwise env-resolved lazily. */
     client?: AsyncRineClient;
+    /**
+     * x402 payment behavior (D2). `autoPay` is OPT-IN and DEFAULT OFF: when true, an
+     * inbound `x402_payment_required` at/below the policy's `autoPayThreshold` is paid
+     * with no LLM turn (still bounded by the caps, deny-by-default, journal and
+     * reserve-lock). Off ⇒ every quote is surfaced to the agent, which pays via
+     * `rine_pay`. Falls back to `RINE_X402_AUTO_PAY` (`1`/`true`) when unset.
+     */
+    payments?: {
+        autoPay?: boolean;
+    };
 }
 /** Build the rine channel. Default-export the result from `agent/channels/rine.ts`. */
 export declare function rineChannel(opts?: RineChannelOptions): import("eve/channels").Channel<undefined, Record<string, unknown>, Record<string, unknown>>;

package/dist/channel.js

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

package/dist/inbound.d.ts

@@ -14,6 +14,15 @@
  * build carry only `{c,r}` and decode with `messageId === undefined`, so the outbound
  * handler falls back to the `send()+parentConversationId` broadcast path.
  */
+/** Bound on the per-runtime `seen` dedupe set before it is cleared wholesale. */
+export declare const SEEN_CAP = 5000;
+/**
+ * Record a handled message id in the bounded per-runtime dedupe set. The set is
+ * cleared wholesale when it reaches {@link SEEN_CAP} (a coarse but allocation-free
+ * eviction — the server-side `delivered_at` ack is the durable dedupe). A no-op
+ * when no set is provided.
+ */
+export declare function rememberSeen(seen: Set<string> | undefined, id: string): void;
 /** What a decoded continuation token yields. */
 export interface ReplyContext {
     /** The rine conversation id to thread the reply into. */
@@ -25,13 +34,23 @@ export interface ReplyContext {
      * Absent for legacy 2-field tokens → caller falls back to send()+parent.
      */
     readonly messageId?: string;
+    /**
+     * Marks a session started by an inbound x402 payment frame (D1). The terminal
+     * assistant message is NEVER prose-replied into a payment thread — that would
+     * corrupt the handshake. The signed payment / receipt is transmitted in-thread
+     * by the pay / fulfill tools instead, so `processCompletion` short-circuits when
+     * this is set.
+     */
+    readonly x402?: boolean;
 }
 /**
  * Encode the raw channel-local continuation token. Eve prepends the channel name
  * (`rine:`); we additionally fence our payload with {@link TOKEN_MARKER} so the
  * decoder can recover it regardless of any prefix the framework adds.
  */
-export declare function encodeReplyToken(conversationId: string, replyTarget: string, messageId?: string): string;
+export declare function encodeReplyToken(conversationId: string, replyTarget: string, messageId?: string, opts?: {
+    x402?: boolean;
+}): string;
 /**
  * Decode a continuation token back to its {@link ReplyContext}. Tolerant of a
  * leading `<channel>:` namespace (or any prefix) and of malformed input —

package/dist/index.d.ts

@@ -16,6 +16,7 @@
 export { rineChannel, processInbound, processCompletion, processFailure, senderContextLine, } from "./channel.js";
 export type { RineChannelOptions, ChannelSend, InboundDeps, CompletionDeps, } from "./channel.js";
 export * from "./tools/index.js";
+export { isX402Frame, handleX402Inbound, renderX402Body, x402GuidanceLine, X402_FRAME_TYPES, } from "./x402.js";
 export { rineSkill, RINE_SKILL_BODY, RINE_SKILL_FILE, RINE_SKILL_DESCRIPTION, } from "./skill.js";
 export { getRineClient } from "./client.js";
 export type { RineClientOpts } from "./client.js";

package/dist/index.js

@@ -1,10 +1,10 @@
 import { o as formatError } from "./tool-BC49DldZ.js";
-import { a as senderContextLine, c as messageIdFromWebhook, i as processInbound, n as processCompletion, o as decodeReplyToken, r as processFailure, s as encodeReplyToken, t as rineChannel } from "./channel-Bg8l58gg.js";
+import { a as processInbound, c as handleX402Inbound, d as x402GuidanceLine, f as decodeReplyToken, i as processFailure, l as isX402Frame, m as messageIdFromWebhook, n as rineChannel, o as senderContextLine, p as encodeReplyToken, r as processCompletion, s as X402_FRAME_TYPES, u as renderX402Body } from "./channel-b0iIAZTh.js";
 import { n as verifyRineSignature, t as signRineBody } from "./hmac-CoaKHmf6.js";
 import { t as getRineClient } from "./client-X_-9CpQT.js";
-import { a as rineSendAndWaitTool, c as rineGroupCreateTool, d as rineGroupRemoveTool, f as rineDiscoverTool, i as rineReplyTool, l as rineGroupInspectTool, n as rineCheckInboxTool, o as rineSendTool, p as rineInspectTool, r as rineReadTool, s as rineThreadTool, t as RINE_TOOLS, u as rineGroupInviteTool } from "./tools-Bm9N6tB5.js";
-import { t as RINE_TOOL_META } from "./registry-BG7S2XJg.js";
-import { a as toolFileContent, c as RINE_SKILL_FILE, i as scaffoldRine, n as envExampleBlock, o as RINE_SKILL_BODY, r as resolveToolSelection, s as RINE_SKILL_DESCRIPTION, t as channelFileContent } from "./scaffold-Dpac1TMU.js";
+import { a as rineReadTool, c as rineSendTool, d as rineGroupInspectTool, f as rineGroupInviteTool, h as rineInspectTool, i as rineCheckInboxTool, l as rineThreadTool, m as rineDiscoverTool, n as rineFulfillTool, o as rineReplyTool, p as rineGroupRemoveTool, r as rinePayTool, s as rineSendAndWaitTool, t as RINE_TOOLS, u as rineGroupCreateTool } from "./tools-BcVm_Onx.js";
+import { t as RINE_TOOL_META } from "./registry-6sWyhOyF.js";
+import { a as toolFileContent, c as RINE_SKILL_FILE, i as scaffoldRine, n as envExampleBlock, o as RINE_SKILL_BODY, r as resolveToolSelection, s as RINE_SKILL_DESCRIPTION, t as channelFileContent } from "./scaffold-0luQyBRK.js";
 import { agentNameFromOrgName, parseOnboardArgs, runOnboard } from "./onboard.js";
 import { deleteRineWebhook, registerRineWebhook } from "./webhook.js";
 import { buildRelayBody, drainOnce, runRelay } from "./relay.js";
@@ -24,4 +24,4 @@ function rineSkill() {
 	});
 }
 //#endregion
-export { RINE_SKILL_BODY, RINE_SKILL_DESCRIPTION, RINE_SKILL_FILE, RINE_TOOLS, RINE_TOOL_META, agentNameFromOrgName, buildRelayBody, channelFileContent, decodeReplyToken, deleteRineWebhook, drainOnce, encodeReplyToken, envExampleBlock, formatError, getRineClient, messageIdFromWebhook, parseOnboardArgs, processCompletion, processFailure, processInbound, registerRineWebhook, resolveToolSelection, rineChannel, rineCheckInboxTool, rineDiscoverTool, rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupRemoveTool, rineInspectTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineSkill, rineThreadTool, runOnboard, runRelay, scaffoldRine, senderContextLine, signRineBody, toolFileContent, verifyRineSignature };
+export { RINE_SKILL_BODY, RINE_SKILL_DESCRIPTION, RINE_SKILL_FILE, RINE_TOOLS, RINE_TOOL_META, X402_FRAME_TYPES, agentNameFromOrgName, buildRelayBody, channelFileContent, decodeReplyToken, deleteRineWebhook, drainOnce, encodeReplyToken, envExampleBlock, formatError, getRineClient, handleX402Inbound, isX402Frame, messageIdFromWebhook, parseOnboardArgs, processCompletion, processFailure, processInbound, registerRineWebhook, renderX402Body, resolveToolSelection, rineChannel, rineCheckInboxTool, rineDiscoverTool, rineFulfillTool, rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupRemoveTool, rineInspectTool, rinePayTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineSkill, rineThreadTool, runOnboard, runRelay, scaffoldRine, senderContextLine, signRineBody, toolFileContent, verifyRineSignature, x402GuidanceLine };

package/dist/{registry-BG7S2XJg.js → registry-6sWyhOyF.js}

@@ -1,7 +1,8 @@
 //#region src/tools/registry.ts
 /**
 * The registry the scaffolder + docs read. Order is the canonical surface order
-* (messaging → discovery → groups). `name` === scaffolded filename === tool name.
+* (messaging → discovery → groups → payments). `name` === scaffolded filename ===
+* tool name.
 */
 const RINE_TOOL_META = [
 	{
@@ -63,6 +64,16 @@ const RINE_TOOL_META = [
 		name: "rine_group_inspect",
 		factoryName: "rineGroupInspectTool",
 		domain: "groups"
+	},
+	{
+		name: "rine_pay",
+		factoryName: "rinePayTool",
+		domain: "payments"
+	},
+	{
+		name: "rine_fulfill",
+		factoryName: "rineFulfillTool",
+		domain: "payments"
 	}
 ];
 //#endregion

package/dist/{scaffold-Dpac1TMU.js → scaffold-0luQyBRK.js}

@@ -1,4 +1,4 @@
-import { t as RINE_TOOL_META } from "./registry-BG7S2XJg.js";
+import { t as RINE_TOOL_META } from "./registry-6sWyhOyF.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 //#region src/skill-content.ts
@@ -86,6 +86,11 @@ RINE_AGENT=
 RINE_WEBHOOK_SECRET=
 # RINE_WEBHOOK_ID=
 # RINE_INBOUND_PATH=${path}
+# x402 payments (optional). RINE_X402_AUTO_PAY=1 auto-pays quotes at/below your
+# policy's autoPayThreshold with no LLM turn (default OFF). RINE_FACILITATOR is the
+# rine_fulfill facilitator — a preset name (cdp/payai/x402-rs) or a base URL.
+# RINE_X402_AUTO_PAY=
+# RINE_FACILITATOR=
 `;
 }
 /**

package/dist/scaffold.js

@@ -1,2 +1,2 @@
-import { a as toolFileContent, i as scaffoldRine, n as envExampleBlock, r as resolveToolSelection, t as channelFileContent } from "./scaffold-Dpac1TMU.js";
+import { a as toolFileContent, i as scaffoldRine, n as envExampleBlock, r as resolveToolSelection, t as channelFileContent } from "./scaffold-0luQyBRK.js";
 export { channelFileContent, envExampleBlock, resolveToolSelection, scaffoldRine, toolFileContent };

package/dist/schemas-groups.d.ts

@@ -20,9 +20,9 @@ export declare const groupCreateInput: z.ZodObject<{
     description?: string | undefined;
 }, {
     name: string;
+    description?: string | undefined;
     enrollment?: "open" | "closed" | "majority" | "unanimity" | undefined;
     visibility?: "public" | "private" | undefined;
-    description?: string | undefined;
     enableMls?: boolean | undefined;
 }>;
 export declare const groupInviteInput: z.ZodObject<{

package/dist/schemas-payments.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Zod input schemas for the 2 x402 payment tools (split out of `schemas.ts` to
+ * hold the ~200-LOC budget — one file per domain). Same authoring rules: rich
+ * `.describe()` on every field, NO identity/credentials in the schema (env-injected,
+ * R3). The facilitator is infra config, resolved from the tool factory / env —
+ * never a model-visible input.
+ */
+import { z } from "zod";
+export declare const payInput: z.ZodObject<{
+    messageId: z.ZodString;
+    autoPay: z.ZodDefault<z.ZodBoolean>;
+    emitMarker: z.ZodDefault<z.ZodBoolean>;
+    allowRepay: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    messageId: string;
+    autoPay: boolean;
+    emitMarker: boolean;
+    allowRepay: boolean;
+}, {
+    messageId: string;
+    autoPay?: boolean | undefined;
+    emitMarker?: boolean | undefined;
+    allowRepay?: boolean | undefined;
+}>;
+export declare const fulfillInput: z.ZodObject<{
+    messageId: z.ZodString;
+    emitMarker: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    messageId: string;
+    emitMarker: boolean;
+}, {
+    messageId: string;
+    emitMarker?: boolean | undefined;
+}>;

package/dist/schemas.d.ts

@@ -103,3 +103,4 @@ export declare const inspectInput: z.ZodObject<{
     handleOrId: string;
 }>;
 export { groupCreateInput, groupInspectInput, groupInviteInput, groupRemoveInput, } from "./schemas-groups.js";
+export { fulfillInput, payInput } from "./schemas-payments.js";

package/dist/tool.d.ts

@@ -32,6 +32,15 @@ export interface RineToolOpts extends RineClientOpts {
      * irreversible network actions. Ignored by read-only tools.
      */
     needsApproval?: "always" | "once" | "never";
+    /**
+     * Facilitator for the payee `rine_fulfill` tool: a preset name
+     * (`cdp` / `payai` / `x402-rs`) or an explicit base URL. Falls back to the
+     * `RINE_FACILITATOR` env var. Ignored by every other tool. Verify/settle is
+     * plain external HTTP to this facilitator — never a rine endpoint.
+     */
+    facilitator?: string;
+    /** Extra HTTP headers (provider auth, e.g. a CDP key) sent to the facilitator. */
+    facilitatorHeaders?: Record<string, string>;
 }
 /**
  * Resolve {@link RineToolOpts.needsApproval} to an Eve `needsApproval` callback,

package/dist/tools/index.d.ts

@@ -12,6 +12,7 @@ import { type RineToolMeta } from "./registry.js";
 export { rineCheckInboxTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool, } from "./messaging.js";
 export { rineDiscoverTool, rineInspectTool } from "./discovery.js";
 export { rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupRemoveTool, } from "./groups.js";
+export { rineFulfillTool, rinePayTool } from "./payments.js";
 export { RINE_TOOL_META, type RineToolMeta, type RineToolDomain, } from "./registry.js";
 export type { RineToolOpts } from "../tool.js";
 /** A rine tool factory: builds an Eve `defineTool` descriptor from options. */

package/dist/tools/index.js

@@ -1,3 +1,3 @@
-import { a as rineSendAndWaitTool, c as rineGroupCreateTool, d as rineGroupRemoveTool, f as rineDiscoverTool, i as rineReplyTool, l as rineGroupInspectTool, n as rineCheckInboxTool, o as rineSendTool, p as rineInspectTool, r as rineReadTool, s as rineThreadTool, t as RINE_TOOLS, u as rineGroupInviteTool } from "../tools-Bm9N6tB5.js";
-import { t as RINE_TOOL_META } from "../registry-BG7S2XJg.js";
-export { RINE_TOOLS, RINE_TOOL_META, rineCheckInboxTool, rineDiscoverTool, rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupRemoveTool, rineInspectTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool };
+import { a as rineReadTool, c as rineSendTool, d as rineGroupInspectTool, f as rineGroupInviteTool, h as rineInspectTool, i as rineCheckInboxTool, l as rineThreadTool, m as rineDiscoverTool, n as rineFulfillTool, o as rineReplyTool, p as rineGroupRemoveTool, r as rinePayTool, s as rineSendAndWaitTool, t as RINE_TOOLS, u as rineGroupCreateTool } from "../tools-BcVm_Onx.js";
+import { t as RINE_TOOL_META } from "../registry-6sWyhOyF.js";
+export { RINE_TOOLS, RINE_TOOL_META, rineCheckInboxTool, rineDiscoverTool, rineFulfillTool, rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupRemoveTool, rineInspectTool, rinePayTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool };

package/dist/tools/payments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The 2 x402 payment tool factories: `rine_pay` (payer) and `rine_fulfill`
+ * (payee). Thin adapters over the ts-sdk `client.payments` facade — signing,
+ * spend policy, journal, and facilitator verify/settle all live in rine-core; the
+ * wallet key is never surfaced. Each returns an Eve `defineTool` descriptor whose
+ * `execute` resolves to a TYPED STATUS STRING (never a reject for an expected
+ * refusal), so the agent reasons over the outcome.
+ *
+ * `rine_pay` reuses the shipped `rine_pay` MCP status vocabulary VERBATIM:
+ * `payment-submitted` / `no-wallet` / `not-payment-required` / `policy-refused` /
+ * `above-auto-pay-threshold` / `already-paid` / `wallet-busy`. `rine_fulfill`
+ * reports the PINNED payee vocabulary (`settled` / `settlement-failed` /
+ * `verification-failed` / `facilitator-error` / `no-facilitator` / `not-payment`),
+ * identical across every surface (CLI/MCP/eve/mastra), with the facilitator's
+ * network slug stored VERBATIM (never CAIP-2 string-matched).
+ */
+import { type RineToolOpts } from "../tool.js";
+/** `rine_pay` — pay a received x402 quote in-thread (payer). */
+export declare function rinePayTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_fulfill` — verify + settle a received payment and send the receipt (payee). */
+export declare function rineFulfillTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;

package/dist/tools/registry.d.ts

@@ -6,7 +6,7 @@
  * attaches the live factories to this metadata for programmatic use.
  */
 /** The canonical domains a rine tool belongs to (drives `init --tools`). */
-export type RineToolDomain = "messaging" | "discovery" | "groups";
+export type RineToolDomain = "messaging" | "discovery" | "groups" | "payments";
 /** Scaffold metadata for one tool: canonical name, export name, domain. */
 export interface RineToolMeta {
     /** Filename slug + runtime tool name (e.g. `rine_send`). */
@@ -17,6 +17,7 @@ export interface RineToolMeta {
 }
 /**
  * The registry the scaffolder + docs read. Order is the canonical surface order
- * (messaging → discovery → groups). `name` === scaffolded filename === tool name.
+ * (messaging → discovery → groups → payments). `name` === scaffolded filename ===
+ * tool name.
  */
 export declare const RINE_TOOL_META: readonly RineToolMeta[];

package/dist/{tools-Bm9N6tB5.js → tools-BcVm_Onx.js}

@@ -1,6 +1,6 @@
 import { a as GROUP_ON_WAIT_MESSAGE, c as groupIsMls, d as renderInbox, f as renderMessageBody, h as renderThread, i as redactToText, l as renderDiscover, m as renderSingleMessage, n as asRecipient, p as renderProfile, r as makeExecute, s as isGroupUnsupportedOnWait, t as approvalGate, u as renderGroup, v as verifiedNote } from "./tool-BC49DldZ.js";
-import { t as RINE_TOOL_META } from "./registry-BG7S2XJg.js";
-import { NotFoundError, asAgentUuid, asGroupUuid, asMessageUuid } from "@rine-network/sdk";
+import { t as RINE_TOOL_META } from "./registry-6sWyhOyF.js";
+import { FACILITATOR_PRESET, NotFoundError, X402Error, X402FacilitatorError, X402_ERROR, X402_MESSAGE_TYPE, asAgentUuid, asGroupUuid, asMessageUuid } from "@rine-network/sdk";
 import { UUID_RE, normalizeHandle, resolveToUuid } from "@rine-network/core";
 import { z } from "zod";
 import { defineTool } from "eve/tools";
@@ -48,6 +48,25 @@ const groupRemoveInput = z.object({
 });
 const groupInspectInput = z.object({ group: z.string().describe("The group to inspect: a handle (`#name@org`) or a UUID. Reports its E2EE mode and policy.") });
 //#endregion
+//#region src/schemas-payments.ts
+/**
+* Zod input schemas for the 2 x402 payment tools (split out of `schemas.ts` to
+* hold the ~200-LOC budget — one file per domain). Same authoring rules: rich
+* `.describe()` on every field, NO identity/credentials in the schema (env-injected,
+* R3). The facilitator is infra config, resolved from the tool factory / env —
+* never a model-visible input.
+*/
+const payInput = z.object({
+	messageId: z.string().describe("The UUID of the received `rine.v1.x402_payment_required` quote to pay. The signed payment is sent back in the same conversation."),
+	autoPay: z.boolean().default(false).describe("If true, pay ONLY when the quote is at/below your policy's autoPayThreshold; otherwise return `above-auto-pay-threshold` without paying. Default false — calling this tool is itself the authorization, still bounded by the spend caps."),
+	emitMarker: z.boolean().default(true).describe("Attach the cleartext status marker (coarse lifecycle state only — never amounts/assets/addresses). Default true; set false for a fully-sealed payment."),
+	allowRepay: z.boolean().default(false).describe("If true, re-pay a quote already paid today (a deliberate second, permanent debit). Default false — a repeat pay of the same messageId returns `already-paid` without spending.")
+});
+const fulfillInput = z.object({
+	messageId: z.string().describe("The UUID of the received `rine.v1.x402_payment` (signed authorization) to fulfill. Verifies and settles it via your configured facilitator, then sends the receipt back in-thread."),
+	emitMarker: z.boolean().default(true).describe("Attach the cleartext status marker on the receipt (coarse lifecycle state only). Default true.")
+});
+//#endregion
 //#region src/schemas.ts
 /**
 * Shared Zod input schemas for the 12 rine tools.
@@ -345,6 +364,151 @@ function rineReplyTool(opts = {}) {
 	});
 }
 //#endregion
+//#region src/tools/payments.ts
+/**
+* The 2 x402 payment tool factories: `rine_pay` (payer) and `rine_fulfill`
+* (payee). Thin adapters over the ts-sdk `client.payments` facade — signing,
+* spend policy, journal, and facilitator verify/settle all live in rine-core; the
+* wallet key is never surfaced. Each returns an Eve `defineTool` descriptor whose
+* `execute` resolves to a TYPED STATUS STRING (never a reject for an expected
+* refusal), so the agent reasons over the outcome.
+*
+* `rine_pay` reuses the shipped `rine_pay` MCP status vocabulary VERBATIM:
+* `payment-submitted` / `no-wallet` / `not-payment-required` / `policy-refused` /
+* `above-auto-pay-threshold` / `already-paid` / `wallet-busy`. `rine_fulfill`
+* reports the PINNED payee vocabulary (`settled` / `settlement-failed` /
+* `verification-failed` / `facilitator-error` / `no-facilitator` / `not-payment`),
+* identical across every surface (CLI/MCP/eve/mastra), with the facilitator's
+* network slug stored VERBATIM (never CAIP-2 string-matched).
+*/
+/** The `rine_pay` terminal statuses, reused verbatim from the MCP payer tool. */
+const PAY_STATUS = {
+	SUBMITTED: "payment-submitted",
+	NO_WALLET: "no-wallet",
+	NOT_PAYMENT_REQUIRED: "not-payment-required",
+	POLICY_REFUSED: "policy-refused",
+	ABOVE_AUTO_PAY_THRESHOLD: "above-auto-pay-threshold",
+	ALREADY_PAID: "already-paid",
+	WALLET_BUSY: "wallet-busy"
+};
+/**
+* The `rine_fulfill` payee statuses — PINNED across every surface (CLI/MCP/eve/
+* mastra) so an LLM or operator script parses one vocabulary everywhere. Mirrors
+* the MCP `rine_fulfill` reference set; eve emits the subset it can reach (the
+* ts-sdk `fulfill` facade owns decryption, so `no-keys` never surfaces here).
+*/
+const FULFILL_STATUS = {
+	SETTLED: "settled",
+	SETTLEMENT_FAILED: "settlement-failed",
+	VERIFICATION_FAILED: "verification-failed",
+	FACILITATOR_ERROR: "facilitator-error",
+	NO_FACILITATOR: "no-facilitator",
+	NOT_PAYMENT: "not-payment"
+};
+/** `<status> — <detail>`: the stable, parseable typed-status line. */
+function status(word, detail) {
+	return `${word} — ${detail}`;
+}
+/** Atomic-unit amount of a requirement (x402 V2 `amount`, else V1 spelling). */
+function requirementSummary(r) {
+	return `${r.amount ?? r.maxAmountRequired ?? "?"} of ${r.asset} on ${r.network} → ${r.payTo}`;
+}
+/** Map an x402 pay refusal to its typed status line (parity with MCP rine_pay). */
+function mapPayError(err, autoPay) {
+	if (err instanceof X402Error) switch (err.code) {
+		case X402_ERROR.ALREADY_PAID: return status(PAY_STATUS.ALREADY_PAID, `${err.message}. Pass allowRepay to pay it again.`);
+		case X402_ERROR.WALLET_BUSY: return status(PAY_STATUS.WALLET_BUSY, err.message);
+		case X402_ERROR.PER_TX_CAP_EXCEEDED:
+			if (autoPay) return status(PAY_STATUS.ABOVE_AUTO_PAY_THRESHOLD, `${err.message}. Re-run without autoPay to authorize explicitly.`);
+			return status(PAY_STATUS.POLICY_REFUSED, err.message);
+		default: return status(PAY_STATUS.POLICY_REFUSED, err.message);
+	}
+	throw err;
+}
+/** `rine_pay` — pay a received x402 quote in-thread (payer). */
+function rinePayTool(opts = {}) {
+	return defineTool({
+		description: "Pay a received x402 payment request (rine.v1.x402_payment_required) in-thread. Decrypts the quote, selects an acceptable requirement under your local spend policy (deny-by-default, caps), signs an EIP-3009 stablecoin authorization with your wallet, and sends the signed payment back in the same conversation. The spend is reserved as the last act before the send (fail-closed, permanent, no refund). Returns a typed `status` — `payment-submitted` on success, else `no-wallet` / `not-payment-required` / `policy-refused` / `above-auto-pay-threshold` / `already-paid` / `wallet-busy`. Does NOT wait for settlement; the receipt arrives later as an ordinary inbox message.",
+		inputSchema: jsonSchema(payInput),
+		outputSchema: STRING_OUTPUT,
+		needsApproval: approvalGate(opts),
+		execute: makeExecute(payInput, opts, async (client, i) => {
+			const msg = await client.read(asMessageUuid(i.messageId));
+			if (msg.type !== X402_MESSAGE_TYPE.PAYMENT_REQUIRED) return status(PAY_STATUS.NOT_PAYMENT_REQUIRED, `message ${i.messageId} is type '${msg.type}', not an x402 payment request.`);
+			try {
+				await client.payments.walletAddress();
+			} catch {
+				return status(PAY_STATUS.NO_WALLET, "no payment wallet is configured for this agent; create one before paying.");
+			}
+			try {
+				const res = await client.payments.pay(msg, {
+					autoPay: i.autoPay,
+					emitMarker: i.emitMarker,
+					allowRepay: i.allowRepay
+				});
+				return status(PAY_STATUS.SUBMITTED, `sent x402 payment ${res.payment.id} (${requirementSummary(res.requirement)}). The settlement receipt will arrive as a later inbox message.`);
+			} catch (err) {
+				return mapPayError(err, i.autoPay);
+			}
+		})
+	});
+}
+/**
+* Resolve the facilitator config from factory opts or `RINE_FACILITATOR`. A
+* `null` return means none is configured (surfaced as `no-facilitator`). An
+* unrecognised reference — neither a preset name nor an `http(s)://` base URL —
+* throws an actionable config error instead of being handed to `fetch` as a
+* bogus URL: parity with the CLI/MCP `resolveFacilitator`, so a typo like
+* `payia` surfaces as a config error naming the bad value, not an opaque
+* `facilitator-error` from a doomed network call.
+*/
+function resolveFacilitator(opts) {
+	const ref = opts.facilitator ?? process.env.RINE_FACILITATOR;
+	if (!ref) return null;
+	const headers = opts.facilitatorHeaders;
+	const preset = FACILITATOR_PRESET[ref];
+	if (preset) return headers ? {
+		...preset,
+		headers
+	} : preset;
+	if (!/^https?:\/\//.test(ref)) throw new Error(`Unknown facilitator '${ref}'. Use a preset (${Object.keys(FACILITATOR_PRESET).join(" | ")}) or an http(s):// base URL.`);
+	return headers ? {
+		url: ref,
+		headers
+	} : { url: ref };
+}
+/** Render a settle-first {@link FulfillResult} to a typed outcome line. */
+function renderFulfill(res) {
+	if (!res.verification.isValid) return status(FULFILL_STATUS.VERIFICATION_FAILED, `verification failed (${res.verification.invalidReason ?? "verification_failed"}); a failure receipt was sent so the payer reaches a terminal state.`);
+	const s = res.settlement;
+	if (s?.success) return status(FULFILL_STATUS.SETTLED, `receipt sent; tx ${s.transaction} on ${s.network}${s.payer ? `, payer ${s.payer}` : ""}.`);
+	return status(FULFILL_STATUS.SETTLEMENT_FAILED, `settlement did not succeed (${s?.errorReason ?? "unknown"}); receipt sent.`);
+}
+/** `rine_fulfill` — verify + settle a received payment and send the receipt (payee). */
+function rineFulfillTool(opts = {}) {
+	return defineTool({
+		description: "Fulfill a received x402 payment (rine.v1.x402_payment): verify the signed authorization and settle it on-chain via your configured facilitator, then send the settlement receipt back in-thread. Settle-first — on a failed verification, a `success:false` receipt is sent so the payer reaches a terminal state. Facilitator verify/settle is plain external HTTP, never a rine endpoint. Returns a typed `status` — `settled` on success, else `settlement-failed` / `verification-failed` / `facilitator-error` / `no-facilitator` / `not-payment`.",
+		inputSchema: jsonSchema(fulfillInput),
+		outputSchema: STRING_OUTPUT,
+		needsApproval: approvalGate(opts),
+		execute: makeExecute(fulfillInput, opts, async (client, i) => {
+			const msg = await client.read(asMessageUuid(i.messageId));
+			if (msg.type !== X402_MESSAGE_TYPE.PAYMENT) return status(FULFILL_STATUS.NOT_PAYMENT, `message ${i.messageId} is type '${msg.type}', not an x402 payment authorization.`);
+			const facilitator = resolveFacilitator(opts);
+			if (!facilitator) return status(FULFILL_STATUS.NO_FACILITATOR, "no facilitator is configured; set RINE_FACILITATOR (a preset name — cdp/payai/x402-rs — or a base URL) to verify and settle payments.");
+			try {
+				return renderFulfill(await client.payments.fulfill(msg, {
+					facilitator,
+					emitMarker: i.emitMarker
+				}));
+			} catch (err) {
+				if (err instanceof X402FacilitatorError) return status(FULFILL_STATUS.FACILITATOR_ERROR, err.message);
+				throw err;
+			}
+		})
+	});
+}
+//#endregion
 //#region src/tools/index.ts
 const FACTORIES = {
 	rineSendTool,
@@ -358,7 +522,9 @@ const FACTORIES = {
 	rineGroupCreateTool,
 	rineGroupInviteTool,
 	rineGroupRemoveTool,
-	rineGroupInspectTool
+	rineGroupInspectTool,
+	rinePayTool,
+	rineFulfillTool
 };
 /** The metadata registry with live factories attached (programmatic use). */
 const RINE_TOOLS = RINE_TOOL_META.map((m) => ({
@@ -366,4 +532,4 @@ const RINE_TOOLS = RINE_TOOL_META.map((m) => ({
 	factory: FACTORIES[m.factoryName]
 }));
 //#endregion
-export { rineSendAndWaitTool as a, rineGroupCreateTool as c, rineGroupRemoveTool as d, rineDiscoverTool as f, rineReplyTool as i, rineGroupInspectTool as l, rineCheckInboxTool as n, rineSendTool as o, rineInspectTool as p, rineReadTool as r, rineThreadTool as s, RINE_TOOLS as t, rineGroupInviteTool as u };
+export { rineReadTool as a, rineSendTool as c, rineGroupInspectTool as d, rineGroupInviteTool as f, rineInspectTool as h, rineCheckInboxTool as i, rineThreadTool as l, rineDiscoverTool as m, rineFulfillTool as n, rineReplyTool as o, rineGroupRemoveTool as p, rinePayTool as r, rineSendAndWaitTool as s, RINE_TOOLS as t, rineGroupCreateTool as u };

package/dist/x402.d.ts

@@ -0,0 +1,38 @@
+/**
+ * x402 payment-aware inbound re-surfacing for the rine channel (D1 + D2).
+ *
+ * The three x402 payment frames are first-class message types carrying a verbatim
+ * x402 V2 object, NOT a chat turn. v1.0 dropped them wholesale (a stateless gateway
+ * that auto-replied prose into a payment handshake would corrupt it). v1.1 re-surfaces
+ * them as an agent turn with STRUCTURED payment context so the model can act via the
+ * dedicated pay / fulfill tools — while the terminal assistant prose stays suppressed
+ * in EVERY case (the `x402` continuation-token flag; the guard hazard never re-arms):
+ *
+ *   - `x402_payment_required` → the quote + guidance to pay via `rine_pay`.
+ *   - `x402_payment`          → the signed authorization + guidance to `rine_fulfill`.
+ *   - `x402_receipt`          → the settlement outcome, informational (no reply).
+ *
+ * D2 auto-pay (opt-in, DEFAULT OFF): when enabled, a `payment_required` at/below the
+ * policy's `autoPayThreshold` is paid with NO LLM turn — still bounded by the policy
+ * caps, deny-by-default, journal and reserve-lock (all in rine-core). Any decline
+ * falls back to surfacing the quote to the model.
+ */
+import type { InboundDeps } from "./channel-core.js";
+import type { DecryptedMessage } from "./types.js";
+/** The three x402 frame types this module re-surfaces. */
+export declare const X402_FRAME_TYPES: readonly ["rine.v1.x402_payment_required", "rine.v1.x402_payment", "rine.v1.x402_receipt"];
+/** Whether a message type is one of the three x402 payment frames. */
+export declare function isX402Frame(type: string): boolean;
+/**
+ * The structured payment body handed to the model as the turn's primary message.
+ * Reads only the decrypted plaintext (the verbatim x402 object) — never ciphertext.
+ */
+export declare function renderX402Body(msg: DecryptedMessage): string;
+/** The routing-guidance line: what the model should do, and the do-not-reply rule. */
+export declare function x402GuidanceLine(msg: DecryptedMessage): string;
+/**
+ * Handle a verified inbound x402 frame (D1). `payment_required` may auto-pay (D2)
+ * when enabled and at/below threshold; otherwise, and for `payment` / `receipt`,
+ * the frame is surfaced to the model as a payment-aware turn.
+ */
+export declare function handleX402Inbound(deps: InboundDeps, msg: DecryptedMessage, messageId: string): Promise<Response>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/eve",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Native Vercel Eve connector for the rine network \u2014 a custom channel that makes an Eve agent reachable over E2E-encrypted (HPKE 1:1, MLS groups RFC 9420, PQ-hybrid) agent-to-agent messaging, plus file-discovered rine tools, a skill, and an init/onboard/relay CLI.",
   "author": "mmmbs <mmmbs@proton.me>",
   "license": "EUPL-1.2",
@@ -48,8 +48,8 @@
     "prepublishOnly": "node scripts/check-no-file-deps.mjs"
   },
   "dependencies": {
-    "@rine-network/core": "^0.7.0",
-    "@rine-network/sdk": "^0.4.0",
+    "@rine-network/core": "^0.11.0",
+    "@rine-network/sdk": "^0.8.0",
     "zod": "^3.25.0",
     "zod-to-json-schema": "^3.24.1"
   },