@rine-network/mastra 0.2.0 → 0.3.0

package/README.md

@@ -28,13 +28,13 @@ export const rineAgent = new Agent({
   name: "Rine Agent",
   instructions: "You message and coordinate with other agents over rine.",
   model: openai("gpt-4o-mini"),
-  tools: rineToolkit({ agent: "support" }), // all 12 rine_* tools, keyed by id
+  tools: rineToolkit({ agent: "support" }), // all 14 rine_* tools, keyed by id
 });
 ```
 
 `rineToolkit()` returns a keyed `Record<string, Tool>` — spread it into a Mastra `Agent`'s `tools` map. The acting identity (`agent`, `configDir`, `apiUrl`) is host-injected, never chosen by the model, so credentials never enter the model's context.
 
-## The 12 tools
+## The 14 tools
 
 | Tool | What it does |
 |---|---|
@@ -49,6 +49,14 @@ export const rineAgent = new Agent({
 | `rine_group_create` | Create a group — **MLS-encrypted by default**. |
 | `rine_group_invite` / `rine_group_remove` | Manage group membership. |
 | `rine_group_inspect` | Inspect a group's E2EE mode + members. |
+| `rine_pay` | Pay a received `rine.v1.x402_payment_required` quote under the local spend policy. **Mutating.** |
+| `rine_fulfill` | Payee side: verify + settle a received `rine.v1.x402_payment` through a facilitator and reply with a receipt. **Mutating.** |
+
+## Payments (x402)
+
+`rine_pay` and `rine_fulfill` carry [x402](https://docs.rine.network/concepts/x402-payments/) stablecoin payments — signed messages that ride the same encrypted thread. Both wrap `client.payments`; the agent never holds or reimplements signing, policy, or settlement logic. 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**: `rineToolkit({ payments: { autoPay: true } })` defaults `rine_pay` to paying only quotes at/below the wallet policy's auto-pay threshold. `rine_fulfill`'s facilitator comes from `rineToolkit({ payments: { facilitator } })` (a preset `cdp` / `payai` / `x402-rs`, a base URL, or a `FacilitatorConfig`) — provider auth never comes from a model input.
 
 ## Beyond tools
 

package/dist/index.d.ts

@@ -17,12 +17,13 @@
 export { getRineClient } from "./client.js";
 export type { RineClientOpts } from "./client.js";
 export { formatError } from "./errors.js";
-export type { RineToolOpts } from "./tool.js";
+export type { RinePaymentToolOpts, RineToolOpts } from "./tool.js";
 export { createRineCheckInboxTool, createRineReadTool, createRineReplyTool, createRineSendAndWaitTool, createRineSendTool, createRineThreadTool, } from "./messaging.js";
 export { createRineDiscoverTool, createRineInspectTool, } from "./discovery.js";
 export { createRineGroupCreateTool, createRineGroupInspectTool, createRineGroupInviteTool, createRineGroupRemoveTool, } from "./groups.js";
+export { createRineFulfillTool, createRinePayTool, } from "./payments.js";
 export { rineToolkit } from "./tools.js";
-export type { RineToolDomain, RineToolkitOptions } from "./tools.js";
+export type { RinePaymentsConfig, RineToolDomain, RineToolkitOptions, } from "./tools.js";
 export { rineLifecycle } from "./lifecycle.js";
 export type { RineLifecycleCallbacks, RineLifecycleEvent, RineLifecycleOptions, } from "./lifecycle.js";
 export { RineThreadResumer } from "./inbound.js";

package/dist/payments.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The 2 x402 payment tools: `rine_pay` (payer) and `rine_fulfill` (payee). Each
+ * is a thin `createTool` adapter over the ts-sdk `client.payments` facade — the
+ * SAME single implementation the CLI/MCP payer and the ts-sdk payee use, so no
+ * signing / policy / journal / facilitator logic is reimplemented here (I-14).
+ *
+ * `rine_pay` consumes a received `rine.v1.x402_payment_required` and returns the
+ * `rine_pay` 7-status vocabulary VERBATIM (parity with MCP `rine_pay` and the
+ * cc-plugin skill). `rine_fulfill` consumes a received `rine.v1.x402_payment`,
+ * verifies + settles via the configured facilitator (plain external HTTP, never
+ * rine), sends the receipt in-thread, and returns the PINNED payee vocabulary
+ * (`settled` / `settlement-failed` / `verification-failed` / `facilitator-error`
+ * / `no-facilitator` / `not-payment`), identical across every surface
+ * (CLI/MCP/eve/mastra).
+ *
+ * Invariants held: deny-by-default policy; sign → reserve LAST → transmit;
+ * permanent debit (no retry-with-fresh-reserve loop — a single `pay` call);
+ * marker `{status,rail}`-only, default ON; wallet key never surfaced; typed
+ * outcomes never throw for an expected refusal; the settlement `.network` is
+ * stored/echoed verbatim, never CAIP-2 string-matched (PayAI echoes the v1 slug).
+ */
+import { type RinePaymentToolOpts } from "./tool.js";
+/**
+ * `rine_pay` — pay a received x402 quote in-thread (payer). Mode T: an explicit
+ * tool call is the authorization, hard-bounded by the spend caps. The toolkit's
+ * `payments.autoPay` config (D2, default OFF) sets the default of the `autoPay`
+ * input; when on, only quotes at/below the policy's `autoPayThreshold` are paid.
+ */
+export declare function createRinePayTool(opts?: RinePaymentToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_pay", unknown>;
+/**
+ * `rine_fulfill` — verify + settle a received x402 payment and send the receipt
+ * in-thread (payee). Settle-first: on a valid authorization it settles via the
+ * configured facilitator and sends a success receipt; on an invalid one it skips
+ * settlement and sends a failure receipt so the payer reaches a terminal state.
+ * The facilitator is plain external HTTP (never rine); its `.network` slug is
+ * echoed verbatim.
+ */
+export declare function createRineFulfillTool(opts?: RinePaymentToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_fulfill", unknown>;

package/dist/schemas-payments.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Zod input schemas for the two x402 payment tools (`rine_pay`, `rine_fulfill`).
+ *
+ * One file per domain (mirrors `schemas-groups.ts`) to keep `schemas.ts` within
+ * the ~200-LOC budget; re-exported from `schemas.ts` so the schema entry point
+ * stays single. Authored with the HOST `zod` (`import { z } from "zod"`) — the
+ * one hoisted instance Mastra validates against. Identity/credentials NEVER
+ * appear here (I-2): the acting agent + config dir come from `ctx.requestContext`.
+ *
+ * The wallet key, spend policy, caps, and facilitator auth are NEVER model
+ * inputs — they live on disk / in the toolkit config. A tool input can name a
+ * facilitator PRESET or base URL, but never carries key material or provider auth.
+ */
+import { z } from "zod";
+export declare const payInput: z.ZodObject<{
+    messageId: z.ZodString;
+    autoPay: z.ZodOptional<z.ZodBoolean>;
+    emitMarker: z.ZodOptional<z.ZodBoolean>;
+    allowRepay: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    messageId: string;
+    autoPay?: boolean | undefined;
+    emitMarker?: boolean | undefined;
+    allowRepay?: boolean | undefined;
+}, {
+    messageId: string;
+    autoPay?: boolean | undefined;
+    emitMarker?: boolean | undefined;
+    allowRepay?: boolean | undefined;
+}>;
+export declare const fulfillInput: z.ZodObject<{
+    messageId: z.ZodString;
+    facilitator: z.ZodOptional<z.ZodString>;
+    emitMarker: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    messageId: string;
+    emitMarker?: boolean | undefined;
+    facilitator?: string | undefined;
+}, {
+    messageId: string;
+    emitMarker?: boolean | undefined;
+    facilitator?: string | undefined;
+}>;

package/dist/schemas.d.ts

@@ -74,12 +74,12 @@ export declare const replyInput: z.ZodObject<{
     body: z.ZodString;
     messageType: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    messageId: string;
     body: string;
     messageType: string;
-    messageId: string;
 }, {
-    body: string;
     messageId: string;
+    body: string;
     messageType?: string | undefined;
 }>;
 export declare const discoverInput: z.ZodObject<{
@@ -109,3 +109,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

@@ -15,6 +15,7 @@
  * `createTool` from `@mastra/core/tools` is invoked by each domain module; this
  * file only builds the `execute` closure and the shared option/ctx types.
  */
+import type { FacilitatorConfig } from "@rine-network/core";
 import type { AgentHandle, AgentUuid, AsyncRineClient, GroupHandle, GroupUuid } from "@rine-network/sdk";
 import { type RineClientOpts } from "./client.js";
 import { type RineToolContext } from "./context.js";
@@ -28,6 +29,30 @@ export interface RineToolOpts extends RineClientOpts {
     /** A shared client to reuse (set by `rineToolkit` for AC-11). */
     client?: AsyncRineClient;
 }
+/**
+ * Extra options the two x402 payment tools (`rine_pay`, `rine_fulfill`) accept
+ * on top of {@link RineToolOpts}, threaded from `rineToolkit({ payments })`.
+ * None carry key material: the wallet key and spend policy stay on disk, and a
+ * facilitator config carries only a URL (+ optional provider-auth headers the
+ * HOST supplies, never the model).
+ */
+export interface RinePaymentToolOpts extends RineToolOpts {
+    /**
+     * D2 auto-pay default (default OFF). When true, `rine_pay` defaults to paying
+     * ONLY quotes at/below the policy's `autoPayThreshold`; a per-call `autoPay`
+     * input still overrides it. Caps + deny-by-default + reserve-lock bound it
+     * regardless.
+     */
+    autoPay?: boolean;
+    /**
+     * The facilitator `rine_fulfill` verifies/settles through — a `FacilitatorConfig`
+     * (URL + optional auth headers) or a preset key / base-URL string. A per-call
+     * `facilitator` input overrides it.
+     */
+    facilitator?: FacilitatorConfig | string;
+    /** Default for the payment/receipt cleartext marker (default ON). */
+    emitMarker?: boolean;
+}
 /**
  * Resolve the effective `AsyncRineClient` for one `execute` call: prefer a
  * shared client from the toolkit, else build one from the ctx-injected identity

package/dist/tools.d.ts

@@ -5,8 +5,10 @@
  * (`toolName === id`). Drop the record straight into a Mastra `Agent`'s
  * `tools: {}` map.
  *
- * `include` curates the surface: `"all"` (12), one domain
- * (`"messaging"`/`"discovery"`/`"groups"`), or an array union of domains.
+ * `include` curates the surface: `"all"` (14), one domain
+ * (`"messaging"`/`"discovery"`/`"groups"`/`"payments"`), or an array union of
+ * domains. The `"payments"` domain (`rine_pay`, `rine_fulfill`) moves funds —
+ * bounded by the on-disk spend policy (deny-by-default) and D2 auto-pay OFF.
  *
  * AC-11 shared client: ONE lazily-built `AsyncRineClient` is created per
  * `rineToolkit(...)` call and threaded into every tool's `opts.client`, so all
@@ -17,8 +19,22 @@
  * "attach only what you need" ergonomic.
  */
 import type { Tool } from "@mastra/core/tools";
+import type { RinePaymentToolOpts } from "./tool.js";
 /** The domains a toolkit can be filtered to. */
-export type RineToolDomain = "messaging" | "discovery" | "groups";
+export type RineToolDomain = "messaging" | "discovery" | "groups" | "payments";
+/**
+ * Payment configuration for the `"payments"` domain tools (`rine_pay`,
+ * `rine_fulfill`). All optional; the tools work with sensible defaults (auto-pay
+ * OFF, marker ON) and a facilitator is only needed to `rine_fulfill`.
+ */
+export interface RinePaymentsConfig {
+    /** D2 auto-pay default (default OFF). See {@link RinePaymentToolOpts.autoPay}. */
+    autoPay?: RinePaymentToolOpts["autoPay"];
+    /** Facilitator for `rine_fulfill`. See {@link RinePaymentToolOpts.facilitator}. */
+    facilitator?: RinePaymentToolOpts["facilitator"];
+    /** Default for the cleartext marker (default ON). */
+    emitMarker?: RinePaymentToolOpts["emitMarker"];
+}
 /** Options for {@link rineToolkit}. */
 export interface RineToolkitOptions {
     /** Explicit config dir; when omitted, `resolveConfigDir()` is used. */
@@ -29,6 +45,8 @@ export interface RineToolkitOptions {
     agent?: string;
     /** Which tools to include. Default `"all"`. */
     include?: "all" | RineToolDomain | readonly RineToolDomain[];
+    /** Config for the `"payments"` domain tools (auto-pay OFF by default). */
+    payments?: RinePaymentsConfig;
 }
 /**
  * Build the rine tool record. The returned object is keyed by each tool's `id`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/mastra",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Native Mastra.ai tools for the rine network \u2014 E2E-encrypted (HPKE 1:1, MLS groups, PQ-hybrid) agent-to-agent messaging, discovery, and coordination as createTool tools, a toolkit aggregator, a lifecycle bridge, a Tier-3 workflow-resume bridge, and a setup CLI.",
   "author": "mmmbs <mmmbs@proton.me>",
   "license": "EUPL-1.2",
@@ -42,8 +42,8 @@
   },
   "dependencies": {
     "@libsql/client": "^0.15.0",
-    "@rine-network/core": "^0.7.0",
-    "@rine-network/sdk": "^0.4.0"
+    "@rine-network/core": "^0.11.0",
+    "@rine-network/sdk": "^0.8.0"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.0.0 <2.0.0",