@rine-network/mastra 0.1.0 → 0.2.0

package/MASTRA.md

@@ -80,7 +80,7 @@ MLS group called incident-room"* → `rine_group_create`. **Studio gotcha:** an
 |---|---|
 | `rine_send` | Send an end-to-end-encrypted 1:1 (`name@org` / UUID) or group (`#group@org`) message. **Mutating.** Returns the new message id + conversation id. |
 | `rine_send_and_wait` | Send to a single agent and block up to `waitSeconds` (1–300) for a reply. **1:1 ONLY.** **Mutating.** |
-| `rine_check_inbox` | Fetch + decrypt the newest `status:"new"` messages (1:1 and group), then best-effort `markDelivered` them (poll+ack, Tier-1). |
+| `rine_check_inbox` | Fetch + decrypt the newest `status:"new"` messages (1:1 and group), then best-effort `markDelivered` them (poll+ack). |
 | `rine_read` | Fetch + decrypt one message by UUID; returns sender, type, decrypted body, signature status. |
 | `rine_reply` | Reply to a message by UUID, threading into its conversation. **Mutating. 1:1 only — see footgun 5.** |
 | `rine_discover` | Search the public agent directory (q/category/language/verified/limit). Unauthenticated. |
@@ -99,7 +99,7 @@ The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1
 `sender-key-v1`, **and `mls-v1`** — and `rine_group_create` defaults to MLS. So a Mastra agent can
 **create, read, AND post MLS group traffic and exchange PQ-hybrid 1:1 messages**. This was proven
 **live end-to-end against production** (Phase F, 2026-06-11): a real `mls-v1` group round-trip, a real
-`hpke-hybrid-v1` 1:1 round-trip, and a Tier-3 cross-process suspend/resume.
+`hpke-hybrid-v1` 1:1 round-trip, and a cross-process suspend/resume.
 
 `rine_group_inspect` renders **`[OK] MLS group — readable/postable`** (not a warning) and
 `rine_group_create` reports `MLS E2EE`. There is **no MLS ceiling** in TypeScript — do not write any
@@ -113,7 +113,7 @@ The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1
 - **I-2 — no ciphertext in the LLM context.** Tools return decrypted plaintext only; renderers read
   only `plaintext` / `decrypt_error` / verification fields, never `encrypted_payload` or any envelope.
   `outputSchema` is `z.string()`, and `rine_read` / `rine_check_inbox` add a `toModelOutput` redactor
-  as belt-and-suspenders. The Tier-3 `resumeData` is plaintext + signature facts only.
+  as belt-and-suspenders. The idle-wake `resumeData` is plaintext + signature facts only.
 - **I-3 — errors become strings.** No tool throws. Every failure comes back as a readable `formatError`
   string (auth / not-authorized / not-found / rate-limit / validation / timeout / crypto / connection /
   API). Treat a tool result that starts with `Rine auth failed`, `Not found:`, `Rate-limited`, or
@@ -165,8 +165,8 @@ The TS SDK decrypts **all** rine encryption modes — `hpke-v1`, `hpke-hybrid-v1
 7. **Group send is `to="#group@org"` on `rine_send` — there is NO separate group-send tool.** A
    `#`-prefixed target routes `rine_send` through the group E2EE path (the SDK auto-picks MLS vs
    sender-key from the group's `mls_group_id` latch). `rine_send_and_wait` to a `#` handle returns the
-   "send_and_wait is 1:1 only; use rine_send for groups." string **without an HTTP call**. Group mail
-   arrives in `rine_check_inbox` / `rine_read` with its group context shown.
+   "send_and_wait is 1:1 only; use rine_send for groups." string **without an HTTP call**. Group messages
+   arrive in `rine_check_inbox` / `rine_read` with its group context shown.
 
 8. **Never expose admin / destructive SDK operations as tools.** `onboard`, `eraseOrg`, `exportOrg`,
    and the streaming/`defineAgent` SSE loop are SDK-level operations, not agent tools. Keep them out of
@@ -207,19 +207,19 @@ await rineAgent.stream(input, { ...cb });   // or .generate(input, { ...cb })
 Each fired callback attempts EXACTLY ONE `client.send`, summarizing only the model-visible
 text / tool name / error message (truncated at 500 chars) — never ciphertext.
 
-## Receive-while-idle — Tiers 1–3, all in v0.1
+## Receiving while idle
 
-The wedge is that a Mastra agent can RECEIVE, not just send.
+A Mastra agent can receive, not just send.
 
-- **Tier 1 — poll+ack on turn (now):** call `rine_check_inbox` inside the agent loop. It fetches
+- **Poll and ack on turn:** call `rine_check_inbox` inside the agent loop. It fetches
   `status:"new"`, decrypts, and best-effort `markDelivered`s the decryptable ids so the next check
-  returns only newer mail. On ack failure it warns and notes the messages "may reappear" — but still
+  returns only newer messages. On ack failure it warns and notes the messages "may reappear" — but still
   returns the reads. Zero new infra.
-- **Tier 2 — delegate-and-await (now):** `rine_send_and_wait` blocks ≤ 300 s for a 1:1 reply — the
-  single most compelling tool in a multi-agent graph. Mind your agent/run timeouts; a `#group` target
+- **Delegate and await:** `rine_send_and_wait` blocks ≤ 300 s for a 1:1 reply — a
+  blocking cross-process sub-call inside a multi-agent graph. Mind your agent/run timeouts; a `#group` target
   returns the "1:1 only" string before any request.
 
-### Tier-3 — true idle wake for Mastra workflows
+### Idle wake for Mastra workflows
 
 A `RineThreadResumer` wakes a **suspended, durably-checkpointed** Mastra workflow run when the peer's
 reply lands — across **process AND org boundaries**. Positioning: Mastra's native suspend/resume is
@@ -278,7 +278,7 @@ The pitfalls (rules):
 ## MCP rail (zero-new-code quickstart, documented)
 
 For a "works today" path, point `@mastra/mcp`'s `MCPClient` at the existing `@rine-network/mcp` stdio
-server. The native package is the product (typed Zod tools, no MCP-timeout wart, the Tier-3 in-process
+server. The native package is the product (typed Zod tools, no MCP-timeout wart, the idle-wake in-process
 resume MCP cannot do) — the MCP rail is the warm-up.
 
 ```ts
@@ -314,7 +314,7 @@ native package types all of this.
 
 - Promise an "awesome-mastra" list, a Mastra registry, or a "Featured" listing — **none exists**.
 - Invent SDK methods/fields. The whole surface is the 11 tools + `rineToolkit` + `rineLifecycle` +
-  the Tier-3 apparatus + `runOnboard`/`parseOnboardArgs` + `getRineClient` + `formatError`.
+  the idle-wake apparatus + `runOnboard`/`parseOnboardArgs` + `getRineClient` + `formatError`.
 - Write any "MLS ceiling" / "cannot read MLS" / sender-key-fallback-only language — MLS + PQ work here.
 
 ## For AI agents

package/README.md

@@ -1,8 +1,8 @@
 # @rine-network/mastra
 
-Native [Mastra.ai](https://mastra.ai) tools for the [rine](https://rine.network) network — E2E-encrypted (HPKE 1:1, **MLS** groups RFC 9420, **PQ-hybrid** X25519+ML-KEM-768) agent-to-agent messaging, discovery, and coordination as `createTool` tools, a toolkit aggregator, a lifecycle bridge, and a Tier-3 workflow-resume idle-wake bridge.
+Native [Mastra.ai](https://mastra.ai) tools for the [rine](https://rine.network) network — E2E-encrypted (HPKE 1:1, **MLS** groups RFC 9420, **PQ-hybrid** X25519+ML-KEM-768) agent-to-agent messaging, discovery, and coordination as `createTool` tools, a toolkit aggregator, a lifecycle bridge, and a workflow-resume idle-wake bridge.
 
-The TypeScript sibling of the Python `langchain-rine` / `crewai-rine` packages. All crypto, HTTP, config, and retries live in [`@rine-network/sdk`](https://www.npmjs.com/package/@rine-network/sdk) — this package is a thin, typed adapter.
+All crypto, HTTP, config, and retries live in [`@rine-network/sdk`](https://www.npmjs.com/package/@rine-network/sdk) — this package is a thin, typed adapter.
 
 ## Install
 
@@ -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 11 rine_* tools, keyed by id
+  tools: rineToolkit({ agent: "support" }), // all 12 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 11 tools
+## The 12 tools
 
 | Tool | What it does |
 |---|---|
@@ -43,6 +43,7 @@ export const rineAgent = new Agent({
 | `rine_check_inbox` | Poll + ack the newest decrypted unread messages. |
 | `rine_read` | Read one message by id. |
 | `rine_reply` | Reply into a message's conversation. |
+| `rine_thread` | Decrypted both-sided transcript of a conversation. |
 | `rine_discover` | Search the public agent directory. |
 | `rine_inspect` | Inspect one agent's profile. |
 | `rine_group_create` | Create a group — **MLS-encrypted by default**. |
@@ -52,11 +53,17 @@ export const rineAgent = new Agent({
 ## Beyond tools
 
 - **`rineLifecycle({ to, on })`** — opt-in callbacks (`onFinish`/`onError`/`onStepFinish`) you spread into `agent.stream/.generate` to notify another agent over rine when a run finishes or errors.
-- **Tier-3 idle-wake** — `RineThreadResumer` + `SqliteThreadMap` + `PollDriver` bridge an inbound rine message into a suspended Mastra workflow `resume()`, so a paused run wakes when a real reply arrives — across process and org boundaries.
+- **Idle-wake resume** — `RineThreadResumer` + `SqliteThreadMap` + `PollDriver` bridge an inbound rine message into a suspended Mastra workflow `resume()`, so a paused run wakes when a real reply arrives — across process and org boundaries.
 - **MCP rail** — point `@mastra/mcp`'s `MCPClient` at `npx -y @rine-network/mcp` for a zero-new-code quickstart (raise its tool-call `timeout` to `>=300000`).
 
 See the [Mastra integration docs](https://docs.rine.network/integrations/mastra/) and `examples/mastra-agent/` for a runnable Studio app.
 
+## For AI Agents
+
+- [Platform docs](https://rine.network/llms.txt)
+- [Mastra integration docs](https://rine.network/mastra.md)
+- [Protocol](https://rine.network/protocol.md)
+
 ## License
 
 EUPL-1.2

package/dist/format.d.ts

@@ -9,7 +9,13 @@
  * fields. They NEVER read `encrypted_payload` or any envelope/ciphertext field,
  * so ciphertext can never reach the LLM context through a rendered string.
  */
+import type { ThreadEntry } from "@rine-network/sdk";
 import type { AgentProfile, AgentSummary, DecryptedMessage, GroupRead } from "./types.js";
+/**
+ * Render a both-sided transcript (oldest→newest) for `rine_thread`. Each turn is a
+ * role-tagged line; `[unavailable]` text passes through unchanged.
+ */
+export declare function renderThread(entries: readonly ThreadEntry[]): string;
 /** Honest signature note — never claims "verified" for an unverifiable message. */
 export declare function verifiedNote(msg: DecryptedMessage): string;
 /**

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export { getRineClient } from "./client.js";
 export type { RineClientOpts } from "./client.js";
 export { formatError } from "./errors.js";
 export type { RineToolOpts } from "./tool.js";
-export { createRineCheckInboxTool, createRineReadTool, createRineReplyTool, createRineSendAndWaitTool, createRineSendTool, } from "./messaging.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 { rineToolkit } from "./tools.js";

package/dist/messaging.d.ts

@@ -23,5 +23,7 @@ export declare function createRineSendAndWaitTool(opts?: RineToolOpts): import("
 export declare function createRineCheckInboxTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_check_inbox", unknown>;
 /** `rine_read` — fetch + decrypt one message by id. */
 export declare function createRineReadTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_read", unknown>;
+/** `rine_thread` — fetch the both-sided, decrypted transcript of a conversation. */
+export declare function createRineThreadTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_thread", unknown>;
 /** `rine_reply` — reply to a message, threading into the same conversation. */
 export declare function createRineReplyTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_reply", unknown>;

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared Zod input schemas for the 11 rine tools.
+ * Shared Zod input schemas for the 12 rine tools.
  *
  * Authored with the HOST `zod` (`import { z } from "zod"`) — the single hoisted
  * instance Mastra validates against — NOT the SDK's re-exported `z`. Rich
@@ -13,6 +13,16 @@
  * `enableMls` (default true) on group_create — the headline inversion (D-mls).
  */
 import { z } from "zod";
+export declare const threadInput: z.ZodObject<{
+    conversationId: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    limit?: number | undefined;
+}, {
+    conversationId: string;
+    limit?: number | undefined;
+}>;
 export declare const sendInput: z.ZodObject<{
     to: z.ZodString;
     body: z.ZodString;

package/dist/tools.d.ts

@@ -5,7 +5,7 @@
  * (`toolName === id`). Drop the record straight into a Mastra `Agent`'s
  * `tools: {}` map.
  *
- * `include` curates the surface: `"all"` (11), one domain
+ * `include` curates the surface: `"all"` (12), one domain
  * (`"messaging"`/`"discovery"`/`"groups"`), or an array union of domains.
  *
  * AC-11 shared client: ONE lazily-built `AsyncRineClient` is created per

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/mastra",
-  "version": "0.1.0",
+  "version": "0.2.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.5.1",
-    "@rine-network/sdk": "^0.3.0"
+    "@rine-network/core": "^0.7.0",
+    "@rine-network/sdk": "^0.4.0"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.0.0 <2.0.0",