@rine-network/eve 0.1.0

package/dist/channel-Bg8l58gg.js

@@ -0,0 +1,304 @@
+import { _ as senderLabel, f as renderMessageBody, g as renderThreadLine, n as asRecipient, v as verifiedNote } from "./tool-BC49DldZ.js";
+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";
+//#region src/transcript.ts
+/** char ≈ 4 × tokens — the coarse proxy the spec specifies (REQ-CTX-01, OQ1). */
+const CHARS_PER_TOKEN = 4;
+/** Marker prepended when older turns were dropped to fit the budget. */
+const OMITTED_MARKER = "[…earlier turns omitted]";
+/**
+* Render the most-recent turns of a thread as role-tagged `context[]` lines within
+* a token budget. Turns are accumulated from the NEWEST end backwards until the
+* char budget (`tokenBudget * 4`) is hit; if any older turns were dropped, a single
+* {@link OMITTED_MARKER} line is prepended. Returns lines oldest→newest, ready to
+* slot into the Eve session `context` array.
+*
+* @param entries Thread entries, ordered oldest→newest (SDK `client.thread()`).
+* @param tokenBudget Approximate token budget for the transcript.
+*/
+function renderTranscriptContext(entries, tokenBudget) {
+	const charBudget = Math.max(0, tokenBudget) * CHARS_PER_TOKEN;
+	const lines = entries.map(renderThreadLine);
+	const kept = [];
+	let used = 0;
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i];
+		const cost = line.length + 1;
+		if (kept.length > 0 && used + cost > charBudget) break;
+		kept.push(line);
+		used += cost;
+	}
+	kept.reverse();
+	if (kept.length < lines.length) kept.unshift(OMITTED_MARKER);
+	return kept;
+}
+//#endregion
+//#region src/inbound.ts
+/**
+* Inbound webhook helpers for the rine channel: extracting the message id from a
+* rine standard-webhook body, and the continuation-token codec.
+*
+* The continuation token is how the channel makes outbound replies STATELESS (R7):
+* it encodes the rine `conversation_id`, the reply target (the group handle for
+* group mail, else the sender handle), and — for 1:1 inbound only — the inbound
+* `message id` so the `message.completed` handler can reply IN-PLACE (via the reply
+* endpoint, preserving the inbound conversation) without any durable per-session map.
+* Because the token bakes in the per-message `m`, it differs on every 1:1 inbound
+* turn, so Eve does NOT resume a prior session from it — cross-turn continuity comes
+* from the general thread primitive (push-injected transcript, Slice E), not session
+* resume. The message id is optional: group inbound and tokens minted by an older
+* build carry only `{c,r}` and decode with `messageId === undefined`, so the outbound
+* handler falls back to the `send()+parentConversationId` broadcast path.
+*/
+/** Sentinel marking our token payload, robust to Eve's `<channel>:` namespacing. */
+const TOKEN_MARKER = "r1.";
+/** base64url (no padding) encode of a UTF-8 string. */
+function b64urlEncode(s) {
+	return Buffer.from(s, "utf-8").toString("base64url");
+}
+/** base64url decode to a UTF-8 string (throws on malformed input). */
+function b64urlDecode(s) {
+	return Buffer.from(s, "base64url").toString("utf-8");
+}
+/**
+* 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.
+*/
+function encodeReplyToken(conversationId, replyTarget, messageId) {
+	const payload = {
+		c: conversationId,
+		r: replyTarget
+	};
+	if (messageId) payload.m = messageId;
+	return `${TOKEN_MARKER}${b64urlEncode(JSON.stringify(payload))}`;
+}
+/**
+* Decode a continuation token back to its {@link ReplyContext}. Tolerant of a
+* leading `<channel>:` namespace (or any prefix) and of malformed input —
+* returns `null` when the token is not one of ours or fails to parse, so the
+* outbound handler can safely skip rather than throw.
+*/
+function decodeReplyToken(token) {
+	if (!token) return null;
+	const idx = token.indexOf(TOKEN_MARKER);
+	if (idx < 0) return null;
+	try {
+		const payload = JSON.parse(b64urlDecode(token.slice(idx + 3)));
+		const conversationId = payload?.c;
+		const replyTarget = payload?.r;
+		if (typeof conversationId !== "string" || typeof replyTarget !== "string") return null;
+		const m = payload?.m;
+		return {
+			conversationId,
+			replyTarget,
+			messageId: typeof m === "string" && m.length > 0 ? m : void 0
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Extract the rine message id from a webhook body. The rine server's standard
+* (`payload_format="rine"`) delivery posts `{ message_id, agent_id, event,
+* timestamp }` (see backend `worker/delivery.py:_build_payload`); the A2A format
+* posts `{ result: { artifactUpdate: { artifact: { artifactId } } } }`. We read
+* `message_id` first, then the A2A artifact id, then tolerate a couple of legacy
+* nesting variants. Returns `undefined` when no id is present (→ 202 ignored).
+*/
+function messageIdFromWebhook(body) {
+	if (!body || typeof body !== "object") return void 0;
+	const b = body;
+	const a2aArtifactId = b.result?.artifactUpdate?.artifact?.artifactId;
+	const fromMessage = b.message?.id;
+	const fromData = b.data?.id;
+	const id = b.message_id ?? a2aArtifactId ?? fromMessage ?? fromData ?? b.id;
+	return typeof id === "string" && id.length > 0 ? id : void 0;
+}
+//#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 (`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
+* `sender_handle` / `from_agent_id` for routing + display. A malicious relay could
+* misroute a reply (never read it — replies stay E2EE). Binding routing to the
+* 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}` : "";
+	return `Inbound rine message from ${senderLabel(msg)}${where} (type ${msg.type}, ${verifiedNote(msg)}). Your reply is delivered back to the sender over rine.`;
+}
+/** Cap on turns fetched for the push-injected transcript (REQ-SRV-04). */
+const THREAD_FETCH_LIMIT = 50;
+/**
+* The inbound pipeline. Returns the HTTP {@link Response} the route should send.
+* Status codes are retry-aware (R8/#10): `5xx` = transient (caller should retry),
+* `4xx` = terminal drop, `2xx` = accepted/benign-ignore.
+*/
+async function processInbound(deps) {
+	if (!deps.secret) return new Response("rine channel not configured: RINE_WEBHOOK_SECRET unset", { status: 503 });
+	if (deps.raw.length > deps.maxBodyBytes) return new Response("payload too large", { status: 413 });
+	if (!verifyRineSignature(deps.raw, deps.signature, deps.secret)) return new Response("invalid signature", { status: 401 });
+	let parsed;
+	try {
+		parsed = JSON.parse(deps.raw.toString("utf-8"));
+	} catch {
+		return new Response("bad json", { status: 400 });
+	}
+	const messageId = messageIdFromWebhook(parsed);
+	if (!messageId) return new Response("ignored", { status: 202 });
+	if (deps.seen?.has(messageId)) return new Response("duplicate", { status: 200 });
+	let msg;
+	try {
+		msg = await deps.client.read(asMessageUuid(messageId));
+	} catch {
+		return new Response("read failed", { status: 503 });
+	}
+	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);
+		return new Response("ignored type", { status: 202 });
+	}
+	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);
+	}
+	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);
+		if (priorTurns.length > 0) context.push(...renderTranscriptContext(priorTurns, deps.threadContextTokenBudget));
+	}
+	await deps.send({
+		message: renderMessageBody(msg),
+		context
+	}, {
+		auth: null,
+		continuationToken: token
+	});
+	return new Response("ok", { status: 200 });
+}
+/**
+* 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.
+*/
+async function processCompletion(deps) {
+	if (deps.finishReason === "tool-calls") return;
+	if (!deps.message) return;
+	const rc = decodeReplyToken(deps.continuationToken);
+	if (!rc) return;
+	if (rc.messageId) {
+		await deps.client.reply(asMessageUuid(rc.messageId), { text: deps.message }, { type: deps.replyMessageType });
+		return;
+	}
+	await deps.client.send(asRecipient(rc.replyTarget), { text: deps.message }, {
+		type: deps.replyMessageType,
+		parentConversationId: rc.conversationId
+	});
+}
+/**
+* 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.
+*/
+async function processFailure(continuationToken, client) {
+	const rc = decodeReplyToken(continuationToken);
+	if (!rc) 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" });
+		return;
+	}
+	await client.send(asRecipient(rc.replyTarget), { text }, {
+		type: "rine.v1.error",
+		parentConversationId: rc.conversationId
+	});
+}
+//#endregion
+//#region src/channel.ts
+const DEFAULT_INBOUND_PATH = "/rine/v1/inbound";
+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). */
+const DEFAULT_IGNORE_TYPES = [
+	"rine.v1.task_response",
+	"rine.v1.error",
+	"rine.v1.receipt"
+];
+/** 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;
+	const replyMessageType = opts.replyMessageType ?? DEFAULT_REPLY_TYPE;
+	const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+	const acceptUnverified = opts.acceptUnverified ?? false;
+	const ignoreTypes = opts.ignoreTypes ?? DEFAULT_IGNORE_TYPES;
+	const threadContextTokenBudget = opts.threadContextTokenBudget ?? DEFAULT_THREAD_CONTEXT_TOKEN_BUDGET;
+	const seen = /* @__PURE__ */ new Set();
+	const client = () => opts.client ?? getRineClient({
+		agent: opts.agent ?? process.env.RINE_AGENT,
+		apiUrl: opts.apiUrl,
+		configDir: opts.configDir
+	});
+	return defineChannel({
+		routes: [POST(path, async (req, { send }) => processInbound({
+			raw: Buffer.from(await req.arrayBuffer()),
+			signature: req.headers.get("x-rine-signature") ?? void 0,
+			secret: process.env.RINE_WEBHOOK_SECRET,
+			client: client(),
+			send,
+			acceptUnverified,
+			maxBodyBytes,
+			ignoreTypes,
+			seen,
+			threadContextTokenBudget
+		}))],
+		events: {
+			"message.completed": async (data, channel) => {
+				try {
+					await processCompletion({
+						finishReason: data.finishReason,
+						message: data.message,
+						continuationToken: channel.continuationToken,
+						client: client(),
+						replyMessageType
+					});
+				} catch {}
+			},
+			"session.failed": async (_data, channel) => {
+				try {
+					await processFailure(channel.continuationToken, client());
+				} catch {}
+			}
+		}
+	});
+}
+//#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 };

package/dist/channel-core.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 (`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
+ * `sender_handle` / `from_agent_id` for routing + display. A malicious relay could
+ * misroute a reply (never read it — replies stay E2EE). Binding routing to the
+ * verified signer needs an SDK change to surface `senderKid`; tracked as a
+ * follow-up. Matches the sibling rine connectors' behavior.
+ */
+import type { AsyncRineClient } from "@rine-network/sdk";
+import type { DecryptedMessage } from "./types.js";
+/** Minimal `send` surface the inbound handler needs (Eve's route `send`). */
+export type ChannelSend = (input: {
+    message: string;
+    context?: string[];
+}, opts: {
+    auth: null;
+    continuationToken: string;
+}) => Promise<unknown>;
+/** The line of context handed to the model so it knows who/where the message is from. */
+export declare function senderContextLine(msg: DecryptedMessage): string;
+export interface InboundDeps {
+    /** Raw request body bytes. */
+    raw: Buffer;
+    /** The `x-rine-signature` header value. */
+    signature: string | undefined;
+    /** The HMAC secret (`RINE_WEBHOOK_SECRET`), or undefined if unset. */
+    secret: string | undefined;
+    client: AsyncRineClient;
+    send: ChannelSend;
+    acceptUnverified: boolean;
+    maxBodyBytes: number;
+    /** Inbound types to ignore (loop guard). */
+    ignoreTypes: readonly string[];
+    /** Bounded set of already-handled message ids (dedupe across retries/replays). */
+    seen?: Set<string>;
+    /**
+     * Approximate token budget for the role-tagged transcript push-injected into the
+     * session context (REQ-CTX-01). When unset, only the sender line is injected.
+     */
+    threadContextTokenBudget?: number;
+}
+/**
+ * The inbound pipeline. Returns the HTTP {@link Response} the route should send.
+ * Status codes are retry-aware (R8/#10): `5xx` = transient (caller should retry),
+ * `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.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `rineChannel(opts?)` — the rine channel for Eve. Re-export its result as the
+ * default export of `agent/channels/rine.ts` (the `init` scaffolder writes that
+ * one-line file). Channels cannot ship as bare npm modules, but the framework's
+ * own `slackChannel()` uses exactly this factory-then-re-export shape.
+ *
+ * It makes an Eve agent a first-class, E2EE-reachable citizen of the rine network:
+ * inbound rine webhooks start/resume a durable session; the terminal assistant
+ * message is encrypted and threaded back over rine. The actual pipeline lives in
+ * `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";
+/** Options for {@link rineChannel}. All optional; identity defaults to env. */
+export interface RineChannelOptions {
+    /** Acting agent (handle/name/UUID); defaults to `process.env.RINE_AGENT`. */
+    agent?: string;
+    apiUrl?: string;
+    configDir?: string;
+    /** Inbound route path; defaults to `RINE_INBOUND_PATH` env or `/rine/v1/inbound`. */
+    path?: string;
+    /** Act on messages whose sender signature did NOT verify (default false). */
+    acceptUnverified?: boolean;
+    /** rine message type used for outbound replies (default `rine.v1.task_response`). */
+    replyMessageType?: string;
+    /**
+     * Inbound message types to ignore (no session, no reply) — the loop guard that
+     * stops two rine-eve agents from auto-replying forever. Defaults to the
+     * connector's own outbound types.
+     */
+    ignoreTypes?: readonly string[];
+    /** Hard cap on inbound body size before HMAC work (default 512 KiB). */
+    maxBodyBytes?: number;
+    /**
+     * Approximate token budget for the role-tagged recent-transcript push-injected
+     * into the stateless Eve session context on each inbound (REQ-CTX-01). Older
+     * turns are truncated first with a `[…earlier turns omitted]` marker; a
+     * single-message thread injects no extra transcript. Default ~2000 tokens.
+     */
+    threadContextTokenBudget?: number;
+    /** A pre-built client (tests / advanced use); otherwise env-resolved lazily. */
+    client?: AsyncRineClient;
+}
+/** 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

@@ -0,0 +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 };

package/dist/client-X_-9CpQT.js

@@ -0,0 +1,44 @@
+import { AsyncRineClient } from "@rine-network/sdk";
+import { resolveApiUrl, resolveConfigDir } from "@rine-network/core";
+//#region src/client.ts
+/**
+* Lazy `AsyncRineClient` construction (invariant R1: side-effect-free import).
+*
+* No client is built at module load. The SDK client is created the first time a
+* tool's `execute` (or a channel handler) actually fires, then memoized per
+* distinct `(configDir, apiUrl)` pair so every rine surface in one Eve process
+* shares ONE client (the client holds no sockets, so sharing is cheap and keeps
+* the OAuth token cache warm). The acting `agent` is applied per-call via a cheap
+* derived `client.withAgent(...)`, never a separate base client.
+*
+* Two footguns the SDK leaves to the caller are closed here:
+*   - `configDir` defaults to `""` in the SDK constructor → it would silently
+*     read/write keys against `process.cwd()`. We resolve it via
+*     `resolveConfigDir()` (env `RINE_CONFIG_DIR` → `~/.config/rine` → cwd/.rine).
+*   - the SDK ignores `RINE_API_URL`; we resolve `apiUrl` via `resolveApiUrl()`.
+*/
+const clientCache = /* @__PURE__ */ new Map();
+function cacheKey(configDir, apiUrl) {
+	return `${configDir} ${apiUrl}`;
+}
+/**
+* Get (or lazily build + memoize) the shared `AsyncRineClient` for `opts`,
+* already scoped to `opts.agent` when present. Call ONLY from inside a tool
+* `execute` / a channel handler — never at module top level (R1).
+*/
+function getRineClient(opts = {}) {
+	const configDir = opts.configDir ?? resolveConfigDir();
+	const apiUrl = opts.apiUrl ?? resolveApiUrl();
+	const key = cacheKey(configDir, apiUrl);
+	let base = clientCache.get(key);
+	if (!base) {
+		base = new AsyncRineClient({
+			configDir,
+			apiUrl
+		});
+		clientCache.set(key, base);
+	}
+	return opts.agent ? base.withAgent(opts.agent) : base;
+}
+//#endregion
+export { getRineClient as t };

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lazy `AsyncRineClient` construction (invariant R1: side-effect-free import).
+ *
+ * No client is built at module load. The SDK client is created the first time a
+ * tool's `execute` (or a channel handler) actually fires, then memoized per
+ * distinct `(configDir, apiUrl)` pair so every rine surface in one Eve process
+ * shares ONE client (the client holds no sockets, so sharing is cheap and keeps
+ * the OAuth token cache warm). The acting `agent` is applied per-call via a cheap
+ * derived `client.withAgent(...)`, never a separate base client.
+ *
+ * Two footguns the SDK leaves to the caller are closed here:
+ *   - `configDir` defaults to `""` in the SDK constructor → it would silently
+ *     read/write keys against `process.cwd()`. We resolve it via
+ *     `resolveConfigDir()` (env `RINE_CONFIG_DIR` → `~/.config/rine` → cwd/.rine).
+ *   - the SDK ignores `RINE_API_URL`; we resolve `apiUrl` via `resolveApiUrl()`.
+ */
+import { AsyncRineClient } from "@rine-network/sdk";
+/** Per-call client overrides; when omitted, env/config resolution applies. */
+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 ONLY from inside a tool
+ * `execute` / a channel handler — never at module top level (R1).
+ */
+export declare function getRineClient(opts?: RineClientOpts): AsyncRineClient;
+/** Test-only: drop all memoized clients (not part of the public surface). */
+export declare function _resetClientCache(): void;

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `formatError(err)` — invariant R2: 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`, so this maps MOST-SPECIFIC FIRST and lets `RineApiError` be the
+ * catch-all for API errors.
+ */
+/**
+ * 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 = "rine_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,51 @@
+/**
+ * Pure render functions: turn SDK return values into the human-readable strings
+ * tools + the channel hand to the LLM / send back over rine.
+ *
+ * Invariant R4: 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 { ThreadEntry } from "@rine-network/sdk";
+import type { AgentProfile, AgentSummary, DecryptedMessage, GroupRead } from "./types.js";
+/** One thread turn as a role-tagged line: `[sent] you: …` / `[received] alice@org: …`. */
+export declare function renderThreadLine(e: ThreadEntry): string;
+/**
+ * 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;
+/**
+ * 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;
+/** Sender label: prefer the human handle, fall back to the agent UUID. */
+export declare function senderLabel(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`, OR the
+ * explicit `mls_enabled`/`mls_pending` flags. With MLS support present this is a
+ * CAPABILITY flag, not a failure flag (R9).
+ */
+export declare function groupIsMls(g: GroupRead): boolean;
+/**
+ * A group rendered for `rine_group_inspect`. Both the MLS and sender-key branches
+ * are `[OK]` — an MLS group is readable/postable from here (R9).
+ */
+export declare function renderGroup(g: GroupRead): string;

package/dist/hmac-CoaKHmf6.js

@@ -0,0 +1,24 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/hmac.ts
+/**
+* Verify a rine standard-webhook signature: `X-Rine-Signature: sha256=<hex>`,
+* where hex = HMAC-SHA256(rawBody, secret). Constant-time compare.
+*
+* This is the TRANSPORT-auth check (the POST genuinely came from rine and was not
+* tampered). It is independent of the per-message Ed25519 sender signature, which
+* the channel verifies separately after decryption (`DecryptedMessage.verified`).
+*/
+function verifyRineSignature(rawBody, header, secret) {
+	if (!header || !secret) return false;
+	const expected = `sha256=${createHmac("sha256", secret).update(typeof rawBody === "string" ? Buffer.from(rawBody) : rawBody).digest("hex")}`;
+	const a = Buffer.from(expected);
+	const b = Buffer.from(header);
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+/** Sign a raw body the way the rine server (and the dev relay) do. */
+function signRineBody(rawBody, secret) {
+	return `sha256=${createHmac("sha256", secret).update(typeof rawBody === "string" ? Buffer.from(rawBody) : rawBody).digest("hex")}`;
+}
+//#endregion
+export { verifyRineSignature as n, signRineBody as t };

package/dist/hmac.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Verify a rine standard-webhook signature: `X-Rine-Signature: sha256=<hex>`,
+ * where hex = HMAC-SHA256(rawBody, secret). Constant-time compare.
+ *
+ * This is the TRANSPORT-auth check (the POST genuinely came from rine and was not
+ * tampered). It is independent of the per-message Ed25519 sender signature, which
+ * the channel verifies separately after decryption (`DecryptedMessage.verified`).
+ */
+export declare function verifyRineSignature(rawBody: Buffer | string, header: string | undefined, secret: string): boolean;
+/** Sign a raw body the way the rine server (and the dev relay) do. */
+export declare function signRineBody(rawBody: Buffer | string, secret: string): string;