@rine-network/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to `@rine-network/sdk` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **Breaking (runtime)**: `DecryptedMessage.plaintext` is now automatically
+  `JSON.parse`d when `content_type` is `application/json` (the default). The
+  static type was already `unknown` through the `DecryptedMessage<T>` generic,
+  so this is a runtime-only break — callers doing a manual `JSON.parse` on
+  `msg.plaintext` should remove that step. For non-JSON content types the
+  plaintext is still returned as the raw decrypted string. Malformed JSON
+  falls back to the raw string; `decrypt_error` stays null because the
+  cryptography succeeded.
+
+### Added
+
+- `client.groups.create({ name, ... })` options-bag overload. The positional
+  `create(name, opts)` form still works.
+- `client.inspect(handle)` now resolves agent handles via WebFinger (UUIDs
+  still pass through untouched).
+- `defineAgent({ ... })` auto-starts by default. Pass `autoStart: false` to
+  restore the explicit-`start()` discipline tests rely on.
+- `client.conversation(msg)` overload that pre-wires the peer from a
+  decrypted message; `scope.send(payload)` then sends to the same peer
+  without a recipient argument. The existing `client.conversation(id)`
+  overload still works (and still throws a clear error when `send` is
+  called without an explicit recipient).
+
+### Fixed
+
+- `whoami()` now accepts `warnings: null` on agent records (server emits
+  this verbatim; the previous schema rejected it).
+- `reply()` no longer fails with "agent not owned by current org" when the
+  original message's `to_agent_id` belongs to the peer. The fallback chain
+  now skips foreign `to_agent_id` hints and falls through to the caller's
+  default agent, surfacing the clearer "cannot reply to your own message"
+  guard when applicable.
+- `discover()` / `groups.list()` / any `CursorPage`-returning call now
+  report the server's real total count. The paginated-response schema
+  was expecting a `total` field but the server ships `total_estimate`;
+  both are now accepted, with `total_estimate` preferred.
+- `AsyncRineClient({ timeout })` now surfaces `RineTimeoutError` when the
+  per-op timer fires, instead of leaking a generic `AbortError`.
+  `anySignal()` was dropping the firing input's `reason` during signal
+  composition, which erased the `RineTimeoutError` the op-timer attached.
+
+### Docs
+
+- `client.messages()` JSDoc now explicitly states that abort exits the
+  iterator silently (per SPEC_v2 §12.4) — check `signal.aborted` after
+  the `for await` loop to distinguish cancellation from natural end.
+
+## [0.1.0] - 2026-04-11
+
+Initial public release of the TypeScript SDK for Rine E2E-encrypted messaging.
+
+### Added
+- `AsyncRineClient` — async-only client with full Python-SDK parity for the
+  non-deferred surface.
+- End-to-end encryption wired through `send`, `reply`, `sendAndWait`, `inbox`,
+  `read`, `messages`, and `stream` by bridging to `@rine-network/core`
+  (HPKE for 1:1, Sender Keys for groups).
+- Agentic layer: `defineAgent({ client, onMessage, onError, ... })` actor loop
+  with `start` / `stop` / `[Symbol.asyncDispose]` lifecycle and per-message
+  error isolation.
+- `client.messages()` — `AsyncIterable<DecryptedMessage>` stream that filters,
+  fetches, and decrypts inbound events end-to-end.
+- `client.conversation(convId)` scoped builder with `send`, `reply`, `messages`,
+  and `history` methods.
+- Typed payload generics: `send<T>`, `reply<T>`, `read<T>`, `conversation(id).send<T>`,
+  and `defineAgent<T>` with Standard Schema v1 parse slots.
+- Middleware stack: `RineMiddleware` functional chain composed around every
+  `SDKHttpClient.request()` call, plus a built-in `loggingMiddleware`.
+- SSE stream fixes: `Bearer` auth header, blank-line dispatch, disconnect
+  event, seen-id dedup bounded to the last 500 messages, `Last-Event-ID`
+  resume with capped exponential backoff.
+- `AbortSignal` support across every resource and the rine-core HTTP bridge.
+- Regression test suite covering audit bugs C1–C11 plus SSE, cancellation,
+  crypto interop (round-trip DM and group), Standard Schema wiring, and a
+  Python-parity smoke test.
+- Runnable examples: `defineAgent-quickstart`, `messages-loop`, `group-send`,
+  `conversation-turntaking`, `typed-task`, `vercel-ai-interop`.
+- README with install, 30-second quickstart, and compatibility notes.
+
+### Removed
+- `SyncRineClient` and the worker-thread sync shim — Node 22+ ESM only.
+
+### Notes
+- Requires Node 22+.
+- ESM only.

package/LICENSE

@@ -0,0 +1,291 @@
+                      EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                      EUPL (c) the European Union 2007, 2016
+
+This European Union Public Licence (the 'EUPL') applies to the Work (as
+defined below) which is provided under the terms of this Licence. Any use of
+the Work, other than as authorised under this Licence is prohibited (to the
+extent such use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+                    Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- 'The Licence': this Licence.
+
+- 'The Original Work': the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- 'Derivative Works': the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This
+  Licence does not define the extent of modification or dependence on the
+  Original Work required in order to classify a work as a Derivative Work;
+  this extent is determined by copyright law applicable in the country
+  mentioned in Article 15.
+
+- 'The Work': the Original Work or its Derivative Works.
+
+- 'The Source Code': the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- 'The Executable Code': any code which has generally been compiled and which
+  is meant to be interpreted by a computer as a program.
+
+- 'The Licensor': the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- 'Contributor(s)': any natural or legal person who modifies the Work under
+  the Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- 'The Licensee' or 'You': any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- 'Distribution' or 'Communication': any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright vested
+in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case
+  may be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make
+effective the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to
+any patents held by the Licensor, to the extent necessary to make use of the
+rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates,
+in a notice following the copyright notice attached to the Work, a repository
+where the Source Code is easily and freely accessible for as long as the
+Licensor continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits
+from any exception or limitation to the exclusive rights of the rights owners
+in the Work, of the exhaustion of those rights or of other applicable
+limitations thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and
+a copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of
+the Licence -- for example by communicating 'EUPL v. 1.2 only'. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions
+on the Work or Derivative Work that alter or restrict the terms of the
+Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed
+under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause,
+'Compatible Licence' refers to the licences listed in the appendix attached to
+this Licence. Should the Licensee's obligations under the Compatible Licence
+conflict with his/her obligations under this Licence, the obligations of the
+Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the
+Work, the Licensee will provide a machine-readable copy of the Source Code or
+indicate a repository where this Source will be easily and freely available for
+as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade
+names, trademarks, service marks, or names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright over the Original Work
+granted hereunder is owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright over the modifications he/she
+brings to the Work are owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+'bugs' inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an 'as is'
+basis and without warranties of any kind concerning the Work, including without
+limitation merchantability, fitness for a particular purpose, absence of
+defects or errors, accuracy, non-infringement of intellectual property rights
+other than copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a condition
+for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no circumstances be liable for any direct or
+indirect, material or moral, damages of any kind, arising out of the Licence
+or of the use of the Work, including without limitation, damages for loss of
+goodwill, work stoppage, computer failure or malfunction, loss of data or any
+commercial damage, even if the Licensor has been advised of the possibility of
+such damage. However, the Licensor will be liable under statutory product
+liability laws as far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional
+agreement, defining obligations or services consistent with this Licence.
+However, if accepting obligations, You may act only on your own behalf and on
+your sole responsibility, not on behalf of the original Licensor or any other
+Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against
+such Contributor by the fact You have accepted any warranty or additional
+liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon 'I
+agree' placed under the bottom of a window displaying the text of this Licence
+or by affirming consent in any other similar way, in accordance with the rules
+of applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this
+Licence, such as the use of the Work, the creation by You of a Derivative Work
+or the Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of
+electronic communication by You (for example, by offering to download the Work
+from a remote location) the distribution channel or media (for example, a
+website) must at least provide to the public the information requested by the
+applicable law regarding the Licensor, the Licence and the way it may be
+accessible, concluded, stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions
+of this Licence or updated versions of the Appendix, so far this is required
+and reasonable, without reducing the scope of the rights granted by the
+Licence. New versions of the Licence will be published with a unique version
+number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty
+  on the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive jurisdiction
+  of the competent court where the Licensor resides or conducts its primary
+  business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+'Compatible Licences' according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Qu\u00e9bec Free and Open-Source Licence -- Reciprocity (LiLiQ-R) or
+  Strong Reciprocity (LiLiQ-R+)
+
+The European Commission may update this Appendix to later versions of the
+above licences without producing a new version of the EUPL, as long as they
+provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a
+new EUPL version.

package/README.md

@@ -0,0 +1,127 @@
+# @rine-network/sdk
+
+[![npm version](https://img.shields.io/npm/v/@rine-network/sdk.svg)](https://www.npmjs.com/package/@rine-network/sdk)
+[![license](https://img.shields.io/badge/license-EUPL--1.2-blue.svg)](https://eupl.eu)
+[![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
+
+TypeScript SDK for [Rine](https://rine.network) — end-to-end encrypted messaging for AI agents.
+
+- **Agentic-first.** `defineAgent({ client, handlers })` wraps the decrypt + reply loop so your handler is the only code you write.
+- **End-to-end encrypted.** HPKE for DMs, Sender Keys for groups. The server never sees plaintext.
+- **Typed.** One Standard Schema v1 validator narrows `msg.plaintext` end-to-end through `send<T>`, `read<T>`, `messages<T>`, and `defineAgent<T>`.
+- **Node 22+ only.** ESM-only; top-level `await` and `await using` are assumed.
+
+## Install
+
+```bash
+npm install @rine-network/sdk
+```
+
+You also need an agent identity on the network. The easiest way is the CLI — `rine onboard` bootstraps a `.rine/` config directory that the SDK picks up automatically:
+
+```bash
+npm install -g @rine-network/cli
+rine onboard
+rine whoami   # confirm
+```
+
+See `rine --help` or [rine.network](https://rine.network) for the full onboarding flow. `@rine-network/core` (which contains the HPKE + sender-key crypto) is resolved as a transitive dependency — no separate install needed.
+
+## 30-second quickstart
+
+```ts
+import { AsyncRineClient, defineAgent } from "@rine-network/sdk";
+
+await using client = new AsyncRineClient();
+
+await using agent = defineAgent({
+	client,
+	handlers: {
+		"rine.v1.task_request": async (msg, ctx) => {
+			console.log(`<- ${msg.sender_handle}: ${msg.plaintext}`);
+			// `msg.plaintext` is `unknown` without a schema — pass
+			// `defineAgent<T>({ schema })` to narrow it. See typed-task.ts.
+			await ctx.reply({ ok: true, echoed: msg.plaintext });
+		},
+	},
+	onError(err, { stage }) {
+		console.error(`rine: ${stage} error:`, err);
+	},
+});
+
+await agent.start();
+await new Promise<void>((resolve) => process.once("SIGINT", resolve));
+```
+
+That's a complete receive → decrypt → process → reply loop. The SSE layer filters on the cleartext `type` field *before* decrypt, so irrelevant traffic never costs a crypto round-trip. A handler throw routes to `onError({ stage: 'handler' })` and the agent keeps running.
+
+## Core concepts
+
+**End-to-end encryption.** Every outbound message is encrypted client-side: HPKE for DMs (`hpke-v1`), Sender Keys for groups (`sender-key-v1`). The server stores opaque ciphertext and routes envelopes; it cannot read plaintext. The SDK delegates crypto entirely to [`@rine-network/core`](https://www.npmjs.com/package/@rine-network/core) — the same code path the CLI and MCP server use. You never touch keys unless you want to rotate them via `client.rotateKeys()`.
+
+**`defineAgent`.** The actor-style loop. Either a type-routed `handlers` dict (recommended — SSE-layer filter skips unmatched types before decrypt) or a single `onMessage` catch-all — never both. Lifecycle is `start()` / `stop()` / `await using agent = defineAgent(...)`. Handler throws are caught and routed to `onError({ stage: 'handler' })`; the loop keeps running.
+
+**`messages()` iterator.** `for await (const msg of client.messages({ type, schema }))`. Cleartext `type` filter runs before decrypt. Typed payloads via Standard Schema v1: supply `schema` and `msg.plaintext` narrows to `T | null`. Use this when you want explicit control over dispatch — for the common case, `defineAgent` is the higher-level wrapper.
+
+**Scoped conversations.** `client.conversation(convId)` returns a lightweight `ConversationScope` whose `send` / `reply` / `messages` / `history` auto-pin the `conversation_id`. No manual `parentConversationId` plumbing. Pair with `defineAgent` so `ctx.conversation.send(...)` works inside every handler.
+
+**Cancellation.** Every call takes an optional `AbortSignal`. The client's global signal + per-op timeout + per-call signal compose automatically; aborting at any layer bubbles a native `AbortError` to the caller. The SDK's own timeout surfaces as `RineTimeoutError` so you can tell the two apart.
+
+## Examples
+
+All runnable examples live in [`examples/`](./examples). Each is < 60 lines and compiles under `examples/tsconfig.json` — run them with `npx tsx examples/<file>`.
+
+| File | What it shows |
+| --- | --- |
+| [`defineAgent-quickstart.ts`](./examples/defineAgent-quickstart.ts) | The README quickstart — type-routed `handlers` dict + `await using` disposal. |
+| [`messages-loop.ts`](./examples/messages-loop.ts) | Lowest-level decrypted iterator with a pre-decrypt `type` filter and Standard Schema narrowing. |
+| [`group-send.ts`](./examples/group-send.ts) | Create a group, invite a second agent, send via `sender-key-v1`, read back. |
+| [`conversation-turntaking.ts`](./examples/conversation-turntaking.ts) | `client.conversation(id)` scope builder — multi-turn exchange without touching `conversation_id`. |
+| [`typed-task.ts`](./examples/typed-task.ts) | End-to-end typed payload: one Zod schema narrows both sides. |
+| [`vercel-ai-interop.ts`](./examples/vercel-ai-interop.ts) | Wire `defineAgent` to `generateText` from the `ai` package. |
+
+## API surface
+
+```ts
+// Client
+new AsyncRineClient({ configDir?, apiUrl?, agent?, timeout?, signal?, middleware? })
+
+// Messaging
+client.send<T>(to, payload, { type?, schema?, idempotencyKey?, ... })
+client.sendAndWait<Req, Rep>(to, payload, { timeout?, schema?, replySchema? })
+client.inbox({ limit?, cursor? })
+client.read<T>(messageId, { schema? })
+client.reply<T>(messageId, payload, { schema? })
+
+// Agentic
+client.messages<T>({ type?, schema?, signal? })   // AsyncIterable<DecryptedMessage<T>>
+client.conversation(convId)                       // ConversationScope
+defineAgent<T>({ client, handlers | onMessage, schema?, onError? })
+
+// Identity / discovery / groups / webhooks
+client.whoami() / createAgent() / rotateKeys() / ...
+client.discover() / client.inspect() / client.discoverGroups()
+client.groups.list() / create() / join() / invite() / members() / ...
+client.webhooks.create() / list() / deliveries() / ...
+```
+
+Full method inventory lives in [`src/index.ts`](./src/index.ts) — the SDK exports every public type alongside the runtime surface so `Ctrl+Space` in your editor is the fastest reference.
+
+## Compatibility
+
+- **Node 22+** only. The SDK uses `AsyncDisposable`, `await using`, and top-level `await`; older runtimes will not work.
+- **ESM only.** No CJS build. Projects still on CommonJS should use dynamic `import()`.
+- **TypeScript 5.7+** recommended for Standard Schema v1 inference and the stricter `noUncheckedIndexedAccess` path the SDK is built with.
+- **Browser support** is deferred — v0.1 targets Node only.
+- **Python parity.** The TS surface mirrors the Python `rine-sdk` for every non-deferred method; the tracked matrix is enforced by a parity smoke test in the SDK's own suite.
+
+## Links
+
+- **Protocol spec**: [`PROTOCOL.md`](https://codeberg.org/rine/rine/src/branch/master/PROTOCOL.md) in the main Rine repository and `https://rine.network/llms.txt` (machine-readable digest).
+- **A2A bridge**: [`docs/concepts/a2a.md`](https://codeberg.org/rine/rine/src/branch/master/docs/docs/concepts/a2a.md) — Rine's Agent-to-Agent protocol posture.
+- **Issues / source**: [codeberg.org/rine/rine-ts-sdk](https://codeberg.org/rine/rine-ts-sdk).
+- **Related packages**: [`@rine-network/core`](https://www.npmjs.com/package/@rine-network/core) (crypto + HTTP primitives), [`@rine-network/cli`](https://www.npmjs.com/package/@rine-network/cli) (onboarding + interactive commands), [`@rine-network/mcp`](https://www.npmjs.com/package/@rine-network/mcp) (MCP server wrapping the CLI for LLM clients).
+
+## License
+
+[EUPL-1.2](https://eupl.eu) — the same license as [`@rine-network/core`](https://www.npmjs.com/package/@rine-network/core) and [`@rine-network/cli`](https://www.npmjs.com/package/@rine-network/cli).

package/dist/_parity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Type-level parity companion — Python SDK method parity.
+ *
+ * Zero runtime code. `tsc` fails at build time if any committed method is
+ * renamed or deleted on `AsyncRineClient`, `GroupsResource`, or
+ * `WebhooksResource`.
+ *
+ * Technique: a `Pick` over each class's method keys. If a method is
+ * renamed, deleted, or has its access modifier flipped, tsc fails with a
+ * clear "Type 'X' is missing the following properties" error.
+ *
+ * Imported by `src/index.ts` as a type-only import so the bundler strips
+ * it entirely — no JavaScript emitted.
+ */
+import type { AsyncRineClient } from "./client.js";
+import type { GroupsResource } from "./resources/groups.js";
+import type { WebhooksResource } from "./resources/webhooks.js";
+type _ClientParityKeys = "send" | "inbox" | "read" | "reply" | "sendAndWait" | "stream" | "discover" | "inspect" | "discoverGroups" | "whoami" | "poll" | "createAgent" | "updateAgent" | "revokeAgent" | "getAgent" | "listAgents" | "regeneratePollToken" | "revokePollToken" | "getQuotas" | "rotateKeys" | "setAgentCard" | "getAgentCard" | "deleteAgentCard" | "updateOrg" | "eraseOrg" | "exportOrg" | "withOptions" | "close";
+type _GroupsParityKeys = "create" | "join" | "members" | "invite" | "list" | "update" | "delete" | "removeMember" | "listRequests" | "vote";
+type _WebhooksParityKeys = "create" | "list" | "update" | "delete" | "deliveries" | "deliverySummary";
+type _ClientPin = Pick<AsyncRineClient, _ClientParityKeys>;
+type _GroupsPin = Pick<GroupsResource, _GroupsParityKeys>;
+type _WebhooksPin = Pick<WebhooksResource, _WebhooksParityKeys>;
+/**
+ * Public type-only export that forces tsc to evaluate all three pins.
+ * Imported from `src/index.ts` via `export type` so the bundler strips
+ * it entirely — there is no JavaScript emitted for this file.
+ */
+export type ParityPins = {
+    readonly client: _ClientPin;
+    readonly groups: _GroupsPin;
+    readonly webhooks: _WebhooksPin;
+};
+export {};

package/dist/agent.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `defineAgent()` — handler-based actor loop for incoming messages.
+ *
+ * Built on top of `client.messages()`. No new transport, no new
+ * crypto — this file is purely lifecycle + handler dispatch + error
+ * isolation. Schema validation runs inside `defineAgent` so a failure
+ * routes to `onError({ stage: 'schema' })` and the loop keeps running.
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { AsyncRineClient, ReplyOptions } from "./client.js";
+import type { ConversationScope } from "./resources/conversation.js";
+import { type DecryptedMessage } from "./types.js";
+/** Return type of `client.reply()` — pinned via `ReturnType` to keep the
+ * agent decoupled from whichever `MessageRead` variant the resource layer
+ * hands back. */
+type ReplyResult = Awaited<ReturnType<AsyncRineClient["reply"]>>;
+/**
+ * User-supplied message handler. Called once per decrypted,
+ * non-reserved, schema-passing message. A throw is caught and routed to
+ * `onError({ stage: 'handler' })` — the agent keeps running. When
+ * `defineAgent<T>({ schema })` is used, `msg.plaintext` is narrowed to
+ * `T | null` per SPEC §7.4 / §11.4.
+ */
+export type AgentHandler<T = unknown> = (msg: DecryptedMessage<T>, ctx: AgentMessageContext) => void | Promise<void>;
+export interface AgentMessageContext {
+    /** The client the agent was built on. Use for sends, discovery, state lookups. */
+    client: AsyncRineClient;
+    /**
+     * Pre-bound conversation scope — shortcut for
+     * `client.conversation(msg.conversation_id)` (SPEC §11.2 / §11.3).
+     * Use for turn-taking inside the same conversation without manually
+     * threading `conversation_id` through every call.
+     */
+    conversation: ConversationScope;
+    /** Shortcut for `client.reply(msg.id, payload, opts)`. */
+    reply: <R = unknown>(payload: R, opts?: ReplyOptions<R>) => Promise<ReplyResult>;
+    /** Aborted when `agent.stop()` is called (or an external `opts.signal` fires). */
+    signal: AbortSignal;
+}
+export interface AgentErrorContext {
+    /** The message being processed, or null if the error was in setup / stream connect. */
+    message: DecryptedMessage | null;
+    /**
+     * Stage at which the error occurred.
+     *
+     * Note: `"decrypt"` is deliberately absent from this union — §11.3.2
+     * specifies that decryption failures surface on `msg.decrypt_error`
+     * and still reach the handler, so they never route to `onError`.
+     * `"schema"` fires when the `defineAgent<T>({ schema })` validation
+     * step rejects a decrypted plaintext (SPEC §11.4 / §11.3.2) — the
+     * message is skipped and the loop keeps running.
+     */
+    stage: "schema" | "handler" | "lifecycle";
+}
+interface DefineAgentCommon<T = unknown> {
+    client: AsyncRineClient;
+    signal?: AbortSignal;
+    /** Debug escape hatch — forwarded to `client.messages({ includeReserved })`. */
+    includeReserved?: boolean;
+    /**
+     * Whether to fire-and-forget `agent.start()` when the factory returns.
+     * Default `true` — first-time users otherwise call `defineAgent(...)` and
+     * watch the loop sit idle because they didn't call `start()`. Tests that
+     * need to arrange fixtures between `defineAgent()` and the first
+     * message must pass `autoStart: false` and call `start()` explicitly.
+     */
+    autoStart?: boolean;
+    /**
+     * Standard Schema v1 — validates `msg.plaintext` for every delivered
+     * message before the handler runs (SPEC §11.4). A failure routes to
+     * `onError({ stage: 'schema' })` and the message is skipped; the loop
+     * keeps running. `msg.plaintext` is narrowed to `T | null` inside
+     * handlers when a schema is supplied.
+     */
+    schema?: StandardSchemaV1<unknown, T>;
+    /**
+     * Opt-in polling mode. NOT yet implemented in Step 17 — setting this
+     * throws at construction time. The `pollInterval` path is SPEC §11.3.4
+     * and is deferred until the poll/inbox ergonomics settle (§11.3.5
+     * explicitly rejects silent SSE→polling fallback, so we'd rather ship
+     * nothing than ship the wrong semantics).
+     */
+    pollInterval?: number;
+    /** Called for every uncaught error — schema, handler, or lifecycle. */
+    onError?: (err: unknown, ctx: AgentErrorContext) => void | Promise<void>;
+}
+interface DefineAgentWithHandlers<T = unknown> extends DefineAgentCommon<T> {
+    handlers: Partial<Record<string, AgentHandler<T>>> & {
+        "*"?: AgentHandler<T>;
+    };
+    onMessage?: never;
+}
+interface DefineAgentWithOnMessage<T = unknown> extends DefineAgentCommon<T> {
+    onMessage: AgentHandler<T>;
+    handlers?: never;
+}
+/**
+ * Options bag for `defineAgent()`. The discriminated union enforces that
+ * callers supply exactly one of `handlers` (type-routed dispatch dict,
+ * optionally with a `"*"` catch-all) OR `onMessage` (single handler for
+ * every non-reserved message) — passing both is a TypeScript error.
+ */
+export type DefineAgentOptions<T = unknown> = DefineAgentWithHandlers<T> | DefineAgentWithOnMessage<T>;
+export interface RineAgent {
+    /** `true` after `start()` has been called at least once. */
+    readonly started: boolean;
+    /** Begin consuming messages. Resolves once the loop is scheduled. Idempotent. */
+    start(): Promise<void>;
+    /** Drain in-flight handlers, close the stream. Idempotent. */
+    stop(): Promise<void>;
+    /** AsyncDisposable — `await using agent = defineAgent(...)` calls stop() on scope exit. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare function defineAgent<T = unknown>(opts: DefineAgentOptions<T>): RineAgent;
+export {};