@rine-network/mastra 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @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.
+
+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.
+
+## Install
+
+```bash
+npm install @rine-network/mastra @mastra/core zod
+```
+
+Requires Node `>=22.13.0` (the `@mastra/core` floor). Onboard a rine identity once (org + agent, ~30–60 s RSA proof-of-work):
+
+```bash
+npx @rine-network/mastra onboard --email you@example.com --slug my-org --name "My Org"
+```
+
+## Quickstart
+
+```ts
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { rineToolkit } from "@rine-network/mastra";
+
+export const rineAgent = new Agent({
+  id: "rine-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
+});
+```
+
+`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
+
+| Tool | What it does |
+|---|---|
+| `rine_send` | Send an encrypted 1:1 or group (`#group@org`) message. |
+| `rine_send_and_wait` | Send and block for a reply (1:1, up to 300 s). |
+| `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_discover` | Search the public agent directory. |
+| `rine_inspect` | Inspect one agent's profile. |
+| `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. |
+
+## 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.
+- **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.
+
+## License
+
+EUPL-1.2

package/bin/onboard.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/onboard.js";
+
+await main(process.argv.slice(2));

package/dist/_threadmap-sql.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SQL constants for {@link SqliteThreadMap} (split out of `threadmap.ts` to keep
+ * each source file under the ~200-LOC budget). One table maps a
+ * `(handle, conversation_id)` thread to the suspended Mastra workflow `runId`.
+ *
+ * The composite key is the durable analog of a LangGraph `thread_id`: it is OUR
+ * responsibility (separate from Mastra's own workflow-snapshot storage) so a
+ * fresh process can find the right suspended run for an inbound rine message.
+ */
+/** The table name; namespaced so it never collides with Mastra's own tables. */
+export declare const TABLE = "rine_mastra_threadmap";
+/** Create the thread-map table if it does not already exist. */
+export declare const CREATE_TABLE_SQL = "CREATE TABLE IF NOT EXISTS rine_mastra_threadmap (\n  handle TEXT NOT NULL,\n  conversation_id TEXT NOT NULL,\n  run_id TEXT NOT NULL,\n  updated_at INTEGER NOT NULL,\n  PRIMARY KEY (handle, conversation_id)\n)";
+/** Upsert a `(handle, conversation_id) → runId` row. */
+export declare const SET_SQL = "INSERT INTO rine_mastra_threadmap (handle, conversation_id, run_id, updated_at)\n  VALUES (?, ?, ?, ?)\n  ON CONFLICT (handle, conversation_id)\n  DO UPDATE SET run_id = excluded.run_id, updated_at = excluded.updated_at";
+/** Look up the runId for a `(handle, conversation_id)` pair. */
+export declare const GET_SQL = "SELECT run_id FROM rine_mastra_threadmap\n  WHERE handle = ? AND conversation_id = ?";
+/** Delete the mapping for a `(handle, conversation_id)` pair. */
+export declare const DELETE_SQL = "DELETE FROM rine_mastra_threadmap\n  WHERE handle = ? AND conversation_id = ?";

package/dist/_zod.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Host-zod re-export + the shared string output schema.
+ *
+ * Every tool's `outputSchema` is `z.string()` (D-output) — a tool returns clean
+ * text to the model, so ciphertext can never ride a struct field and benign
+ * "no reply" strings never trip v1 output-validation (PHASE0_CONTRACT P0-2).
+ * This is authored with the HOST `zod` (the single hoisted instance Mastra
+ * validates against), NOT the SDK's re-exported `z`. Centralizing the one shared
+ * instance here keeps `import { z } from "zod"` out of every tool module while
+ * staying drift-proof.
+ */
+import { z } from "zod";
+export { z };
+/** The shared `outputSchema` for every rine tool: a plain string. */
+export declare const strResult: z.ZodString;

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lazy `AsyncRineClient` construction (invariant I-1: side-effect-free import).
+ *
+ * No client is built at module load or in any `createTool` factory body — the
+ * SDK client is created the first time a tool's `execute` actually fires, then
+ * memoized per distinct option set so all tools from one `rineToolkit(...)`
+ * call share ONE client (AC-11; the client holds no sockets, so sharing is
+ * cheap and keeps the OAuth token cache warm).
+ *
+ * Two footguns the SDK leaves to the caller are closed here (D-config-resolve):
+ *   - `configDir` defaults to `""` in the SDK constructor → it would silently
+ *     write/read keys against `process.cwd()`. We resolve it explicitly via
+ *     `resolveConfigDir()` unless the caller passed one.
+ *   - the SDK ignores `RINE_API_URL`; we resolve `apiUrl` via `resolveApiUrl()`
+ *     unless the caller passed one.
+ */
+import { AsyncRineClient } from "@rine-network/sdk";
+/** Per-tool / per-toolkit client overrides threaded from `rineToolkit(opts)`. */
+export interface RineClientOpts {
+    /** Explicit config dir; when omitted, `resolveConfigDir()` is used. */
+    configDir?: string;
+    /** Explicit API URL; when omitted, `resolveApiUrl()` is used. */
+    apiUrl?: string;
+    /** Acting agent (handle/name/UUID) sent as `X-Rine-Agent` on every request. */
+    agent?: string;
+}
+/**
+ * Get (or lazily build + memoize) the shared `AsyncRineClient` for `opts`,
+ * already scoped to `opts.agent` when present.
+ *
+ * Call this ONLY from inside an `execute` / a fired callback / a driver start —
+ * never at module top level or in a factory body (I-1).
+ */
+export declare function getRineClient(opts?: RineClientOpts): AsyncRineClient;
+/**
+ * Test-only: drop all memoized clients so a fresh resolution runs next call.
+ * Not part of the public package surface (not re-exported from `index.ts`).
+ */
+export declare function _resetClientCache(): void;

package/dist/context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Identity injection via Mastra's `RequestContext` (P0-3, BLOCKING — verified
+ * in-rig). The acting agent + config dir are read from `ctx.requestContext`
+ * inside a tool's `execute`, NEVER from the model-visible `inputSchema` (I-2 /
+ * Mastra's own security rule). Keys are `rine-`-namespaced to avoid collision
+ * with Mastra's reserved `mastra__*` keys.
+ *
+ * Import the `RequestContext` class itself from `@mastra/core/request-context`
+ * (the `./runtime-context` subpath does NOT exist on @mastra/core 1.41.0; there
+ * is NO `runtimeContext` field on the execute ctx).
+ */
+/** RequestContext key carrying the acting agent (handle/name/UUID). */
+export declare const RINE_ACTING_AGENT = "rine-acting-agent";
+/** RequestContext key carrying the explicit config dir override. */
+export declare const RINE_CONFIG_DIR = "rine-config-dir";
+/** RequestContext key carrying the explicit API-URL override. */
+export declare const RINE_API_URL = "rine-api-url";
+/**
+ * The slice of a Mastra tool-`execute` ctx the rine tools read. Structurally
+ * typed (a `.get(key)` reader) so the package does not hard-depend on a Mastra
+ * type that ships under a class we'd have to import at runtime — and so tests
+ * can pass a plain object. The real `ctx.requestContext` satisfies this.
+ */
+export interface RineToolContext {
+    requestContext?: {
+        get(key: string): unknown;
+    };
+}
+/** Read a string value from a tool ctx's requestContext, or undefined. */
+export declare function readContext(ctx: RineToolContext | undefined, key: string): string | undefined;

package/dist/discovery.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The 2 discovery tools: `rine_discover`, `rine_inspect` (SPEC §6 discovery
+ * table). Both are unauthenticated directory reads. `discover` exposes only the
+ * fields the TS `DiscoveryFilters` supports — q/category/language/verified/limit
+ * (the Python tag/jurisdiction/pricingModel fields are dropped, D-discover-fields).
+ */
+import { type RineToolOpts } from "./tool.js";
+/** `rine_discover` — search the public agent directory. */
+export declare function createRineDiscoverTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_discover", unknown>;
+/** `rine_inspect` — fetch one agent's full public profile. */
+export declare function createRineInspectTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_inspect", unknown>;

package/dist/drivers.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Tier-3 wake drivers (D-tier3-driver). Two ways to feed inbound rine messages
+ * into a {@link RineThreadResumer}:
+ *
+ *   - {@link PollDriver} (default) — a long-lived host loop over the SDK's
+ *     `defineAgent`/`watch` SSE delivery. Each inbound message →
+ *     `resumer.handleInbound(msg)`. Works anywhere with outbound connectivity,
+ *     zero infra.
+ *   - {@link makeWebhookHandler} (opt-in) — returns a `Callable` the user mounts
+ *     on their own HTTP route (rine outbound webhook → resume). Needs ingress.
+ *
+ * **Serverless caveat (docs must shout):** Mastra's built-in scheduler and a
+ * poll loop **silently never fire** on Vercel/Netlify/Lambda/CF Workers (the
+ * process dies between requests) — `@mastra/inngest` is required there.
+ *
+ * I-1: NO `AsyncRineClient` and NO SSE loop are built at construction. The
+ * `PollDriver` builds its client + `defineAgent` only on `start()`; the webhook
+ * handler builds nothing until it is actually called.
+ */
+import { type DecryptedMessage } from "@rine-network/sdk";
+import { type RineClientOpts } from "./client.js";
+import type { RineThreadResumer } from "./inbound.js";
+/** Options for {@link PollDriver}. Client overrides thread through to the SDK. */
+export interface PollDriverOptions extends RineClientOpts {
+    /** The resumer every inbound SSE message is dispatched to. */
+    resumer: RineThreadResumer;
+    /** Optional logger; defaults to `console`. */
+    logger?: Pick<Console, "debug" | "warn" | "error">;
+}
+/**
+ * The default Tier-3 wake driver: a long-lived `defineAgent` SSE loop that wakes
+ * suspended workflow runs. Build it, then call {@link start}; call {@link stop}
+ * on teardown. The SDK isolates per-message handler errors, so one bad message
+ * never tears down the loop.
+ */
+export declare class PollDriver {
+    private readonly resumer;
+    private readonly clientOpts;
+    private readonly log;
+    private agent?;
+    constructor(opts: PollDriverOptions);
+    /**
+     * Start the SSE delivery loop. Lazily builds the `AsyncRineClient` + the
+     * `defineAgent` actor (I-1 — nothing networked until now). Idempotent: a
+     * second call is a no-op while a loop is running.
+     */
+    start(): Promise<void>;
+    /** Stop the SSE loop, draining in-flight handlers. Idempotent. */
+    stop(): Promise<void>;
+}
+/** A mounted webhook handler: feed it one inbound message, get the outcome. */
+export type WebhookHandler = (msg: DecryptedMessage) => Promise<{
+    resumed: boolean;
+}>;
+/** Options for {@link makeWebhookHandler}. */
+export interface WebhookHandlerOptions {
+    /** The resumer each delivered message is dispatched to. */
+    resumer: RineThreadResumer;
+    /** Optional logger; defaults to `console`. */
+    logger?: Pick<Console, "debug" | "warn" | "error">;
+}
+/**
+ * The opt-in webhook wake driver. Returns a `Callable` the user invokes from
+ * their own HTTP route on a rine outbound webhook delivery; it dispatches the
+ * decrypted message to {@link RineThreadResumer.handleInbound} and reports
+ * whether a run was resumed. I-1: builds nothing until called.
+ *
+ * The caller is responsible for decrypting the webhook payload into a
+ * `DecryptedMessage` (e.g. via the SDK) before invoking the handler — keeping
+ * crypto in the SDK and this handler transport-agnostic.
+ */
+export declare function makeWebhookHandler(opts: WebhookHandlerOptions): WebhookHandler;

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `formatError(err)` — invariant I-3: turn any thrown SDK error into a readable
+ * string for the LLM, never a stack trace. Tools wrap their one `await client.*`
+ * call in `try/catch → formatError` and RESOLVE (never reject) for mapped errors.
+ *
+ * Ordering matters: the TS SDK error classes form a hierarchy rooted at
+ * `RineApiError` (e.g. `AuthenticationError extends RineApiError`), so this maps
+ * MOST-SPECIFIC FIRST and lets `RineApiError` be the catch-all for API errors.
+ *
+ * Differences from the Python `_format_error` (verified `rine-ts-sdk/src/errors.ts`):
+ *   - there is NO `MlsUnsupportedError` — MLS works; a genuine future MLS-op
+ *     failure surfaces as `CryptoError`/`RineApiError`, not a "can't do MLS"
+ *     message.
+ *   - there is NO `UnsupportedTargetError` — the group-on-`sendAndWait` case is
+ *     a plain `Error` caught by message substring INSIDE the tool (see
+ *     `isGroupUnsupportedOnWait`), not here.
+ */
+/**
+ * True when `err` is the plain `Error` `sendAndWait` throws for a group handle.
+ * The `send_and_wait` tool checks this BEFORE `formatError` and returns the
+ * "1:1 only" guidance; it is not a typed SDK error class.
+ */
+export declare function isGroupUnsupportedOnWait(err: unknown): boolean;
+/** The fixed reply for the group-on-`sendAndWait` case. */
+export declare const GROUP_ON_WAIT_MESSAGE = "send_and_wait is 1:1 only; use rine_send for groups.";
+export declare function formatError(err: unknown): string;

package/dist/format.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure render functions: turn SDK return values into the human-readable strings
+ * tools hand back to the LLM. Ported field-for-field from the Python `_format.py`
+ * (`AGENT_OUT_precedent_blueprint.md §6`) — same snake_case wire field names —
+ * with ONE inversion: the group MLS branch reads `[OK]` instead of `[WARN]`,
+ * because the TS SDK fully reads/posts MLS + PQ traffic (D-mls).
+ *
+ * Invariant I-2: these read ONLY `plaintext` / `decrypt_error` / verification
+ * 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 { AgentProfile, AgentSummary, DecryptedMessage, GroupRead } from "./types.js";
+/** Honest signature note — never claims "verified" for an unverifiable message. */
+export declare function verifiedNote(msg: DecryptedMessage): string;
+/**
+ * THE PLAINTEXT-IS-JSON FOOTGUN. Outbound sends wrap `{ text: body }`, and the
+ * SDK auto-`JSON.parse`s inbound `application/json` plaintext into a structured
+ * value. Unwrap defensively so the model sees prose, never raw JSON:
+ *   - a string → returned as-is
+ *   - `{ text: "…" }` → the inner text
+ *   - anything else → compact JSON (last resort)
+ */
+export declare function unwrapText(plaintext: unknown): string;
+/** Body of a message: decrypt error if unreadable, else the unwrapped plaintext. */
+export declare function renderMessageBody(msg: DecryptedMessage): string;
+/** A single message rendered across multiple labeled lines (for `rine_read`). */
+export declare function renderSingleMessage(msg: DecryptedMessage): string;
+/** A numbered inbox list, or the empty-state line. */
+export declare function renderInbox(items: readonly DecryptedMessage[]): string;
+/** A numbered discovery list, or the empty-state line. */
+export declare function renderDiscover(items: readonly AgentSummary[]): string;
+/** A full agent profile (for `rine_inspect`). */
+export declare function renderProfile(p: AgentProfile): string;
+/**
+ * Self-diagnose a group's E2EE mode. Uses `mls_group_id !== null` (the source of
+ * truth — the public `EncryptionVersion` enum is MISSING `mls-v1`/`hpke-hybrid-v1`
+ * despite the SDK decrypting them), OR the explicit `mls_enabled`/`mls_pending`
+ * flags. With MLS support present this is now a CAPABILITY flag, not a failure flag.
+ */
+export declare function groupIsMls(g: GroupRead): boolean;
+/**
+ * A group rendered for `rine_group_inspect`. THE INVERSION: both the MLS and
+ * sender-key branches are `[OK]` — an MLS group is readable/postable here, not a
+ * warned-about ceiling (the Python integration printed `[WARN] MLS — cannot
+ * read/post`).
+ */
+export declare function renderGroup(g: GroupRead): string;

package/dist/groups.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The 4 group tools: `rine_group_create`, `rine_group_invite`,
+ * `rine_group_remove`, `rine_group_inspect` (SPEC §6 groups table — the
+ * INVERTED, MLS-capable section).
+ *
+ * `group_create` exposes `enableMls` (default true) — the headline differentiator
+ * (D-mls): the SDK best-effort-inits an MLS group and the renderer reports
+ * `[OK] MLS`, not a `[WARN]` ceiling.
+ *
+ * The TS SDK's `groups.invite`/`removeMember`/`get` take BRANDED UUIDs
+ * positionally (unlike the Python SDK, which resolved handles internally), so
+ * invite/remove/inspect PRE-RESOLVE handle→UUID here (D-handle-resolve):
+ *   - a group → `groups.list()` + local match (`findGroup`),
+ *   - an agent → `resolveToUuid` (WebFinger) → its UUID (or pass a UUID through).
+ *     WebFinger — not the public directory — so unlisted agents resolve too.
+ */
+import { type RineToolOpts } from "./tool.js";
+/** `rine_group_create` — create an MLS-by-default coordination group. */
+export declare function createRineGroupCreateTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_create", unknown>;
+/** `rine_group_invite` — invite an agent into a group (handle→UUID pre-resolved). */
+export declare function createRineGroupInviteTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_invite", unknown>;
+/** `rine_group_remove` — remove a member; group keys rotate (handle→UUID pre-resolved). */
+export declare function createRineGroupRemoveTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_remove", unknown>;
+/** `rine_group_inspect` — report a group's E2EE mode + policy (`[OK] MLS` self-diagnosis). */
+export declare function createRineGroupInspectTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_group_inspect", unknown>;

package/dist/inbound.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Tier-3 inbound resumer (`RineThreadResumer`) — the TS analog of the Python
+ * `RineThreadResumer`, much simpler because the SDK does SSE delivery.
+ *
+ * An inbound rine message wakes a SUSPENDED Mastra workflow run:
+ *   1. resolve the message's `(handle, conversation_id)` → stored `runId` via the
+ *      {@link ThreadMapStore} (no mapping ⇒ skip, do NOT ack — lossless);
+ *   2. **rehydrate the snapshot via `getWorkflowRunById(runId)` BEFORE resume**
+ *      (the load-bearing P0-10 recipe; defends mastra #5521 where
+ *      `createRun({runId})` would otherwise read an empty in-process run-map);
+ *      a non-suspended / unknown run ⇒ skip, do NOT ack;
+ *   3. build `resumeData` from `plaintext` / `verified` / `from` ONLY
+ *      (I-2: JSON-serializable, never ciphertext or an SDK client) — a
+ *      decrypt-failed message ⇒ skip, do NOT ack;
+ *   4. `createRun({runId}).resume({ step, resumeData })` to continue the run.
+ *
+ * **Lossless-by-default (langchain D16):** every skip path leaves the message in
+ * the rine inbox (no `markDelivered`), so a later poll can retry after the run is
+ * mapped / key recovery succeeds. The resumer NEVER acks.
+ */
+import type { ThreadMapStore } from "./threadmap.js";
+import type { DecryptedMessage } from "./types.js";
+/**
+ * The minimal Mastra-workflow surface the resumer drives (the P0-10 recipe). A
+ * real `mastra.getWorkflow(id)` satisfies this structurally — we type only the
+ * two methods used so the package does not hard-couple to a workflow generic and
+ * tests can pass a fake. `step` is the suspended step (a `createStep` object or
+ * its string id), per `Run.resume({ step, resumeData })`.
+ */
+export interface ResumableWorkflow {
+    /** Rehydrate a suspended run's snapshot from shared storage (or `null`). */
+    getWorkflowRunById(runId: string): Promise<WorkflowSnapshot | null>;
+    /** Reattach to a run by id; `resume` then continues from its suspended step. */
+    createRun(opts: {
+        runId: string;
+    }): Promise<ResumableRun>;
+}
+/** The rehydrated snapshot — only its suspended-status shape is read here. */
+export interface WorkflowSnapshot {
+    /** Run status; `"suspended"` means it is waiting on a resume. */
+    status?: string;
+    /** The suspended step path(s), when surfaced by the snapshot. */
+    suspended?: unknown;
+}
+/** A run reattached by id, ready to `resume`. */
+export interface ResumableRun {
+    resume(params: {
+        step?: unknown;
+        resumeData: ResumeData;
+    }): Promise<unknown>;
+}
+/**
+ * The JSON-serializable payload handed to the suspended step on resume. I-2:
+ * plaintext + signature facts ONLY — no ciphertext, no envelope, no SDK client.
+ */
+export interface ResumeData {
+    /** Unwrapped decrypted body (or a decrypt-error marker), never ciphertext. */
+    plaintext: string;
+    /** Whether the inbound message's signature verified. */
+    verified: boolean;
+    /** Sender handle (or agent UUID fallback), for the resumed step's context. */
+    from: string;
+    /** The inbound message id, for the step's threading/audit. */
+    messageId: string;
+}
+/** Options for {@link RineThreadResumer}. */
+export interface RineThreadResumerOptions {
+    /** A pre-built workflow with snapshot storage already bound (P0-10). */
+    workflow: ResumableWorkflow;
+    /** The durable `(handle, conversation) → runId` map. */
+    threadMap: ThreadMapStore;
+    /** The suspended step to resume; omit when exactly one step is suspended. */
+    step?: unknown;
+    /** Optional logger; defaults to `console`. Used for skip-path diagnostics. */
+    logger?: Pick<Console, "debug" | "warn">;
+}
+/** Outcome of {@link RineThreadResumer.handleInbound} — observable for drivers/tests. */
+export type ResumeOutcome = {
+    resumed: true;
+    runId: string;
+} | {
+    resumed: false;
+    reason: "no-map" | "not-suspended" | "decrypt-failed" | "no-conversation" | "failed";
+};
+/**
+ * Wakes suspended Mastra workflow runs from inbound rine messages. Build ONE per
+ * driver and feed every inbound message through {@link handleInbound}.
+ */
+export declare class RineThreadResumer {
+    private readonly workflow;
+    private readonly threadMap;
+    private readonly step?;
+    private readonly log;
+    constructor(opts: RineThreadResumerOptions);
+    /**
+     * Resume the workflow run mapped to this message's thread. Returns the
+     * outcome; on any skip path it logs + returns `{ resumed: false }` and does
+     * NOT ack the message (lossless — it stays in the rine inbox for a retry).
+     */
+    handleInbound(msg: DecryptedMessage): Promise<ResumeOutcome>;
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @rine-network/mastra — native Mastra.ai tools for the rine network.
+ *
+ * E2E-encrypted (HPKE 1:1, MLS groups RFC 9420, PQ-hybrid) agent-to-agent
+ * messaging, discovery, and coordination as Mastra `createTool` tools, plus a
+ * toolkit aggregator, a lifecycle bridge, a Tier-3 workflow-resume bridge, and
+ * an out-of-band onboard CLI.
+ *
+ * Re-export surface — filled out as the build stages land the tools, the
+ * aggregator, the lifecycle bridge, and the Tier-3 apparatus. The foundation
+ * (client builder, error formatter, renderers, schemas) is exported now so
+ * tests and downstream stages can consume it.
+ *
+ * Import is side-effect-free (I-1): nothing here constructs a client, reads a
+ * credential, or opens a socket at module load.
+ */
+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 { createRineDiscoverTool, createRineInspectTool, } from "./discovery.js";
+export { createRineGroupCreateTool, createRineGroupInspectTool, createRineGroupInviteTool, createRineGroupRemoveTool, } from "./groups.js";
+export { rineToolkit } from "./tools.js";
+export type { RineToolDomain, RineToolkitOptions } from "./tools.js";
+export { rineLifecycle } from "./lifecycle.js";
+export type { RineLifecycleCallbacks, RineLifecycleEvent, RineLifecycleOptions, } from "./lifecycle.js";
+export { RineThreadResumer } from "./inbound.js";
+export type { ResumableRun, ResumableWorkflow, ResumeData, ResumeOutcome, RineThreadResumerOptions, WorkflowSnapshot, } from "./inbound.js";
+export { InMemoryThreadMap, SqliteThreadMap, } from "./threadmap.js";
+export type { SqliteThreadMapOptions, ThreadMapStore, } from "./threadmap.js";
+export { makeWebhookHandler, PollDriver } from "./drivers.js";
+export type { PollDriverOptions, WebhookHandler, WebhookHandlerOptions, } from "./drivers.js";
+export { parseOnboardArgs, runOnboard } from "./onboard.js";
+export type { OnboardArgs, OnboardIO, OnboardOptions } from "./onboard.js";
+export { RINE_ACTING_AGENT, RINE_API_URL, RINE_CONFIG_DIR, } from "./context.js";
+export type { RineToolContext } from "./context.js";
+export type { AgentProfile, AgentSummary, DecryptedMessage, GroupRead, InviteResult, MessageRead, } from "./types.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Outbound lifecycle bridge `rineLifecycle` (SPEC §8 + PHASE0_CONTRACT P0-7).
+ *
+ * Mastra has NO callback-handler object class. The faithful 1:1 of the Python
+ * `RineCallbackHandler` is a FACTORY returning the top-level callbacks
+ * `agent.stream(...)` / `agent.generate(...)` accept — verified identical across
+ * both methods (P0-7). Spread the result into either:
+ *   const cb = rineLifecycle({ to: "ops@acme", on: ["finish", "error"] });
+ *   await agent.stream(input, { ...cb });    // or .generate(input, { ...cb })
+ *
+ * Selector → callback map (port verbatim from the Python listener):
+ *   finish → onFinish     ({text,…})              → "agent finished: {text}"
+ *   error  → onError      ({error})               → "agent error: {error}"
+ *   step   → onStepFinish ({toolCalls,…})         → "step: {toolName}"
+ *
+ * Invariants:
+ *   - I-1: opt-in by instantiation; the `AsyncRineClient` is built lazily on the
+ *     FIRST fired callback (never at module load or in this factory body).
+ *   - I-2: only the model-visible `text` / tool name / error message is summarized
+ *     into the notify body — never ciphertext (these callbacks never see an
+ *     envelope).
+ *   - Best-effort: each fired callback attempts EXACTLY ONE `client.send` (AC-13);
+ *     a send failure is swallowed + debug-logged and never thrown out of the
+ *     callback (AC-14) — a notify failure must not crash the agent run.
+ */
+import { type RineClientOpts } from "./client.js";
+/** The lifecycle selectors a caller can opt into. */
+export type RineLifecycleEvent = "finish" | "error" | "step";
+/** Options for {@link rineLifecycle}. */
+export interface RineLifecycleOptions extends RineClientOpts {
+    /** Recipient handle/UUID every notify is sent to (`name@org`, `#group@org`). */
+    to: string;
+    /** Which lifecycle events fire a notify. Defaults to `["finish", "error"]`. */
+    on?: readonly RineLifecycleEvent[];
+}
+/** The callback bag spread into `agent.stream(...)` / `agent.generate(...)`. */
+export interface RineLifecycleCallbacks {
+    onFinish?: (event: unknown) => void;
+    onError?: (event: unknown) => void;
+    onStepFinish?: (event: unknown) => void;
+}
+/**
+ * Build the opt-in outbound lifecycle bridge. Returns ONLY the callbacks for the
+ * selected events (so `{ ...cb }` never installs a no-op for an unselected one).
+ * The client is resolved lazily on the first fired callback (I-1).
+ */
+export declare function rineLifecycle(opts: RineLifecycleOptions): RineLifecycleCallbacks;

package/dist/messaging.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The 5 messaging tools: `rine_send`, `rine_send_and_wait`, `rine_check_inbox`,
+ * `rine_read`, `rine_reply` (SPEC §6 messaging table). Each is a thin
+ * `createTool` adapter: one `AsyncRineClient` call rendered to a string, wrapped
+ * by `makeExecute` (lazy client + formatError). Identity comes from
+ * `ctx.requestContext`, never the model-visible `inputSchema`.
+ *
+ * I-2 holds throughout: renderers read only plaintext/decrypt_error/verification
+ * (`format.ts`), never the ciphertext envelope. `rine_check_inbox` is the
+ * Track-0 poll+ack receive primitive (Tier-1).
+ */
+import { type RineToolOpts } from "./tool.js";
+/** `rine_send` — send a 1:1 or `#`-group message (the SDK auto-routes groups). */
+export declare function createRineSendTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_send", unknown>;
+/** `rine_send_and_wait` — 1:1 send that blocks for a reply (Tier-2, ms timeout). */
+export declare function createRineSendAndWaitTool(opts?: RineToolOpts): import("@mastra/core/tools").Tool<any, any, any, any, import("@mastra/core/tools").ToolExecutionContext<any, any, unknown>, "rine_send_and_wait", unknown>;
+/**
+ * `rine_check_inbox` — poll the newest new messages, decrypt them, then
+ * best-effort `markDelivered` the decryptable ids so a later check returns only
+ * newer mail (Track-0 poll+ack, Tier-1). On ack failure: warn + note the
+ * messages "may reappear" but still return the reads (AC-5).
+ */
+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_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>;