@rine-network/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,3028 @@
+import { HttpClient, decryptGroupMessage, decryptMessage, encryptGroupMessage, encryptMessage, encryptionPublicKeyToJWK, fetchAgents, fetchAndIngestPendingSKDistributions, fetchRecipientEncryptionKey, generateAgentKeys, getOrCreateSenderKey, getOrRefreshToken, loadCredentials, performRegistration, resolveAgent, resolveToUuid, saveAgentKeys, saveCredentials, signingPublicKeyToJWK, validateSlug } from "@rine-network/core";
+import { z, z as z$1 } from "zod";
+//#region src/errors.ts
+/**
+* Typed error hierarchy for the Rine SDK.
+*
+* Mirrors the Python SDK error hierarchy (rine/errors.py) but adapted for TypeScript.
+* All error classes are compatible with the `raiseForStatus()` pattern.
+*/
+/** Base exception for all Rine SDK errors. */
+var RineError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RineError";
+	}
+};
+/** HTTP API error with status code and detail. */
+var RineApiError = class extends RineError {
+	constructor(status, detail, raw) {
+		super(`${status}: ${detail}`);
+		this.status = status;
+		this.detail = detail;
+		this.raw = raw;
+		this.name = "RineApiError";
+	}
+};
+/** 401 — invalid or missing credentials. */
+var AuthenticationError = class extends RineApiError {
+	constructor(detail = "Authentication failed", raw) {
+		super(401, detail, raw);
+		this.name = "AuthenticationError";
+	}
+};
+/** 403 — insufficient permissions for the requested operation. */
+var AuthorizationError = class extends RineApiError {
+	constructor(detail = "Permission denied", raw) {
+		super(403, detail, raw);
+		this.name = "AuthorizationError";
+	}
+};
+/** 404 — the requested resource was not found. */
+var NotFoundError = class extends RineApiError {
+	constructor(detail = "Resource not found", raw) {
+		super(404, detail, raw);
+		this.name = "NotFoundError";
+	}
+};
+/** 409 — resource conflict (e.g., duplicate slug or agent name). */
+var ConflictError = class extends RineApiError {
+	constructor(detail = "Conflict", raw) {
+		super(409, detail, raw);
+		this.name = "ConflictError";
+	}
+};
+/** 429 — rate limit exceeded. */
+var RateLimitError = class extends RineApiError {
+	retryAfter;
+	constructor(detail, retryAfter, raw) {
+		super(429, detail, raw);
+		this.name = "RateLimitError";
+		this.retryAfter = retryAfter;
+	}
+};
+/** 422 — request validation failed. */
+var ValidationError = class extends RineApiError {
+	constructor(detail = "Validation error", raw) {
+		super(422, detail, raw);
+		this.name = "ValidationError";
+	}
+};
+/** 500 — unexpected server error. */
+var InternalServerError = class extends RineApiError {
+	constructor(detail = "Internal server error", raw) {
+		super(500, detail, raw);
+		this.name = "InternalServerError";
+	}
+};
+/** 503 — service temporarily unavailable. */
+var ServiceUnavailableError = class extends RineApiError {
+	constructor(detail = "Service unavailable", raw) {
+		super(503, detail, raw);
+		this.name = "ServiceUnavailableError";
+	}
+};
+/** Request timed out — the server did not respond in time. */
+var RineTimeoutError = class extends RineError {
+	constructor(message = "Request timed out") {
+		super(message);
+		this.name = "RineTimeoutError";
+	}
+};
+/** Network-level failure — could not reach the server. */
+var APIConnectionError = class extends RineError {
+	cause;
+	constructor(message = "Connection failed", cause) {
+		super(message);
+		this.name = "APIConnectionError";
+		this.cause = cause;
+	}
+};
+/** Encryption or decryption failure. */
+var CryptoError = class extends RineError {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.name = "CryptoError";
+		this.cause = cause;
+	}
+};
+/** Missing or invalid SDK configuration. */
+var ConfigError = class extends RineError {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigError";
+	}
+};
+/** Client-side schema validation failure (Standard Schema v1). */
+var SchemaValidationError = class extends RineError {
+	constructor(message) {
+		super(message);
+		this.name = "SchemaValidationError";
+	}
+};
+const STATUS_MAP = new Map([
+	[401, AuthenticationError],
+	[403, AuthorizationError],
+	[404, NotFoundError],
+	[409, ConflictError],
+	[422, ValidationError],
+	[500, InternalServerError],
+	[503, ServiceUnavailableError]
+]);
+/**
+* Raise the appropriate error class for an HTTP status code.
+*
+* @param status - HTTP status code.
+* @param detail - Error detail string from the server.
+* @param raw   - Optional raw response body for debugging.
+*/
+function raiseForStatus(status, detail, raw) {
+	if (status === 429) throw new RateLimitError(detail, raw?.headers?.get("retry-after") ? Number.parseInt(raw.headers.get("retry-after"), 10) : void 0, raw);
+	const cls = STATUS_MAP.get(status);
+	if (cls) throw new cls(detail, raw);
+	throw new RineApiError(status, detail, raw);
+}
+//#endregion
+//#region src/onboard.ts
+/**
+* Standalone org registration — REQ-01, REQ-02, REQ-03.
+*
+* Module-level function (not a client method) because credentials don't
+* exist yet at registration time. Delegates to rine-core's
+* `performRegistration` for the PoW + credential persistence flow.
+*/
+/**
+* Register a new org on the Rine network.
+*
+* Solves the RSA time-lock proof-of-work, saves credentials to
+* `{configDir}/credentials.json`, and caches the initial OAuth token.
+*
+* @throws {ValidationError} If the slug fails client-side validation.
+* @throws {ConflictError} If the email or slug is already registered.
+* @throws {RateLimitError} On 429 from the server.
+* @throws {RineError} On PoW challenge expiry or other failures.
+*/
+async function register(opts) {
+	if (!validateSlug(opts.slug)) throw new ValidationError(`Invalid slug "${opts.slug}" — must be 2-32 lowercase alphanumeric chars or hyphens, no leading/trailing hyphen.`);
+	try {
+		const result = await performRegistration(opts.apiUrl, opts.configDir, "default", {
+			email: opts.email,
+			slug: opts.slug,
+			name: opts.name
+		}, opts.onProgress);
+		return {
+			orgId: result.org_id,
+			clientId: result.client_id
+		};
+	} catch (err) {
+		if (err instanceof Error) {
+			const msg = err.message;
+			if (msg.includes("already registered") || msg.includes("Conflict")) throw new ConflictError(msg);
+			if (msg.includes("Rate limited")) throw new RateLimitError(msg);
+			if (msg.includes("expired")) throw new RineError(msg);
+		}
+		throw err;
+	}
+}
+//#endregion
+//#region src/types.ts
+/**
+* Branded domain types + Zod schemas co-located.
+*
+* Branded types prevent mixing handles, UUIDs, and group IDs at compile time.
+* Zod schemas serve as single source of truth for both runtime parsing and
+* static type inference (via `z.infer<typeof schema>`).
+*
+* NOTE: All datetime fields use ISO-8601 strings (not Date objects) to match
+* the Python SDK's Pydantic datetime serialisation and the API wire format.
+*/
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const AGENT_HANDLE_RE = /^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9_.+-]+$/;
+const GROUP_HANDLE_RE = /^#[a-zA-Z0-9_-]+@[a-zA-Z0-9_.+-]+$/;
+function isAgentHandle(s) {
+	return AGENT_HANDLE_RE.test(s);
+}
+function isGroupHandle(s) {
+	return GROUP_HANDLE_RE.test(s);
+}
+function asAgentUuid(s) {
+	if (!UUID_RE.test(s)) throw new TypeError(`Invalid UUID: ${s}`);
+	return s;
+}
+function asGroupUuid(s) {
+	if (!UUID_RE.test(s)) throw new TypeError(`Invalid UUID: ${s}`);
+	return s;
+}
+function asMessageUuid(s) {
+	if (!UUID_RE.test(s)) throw new TypeError(`Invalid UUID: ${s}`);
+	return s;
+}
+function asOrgUuid(s) {
+	if (!UUID_RE.test(s)) throw new TypeError(`Invalid UUID: ${s}`);
+	return s;
+}
+function asWebhookUuid(s) {
+	if (!UUID_RE.test(s)) throw new TypeError(`Invalid UUID: ${s}`);
+	return s;
+}
+/**
+* Canonical rine message type strings. Derived from `PROTOCOL.md §458-474`
+* and the Python SDK constants (`rine-sdk/src/rine/_constants.py:48`).
+*
+* Use these rather than raw strings — IDE autocomplete + compile-time
+* validation + no typo-drift between consumers.
+*/
+const MessageType = {
+	Dm: "rine.v1.dm",
+	TaskRequest: "rine.v1.task_request",
+	TaskResponse: "rine.v1.task_response",
+	StatusUpdate: "rine.v1.status_update",
+	Negotiation: "rine.v1.negotiation",
+	Receipt: "rine.v1.receipt",
+	ErrorNotice: "rine.v1.error",
+	CapabilityQuery: "rine.v1.capability_query",
+	CapabilityResponse: "rine.v1.capability_response",
+	PaymentRequest: "rine.v1.payment_request",
+	PaymentConfirmation: "rine.v1.payment_confirmation",
+	ConsentRequest: "rine.v1.consent_request",
+	ConsentGrant: "rine.v1.consent_grant",
+	ConsentRevoke: "rine.v1.consent_revoke",
+	IdentityVerification: "rine.v1.identity_verification",
+	SenderKeyDistribution: "rine.v1.sender_key_distribution",
+	SenderKeyRequest: "rine.v1.sender_key_request",
+	GroupInvite: "rine.v1.group_invite",
+	Text: "rine.v1.text",
+	A2AMessage: "a2a.v1.message"
+};
+const ConversationStatus = {
+	Submitted: "submitted",
+	Open: "open",
+	Paused: "paused",
+	InputRequired: "input_required",
+	Completed: "completed",
+	Rejected: "rejected",
+	Canceled: "canceled",
+	Failed: "failed"
+};
+const JoinRequestStatus = {
+	Pending: "pending",
+	Approved: "approved",
+	Denied: "denied",
+	Expired: "expired"
+};
+const VoteChoice = {
+	Approve: "approve",
+	Deny: "deny"
+};
+const WebhookJobStatus = {
+	Pending: "pending",
+	Processing: "processing",
+	Delivered: "delivered",
+	Failed: "failed",
+	Dead: "dead"
+};
+const EncryptionVersion = {
+	HpkeV1: "hpke-v1",
+	SenderKeyV1: "sender-key-v1"
+};
+const MESSAGE_TYPE_RE = /^[a-z0-9][a-z0-9_-]*(\.[a-z0-9][a-z0-9_-]*){2,}$/;
+/** Validate a custom message type against the server-side regex. */
+function isValidMessageType(s) {
+	return MESSAGE_TYPE_RE.test(s);
+}
+/**
+* Message types the E2EE layer consumes internally and that must NEVER
+* surface to user code. Enforced by `client.messages()` and `defineAgent`
+* via the `includeReserved` debug escape hatch (SPEC D6d).
+*/
+const RESERVED_MESSAGE_TYPES = new Set([MessageType.SenderKeyDistribution]);
+const OrgReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	name: z$1.string(),
+	slug: z$1.string().nullable().optional(),
+	contact_email: z$1.string().nullable().optional(),
+	country_code: z$1.string().nullable().optional(),
+	trust_tier: z$1.number().int().default(0),
+	agent_count: z$1.number().int().default(0),
+	created_at: z$1.string().datetime()
+});
+const AgentReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	name: z$1.string(),
+	handle: z$1.string(),
+	human_oversight: z$1.boolean().default(true),
+	incoming_policy: z$1.string().default("accept_all"),
+	outgoing_policy: z$1.string().default("send_all"),
+	created_at: z$1.string().datetime(),
+	revoked_at: z$1.string().datetime().nullable().optional(),
+	unlisted: z$1.boolean().optional(),
+	verification_words: z$1.string().nullable().optional(),
+	warnings: z$1.array(z$1.string()).nullish(),
+	poll_url: z$1.string().nullable().optional()
+});
+const WhoAmISchema = z$1.object({
+	org: OrgReadSchema,
+	agents: z$1.array(AgentReadSchema),
+	trust_tier: z$1.number().int().default(0)
+});
+const MessageReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	conversation_id: z$1.string().uuid(),
+	from_agent_id: z$1.string().uuid().nullable().optional(),
+	to_agent_id: z$1.string().uuid().nullable().optional(),
+	sender_handle: z$1.string().nullable().optional(),
+	recipient_handle: z$1.string().nullable().optional(),
+	type: z$1.string(),
+	encrypted_payload: z$1.string(),
+	encryption_version: z$1.string(),
+	sender_signing_kid: z$1.string().nullable().optional(),
+	content_type: z$1.string().nullable().optional(),
+	metadata: z$1.record(z$1.unknown()).default({}),
+	created_at: z$1.string().datetime(),
+	delivered_at: z$1.string().datetime().nullable().optional(),
+	read_at: z$1.string().datetime().nullable().optional(),
+	group_id: z$1.string().uuid().nullable().optional(),
+	group_handle: z$1.string().nullable().optional()
+});
+const DecryptedMessageSchema = MessageReadSchema.extend({
+	plaintext: z$1.unknown().nullable().optional(),
+	verified: z$1.boolean().default(false),
+	verification_status: z$1.enum([
+		"verified",
+		"invalid",
+		"unverifiable"
+	]).default("unverifiable"),
+	decrypt_error: z$1.string().nullable().optional()
+});
+/**
+* Wire-format Zod schema for `{ sent, reply }` — retained for symmetry with
+* the other `*Schema` exports even though the resource layer no longer calls
+* `parse(SendAndWaitResultSchema, …)` directly (Step 19 replaced that with
+* an explicit object literal so the generic `Rep` narrowing could flow
+* through). The hand-rolled `SendAndWaitResult<Rep>` below is the type
+* `client.sendAndWait<Req, Rep>()` returns; the two are structurally
+* equivalent at `Rep = unknown` but the Zod inference does not carry
+* the generic, so consumers that want typed plaintext should rely on
+* the function return type, not `z.infer<typeof SendAndWaitResultSchema>`.
+*/
+const SendAndWaitResultSchema = z$1.object({
+	sent: MessageReadSchema,
+	reply: DecryptedMessageSchema.nullable()
+});
+const GroupReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	name: z$1.string(),
+	handle: z$1.string(),
+	description: z$1.string().nullable().optional(),
+	enrollment_policy: z$1.string().default("closed"),
+	visibility: z$1.string().default("private"),
+	isolated: z$1.boolean().default(false),
+	vote_duration_hours: z$1.number().int().default(72),
+	member_count: z$1.number().int().default(0),
+	created_at: z$1.string().datetime()
+});
+const GroupMemberSchema = z$1.object({
+	id: z$1.string().uuid().nullable().optional(),
+	group_id: z$1.string().uuid(),
+	agent_id: z$1.string().uuid(),
+	role: z$1.string().default("member"),
+	joined_at: z$1.string().datetime(),
+	agent_handle: z$1.string().nullable().optional()
+});
+const JoinRequestReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	group_id: z$1.string().uuid(),
+	agent_id: z$1.string().uuid(),
+	invited_by: z$1.string().uuid().nullable().optional(),
+	message: z$1.string().nullable().optional(),
+	status: z$1.string(),
+	expires_at: z$1.string().datetime().nullable().optional(),
+	created_at: z$1.string().datetime(),
+	resolved_at: z$1.string().datetime().nullable().optional(),
+	your_vote: z$1.string().nullable().optional()
+});
+const JoinedResultSchema = z$1.object({
+	status: z$1.literal("joined"),
+	member: GroupMemberSchema
+});
+const PendingJoinResultSchema = z$1.object({
+	status: z$1.literal("pending"),
+	request: JoinRequestReadSchema
+});
+const JoinResultSchema = z$1.discriminatedUnion("status", [JoinedResultSchema, PendingJoinResultSchema]);
+const InviteResultSchema = z$1.object({
+	status: z$1.string(),
+	request_id: z$1.string().uuid().nullable().optional()
+});
+const GroupSummarySchema = z$1.object({
+	id: z$1.string().uuid(),
+	name: z$1.string(),
+	handle: z$1.string(),
+	description: z$1.string().nullable().optional(),
+	visibility: z$1.string().default("public"),
+	member_count: z$1.number().int().default(0)
+});
+const VoteResponseSchema = z$1.object({
+	request_id: z$1.string().uuid(),
+	your_vote: z$1.string(),
+	status: z$1.string()
+});
+const AgentSummarySchema = z$1.object({
+	id: z$1.string().uuid(),
+	name: z$1.string(),
+	handle: z$1.string(),
+	description: z$1.string().nullable().optional(),
+	category: z$1.string().nullable().optional(),
+	verified: z$1.boolean().default(false)
+});
+const AgentProfileSchema = z$1.object({
+	id: z$1.string().uuid(),
+	name: z$1.string(),
+	handle: z$1.string(),
+	description: z$1.string().nullable().optional(),
+	category: z$1.string().nullable().optional(),
+	verified: z$1.boolean().default(false),
+	human_oversight: z$1.boolean().default(true),
+	created_at: z$1.string().datetime().nullable().optional()
+});
+const AgentCardSchema = z$1.object({
+	id: z$1.string().uuid(),
+	agent_id: z$1.string().uuid(),
+	name: z$1.string(),
+	description: z$1.string().nullable().optional(),
+	version: z$1.string().nullable().optional(),
+	is_public: z$1.boolean().default(false),
+	skills: z$1.array(z$1.record(z$1.unknown())).optional().default([]),
+	rine: z$1.record(z$1.unknown()).optional().default({}),
+	created_at: z$1.string().datetime(),
+	updated_at: z$1.string().datetime().nullable().optional()
+});
+const WebhookReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	agent_id: z$1.string().uuid(),
+	url: z$1.string(),
+	active: z$1.boolean().default(true),
+	created_at: z$1.string().datetime()
+});
+const WebhookCreatedSchema = WebhookReadSchema.extend({ secret: z$1.string() });
+const WebhookDeliveryReadSchema = z$1.object({
+	id: z$1.string().uuid(),
+	webhook_id: z$1.string().uuid(),
+	message_id: z$1.string().uuid(),
+	status: z$1.string(),
+	attempts: z$1.number().int().default(0),
+	max_attempts: z$1.number().int().default(5),
+	last_error: z$1.string().nullable().optional(),
+	created_at: z$1.string().datetime(),
+	delivered_at: z$1.string().datetime().nullable().optional(),
+	next_attempt_at: z$1.string().datetime().nullable().optional()
+});
+const WebhookJobSummarySchema = z$1.object({
+	total: z$1.number().int().default(0),
+	delivered: z$1.number().int().default(0),
+	failed: z$1.number().int().default(0),
+	dead: z$1.number().int().default(0),
+	pending: z$1.number().int().default(0),
+	processing: z$1.number().int().default(0)
+});
+const QuotaEntrySchema = z$1.object({
+	limit: z$1.number().int().nullable(),
+	used: z$1.number().int().nullable().optional()
+});
+const OrgQuotasSchema = z$1.object({
+	tier: z$1.number().int(),
+	quotas: z$1.record(QuotaEntrySchema)
+});
+const PollTokenResponseSchema = z$1.object({ poll_url: z$1.string() });
+const RineEventSchema = z$1.object({
+	type: z$1.enum([
+		"message",
+		"heartbeat",
+		"status",
+		"disconnect"
+	]),
+	data: z$1.string(),
+	id: z$1.string().nullable().optional()
+});
+const ErasureResultSchema = z$1.object({
+	org_id: z$1.string().uuid(),
+	erased_at: z$1.string().datetime(),
+	messages_deleted: z$1.number().int(),
+	agents_deleted: z$1.number().int(),
+	conversations_deleted: z$1.number().int(),
+	groups_deleted: z$1.number().int().default(0)
+});
+const PaginatedResponseSchema = (itemSchema) => z$1.object({
+	items: z$1.array(itemSchema),
+	total_estimate: z$1.number().int().nullish(),
+	total: z$1.number().int().nullish(),
+	next_cursor: z$1.string().nullable().optional(),
+	prev_cursor: z$1.string().nullable().optional()
+});
+/**
+* CursorPage raw response schema — used by adapters.parsePaginated().
+* This is NOT a generic schema; it accepts a Zod schema for the item type
+* and returns the full paginated response schema.
+*/
+function cursorPageSchema(itemSchema) {
+	return PaginatedResponseSchema(itemSchema);
+}
+//#endregion
+//#region src/utils/cursor-page.ts
+/**
+* CursorPage<T> — async iterable + hasNext/hasPrev.
+*
+* Mirrors the Python SDK's CursorPage[T] pattern. The caller-passing
+* `autoPaginate(fetchPage)` method was deleted per SPEC §13.3 — use the
+* dedicated `client.inboxAll()` / `client.discoverAll()` / `client.discoverGroupsAll()`
+* async generators instead, which own their fetch loop.
+*/
+/**
+* Cursor-paginated response.
+*
+* @typeParam T - Item type (DecryptedMessage, AgentSummary, etc.)
+*/
+var CursorPage = class {
+	constructor(items, total, nextCursor, prevCursor) {
+		this.items = items;
+		this.total = total;
+		this.nextCursor = nextCursor;
+		this.prevCursor = prevCursor;
+	}
+	get hasNext() {
+		return this.nextCursor != null;
+	}
+	get hasPrev() {
+		return this.prevCursor != null;
+	}
+	async *[Symbol.asyncIterator]() {
+		yield* this.items;
+	}
+};
+//#endregion
+//#region src/api/adapters.ts
+/**
+* Parse a raw API response through a Zod schema.
+* Throws ZodError with descriptive messages on validation failure.
+*/
+function parse(schema, data) {
+	return schema.parse(data);
+}
+/**
+* Parse a raw paginated API response into a CursorPage instance.
+*
+* The raw response shape: { items: T[], total, next_cursor?, prev_cursor? }
+* We validate each item through the provided schema, then construct a CursorPage.
+*
+* @param itemSchema - Zod schema for each item in the items array.
+* @param raw        - Raw API response (unknown).
+*
+* @example
+* ```ts
+* const raw = await http.get<unknown>('/directory/agents', { params: { q: 'bot' } });
+* return parseCursorPage(AgentSummarySchema, raw);
+* ```
+*/
+function parseCursorPage(itemSchema, raw) {
+	const parsed = cursorPageSchema(itemSchema).parse(raw);
+	return new CursorPage(parsed.items, parsed.total_estimate ?? parsed.total ?? parsed.items.length, parsed.next_cursor ?? null, parsed.prev_cursor ?? null);
+}
+//#endregion
+//#region src/utils/abort.ts
+/**
+* AbortSignal helpers for composable cancellation.
+*
+* Provides:
+* - `timeoutSignal(ms)` — `{ signal, clear }` pair that aborts after ms ms
+*   with an `RineTimeoutError` reason. Callers MUST call `clear()` in a
+*   `finally` block so the timer is cancelled on early completion
+*   (audit MINOR-4, SPEC_v2 §14.3).
+* - `anySignal(...signals)` — signal that aborts when ANY of the inputs abort
+*/
+/**
+* Create a signal that fires after `ms` milliseconds.
+*
+* Returns a `{ signal, clear }` pair. Callers MUST invoke `clear()` in a
+* `finally` block (or equivalent) to cancel the timer on early completion —
+* otherwise the timer will still fire, aborting an already-settled signal
+* and leaking a timer handle per call. `clear()` is idempotent.
+*
+* When the timer fires, the signal is aborted with an `RineTimeoutError`
+* reason so `catch` sites can distinguish an SDK timeout from a user-cancel
+* via `err instanceof RineTimeoutError` (SPEC_v2 §14.4).
+*/
+function timeoutSignal(ms) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new RineTimeoutError(`timeout after ${ms}ms`)), ms);
+	return {
+		signal: controller.signal,
+		clear: () => clearTimeout(timer)
+	};
+}
+/**
+* Combine multiple signals into one that aborts when ANY input aborts.
+*
+* The composed signal's `reason` is the reason from whichever input fired
+* first — this preserves the `RineTimeoutError` reason attached by
+* `timeoutSignal()` (and matching per-op timers in resources), so downstream
+* `signal.reason instanceof RineTimeoutError` checks classify timeouts
+* correctly instead of seeing a generic `AbortError` (SPEC_v2 §14.4).
+*
+* Listeners are detached from the remaining inputs as soon as the combined
+* signal fires — this prevents retaining long-lived source signals (e.g. a
+* global client signal) through short-lived request signals.
+*/
+function anySignal(...signals) {
+	const controller = new AbortController();
+	const cleanup = [];
+	const abort = (reason) => {
+		controller.abort(reason);
+		for (const off of cleanup) off();
+		cleanup.length = 0;
+	};
+	for (const signal of signals) {
+		if (signal.aborted) {
+			abort(signal.reason);
+			return controller.signal;
+		}
+		const onAbort = () => abort(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		cleanup.push(() => signal.removeEventListener("abort", onAbort));
+	}
+	return controller.signal;
+}
+//#endregion
+//#region src/utils/sleep.ts
+/**
+* Shared sleep utility — avoids triplication across client.ts, polling.ts, streams.ts.
+*/
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Like `sleep()` but aborts early when the given signal fires. Used in
+* polling/streaming loops so cancellation during backoff doesn't wait
+* the full interval.
+*/
+function sleepWithSignal(ms, signal) {
+	if (!signal) return sleep(ms);
+	if (ms <= 0 || signal.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/api/middleware.ts
+/**
+* Fold a middleware array into a single bound pipeline.
+*
+* Composed once at `SDKHttpClient` construction. The first element of
+* `middleware` is the outermost layer (called first); the last element is
+* adjacent to `core`. Order corresponds to the reader's mental model: a
+* `loggingMiddleware` placed first wraps everything below it.
+*
+* ```
+* user's middleware[0]  ← outermost, called first
+*   └── user's middleware[1]
+*       └── user's middleware[2]
+*           └── core request
+* ```
+*/
+function composeMiddleware(middleware, core) {
+	return middleware.reduceRight((next, mw) => (ctx) => mw(ctx, () => next(ctx)), core);
+}
+const DEFAULT_REDACT = ["authorization", "cookie"];
+/**
+* Logs one line per request start + one line per response (with duration).
+* On error (middleware throw or downstream rejection) logs a `✗` line and
+* re-throws — never swallows errors.
+*
+* Format:
+*   rine → {method} {url} op={operation}
+*   rine ← {status} {method} {url} ({durationMs}ms)
+*   rine ✗ {method} {url} {err.name}: {err.message}
+*/
+function loggingMiddleware(opts = {}) {
+	const logger = opts.logger ?? console;
+	const redactSet = new Set((opts.redact ?? DEFAULT_REDACT).map((h) => h.toLowerCase()));
+	redactSet.add("authorization");
+	return async (ctx, next) => {
+		const started = Date.now();
+		const redactedHeaders = snapshotHeaders(ctx.headers, redactSet);
+		logger.log(`rine → ${ctx.method} ${ctx.url} op=${ctx.operation}`, { headers: redactedHeaders });
+		try {
+			const res = await next();
+			const durationMs = Date.now() - started;
+			logger.log(`rine ← ${res.status} ${ctx.method} ${ctx.url} (${durationMs}ms)`);
+			return res;
+		} catch (err) {
+			const name = err instanceof Error ? err.name : "Error";
+			const message = err instanceof Error ? err.message : String(err);
+			logger.log(`rine ✗ ${ctx.method} ${ctx.url} ${name}: ${message}`);
+			throw err;
+		}
+	};
+}
+/**
+* Snapshot a `Headers` object into a plain record with redaction applied.
+* Produces a stable, logger-friendly object (Headers itself doesn't pretty-
+* print inside structured loggers).
+*/
+function snapshotHeaders(headers, redactSet) {
+	const out = {};
+	headers.forEach((value, key) => {
+		out[key] = redactSet.has(key.toLowerCase()) ? "[REDACTED]" : value;
+	});
+	return out;
+}
+//#endregion
+//#region src/api/http.ts
+/**
+* Internal HTTP layer for the SDK.
+*
+* Wraps rine-core's HttpClient to add:
+* - Native AbortSignal support (via a thin fetch wrapper)
+* - Per-request timeout via AbortSignal.timeout()
+* - Typed error mapping via raiseForStatus()
+* - Agent header injection
+* - User middleware pipeline (SPEC §9.2–§9.6)
+*
+* Middleware wraps `.get/.post/.put/.patch/.delete` only. It does NOT wrap
+* `openStream()` (SSE lifecycle) or `getCoreHttpClient()` (crypto-path —
+* those calls go through a separate rine-core HttpClient per §6.5).
+*/
+var SDKHttpClient = class {
+	_configDir;
+	apiUrl;
+	agentHeader;
+	_timeout;
+	maxRetries;
+	/**
+	* The user middleware chain, preserved so derived clients
+	* (`client.withSignal`, `withTimeout`, `withAgent`) can forward it. The
+	* compiled pipeline lives in `this.pipeline`.
+	*/
+	middleware;
+	/** Composed middleware pipeline — SPEC §9.3. Bound once at construction. */
+	pipeline;
+	get configDir() {
+		return this._configDir;
+	}
+	get timeout() {
+		return this._timeout;
+	}
+	constructor(opts = {}) {
+		this._configDir = opts.configDir ?? "";
+		this.apiUrl = opts.apiUrl ?? "https://api.rine.network";
+		this.agentHeader = opts.agent ? { "X-Rine-Agent": opts.agent } : void 0;
+		this._timeout = opts.timeout ?? 3e4;
+		this.maxRetries = opts.maxRetries ?? 2;
+		this.middleware = opts.middleware ?? [];
+		const coreRequest = this.createCoreRequest();
+		this.pipeline = composeMiddleware(this.middleware, coreRequest);
+	}
+	/**
+	* GET /path with typed response.
+	*/
+	async get(path, opts = {}) {
+		return this.request("GET", path, opts);
+	}
+	/**
+	* POST /path with optional body.
+	*/
+	async post(path, body, opts = {}) {
+		return this.request("POST", path, {
+			...opts,
+			body
+		});
+	}
+	/**
+	* POST /path returning both HTTP status code and parsed body.
+	* Used when the caller must branch on status (e.g. 200 vs 202).
+	*/
+	async postWithStatus(path, body, opts = {}) {
+		return this.requestWithStatus("POST", path, {
+			...opts,
+			body
+		});
+	}
+	/**
+	* PUT /path with optional body.
+	*/
+	async put(path, body, opts = {}) {
+		return this.request("PUT", path, {
+			...opts,
+			body
+		});
+	}
+	/**
+	* PATCH /path with optional body.
+	*/
+	async patch(path, body, opts = {}) {
+		return this.request("PATCH", path, {
+			...opts,
+			body
+		});
+	}
+	/**
+	* DELETE /path.
+	*/
+	async delete(path, opts = {}) {
+		return this.request("DELETE", path, opts);
+	}
+	/**
+	* Open a long-lived streaming GET with auth applied. Used by the SSE
+	* resource — returns the raw Response so the caller can consume the body.
+	*
+	* No per-request timeout is applied: streams are long-lived by design, so
+	* lifetime is controlled exclusively by the caller's AbortSignal.
+	*
+	* **Middleware scope**: `openStream` does NOT run the user middleware
+	* pipeline. SSE lifecycle (long-lived, Last-Event-ID resume, reconnect)
+	* is incompatible with the one-shot request/response middleware shape.
+	* See SPEC §9.6 / §12.3.4 for the scope boundary and the `fetchWithAuth`
+	* auth-injection path.
+	*
+	* @param opts.signal - REQUIRED. A long-lived stream without a cancel
+	*   signal leaks a connection forever, so the type enforces it. Fire-and-
+	*   forget callers can pass `new AbortController().signal` explicitly
+	*   (see `neverAbortingSignal()` in `streams.ts` for the documented
+	*   escape hatch).
+	*/
+	async openStream(path, opts) {
+		const url = buildUrl(this.apiUrl, path);
+		const headers = {
+			Accept: "text/event-stream",
+			...this.agentHeader ?? {},
+			...opts.headers ?? {}
+		};
+		return this.fetchWithAuth("GET", url, headers, void 0, opts.signal, false);
+	}
+	/**
+	* Returns a rine-core HttpClient bound to the same credentials, base URL,
+	* and agent header as this SDKHttpClient, scoped to the given signal.
+	*
+	* Short-lived by contract — construct one per crypto operation, do not
+	* cache. Cost is one object allocation (no network, no token fetch, no
+	* file I/O at construction). The tokenFn closure reads the same config
+	* dir and token cache as the SDK's REST path, so a refresh on either
+	* side is visible to the other.
+	*
+	* Middleware scope: calls made through the returned client do NOT run
+	* the SDK middleware pipeline (see SPEC §6.5).
+	*/
+	getCoreHttpClient(opts = {}) {
+		const entry = loadCredentials(this._configDir).default;
+		return new HttpClient({
+			apiUrl: this.apiUrl,
+			tokenFn: (force) => getOrRefreshToken(this._configDir, this.apiUrl, entry, "default", { force }),
+			defaultHeaders: this.agentHeader,
+			canRefresh: true,
+			signal: opts.signal
+		});
+	}
+	async request(method, path, opts = {}) {
+		const res = await this.executeRequest(method, path, opts);
+		if (res.status === 204 || res.headers.get("content-length") === "0") return;
+		return await res.json();
+	}
+	/**
+	* Like `request()` but also returns the HTTP status code. Used when
+	* the caller must branch on status (e.g. 200 vs 202 for group join).
+	*/
+	async requestWithStatus(method, path, opts = {}) {
+		const res = await this.executeRequest(method, path, opts);
+		if (res.status === 204 || res.headers.get("content-length") === "0") return {
+			status: res.status,
+			body: void 0
+		};
+		return {
+			status: res.status,
+			body: await res.json()
+		};
+	}
+	/**
+	* Shared request execution: builds context, runs middleware pipeline,
+	* handles errors and timeouts, returns the validated Response.
+	*/
+	async executeRequest(method, path, opts = {}) {
+		const { params, extraHeaders, signal, body, operation } = opts;
+		const url = buildUrl(this.apiUrl, path, params);
+		const headers = buildHeaders(this.agentHeader, extraHeaders, body);
+		const ac = new AbortController();
+		const timeoutId = setTimeout(() => ac.abort(), this.timeout);
+		const fetchSignal = signal ? anySignal(signal, ac.signal) : ac.signal;
+		if (operation === void 0) throw new Error(`SDKHttpClient.${method.toLowerCase()}(${path}) was called without opts.operation — every resource method must set a RineOperation label.`);
+		const ctx = {
+			method,
+			url,
+			headers: new Headers(headers),
+			body,
+			signal: fetchSignal,
+			operation,
+			transport: "rest"
+		};
+		callMeta.set(ctx, { unauthenticated: opts.unauthenticated === true });
+		try {
+			const res = await this.pipeline(ctx);
+			clearTimeout(timeoutId);
+			if (!res.ok) {
+				const detail = await parseErrorDetail(res);
+				raiseForStatus(res.status, detail, res);
+			}
+			return res;
+		} catch (err) {
+			clearTimeout(timeoutId);
+			if (err instanceof Error && err.name === "AbortError") {
+				if (signal?.aborted) {
+					if (signal.reason instanceof RineTimeoutError) throw signal.reason;
+					throw err;
+				}
+				throw new RineTimeoutError(`Request to ${method} ${path} timed out after ${this.timeout}ms`);
+			}
+			throw err;
+		}
+	}
+	/**
+	* Build the innermost "core" transport function handed to
+	* `composeMiddleware`. It reads from `ctx` *after* middleware has run
+	* so header mutations (auth, tracing, redact) take effect on the wire.
+	*
+	* Core handles auth injection + 401 refresh — these are transport
+	* concerns (Dec-3.1), so middleware sees one logical call, not per-retry
+	* attempts.
+	*/
+	createCoreRequest() {
+		return async (ctx) => {
+			const unauthenticated = callMeta.get(ctx)?.unauthenticated === true;
+			const headers = headersToRecord(ctx.headers);
+			const serializedBody = serializeBody(ctx.body);
+			return this.fetchWithAuth(ctx.method, ctx.url, headers, serializedBody, ctx.signal, unauthenticated);
+		};
+	}
+	async fetchWithAuth(method, url, headers, body, fetchSignal, unauthenticated) {
+		const doFetch = async () => {
+			if (unauthenticated) return fetch(url, {
+				method,
+				headers,
+				body,
+				signal: fetchSignal
+			});
+			const creds = loadCredentials(this._configDir).default;
+			headers.Authorization = `Bearer ${await getOrRefreshToken(this._configDir, this.apiUrl, creds, "default")}`;
+			const res = await fetch(url, {
+				method,
+				headers,
+				body,
+				signal: fetchSignal
+			});
+			if (res.status === 401) {
+				headers.Authorization = `Bearer ${await getOrRefreshToken(this._configDir, this.apiUrl, creds, "default", { force: true })}`;
+				return fetch(url, {
+					method,
+					headers,
+					body,
+					signal: fetchSignal
+				});
+			}
+			return res;
+		};
+		let attempt = 0;
+		while (true) {
+			const res = await doFetch();
+			if (res.status !== 429 || attempt >= this.maxRetries) return res;
+			attempt += 1;
+			const delayMs = parseRetryAfter(res.headers.get("Retry-After"), attempt);
+			if (fetchSignal.aborted) return res;
+			await sleepWithSignal(delayMs, fetchSignal);
+		}
+	}
+};
+const callMeta = /* @__PURE__ */ new WeakMap();
+function buildUrl(baseUrl, path, params) {
+	let url = path.startsWith("http://") || path.startsWith("https://") ? path : baseUrl + path;
+	if (params) {
+		const qs = new URLSearchParams(Object.entries(params).filter(([, v]) => v !== void 0).map(([k, v]) => [k, String(v)])).toString();
+		if (qs) url += `?${qs}`;
+	}
+	return url;
+}
+function buildHeaders(agentHeader, extraHeaders, body) {
+	const headers = {
+		...agentHeader ?? {},
+		...extraHeaders ?? {}
+	};
+	if (body !== void 0) headers["Content-Type"] = "application/json";
+	return headers;
+}
+function headersToRecord(headers) {
+	const out = {};
+	headers.forEach((value, key) => {
+		out[key] = value;
+	});
+	return out;
+}
+function serializeBody(body) {
+	if (body === void 0) return void 0;
+	return JSON.stringify(body);
+}
+async function parseErrorDetail(res) {
+	try {
+		const body = await res.json();
+		if (typeof body.detail === "string") return body.detail;
+		if (Array.isArray(body.detail)) return body.detail.map((e) => typeof e === "string" ? e : e.msg).join("; ");
+	} catch {}
+	return res.statusText;
+}
+/**
+* Parse the `Retry-After` response header and pick a delay, capped at 30s
+* (SPEC §9.4). Supports both numeric "seconds" and RFC 7231 HTTP-date forms;
+* falls back to exponential backoff (1s, 2s, 4s, ...) keyed on the attempt
+* counter when the server omits or emits an unparseable value.
+*/
+function parseRetryAfter(header, attempt) {
+	const MAX_DELAY_MS = 3e4;
+	const fallback = Math.min(MAX_DELAY_MS, 2 ** (attempt - 1) * 1e3);
+	if (!header) return fallback;
+	const asNumber = Number(header);
+	if (Number.isFinite(asNumber) && asNumber >= 0) return Math.min(MAX_DELAY_MS, asNumber * 1e3);
+	const asDate = Date.parse(header);
+	if (!Number.isNaN(asDate)) return Math.max(0, Math.min(MAX_DELAY_MS, asDate - Date.now()));
+	return fallback;
+}
+//#endregion
+//#region src/utils/schema.ts
+/**
+* Validate an arbitrary value against a Standard Schema v1 and return the
+* typed output. The validator may return a synchronous result or a promise,
+* so this helper always awaits. On failure, the first issue's message is
+* used as the `ValidationError` detail — detail enough to point at the
+* field without dumping the full issue list into the error message.
+*/
+async function parsePlaintext(value, schema) {
+	const result = await schema["~standard"].validate(value);
+	if (result.issues !== void 0) {
+		const first = result.issues[0];
+		throw new SchemaValidationError(`Plaintext failed schema validation${first?.path && first.path.length > 0 ? ` at ${formatPath(first.path)}` : ""}: ${first?.message ?? "(no message)"}`);
+	}
+	return result.value;
+}
+/**
+* JSON-parse a `DecryptedMessage.plaintext` string and validate it via a
+* Standard Schema v1, returning a typed `DecryptedMessage<T>`. Leaves
+* messages with `plaintext == null` untouched (decrypt-failed envelopes
+* still surface to the caller so they can branch on `decrypt_error`).
+*
+* The JSON-parse step is mandatory: Standard Schemas like Zod's `z.object`
+* validate structured input, not raw strings. If a caller's payload is
+* already a plain string, they can use `z.string()` as the schema and the
+* JSON-parse round-trip is still well-defined (`JSON.parse('"hi"') === "hi"`).
+*/
+async function parseMessagePlaintext(msg, schema) {
+	if (msg.plaintext == null) return msg;
+	let candidate;
+	try {
+		candidate = typeof msg.plaintext === "string" ? JSON.parse(msg.plaintext) : msg.plaintext;
+	} catch (err) {
+		throw new SchemaValidationError(`Plaintext is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const value = await parsePlaintext(candidate, schema);
+	return {
+		...msg,
+		plaintext: value
+	};
+}
+/**
+* Validate an outbound payload against a Standard Schema v1 before it is
+* handed to the encryption layer. SPEC §11.4: outbound schemas run *before*
+* encrypt so a shape failure rejects without sending any ciphertext.
+*
+* This helper returns the validated (possibly transformed — schemas may
+* parse / coerce) value so the caller can encrypt the narrowed form rather
+* than the raw input. For schemas that are pure type guards (no transforms)
+* the returned value is reference-equal to the input.
+*/
+async function validateOutbound(payload, schema) {
+	return parsePlaintext(payload, schema);
+}
+function formatPath(path) {
+	return path.map((seg) => {
+		const key = typeof seg === "object" && seg !== null ? seg.key : seg;
+		return typeof key === "number" ? `[${key}]` : String(key);
+	}).join(".");
+}
+//#endregion
+//#region src/resources/conversation.ts
+function looksLikeRecipient(value) {
+	if (typeof value !== "string") return false;
+	return UUID_RE.test(value) || isAgentHandle(value) || isGroupHandle(value);
+}
+var ConversationScope = class {
+	/**
+	* Peer auto-wired when the scope was built via `client.conversation(msg)`.
+	* When set, the two-arg `scope.send(payload)` form routes to this peer
+	* without requiring an explicit recipient. Null when the scope was
+	* built from a bare conversation id.
+	*/
+	peer;
+	/**
+	* Anchor message id — set when the scope was built via
+	* `client.conversation(msg)`. When present, `scope.send()` routes
+	* through `client.reply(anchorMessageId, …)` so the server threads
+	* the new message into the existing conversation. Null when the
+	* scope was built from a bare conversation id string.
+	*/
+	anchorMessageId;
+	constructor(client, id, peer = null, anchorMessageId = null) {
+		this.client = client;
+		this.id = id;
+		this.peer = peer;
+		this.anchorMessageId = anchorMessageId;
+	}
+	send(a, b, c) {
+		let payload;
+		let opts;
+		if (looksLikeRecipient(a)) {
+			const to = a;
+			payload = b;
+			opts = c ?? {};
+			if (this.anchorMessageId != null) {
+				if (this.peer != null && to !== this.peer) return Promise.reject(/* @__PURE__ */ new Error(`ConversationScope.send(): explicit recipient "${to}" does not match scope peer "${this.peer}". The reply endpoint auto-routes to the original peer; use client.send() directly for cross-conversation sends.`));
+				return this.client.reply(this.anchorMessageId, payload, opts);
+			}
+			return Promise.reject(/* @__PURE__ */ new Error("ConversationScope was built from a bare conversation id and cannot thread sends. Use client.conversation(message) to pin a message anchor, or call client.send() / client.reply() directly."));
+		}
+		payload = a;
+		opts = b ?? {};
+		if (this.anchorMessageId == null || this.peer == null) return Promise.reject(/* @__PURE__ */ new Error("ConversationScope was built from a bare conversation id and cannot thread sends. Use client.conversation(message) to pin a message anchor, or call client.send() / client.reply() directly."));
+		return this.client.reply(this.anchorMessageId, payload, opts);
+	}
+	reply(messageId, payload, opts = {}) {
+		return this.client.reply(messageId, payload, opts);
+	}
+	messages(opts = {}) {
+		return this.messagesGenerator(opts);
+	}
+	history(opts = {}) {
+		return this.historyGenerator(opts);
+	}
+	async *messagesGenerator(opts) {
+		const streamOpts = {};
+		if (opts.type !== void 0) streamOpts.type = opts.type;
+		if (opts.signal !== void 0) streamOpts.signal = opts.signal;
+		if (opts.agent !== void 0) streamOpts.agent = opts.agent;
+		if (opts.lastEventId !== void 0) streamOpts.lastEventId = opts.lastEventId;
+		if (opts.schema !== void 0) streamOpts.schema = opts.schema;
+		for await (const msg of this.client.messages(streamOpts)) if (msg.conversation_id === this.id) yield msg;
+	}
+	async *historyGenerator(opts) {
+		const limit = opts.limit ?? 50;
+		const maxItems = opts.maxItems;
+		const schema = opts.schema;
+		let cursor = opts.cursor;
+		let yielded = 0;
+		while (true) {
+			const inboxOpts = { limit };
+			if (cursor !== void 0) inboxOpts.cursor = cursor;
+			if (opts.agent !== void 0) inboxOpts.agent = opts.agent;
+			if (opts.signal !== void 0) inboxOpts.signal = opts.signal;
+			const page = await this.client.inbox(inboxOpts);
+			for (const msg of page.items) {
+				if (msg.conversation_id !== this.id) continue;
+				yield schema !== void 0 && msg.decrypt_error == null ? await parseMessagePlaintext(msg, schema) : msg;
+				yielded += 1;
+				if (maxItems !== void 0 && yielded >= maxItems) return;
+			}
+			if (!page.hasNext || page.nextCursor == null) return;
+			cursor = page.nextCursor;
+		}
+	}
+};
+//#endregion
+//#region src/resources/decrypt.ts
+/**
+* Shared decryption helper used by `messages.inbox()`, `messages.read()`,
+* `messages.sendAndWait()` (Phase 2), and `client.messages()` (§11.1).
+*
+* Dispatch is driven by `encryption_version`:
+*   - `hpke-v1`        → `decryptMessage` (1:1, recipient's X25519 private key).
+*   - `sender-key-v1`  → `decryptGroupMessage`. On a sender-key dispatch failure,
+*                        optionally retries once after calling
+*                        `fetchAndIngestPendingSKDistributions` (matches Python
+*                        SDK `read()` discipline).
+*   - anything else    → returned as-is with `decrypt_error` populated.
+*
+* Crypto failures (including the post-retry failure on the sender-key path)
+* populate `decrypt_error` and do NOT throw — callers branch on
+* `msg.decrypt_error !== null`. User cancellation (`AbortError`) is always
+* re-thrown so a cancelled `inbox()` rejects cleanly instead of resolving
+* with a page of "failed" items.
+*/
+async function decryptEnvelope(opts) {
+	const { core, configDir, agentId, msg, retrySenderKey = false } = opts;
+	const encryptedPayload = msg.encrypted_payload;
+	if (!encryptedPayload) return applyDecryptError(msg, "missing encrypted_payload");
+	try {
+		if (msg.encryption_version === "hpke-v1") return applyDecryptResult(msg, await decryptMessage(configDir, agentId, encryptedPayload, core));
+		if (msg.encryption_version === "sender-key-v1") {
+			if (!msg.group_id) return applyDecryptError(msg, "sender-key message missing group_id");
+			try {
+				return applyDecryptResult(msg, await decryptGroupMessage(configDir, agentId, msg.group_id, encryptedPayload, core));
+			} catch (firstErr) {
+				rethrowIfAbort(firstErr);
+				if (!retrySenderKey) return applyDecryptError(msg, errMessage(firstErr), classifyGroupError(firstErr));
+				try {
+					await fetchAndIngestPendingSKDistributions(core, configDir, agentId);
+					return applyDecryptResult(msg, await decryptGroupMessage(configDir, agentId, msg.group_id, encryptedPayload, core));
+				} catch (retryErr) {
+					rethrowIfAbort(retryErr);
+					return applyDecryptError(msg, errMessage(retryErr), classifyGroupError(retryErr));
+				}
+			}
+		}
+		return applyDecryptError(msg, `unknown encryption_version: ${msg.encryption_version}`);
+	} catch (err) {
+		rethrowIfAbort(err);
+		return applyDecryptError(msg, errMessage(err));
+	}
+}
+function applyDecryptResult(msg, result) {
+	return {
+		...msg,
+		metadata: msg.metadata ?? {},
+		plaintext: autoParsePlaintext(msg.content_type, result.plaintext),
+		verified: result.verified,
+		verification_status: result.verificationStatus,
+		decrypt_error: null
+	};
+}
+/**
+* If the payload was JSON (the default content-type), auto-parse the
+* decrypted string into a structured value before handing it to callers.
+*
+* Without this, first-time users see the raw serialized string and
+* mistake it for a double-encoding. Callers that pass a Standard Schema
+* still work: `parseMessagePlaintext` in `utils/schema.ts` accepts both
+* a string (parses it) and an already-parsed value (treats it as
+* structured input).
+*
+* Failure is silent on purpose — if the bytes claim to be JSON but are
+* malformed, the decrypt layer succeeded and we hand back the raw string
+* rather than synthesising a `decrypt_error`. Crypto observability and
+* content-format observability are different concerns (SPEC §10.2).
+*/
+function autoParsePlaintext(contentType, plaintext) {
+	if ((contentType ?? "application/json") !== "application/json") return plaintext;
+	if (typeof plaintext !== "string") return plaintext;
+	try {
+		return JSON.parse(plaintext);
+	} catch {
+		return plaintext;
+	}
+}
+function applyDecryptError(msg, error, status = "unverifiable") {
+	return {
+		...msg,
+		metadata: msg.metadata ?? {},
+		plaintext: void 0,
+		verified: false,
+		verification_status: status,
+		decrypt_error: error
+	};
+}
+/**
+* Map a sender-key decrypt failure to a `verification_status`.
+*
+* `decryptGroupMessage` throws `"Sender signature verification failed"` when
+* the inner-envelope Ed25519 signature doesn't match the sender's published
+* signing key (see `rine-core/src/crypto/message.ts`). That is the `invalid`
+* case — the recipient successfully derived the message key but cannot trust
+* the author. Every other failure (ratchet state missing, AEAD failure,
+* truncated ciphertext, malformed envelope, etc.) is `unverifiable` because
+* the recipient couldn't even get as far as a signature check.
+*
+* Without this classification every group failure collapses to
+* `unverifiable` and callers lose the ability to distinguish "bad sender"
+* from "missing key material" — the same gap the adherence audit for
+* Step 22 flagged as a blocker.
+*/
+function classifyGroupError(err) {
+	if (errMessage(err).toLowerCase().includes("signature verification failed")) return "invalid";
+	return "unverifiable";
+}
+/**
+* Re-throw if the error is an `AbortError` from an aborted signal. Decrypt
+* failures populate `decrypt_error` per §10.2, but user cancellation (via
+* `opts.signal` or the op timer) must bubble out as an AbortError rather
+* than being silently converted to a `decrypt_error` string on an
+* otherwise "successful" page.
+*/
+function rethrowIfAbort(err) {
+	if (err instanceof Error && err.name === "AbortError") throw err;
+}
+function errMessage(err) {
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+//#endregion
+//#region src/resources/discovery.ts
+/**
+* Discovery resource — discover, inspect, discoverGroups.
+*/
+var DiscoveryResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	async discover(filters) {
+		return parseCursorPage(AgentSummarySchema, await this.http.get("/directory/agents", {
+			params: {
+				q: filters?.q,
+				category: filters?.category,
+				language: filters?.language,
+				verified: filters?.verified,
+				limit: filters?.limit,
+				cursor: filters?.cursor
+			},
+			operation: "discover"
+		}));
+	}
+	/**
+	* Fetch a directory agent profile and unwrap the A2A card envelope
+	*
+	*
+	* Accepts either a UUID (pass-through) or an agent handle
+	* (`name@org.rine.network`, resolved via WebFinger by
+	* `resolveToUuid`). The directory route only accepts UUIDs, so the
+	* handle lookup has to happen client-side.
+	*
+	* Server response shape:
+	* ```
+	* {
+	*   card: { name, description, rine: { agent_id, handle, category, verified, human_oversight } },
+	*   directory_metadata: { registered_at, ... }
+	* }
+	* ```
+	*
+	* Legacy flat shape is still accepted (the fallback `parse()` branch).
+	*/
+	async inspect(handleOrId) {
+		const uuid = await resolveToUuid(this.http.apiUrl, handleOrId);
+		return parse(AgentProfileSchema, unwrapDirectoryCard(await this.http.get(`/directory/agents/${uuid}`, { operation: "inspect" }), uuid));
+	}
+	async discoverGroups(opts) {
+		return parseCursorPage(GroupSummarySchema, await this.http.get("/directory/groups", {
+			params: {
+				q: opts?.q,
+				limit: opts?.limit,
+				cursor: opts?.cursor
+			},
+			operation: "discoverGroups"
+		}));
+	}
+};
+function unwrapDirectoryCard(data, fallbackId) {
+	if (!isRecord(data) || !isRecord(data.card)) return data;
+	const card = data.card;
+	const rine = isRecord(card.rine) ? card.rine : {};
+	const directoryMetadata = isRecord(data.directory_metadata) ? data.directory_metadata : {};
+	return {
+		id: rine.agent_id ?? fallbackId,
+		name: card.name ?? "",
+		handle: rine.handle ?? "",
+		description: card.description ?? null,
+		category: rine.category ?? null,
+		verified: rine.verified ?? false,
+		human_oversight: rine.human_oversight ?? true,
+		created_at: directoryMetadata.registered_at ?? null
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/resources/groups.ts
+/**
+* Groups resource — create, get, list, join, members, invite,
+* update, delete, removeMember, listRequests, vote.
+*
+* Step 10 — Track B: routes + bodies aligned with server endpoints per
+* SPEC §10.6. Handle-resolution (`_resolveGroupAsync`) is not added here
+* (Step 11+), so UUID-only parameters remain the current limit.
+*/
+var GroupsResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	async list() {
+		return parseCursorPage(GroupReadSchema, await this.http.get("/groups", { operation: "groupsList" }));
+	}
+	/**
+	* Create a new group. Two call styles:
+	*
+	*   client.groups.create('my-group', { visibility: 'public' })
+	*   client.groups.create({ name: 'my-group', visibility: 'public' })
+	*
+	* The options-bag form matches the rest of the SDK surface (`inbox`,
+	* `discover`, `sendAndWait`) and is the recommended ergonomic for
+	* first-time users; the positional form is kept for existing callers.
+	*/
+	async create(nameOrOpts, maybeOpts = {}) {
+		const { name, opts } = typeof nameOrOpts === "string" ? {
+			name: nameOrOpts,
+			opts: maybeOpts
+		} : {
+			name: nameOrOpts.name,
+			opts: nameOrOpts
+		};
+		const body = { name };
+		if (opts.description !== void 0) body["description"] = opts.description;
+		if (opts.enrollment !== void 0) body["enrollment_policy"] = opts.enrollment;
+		if (opts.visibility !== void 0) body["visibility"] = opts.visibility;
+		return parse(GroupReadSchema, await this.http.post("/groups", body, {
+			signal: opts.signal,
+			operation: "groupsCreate"
+		}));
+	}
+	async get(groupId) {
+		return parse(GroupReadSchema, await this.http.get(`/groups/${groupId}`, { operation: "groupsGet" }));
+	}
+	/**
+	* Update group metadata.
+	*
+	* Route: `PATCH /groups/{id}` with body of camelCase → snake_case
+	* mapped fields. Previously missing from the TS SDK.
+	*/
+	async update(groupId, opts) {
+		const body = {};
+		if (opts.description !== void 0) body["description"] = opts.description;
+		if (opts.enrollment !== void 0) body["enrollment_policy"] = opts.enrollment;
+		if (opts.visibility !== void 0) body["visibility"] = opts.visibility;
+		if (opts.voteDurationHours !== void 0) body["vote_duration_hours"] = opts.voteDurationHours;
+		return parse(GroupReadSchema, await this.http.patch(`/groups/${groupId}`, body, {
+			signal: opts.signal,
+			operation: "groupsUpdate"
+		}));
+	}
+	/**
+	* Delete a group (owner only). Previously missing from the TS SDK.
+	*/
+	async delete(groupId, opts = {}) {
+		await this.http.delete(`/groups/${groupId}`, {
+			signal: opts.signal,
+			operation: "groupsDelete"
+		});
+	}
+	async join(groupId, opts = {}) {
+		const body = {};
+		if (opts.message !== void 0) body["message"] = opts.message;
+		const res = await this.http.postWithStatus(`/groups/${groupId}/join`, body, {
+			signal: opts.signal,
+			operation: "groupsJoin"
+		});
+		if (res.status === 202) return {
+			status: "pending",
+			request: parse(JoinRequestReadSchema, res.body)
+		};
+		return {
+			status: "joined",
+			member: parse(GroupMemberSchema, res.body)
+		};
+	}
+	async invite(groupId, agentId, opts) {
+		return parse(InviteResultSchema, await this.http.post(`/groups/${groupId}/invite`, {
+			agent_id: agentId,
+			...opts?.message && { message: opts.message }
+		}, {
+			signal: opts?.signal,
+			operation: "groupsInvite"
+		}));
+	}
+	/**
+	* Remove a member from a group. Previously missing from the TS SDK.
+	*
+	* Route: `DELETE /groups/{groupId}/members/{agentId}`.
+	*/
+	async removeMember(groupId, agentId, opts = {}) {
+		await this.http.delete(`/groups/${groupId}/members/${agentId}`, {
+			signal: opts.signal,
+			operation: "groupsRemoveMember"
+		});
+	}
+	async members(groupId) {
+		return parseCursorPage(GroupMemberSchema, await this.http.get(`/groups/${groupId}/members`, { operation: "groupsMembers" }));
+	}
+	/**
+	* List pending join requests for a group.
+	*
+	* Route: `GET /groups/{groupId}/requests` (fixes parity gap — TS
+	* previously used `/join-requests`). Returns a plain array to match
+	* Python SDK `groups.list_requests`.
+	*/
+	async listRequests(groupId) {
+		return parseCursorPage(JoinRequestReadSchema, await this.http.get(`/groups/${groupId}/requests`, { operation: "groupsListRequests" })).items;
+	}
+	/**
+	* Vote on a pending join request (fixes audit C-adjacent — missing
+	* group segment).
+	*
+	* Route: `POST /groups/{groupId}/requests/{requestId}/vote`.
+	*/
+	async vote(groupId, requestId, choice) {
+		return parse(VoteResponseSchema, await this.http.post(`/groups/${groupId}/requests/${requestId}/vote`, { vote: choice }, { operation: "groupsVote" }));
+	}
+};
+//#endregion
+//#region src/resources/identity.ts
+/**
+* Identity resource — whoami, createAgent, listAgents, getAgent, updateAgent,
+* revokeAgent, rotateKeys, agent cards, poll tokens, quotas.
+*/
+var IdentityResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Fetch the current org identity, agent list, and trust tier.
+	*
+	* Routes: `GET /agents` + `GET /org` — the server does not expose a
+	* single `/agents/whoami` endpoint; the Python SDK makes both calls and
+	* composes the `WhoAmI` client-side (`_client.py:605-621`). This TS
+	* implementation mirrors that exactly.
+	*/
+	async whoami(opts) {
+		const agents = unwrapAgentsList(await this.http.get("/agents", {
+			signal: opts?.signal,
+			operation: "whoami"
+		})).map((a) => parse(AgentReadSchema, a));
+		const org = parse(OrgReadSchema, await this.http.get("/org", {
+			signal: opts?.signal,
+			operation: "whoami"
+		}));
+		return parse(WhoAmISchema, {
+			org,
+			agents,
+			trust_tier: org.trust_tier ?? 0
+		});
+	}
+	/**
+	* Create a new agent with locally generated E2EE keypairs.
+	*
+	* Matches Python `rine._onboard.create_agent` flow:
+	*   1. Generate Ed25519 + X25519 keypairs via rine-core `generateAgentKeys()`.
+	*   2. POST `/agents` with `{name, human_oversight, unlisted, signing_public_key,
+	*      encryption_public_key}` (public keys as JWKs). The server's `AgentCreate`
+	*      schema is `extra="forbid"`, so no other fields may be sent on creation.
+	*   3. Persist private keys under `{configDir}/keys/{agentId}/` via
+	*      rine-core `saveAgentKeys()` so the new agent can immediately participate
+	*      in E2EE send/receive without any manual key setup.
+	*
+	* Partial failure: if the POST succeeds but `saveAgentKeys` throws, the
+	* server-side agent exists but the caller has no private keys — surfaced
+	* as the raw I/O error. Callers must treat this as a partial failure.
+	*/
+	async createAgent(name, opts) {
+		const { signal, ...body } = opts ?? {};
+		requireConfigDir(this.http.configDir, "createAgent");
+		const keys = generateAgentKeys();
+		const agent = parse(AgentReadSchema, await this.http.post("/agents", {
+			name,
+			...body,
+			signing_public_key: signingPublicKeyToJWK(keys.signing.publicKey),
+			encryption_public_key: encryptionPublicKeyToJWK(keys.encryption.publicKey)
+		}, {
+			signal,
+			operation: "createAgent"
+		}));
+		saveAgentKeys(this.http.configDir, agent.id, keys);
+		if (agent.poll_url) try {
+			const creds = loadCredentials(this.http.configDir);
+			if (creds.default) {
+				creds.default.poll_url = agent.poll_url;
+				saveCredentials(this.http.configDir, creds);
+			}
+		} catch {}
+		return agent;
+	}
+	async listAgents(opts) {
+		return parseCursorPage(AgentReadSchema, await this.http.get("/agents", {
+			params: { include_revoked: opts?.includeRevoked },
+			operation: "listAgents"
+		})).items;
+	}
+	async getAgent(agentId) {
+		return parse(AgentReadSchema, await this.http.get(`/agents/${agentId}`, { operation: "getAgent" }));
+	}
+	async updateAgent(agentId, patch) {
+		return parse(AgentReadSchema, await this.http.patch(`/agents/${agentId}`, patch, { operation: "updateAgent" }));
+	}
+	async revokeAgent(agentId) {
+		return parse(AgentReadSchema, await this.http.delete(`/agents/${agentId}`, { operation: "revokeAgent" }));
+	}
+	/**
+	* Rotate this agent's signing + encryption keypairs.
+	*
+	* Route: `POST /agents/{id}/keys`.
+	*
+	* Generates fresh Ed25519 + X25519 keypairs locally, uploads the public
+	* halves to the server (JWK-encoded), then overwrites the on-disk private
+	* keys via `saveAgentKeys()`. Matches Python `AsyncRineClient.rotate_keys`
+	* flow.
+	*
+	* Key rotation is visible to future peers immediately; messages encrypted
+	* to the previous encryption key can still be decrypted as long as the
+	* caller retains a copy of the old private key out-of-band (the SDK does
+	* not keep a history of rotated-out keys).
+	*
+	* Partial failure: if the POST succeeds but `saveAgentKeys` throws mid-write,
+	* the server has the new public keys while the on-disk state may be
+	* inconsistent (`saveAgentKeys` writes signing.key then encryption.key as
+	* two separate file ops, not atomically). Senders will encrypt to the new
+	* keys the server advertises but the client may still hold the old private
+	* half — silent decryption failure. Track as rine-core follow-up.
+	*/
+	async rotateKeys(agentId, opts) {
+		requireConfigDir(this.http.configDir, "rotateKeys");
+		const keys = generateAgentKeys();
+		const agent = parse(AgentReadSchema, await this.http.post(`/agents/${agentId}/keys`, {
+			signing_public_key: signingPublicKeyToJWK(keys.signing.publicKey),
+			encryption_public_key: encryptionPublicKeyToJWK(keys.encryption.publicKey)
+		}, {
+			signal: opts?.signal,
+			operation: "rotateKeys"
+		}));
+		saveAgentKeys(this.http.configDir, agentId, keys);
+		return agent;
+	}
+	async getAgentCard(agentId) {
+		return parse(AgentCardSchema, await this.http.get(`/agents/${agentId}/card`, { operation: "getAgentCard" }));
+	}
+	/**
+	* Upsert an agent card.
+	*
+	* Body shape: `{name, description, version?, is_public?, skills?, rine?}`
+	* where `categories`, `languages` and `pricing_model` are nested inside
+	* the `rine` sub-object — matches Python exactly. The previous TS
+	* flattened everything, which the server silently dropped.
+	*/
+	async setAgentCard(agentId, card) {
+		const body = toAgentCardBody(card);
+		return parse(AgentCardSchema, await this.http.put(`/agents/${agentId}/card`, body, { operation: "setAgentCard" }));
+	}
+	async deleteAgentCard(agentId) {
+		await this.http.delete(`/agents/${agentId}/card`, { operation: "deleteAgentCard" });
+	}
+	/**
+	* Regenerate the agent's poll token.
+	*
+	* Route: `POST /agents/{id}/poll-token` — the old `/poll-token/regenerate`
+	* path never existed on the server.
+	*/
+	async regeneratePollToken(agentId) {
+		return parse(PollTokenResponseSchema, await this.http.post(`/agents/${agentId}/poll-token`, void 0, { operation: "regeneratePollToken" }));
+	}
+	async revokePollToken(agentId) {
+		await this.http.delete(`/agents/${agentId}/poll-token`, { operation: "revokePollToken" });
+	}
+	async getQuotas() {
+		return parse(OrgQuotasSchema, await this.http.get("/org/quotas", { operation: "getQuotas" }));
+	}
+	/** Lazy-cached org ID for erase/export URL paths. */
+	cachedOrgId = null;
+	/** Fetch the caller's org UUID, caching on the instance. */
+	async getOrgId(opts) {
+		if (this.cachedOrgId) return this.cachedOrgId;
+		this.cachedOrgId = (await this.whoami(opts)).org.id;
+		return this.cachedOrgId;
+	}
+	async updateOrg(patch, opts) {
+		const body = {};
+		if (patch.name !== void 0) body.name = patch.name;
+		if (patch.contact_email !== void 0) body.contact_email = patch.contact_email;
+		if (patch.country_code !== void 0) body.country_code = patch.country_code;
+		if (patch.slug !== void 0) body.slug = patch.slug;
+		const org = parse(OrgReadSchema, await this.http.patch("/org", body, {
+			signal: opts?.signal,
+			operation: "updateOrg"
+		}));
+		this.cachedOrgId = org.id;
+		return org;
+	}
+	async eraseOrg(opts) {
+		if (opts.confirm !== true) throw new RineError("eraseOrg() permanently destroys all data. Pass { confirm: true } to proceed.");
+		const orgId = await this.getOrgId({ signal: opts.signal });
+		return parse(ErasureResultSchema, await this.http.delete(`/orgs/${orgId}`, {
+			signal: opts.signal,
+			operation: "eraseOrg"
+		}));
+	}
+	async exportOrg(opts) {
+		const orgId = await this.getOrgId(opts);
+		const res = await this.http.get(`/orgs/${orgId}/export`, {
+			signal: opts?.signal,
+			extraHeaders: { Accept: "application/x-ndjson" },
+			operation: "exportOrg"
+		});
+		if (Array.isArray(res)) return res;
+		if (typeof res === "string") return res.split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
+		return [res];
+	}
+};
+/**
+* Guard against the `SDKHttpClient` default `_configDir = ""` footgun: with
+* an empty configDir, `saveAgentKeys` resolves `keys/{agentId}` against
+* `process.cwd()` and silently writes private keys into the caller's working
+* directory. Any method that persists keypairs must call this first.
+*/
+function requireConfigDir(configDir, method) {
+	if (configDir === "") throw new Error(`${method}() requires a non-empty SDK configDir — pass one via new AsyncRineClient({ configDir }) so private keys persist under {configDir}/keys/{agentId}/ instead of the current working directory.`);
+}
+/**
+* `GET /agents` sometimes returns a bare array (paginated list default) and
+* sometimes a `{items: [...]}` envelope depending on version. The Python SDK
+* handles both (`data.get("items", data)` — `_client.py:612`); do the same.
+*/
+function unwrapAgentsList(raw) {
+	if (Array.isArray(raw)) return raw;
+	if (typeof raw === "object" && raw !== null && "items" in raw && Array.isArray(raw.items)) return raw.items;
+	return [];
+}
+function toAgentCardBody(card) {
+	const rine = {};
+	if (card.categories !== void 0) rine["categories"] = card.categories;
+	if (card.languages !== void 0) rine["languages"] = card.languages;
+	if (card.pricing_model !== void 0) rine["pricing_model"] = card.pricing_model;
+	const body = {
+		name: card.name,
+		description: card.description
+	};
+	if (card.version !== void 0) body["version"] = card.version;
+	if (card.is_public !== void 0) body["is_public"] = card.is_public;
+	if (card.skills !== void 0) body["skills"] = card.skills;
+	if (Object.keys(rine).length > 0) body["rine"] = rine;
+	return body;
+}
+//#endregion
+//#region src/resources/messages.ts
+/**
+* Messages resource — send, inbox, read, reply, sendAndWait.
+*
+* All outbound messages are E2E-encrypted before leaving the SDK. Inbound
+* messages are auto-decrypted with sender-key retry on read().
+*/
+const DEFAULT_SEND_TYPE = "rine.v1.task_request";
+const DEFAULT_REPLY_TYPE = "rine.v1.task_response";
+var MessagesResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	async send(to, payload, opts = {}) {
+		const op = this.beginOp(opts.signal);
+		try {
+			const core = this.http.getCoreHttpClient({ signal: op.signal });
+			const senderId = await this.resolveSenderId(core, opts.agent);
+			const body = await this.buildSendBody(core, senderId, to, payload, opts);
+			return parse(MessageReadSchema, await this.http.post("/messages", body, {
+				signal: op.signal,
+				operation: "send",
+				extraHeaders: mergeHeaders(idempotencyHeader(opts.idempotencyKey), agentOverrideHeader(opts.agent))
+			}));
+		} finally {
+			op.clear();
+		}
+	}
+	/**
+	* Fetch the current agent's inbox with auto-decryption (fixes audit C2).
+	*
+	* Route is `GET /agents/{agentId}/messages` — requires resolving the
+	* caller's agent UUID up-front (via the same `resolveSenderId()` path as
+	* `send()` / `reply()`), so the inbox is always scoped to one specific
+	* agent even in multi-agent orgs.
+	*
+	* Decryption runs per-item via `decryptEnvelope()`. Failures populate
+	* `decrypt_error` on the returned `DecryptedMessage` instead of throwing
+	* — the page still contains the envelope, just without plaintext. This
+	* matches the Python SDK's "best-effort" inbox contract.
+	*/
+	async inbox(opts = {}) {
+		const op = this.beginOp(opts.signal);
+		try {
+			const core = this.http.getCoreHttpClient({ signal: op.signal });
+			const agentId = await this.resolveSenderId(core, opts.agent);
+			const page = parseCursorPage(DecryptedMessageSchema, await this.http.get(`/agents/${agentId}/messages`, {
+				params: {
+					limit: opts.limit,
+					cursor: opts.cursor
+				},
+				signal: op.signal,
+				operation: "inbox",
+				extraHeaders: agentOverrideHeader(opts.agent)
+			}));
+			return new CursorPage(await Promise.all(page.items.map((item) => decryptEnvelope({
+				core,
+				configDir: this.http.configDir,
+				agentId,
+				msg: item
+			}))), page.total, page.nextCursor, page.prevCursor);
+		} finally {
+			op.clear();
+		}
+	}
+	/**
+	* Fetch and decrypt a single message by id (fixes audit C3).
+	*
+	* Dispatches to `decryptMessage` (HPKE) or `decryptGroupMessage`
+	* (sender-key) based on `encryption_version`. On a sender-key failure
+	* (e.g. the reader has not yet ingested the sender's distribution),
+	* retries once after calling `fetchAndIngestPendingSKDistributions` via
+	* the rine-core bridge — matches Python SDK discipline.
+	*
+	* Failures on the HPKE path or after the sender-key retry populate
+	* `decrypt_error` on the returned message instead of throwing, so
+	* callers can branch on `msg.decrypt_error !== null`.
+	*/
+	async read(messageId, opts = {}) {
+		const op = this.beginOp(opts.signal);
+		try {
+			const core = this.http.getCoreHttpClient({ signal: op.signal });
+			const agentId = await this.resolveSenderId(core, opts.agent);
+			const msg = parse(DecryptedMessageSchema, await this.http.get(`/messages/${messageId}`, {
+				signal: op.signal,
+				operation: "read",
+				extraHeaders: agentOverrideHeader(opts.agent)
+			}));
+			return decryptEnvelope({
+				core,
+				configDir: this.http.configDir,
+				agentId,
+				msg,
+				retrySenderKey: true
+			});
+		} finally {
+			op.clear();
+		}
+	}
+	async reply(messageId, payload, opts = {}) {
+		const op = this.beginOp(opts.signal);
+		try {
+			const core = this.http.getCoreHttpClient({ signal: op.signal });
+			const original = parse(MessageReadSchema, await core.get(`/messages/${messageId}`));
+			const recipientId = original.from_agent_id;
+			if (!recipientId) throw new Error(`Cannot reply to message ${messageId}: original has no sender (system message?)`);
+			const agents = await fetchAgents(core);
+			const ownedAgentIds = new Set(agents.map((a) => a.id));
+			const toAgentIdIfOwned = original.to_agent_id && ownedAgentIds.has(original.to_agent_id) ? original.to_agent_id : void 0;
+			const senderHint = opts.agent ?? toAgentIdIfOwned ?? this.defaultAgentHint();
+			const senderId = await this.resolveSenderId(core, senderHint, agents);
+			if (recipientId === senderId) throw new Error(`Cannot reply to your own message (${messageId}). Send a new message to continue the conversation.`);
+			const recipientPk = await fetchRecipientEncryptionKey(core, recipientId);
+			const encrypted = await encryptMessage(this.http.configDir, senderId, recipientPk, payload);
+			const body = {
+				type: opts.type ?? DEFAULT_REPLY_TYPE,
+				content_type: opts.contentType ?? "application/json",
+				...encrypted
+			};
+			if (opts.metadata) body.metadata = opts.metadata;
+			return parse(MessageReadSchema, await this.http.post(`/messages/${messageId}/reply`, body, {
+				signal: op.signal,
+				operation: "reply",
+				extraHeaders: mergeHeaders(idempotencyHeader(opts.idempotencyKey), agentOverrideHeader(opts.agent))
+			}));
+		} finally {
+			op.clear();
+		}
+	}
+	/**
+	* Atomic send-and-wait via `POST /messages/sync`.
+	*
+	* The server's `/messages/sync` endpoint accepts a full `MessageCreate`
+	* body (same shape as `POST /messages`) plus a `?timeout_ms` query param.
+	* It creates the message, delivers it, then long-polls for a reply — all
+	* in one HTTP request. Returns `SyncMessageResponse = { message, reply,
+	* conversation_id, status }`.
+	*
+	* Returns `{ sent, reply }`. `reply` is null on long-poll timeout.
+	*
+	* Note: the server rejects group handles on `/messages/sync`, so this
+	* method is 1:1 DMs only.
+	*/
+	async sendAndWait(to, payload, opts = {}) {
+		if (isGroupHandle(to)) throw new Error("sendAndWait() does not support group handles — the server's /messages/sync endpoint is 1:1 only.");
+		const op = this.beginOp(opts.signal);
+		try {
+			const core = this.http.getCoreHttpClient({ signal: op.signal });
+			const senderId = await this.resolveSenderId(core, opts.agent);
+			const body = await this.buildSendBody(core, senderId, to, payload, {
+				type: opts.type,
+				contentType: opts.contentType,
+				metadata: opts.metadata
+			});
+			const timeoutMs = opts.timeout ?? 3e4;
+			const raw = await this.http.post("/messages/sync", body, {
+				params: { timeout_ms: timeoutMs },
+				signal: op.signal,
+				operation: "sendAndWait",
+				extraHeaders: mergeHeaders(idempotencyHeader(opts.idempotencyKey), agentOverrideHeader(opts.agent))
+			});
+			const sent = parse(MessageReadSchema, raw?.message);
+			let decryptedReply = null;
+			const rawReply = raw?.reply;
+			if (rawReply != null) {
+				const replyMsg = parse(DecryptedMessageSchema, rawReply);
+				decryptedReply = await decryptEnvelope({
+					core,
+					configDir: this.http.configDir,
+					agentId: senderId,
+					msg: replyMsg,
+					retrySenderKey: true
+				});
+			}
+			return {
+				sent,
+				reply: decryptedReply
+			};
+		} finally {
+			op.clear();
+		}
+	}
+	/**
+	* Build the `POST /messages` body with real E2EE output.
+	*
+	* - Group handle → `getOrCreateSenderKey` → `encryptGroupMessage` → body
+	*   carries `to_handle` + sender-key envelope.
+	* - Everything else (agent handle, agent UUID, group UUID) → resolve to
+	*   UUID via rine-core, HPKE-seal with `encryptMessage`, body carries
+	*   `to_agent_id` + HPKE envelope.
+	*
+	* Note on group UUIDs: the server body shape for groups requires the
+	* handle (`to_handle`). Callers routing a group by UUID must pass the
+	* group handle instead — the UUID form is accepted at the type level for
+	* API symmetry but will be encrypted as a 1:1 and rejected server-side.
+	*/
+	async buildSendBody(core, senderId, to, payload, opts) {
+		const target = to;
+		const base = {
+			type: opts.type ?? DEFAULT_SEND_TYPE,
+			content_type: opts.contentType ?? "application/json"
+		};
+		if (opts.metadata) base.metadata = opts.metadata;
+		if (opts.parentConversationId) base.parent_conversation_id = opts.parentConversationId;
+		if (opts.conversationMetadata) base.conversation_metadata = opts.conversationMetadata;
+		if (isGroupHandle(target)) {
+			const extraHeaders = { "X-Rine-Agent": senderId };
+			const { state, groupId } = await getOrCreateSenderKey(core, this.http.configDir, senderId, target, extraHeaders);
+			const { result } = await encryptGroupMessage(this.http.configDir, senderId, groupId, state, payload);
+			return {
+				...base,
+				to_handle: target,
+				...result
+			};
+		}
+		const recipientId = await resolveToUuid(this.http.apiUrl, target);
+		const recipientPk = await fetchRecipientEncryptionKey(core, recipientId);
+		const encrypted = await encryptMessage(this.http.configDir, senderId, recipientPk, payload);
+		return {
+			...base,
+			to_agent_id: recipientId,
+			...encrypted
+		};
+	}
+	/**
+	* Resolve the sender agent to a UUID suitable for loading local keys.
+	*
+	* Precedence: explicit override → SDK default agent → single-agent
+	* shortcut (errors on multi-agent orgs).
+	*
+	* Makes one `GET /agents` request per send; caching is deferred (the
+	* Python SDK and rine-cli do not cache either).
+	*
+	* Also verifies the resolved agent is in the caller's own org. `resolveAgent`
+	* short-circuits on UUIDs without validating membership, so a foreign-org
+	* UUID (e.g. an `original.to_agent_id` from a misrouted reply) would slip
+	* through and fail later inside `loadAgentKeys` with a confusing "keys file
+	* not found" filesystem error. The membership check turns that into a clear
+	* "not your agent" error (addresses Step 11 audit R3).
+	*
+	* Exposed as `public` (not `private`) so `client.messages()` (§11.1) can
+	* reuse the same resolution path for its SSE-bound decryption loop.
+	*/
+	async resolveSenderId(core, explicit, preFetchedAgents) {
+		const hint = explicit ?? this.defaultAgentHint();
+		const agents = preFetchedAgents ?? await fetchAgents(core);
+		const senderId = await resolveAgent(this.http.apiUrl, agents, hint);
+		if (!agents.some((a) => a.id === senderId)) throw new Error(`Agent ${senderId} is not owned by the current org — cannot sign on its behalf. Pass an agent from your own org via opts.agent, or omit it to use the default.`);
+		return senderId;
+	}
+	defaultAgentHint() {
+		return this.http.agentHeader?.["X-Rine-Agent"];
+	}
+	/**
+	* Open an operation-scoped cancellation window that spans the whole
+	* encrypt → post chain. One timer, one AbortController. The `clear`
+	* callback must run in `finally` to satisfy audit MINOR-4 (timer leak).
+	*
+	* The op-timer aborts with a `RineTimeoutError` reason so that callers
+	* and `SDKHttpClient.request()` can distinguish user-signal abort
+	* (native AbortError) from SDK op-timer expiry (`RineTimeoutError`).
+	* Fixes the step-27 crypto audit Cr1 (SPEC §14.4).
+	*/
+	beginOp(userSignal) {
+		const timeoutAC = new AbortController();
+		const timer = setTimeout(() => timeoutAC.abort(new RineTimeoutError(`Operation timed out after ${this.http.timeout}ms`)), this.http.timeout);
+		return {
+			signal: userSignal ? anySignal(userSignal, timeoutAC.signal) : timeoutAC.signal,
+			clear: () => clearTimeout(timer)
+		};
+	}
+};
+function idempotencyHeader(key) {
+	if (!key) return void 0;
+	return { "Idempotency-Key": key };
+}
+function agentOverrideHeader(agent) {
+	if (!agent) return void 0;
+	return { "X-Rine-Agent": agent };
+}
+function mergeHeaders(...parts) {
+	const merged = {};
+	for (const part of parts) if (part) Object.assign(merged, part);
+	return Object.keys(merged).length > 0 ? merged : void 0;
+}
+//#endregion
+//#region src/resources/polling.ts
+/**
+* Polling resource — lightweight count check + callback-based watch().
+*/
+var PollingResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Lightweight poll — returns message count for the authenticated agent.
+	* No auth required, firewall-friendly.
+	*
+	* Route: reads `poll_url` from the default credential entry (a full path
+	* like `/poll/<token>` stamped in at agent-create time). The server does
+	* NOT expose a bare `/poll` endpoint — this was a route drift in the
+	* original TS rework surfaced by the step-27 audit. Matches Python
+	* `AsyncRineClient.poll` (`_client.py:623-636`).
+	*
+	* @example
+	* ```ts
+	* const count = await client.polling.poll();
+	* ```
+	*/
+	async poll(opts) {
+		const pollUrl = loadCredentials(this.http.configDir).default?.poll_url;
+		if (!pollUrl) throw new ConfigError("No poll URL. Create an agent first with client.createAgent().");
+		const raw = await this.http.get(pollUrl, {
+			unauthenticated: true,
+			signal: opts?.signal,
+			operation: "poll"
+		});
+		if (typeof raw === "number") return raw;
+		if (typeof raw === "object" && raw !== null && "count" in raw) return raw.count;
+		return Number(raw);
+	}
+	/**
+	* watchPoll — call a callback each time the poll count increases.
+	*
+	* Returns an unsubscribe function.
+	*
+	* @example
+	* ```ts
+	* const unsubscribe = await client.polling.watchPoll((newCount) => {
+	*   console.log('New message count:', newCount);
+	* });
+	* // Later: unsubscribe()
+	* ```
+	*/
+	watchPoll(onCountChange, opts = {}) {
+		const { interval = 5e3, signal } = opts;
+		let lastCount = 0;
+		let stopped = false;
+		const tick = async () => {
+			while (!stopped) {
+				if (signal?.aborted) break;
+				try {
+					const count = await this.poll();
+					if (count > lastCount) {
+						lastCount = count;
+						onCountChange(count);
+					}
+				} catch {}
+				await sleepWithSignal(interval, signal);
+			}
+		};
+		tick();
+		return () => {
+			stopped = true;
+		};
+	}
+};
+//#endregion
+//#region src/utils/sse.ts
+/**
+* Convert a fetch Response with an SSE body into an AsyncIterable of RineEvent.
+*
+* @param response - A fetch Response whose body is an SSE stream.
+* @param signal   - AbortSignal for cancellation.
+*
+* Usage:
+* ```ts
+* const resp = await fetch(url, { headers: { Accept: 'text/event-stream' } });
+* for await (const event of toAsyncIter(resp, signal)) {
+*   console.log(event.type, event.data);
+* }
+* ```
+*/
+async function* toAsyncIter(response, signal) {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let eventType = "";
+	let eventData = "";
+	let eventId = null;
+	const warnedUnknownTypes = /* @__PURE__ */ new Set();
+	const cleanup = () => {
+		reader.cancel().catch(() => {});
+	};
+	signal.addEventListener("abort", cleanup, { once: true });
+	if (signal.aborted) {
+		signal.removeEventListener("abort", cleanup);
+		cleanup();
+		return;
+	}
+	const flush = function* () {
+		if (!(eventType || eventData)) return;
+		const event = parseRineEvent(eventType, eventData, eventId ?? void 0, warnedUnknownTypes);
+		if (event !== null) yield event;
+	};
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines[lines.length - 1] ?? "";
+			for (const raw of lines.slice(0, -1)) {
+				const line = parseLine(raw);
+				if (line === null) continue;
+				if (line.field === "dispatch") {
+					yield* flush();
+					eventType = "";
+					eventData = "";
+					eventId = null;
+				} else if (line.field === "event") eventType = line.value;
+				else if (line.field === "data") {
+					if (eventData) eventData += "\n";
+					eventData += line.value;
+				} else if (line.field === "id") eventId = line.value;
+			}
+			if (signal.aborted) break;
+		}
+		yield* flush();
+	} finally {
+		signal.removeEventListener("abort", cleanup);
+	}
+}
+function parseLine(raw) {
+	const line = raw.trimEnd();
+	if (!line) return { field: "dispatch" };
+	if (line.startsWith(":")) return null;
+	const colonIdx = line.indexOf(":");
+	if (colonIdx === -1) return null;
+	const field = line.slice(0, colonIdx);
+	const rawValue = line.slice(colonIdx + 1);
+	const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+	if (field === "event") return {
+		field: "event",
+		value
+	};
+	if (field === "data") return {
+		field: "data",
+		value
+	};
+	if (field === "id") return {
+		field: "id",
+		value
+	};
+	return null;
+}
+function parseRineEvent(rawType, data, id, warnedUnknownTypes) {
+	const type = mapEventType(rawType);
+	if (type === null) {
+		if (!warnedUnknownTypes.has(rawType)) {
+			warnedUnknownTypes.add(rawType);
+			console.warn(`rine: unknown SSE event type ignored: ${rawType}`);
+		}
+		return null;
+	}
+	return {
+		type,
+		data,
+		id
+	};
+}
+function mapEventType(raw) {
+	switch (raw) {
+		case "message": return "message";
+		case "heartbeat": return "heartbeat";
+		case "status": return "status";
+		case "disconnect": return "disconnect";
+		case "": return "message";
+		default: return null;
+	}
+}
+//#endregion
+//#region src/utils/seen-ids.ts
+/**
+* Bounded FIFO seen-ID set.
+*
+* Used by both the SSE stream layer (reconnect replay dedup per SPEC_v2 §12.3.3)
+* and the poll-based `watch()` path (see `client.ts`). On reconnect with
+* `Last-Event-ID`, the server's catch-up phase can race with the NOTIFY
+* delivery and re-emit events already seen; this class is the guard against
+* dispatching them twice.
+*
+* Capacity defaults to 500 (SPEC §12.3.3 N — ~18 KB of RAM, ~10 minutes of
+* traffic at 1 msg/s — comfortably larger than any plausible reconnect
+* replay window, small enough to stay negligible).
+*/
+var SeenIds = class {
+	set = /* @__PURE__ */ new Set();
+	queue = [];
+	constructor(capacity = 500) {
+		this.capacity = capacity;
+	}
+	/** Returns true if the id is new (caller should dispatch), false if duplicate. */
+	record(id) {
+		if (this.set.has(id)) return false;
+		this.set.add(id);
+		this.queue.push(id);
+		while (this.queue.length > this.capacity) {
+			const evicted = this.queue.shift();
+			if (evicted !== void 0) this.set.delete(evicted);
+		}
+		return true;
+	}
+	has(id) {
+		return this.set.has(id);
+	}
+	get size() {
+		return this.set.size;
+	}
+};
+//#endregion
+//#region src/resources/streams.ts
+var StreamsResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Open an SSE stream yielding RineEvents.
+	*
+	* For agentic use cases, prefer `client.messages()` (SPEC §11.1) which
+	* wraps this with local decryption and cleartext type filtering — this
+	* method is the lower-level raw-event primitive.
+	*
+	* @example
+	* ```ts
+	* const ac = new AbortController();
+	* setTimeout(() => ac.abort(), 60_000);
+	*
+	* for await (const event of client.streams.stream({ signal: ac.signal })) {
+	*   console.log(event.type, event.id);
+	* }
+	* ```
+	*/
+	stream(opts = {}) {
+		const { signal, agent, timeout, lastEventId } = opts;
+		const agentSegment = agent ? `/agents/${agent}` : "";
+		let combinedSignal;
+		if (signal && timeout !== void 0) combinedSignal = anySignal(signal, AbortSignal.timeout(timeout));
+		else if (signal) combinedSignal = signal;
+		else if (timeout !== void 0) combinedSignal = AbortSignal.timeout(timeout);
+		else combinedSignal = neverAbortingSignal();
+		return this.connect(agentSegment, combinedSignal, lastEventId);
+	}
+	async *connect(agentSegment, signal, initialLastEventId) {
+		let lastEventId = initialLastEventId;
+		let backoff = 1;
+		const seen = new SeenIds(500);
+		while (!signal.aborted) {
+			const headers = {};
+			if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+			try {
+				const response = await this.http.openStream(`${agentSegment}/stream`, {
+					headers,
+					signal
+				});
+				if (!response.ok) throw new Error(`SSE stream error: ${response.status} ${response.statusText}`);
+				backoff = 1;
+				for await (const event of toAsyncIter(response, signal)) {
+					if (event.id) {
+						if (!seen.record(event.id)) continue;
+						lastEventId = event.id;
+					}
+					yield event;
+				}
+				yield {
+					type: "disconnect",
+					data: "stream ended"
+				};
+				break;
+			} catch (err) {
+				if (signal.aborted) break;
+				backoff = Math.min(backoff * 2, 30);
+				yield {
+					type: "heartbeat",
+					data: `reconnecting in ${backoff}s: ${err instanceof Error ? err.message : String(err)}`
+				};
+				await sleepWithSignal(backoff * 1e3, signal);
+				if (signal.aborted) break;
+			}
+		}
+	}
+};
+function neverAbortingSignal() {
+	return new AbortController().signal;
+}
+//#endregion
+//#region src/resources/webhooks.ts
+/**
+* Webhooks resource — create, list, update, delete, deliveries.
+*
+* Step 10 — Track B: `create()` now takes the required `agentId` + optional
+* `events` list per server schema; `update()` accepts only the `active`
+* toggle (matches Python SDK). SPEC §10.7.
+*/
+var WebhooksResource = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Register a webhook.
+	*
+	* Route: `POST /webhooks` with body `{agent_id, url, events?}`.
+	* `agent_id` is required by the server schema — previous TS SDK
+	* omitted it entirely, which 422'd every call.
+	*/
+	async create(agentId, url, opts = {}) {
+		const body = {
+			agent_id: agentId,
+			url
+		};
+		if (opts.events !== void 0) body.events = opts.events;
+		return parse(WebhookCreatedSchema, await this.http.post("/webhooks", body, {
+			signal: opts.signal,
+			operation: "webhooksCreate"
+		}));
+	}
+	async list(opts = {}) {
+		return parseCursorPage(WebhookReadSchema, await this.http.get("/webhooks", {
+			params: {
+				agent_id: opts.agentId,
+				include_inactive: opts.includeInactive
+			},
+			signal: opts.signal,
+			operation: "webhooksList"
+		}));
+	}
+	/**
+	* Toggle a webhook's active flag.
+	*
+	* Body restricted to `{active}` per server schema — the previous TS
+	* SDK accepted `Partial<WebhookRead>` which did not match the server.
+	*/
+	async update(id, opts) {
+		return parse(WebhookReadSchema, await this.http.patch(`/webhooks/${id}`, { active: opts.active }, {
+			signal: opts.signal,
+			operation: "webhooksUpdate"
+		}));
+	}
+	async delete(id) {
+		await this.http.delete(`/webhooks/${id}`, { operation: "webhooksDelete" });
+	}
+	async deliveries(id, opts = {}) {
+		return parseCursorPage(WebhookDeliveryReadSchema, await this.http.get(`/webhooks/${id}/deliveries`, {
+			params: {
+				status: opts.status,
+				limit: opts.limit,
+				offset: opts.offset
+			},
+			signal: opts.signal,
+			operation: "webhooksDeliveries"
+		}));
+	}
+	/**
+	* Aggregated delivery counts for a webhook.
+	*
+	* Route: `GET /webhooks/{id}/deliveries/summary`. Matches Python SDK
+	* `webhooks.delivery_summary` (SPEC §10.7).
+	*/
+	async deliverySummary(id, opts = {}) {
+		return parse(WebhookJobSummarySchema, await this.http.get(`/webhooks/${id}/deliveries/summary`, {
+			signal: opts.signal,
+			operation: "webhooksDeliverySummary"
+		}));
+	}
+};
+//#endregion
+//#region src/client.ts
+let __includeReservedWarned = false;
+/**
+* Async client for the Rine E2E-encrypted messaging API.
+*
+* All messages are encrypted client-side (HPKE for 1:1, Sender Keys for
+* groups) before leaving the process. Construct via `new AsyncRineClient()`
+* or `defineAgent()` for the handler-based pattern.
+*/
+var AsyncRineClient = class AsyncRineClient {
+	http;
+	_signal;
+	messagingResource;
+	streams;
+	polling;
+	groups;
+	webhooks;
+	discovery;
+	identity;
+	constructor(opts = {}) {
+		this.http = new SDKHttpClient({
+			configDir: opts.configDir,
+			apiUrl: opts.apiUrl,
+			agent: opts.agent,
+			timeout: opts.timeout,
+			maxRetries: opts.maxRetries,
+			middleware: opts.middleware
+		});
+		this._signal = opts.signal;
+		this.messagingResource = new MessagesResource(this.http);
+		this.streams = new StreamsResource(this.http);
+		this.polling = new PollingResource(this.http);
+		this.groups = new GroupsResource(this.http);
+		this.webhooks = new WebhooksResource(this.http);
+		this.discovery = new DiscoveryResource(this.http);
+		this.identity = new IdentityResource(this.http);
+	}
+	/**
+	* Send an E2E-encrypted message to an agent or group.
+	*
+	* @param to - Recipient handle (`name@org.rine.network`), group handle
+	*   (`#group@org.rine.network`), or UUID.
+	* @param payload - Message payload (encrypted before sending).
+	* @param opts - Optional type, metadata, schema validation, signal.
+	* @returns The server-acknowledged message envelope.
+	* @throws {SchemaValidationError} If `opts.schema` is set and payload fails validation.
+	*
+	* @example
+	* ```ts
+	* const msg = await client.send("bot@acme.rine.network", { task: "summarize" });
+	* ```
+	*/
+	async send(to, payload, opts) {
+		if (typeof to !== "string") throw new Error(`client.send() expects (to, payload, opts); first arg must be a recipient handle or UUID, got ${typeof to}. Did you pass the payload first?`);
+		const validated = opts?.schema !== void 0 ? await validateOutbound(payload, opts.schema) : payload;
+		const { schema: _schema, ...rest } = opts ?? {};
+		return this.messagingResource.send(to, validated, {
+			signal: this._signal,
+			...rest
+		});
+	}
+	async sendAndWait(to, payload, opts) {
+		if (typeof to !== "string") throw new Error(`client.sendAndWait() expects (to, payload, opts); first arg must be a recipient handle or UUID, got ${typeof to}. Did you pass the payload first?`);
+		const validated = opts?.schema !== void 0 ? await validateOutbound(payload, opts.schema) : payload;
+		const { schema: _schema, replySchema, ...rest } = opts ?? {};
+		const result = await this.messagingResource.sendAndWait(to, validated, {
+			signal: this._signal,
+			...rest
+		});
+		if (replySchema !== void 0 && result.reply !== null && result.reply.decrypt_error == null) {
+			const typedReply = await parseMessagePlaintext(result.reply, replySchema);
+			return {
+				sent: result.sent,
+				reply: typedReply
+			};
+		}
+		return result;
+	}
+	/** Fetch the current agent's inbox with automatic decryption. */
+	inbox(opts) {
+		return this.messagingResource.inbox({
+			signal: this._signal,
+			...opts
+		});
+	}
+	/**
+	* Auto-paginating async iterator over every message in the inbox.
+	*
+	* Walks `nextCursor` until exhausted and yields each `DecryptedMessage` as
+	* it arrives. Lazy — holds at most one page in memory. Replaces the
+	* deleted `CursorPage.autoPaginate(fetchPage)` helper per SPEC §13.2/§13.3.
+	*
+	* @example
+	* ```ts
+	* for await (const msg of client.inboxAll({ limit: 100 })) {
+	*   console.log(msg.plaintext);
+	* }
+	* ```
+	*/
+	async *inboxAll(opts) {
+		let cursor = opts?.cursor;
+		while (true) {
+			const page = await this.inbox({
+				...opts,
+				cursor
+			});
+			yield* page.items;
+			if (!page.hasNext || page.nextCursor == null) return;
+			cursor = page.nextCursor;
+		}
+	}
+	/** Fetch and decrypt a single message by ID. */
+	async read(messageId, opts) {
+		const { schema, ...rest } = opts ?? {};
+		const msg = await this.messagingResource.read(messageId, {
+			signal: this._signal,
+			...rest
+		});
+		if (schema !== void 0 && msg.decrypt_error == null) return parseMessagePlaintext(msg, schema);
+		return msg;
+	}
+	/**
+	* Reply to a message, threading into the same conversation.
+	*
+	* @param messageId - UUID of the message to reply to.
+	* @param payload - Reply payload (encrypted before sending).
+	* @param opts - Optional type, metadata, schema validation, signal.
+	* @returns The server-acknowledged reply envelope.
+	*
+	* @example
+	* ```ts
+	* await client.reply(msg.id, { status: "done", result: 42 });
+	* ```
+	*/
+	async reply(messageId, payload, opts) {
+		if (typeof messageId !== "string") throw new Error(`client.reply() expects (messageId, payload, opts); first arg must be a message UUID string, got ${typeof messageId}. Did you pass the payload first?`);
+		const validated = opts?.schema !== void 0 ? await validateOutbound(payload, opts.schema) : payload;
+		const { schema: _schema, ...rest } = opts ?? {};
+		return this.messagingResource.reply(messageId, validated, {
+			signal: this._signal,
+			...rest
+		});
+	}
+	/**
+	* Decrypted message iterator — the agentic headline surface (§11.1).
+	*
+	* Thin transform over `this.streams.stream()` that parses the inline
+	* `MessageRead` envelope from each `event: message` SSE frame, runs the
+	* pre-decrypt type filter (D6c) and reserved-type hiding (D6d), then
+	* decrypts via the shared `decryptEnvelope()` helper.
+	*
+	* Key property per §11.1.1: decryption is local, not a round-trip via
+	* `read()`. The server already JSON-encodes the full envelope into the
+	* SSE `data:` field (`src/rine/api/agent_stream.py:27`), so the SDK
+	* never needs a second `GET /messages/{id}` per message.
+	*
+	* Lifetime: bound to `opts.signal`. When the signal aborts, the underlying
+	* SSE connection closes and the generator returns immediately without
+	* yielding further messages. **No error is thrown on abort** — long-lived
+	* stream iterators exit silently per SPEC_v2 §12.4, matching the standard
+	* async-iterator cancellation contract. To distinguish "aborted" from
+	* "ended naturally", check `opts.signal?.aborted` after the `for await`
+	* loop exits. Without a signal, iteration continues until the caller
+	* `break`s out of the `for await` loop (triggering the generator's
+	* `return()`, which closes the underlying SSE connection).
+	*
+	* Non-message events (`heartbeat`, `status`, `disconnect`) and reserved
+	* message types are silently dropped. Crypto failures populate
+	* `decrypt_error` on the yielded message rather than throwing — same
+	* discipline as `inbox()` / `read()`.
+	*
+	* Typed payload generics (`messages<T>({ schema })`) and the Standard
+	* Schema v1 validation hook are wired end-to-end in Step 19: if `schema`
+	* is supplied each decrypted message is JSON-parsed and validated before
+	* being yielded, and `msg.plaintext` narrows to `T | null`. A schema
+	* failure throws `ValidationError` out of the generator and iteration
+	* ends — the same semantics as `read<T>()`. Inside `defineAgent<T>` the
+	* failure is caught and routed to `onError({ stage: 'schema' })`.
+	*
+	* @example
+	* ```ts
+	* const ac = new AbortController();
+	* for await (const msg of client.messages({ signal: ac.signal })) {
+	*   console.log(msg.type, msg.plaintext);
+	* }
+	* ```
+	*/
+	messages(opts = {}) {
+		return this.messagesGenerator(opts);
+	}
+	async *messagesGenerator(opts) {
+		const signal = opts.signal ?? this._signal;
+		if (opts.includeReserved && !__includeReservedWarned) {
+			__includeReservedWarned = true;
+			console.warn("rine: client.messages({ includeReserved: true }) is a debug-only escape hatch; behavior may change between minor versions.");
+		}
+		const core = this.http.getCoreHttpClient({ signal });
+		const agentId = await this.messagingResource.resolveSenderId(core, opts.agent);
+		const filterTypes = normalizeTypeFilter(opts.type);
+		const stream = this.streams.stream({
+			signal,
+			agent: agentId,
+			lastEventId: opts.lastEventId
+		});
+		let warnedParseFailure = false;
+		for await (const ev of stream) {
+			if (signal?.aborted) return;
+			if (ev.type !== "message") continue;
+			let envelope;
+			try {
+				envelope = parse(DecryptedMessageSchema, JSON.parse(ev.data));
+			} catch (err) {
+				if (!warnedParseFailure) {
+					warnedParseFailure = true;
+					const reason = err instanceof Error ? err.message : String(err);
+					console.warn(`rine: client.messages() dropped malformed SSE envelope (${reason}); further drops on this stream are silent`);
+				}
+				continue;
+			}
+			if (!opts.includeReserved && RESERVED_MESSAGE_TYPES.has(envelope.type)) continue;
+			if (filterTypes && !filterTypes.has(envelope.type)) continue;
+			const decrypted = await decryptEnvelope({
+				core,
+				configDir: this.http.configDir,
+				agentId,
+				msg: envelope
+			});
+			yield opts.schema !== void 0 && decrypted.decrypt_error == null ? await parseMessagePlaintext(decrypted, opts.schema) : decrypted;
+		}
+	}
+	conversation(convIdOrMsg) {
+		if (typeof convIdOrMsg === "string") return new ConversationScope(this, convIdOrMsg);
+		const msg = convIdOrMsg;
+		const selfHandle = this.http.agentHeader?.["X-Rine-Agent"];
+		const peer = derivePeerFromMessage(msg, selfHandle);
+		return new ConversationScope(this, msg.conversation_id, peer, msg.id);
+	}
+	stream(opts) {
+		return this.streams.stream({
+			signal: this._signal,
+			...opts
+		});
+	}
+	/** Check how many unread messages are waiting (lightweight poll). */
+	poll() {
+		return this.polling.poll();
+	}
+	/**
+	* Watch for incoming messages via polling — calls `handler` on each new message.
+	*
+	* Note: `watch()` is NOT in the Python SDK — it is a TypeScript-only ergonomic
+	* surface added for polling agents behind firewalls.
+	*
+	* Returns an unsubscribe function.
+	*/
+	async watch(handler, opts) {
+		const { signal, pollInterval = 5e3, onError } = {
+			signal: this._signal,
+			...opts
+		};
+		let stopped = false;
+		const seen = new SeenIds(500);
+		const tick = async () => {
+			while (!stopped) {
+				if (signal?.aborted) break;
+				try {
+					const sorted = [...(await this.inbox({
+						limit: 10,
+						signal
+					})).items].sort((a, b) => {
+						const ta = a.created_at ?? "";
+						const tb = b.created_at ?? "";
+						return ta.localeCompare(tb);
+					});
+					for (const msg of sorted) {
+						const id = msg.id;
+						if (!seen.record(id)) continue;
+						await handler(msg);
+					}
+				} catch (err) {
+					if (onError) onError(err);
+				}
+				await sleepWithSignal(pollInterval, signal);
+			}
+		};
+		tick();
+		return () => {
+			stopped = true;
+		};
+	}
+	/** Fetch the current org identity, agent list, and trust tier. */
+	whoami() {
+		return this.identity.whoami();
+	}
+	createAgent(name, opts) {
+		return this.identity.createAgent(name, opts);
+	}
+	listAgents(opts) {
+		return this.identity.listAgents(opts);
+	}
+	getAgent(agentId) {
+		return this.identity.getAgent(agentId);
+	}
+	updateAgent(agentId, patch) {
+		return this.identity.updateAgent(agentId, patch);
+	}
+	revokeAgent(agentId) {
+		return this.identity.revokeAgent(agentId);
+	}
+	rotateKeys(agentId) {
+		return this.identity.rotateKeys(agentId);
+	}
+	getAgentCard(agentId) {
+		return this.identity.getAgentCard(agentId);
+	}
+	setAgentCard(agentId, card) {
+		return this.identity.setAgentCard(agentId, card);
+	}
+	deleteAgentCard(agentId) {
+		return this.identity.deleteAgentCard(agentId);
+	}
+	regeneratePollToken(agentId) {
+		return this.identity.regeneratePollToken(agentId);
+	}
+	revokePollToken(agentId) {
+		return this.identity.revokePollToken(agentId);
+	}
+	getQuotas() {
+		return this.identity.getQuotas();
+	}
+	updateOrg(patch, opts) {
+		return this.identity.updateOrg(patch, opts);
+	}
+	eraseOrg(opts) {
+		return this.identity.eraseOrg(opts);
+	}
+	exportOrg(opts) {
+		return this.identity.exportOrg(opts);
+	}
+	discover(filters) {
+		return this.discovery.discover(filters);
+	}
+	/**
+	* Auto-paginating async iterator over every agent that matches the
+	* supplied discovery filters. Walks `nextCursor` until exhausted.
+	* Replaces `CursorPage.autoPaginate()` per SPEC §13.2/§13.3.
+	*/
+	async *discoverAll(filters) {
+		let cursor = filters?.cursor;
+		while (true) {
+			const page = await this.discovery.discover({
+				...filters,
+				cursor
+			});
+			yield* page.items;
+			if (!page.hasNext || page.nextCursor == null) return;
+			cursor = page.nextCursor;
+		}
+	}
+	inspect(handleOrId) {
+		return this.discovery.inspect(handleOrId);
+	}
+	discoverGroups(opts) {
+		return this.discovery.discoverGroups(opts);
+	}
+	async *discoverGroupsAll(opts) {
+		let cursor;
+		while (true) {
+			const page = await this.discovery.discoverGroups({
+				...opts,
+				cursor
+			});
+			yield* page.items;
+			if (!page.hasNext || page.nextCursor == null) return;
+			cursor = page.nextCursor;
+		}
+	}
+	/**
+	* Python-parity `with_options` — returns a new `AsyncRineClient` that
+	* shares credentials and middleware but applies the supplied overrides.
+	* Any option not provided inherits from this client.
+	*
+	* See SPEC §10.8 — this is the idiomatic single-method replacement for
+	* the narrower `withSignal` / `withTimeout` / `withAgent` helpers, which
+	* remain available for callers that prefer the specialised APIs.
+	*/
+	withOptions(opts) {
+		return new AsyncRineClient({
+			configDir: this.http.configDir,
+			apiUrl: this.http.apiUrl,
+			agent: opts.agent ?? this.http.agentHeader?.["X-Rine-Agent"],
+			timeout: opts.timeout ?? this.http.timeout,
+			maxRetries: opts.maxRetries ?? this.http.maxRetries,
+			middleware: this.http.middleware,
+			signal: opts.signal ?? this._signal
+		});
+	}
+	/** Return a derived client bound to the given AbortSignal. */
+	withSignal(signal) {
+		return this.withOptions({ signal });
+	}
+	/** Return a derived client with a different request timeout. */
+	withTimeout(ms) {
+		return this.withOptions({ timeout: ms });
+	}
+	/** Return a derived client acting as a different agent. */
+	withAgent(agent) {
+		return this.withOptions({ agent });
+	}
+	/** Release any resources held by this client. */
+	async close() {}
+	/** Implements `AsyncDisposable` — delegates to `close()`. */
+	[Symbol.asyncDispose]() {
+		return this.close();
+	}
+};
+/**
+* Normalize the `type` filter from `client.messages()` into a Set for O(1)
+* membership tests. Returns `undefined` when no filter was passed (caller
+* branches on `filterTypes !== undefined`).
+*/
+function normalizeTypeFilter(filter) {
+	if (filter === void 0) return void 0;
+	if (typeof filter === "string") return new Set([filter]);
+	if (filter.length === 0) return void 0;
+	return new Set(filter);
+}
+/**
+* Derive the "other party" for a conversation scope from a decrypted
+* message. Supports group messages (peer = group handle) and 1:1 DMs
+* (peer = original sender's handle or UUID). Returns `null` when the
+* derivation is ambiguous (system message, missing handle on a group
+* frame, etc.) so that `scope.send(payload)` surfaces the clear
+* "no peer" error instead of misrouting to a stale address.
+*/
+function derivePeerFromMessage(msg, selfHandle) {
+	if (msg.group_id) return msg.group_handle ?? null;
+	if (selfHandle && msg.sender_handle === selfHandle) {
+		if (msg.recipient_handle) return msg.recipient_handle;
+		if (msg.to_agent_id) return msg.to_agent_id;
+		return null;
+	}
+	if (msg.sender_handle) return msg.sender_handle;
+	if (msg.from_agent_id) return msg.from_agent_id;
+	return null;
+}
+//#endregion
+//#region src/agent.ts
+/**
+* Grace period after `stop()` before in-flight handlers are logged as
+* still-running. SPEC §11.3.3 — we don't forcibly terminate user promises
+* (Node has no mechanism), we just wait and then log.
+*/
+const STOP_GRACE_MS = 3e4;
+function defineAgent(opts) {
+	if (opts.pollInterval !== void 0) throw new Error("defineAgent: pollInterval is not yet supported. Use SSE (the default) for message delivery.");
+	const { client, signal: externalSignal, includeReserved, onError, schema } = opts;
+	const internalStop = new AbortController();
+	const composedSignal = externalSignal ? anySignal(externalSignal, internalStop.signal) : internalStop.signal;
+	const handlerMode = "handlers" in opts && opts.handlers !== void 0;
+	const handlers = handlerMode ? opts.handlers : void 0;
+	const onMessage = !handlerMode ? opts.onMessage : void 0;
+	let typeFilter;
+	if (handlers) {
+		const keys = Object.keys(handlers).filter((k) => k !== "*");
+		if (!(handlers["*"] !== void 0) && keys.length > 0) typeFilter = keys;
+	}
+	const inflight = /* @__PURE__ */ new Set();
+	let started = false;
+	let stopPromise = null;
+	let loopPromise = null;
+	const reportError = async (err, ctx) => {
+		if (onError === void 0) {
+			const msgId = ctx.message?.id ?? "<no-msg>";
+			const msgType = ctx.message?.type ?? "<no-type>";
+			const name = err instanceof Error ? err.name : "Error";
+			const reason = err instanceof Error ? err.message : String(err);
+			console.error(`rine: defineAgent ${ctx.stage} error on ${msgId} (${msgType}): ${name}: ${reason}`);
+			return;
+		}
+		try {
+			await onError(err, ctx);
+		} catch (innerErr) {
+			const reason = innerErr instanceof Error ? innerErr.message : String(innerErr);
+			console.error(`rine: defineAgent onError itself threw: ${reason}`);
+		}
+	};
+	const dispatch = async (msg) => {
+		let typed;
+		if (schema !== void 0 && msg.decrypt_error == null) try {
+			typed = await parseMessagePlaintext(msg, schema);
+		} catch (err) {
+			await reportError(err, {
+				message: msg,
+				stage: "schema"
+			});
+			return;
+		}
+		else typed = msg;
+		const ctx = {
+			client,
+			conversation: client.conversation(msg),
+			reply: (payload, replyOpts) => client.reply(asMessageUuid(msg.id), payload, replyOpts),
+			signal: composedSignal
+		};
+		let handler;
+		if (handlers) handler = handlers[msg.type] ?? handlers["*"];
+		else if (onMessage) handler = onMessage;
+		if (!handler) return;
+		try {
+			await handler(typed, ctx);
+		} catch (err) {
+			await reportError(err, {
+				message: msg,
+				stage: "handler"
+			});
+		}
+	};
+	const runLoop = async () => {
+		try {
+			const messageOpts = {
+				signal: composedSignal,
+				includeReserved
+			};
+			if (typeFilter) messageOpts.type = typeFilter;
+			for await (const msg of client.messages(messageOpts)) {
+				if (composedSignal.aborted) break;
+				const task = dispatch(msg);
+				inflight.add(task);
+				task.finally(() => inflight.delete(task));
+			}
+		} catch (err) {
+			if (composedSignal.aborted) return;
+			await reportError(err, {
+				message: null,
+				stage: "lifecycle"
+			});
+		}
+	};
+	const agent = {
+		get started() {
+			return started;
+		},
+		async start() {
+			if (started) return;
+			started = true;
+			if (composedSignal.aborted) {
+				loopPromise = Promise.resolve();
+				return;
+			}
+			loopPromise = runLoop();
+		},
+		stop() {
+			if (stopPromise) return stopPromise;
+			started = true;
+			stopPromise = (async () => {
+				if (!internalStop.signal.aborted) internalStop.abort();
+				if (loopPromise) try {
+					await loopPromise;
+				} catch {}
+				if (inflight.size > 0) {
+					let timedOut = false;
+					let timerHandle;
+					const timeout = new Promise((resolve) => {
+						timerHandle = setTimeout(() => {
+							timedOut = true;
+							resolve();
+						}, STOP_GRACE_MS);
+					});
+					try {
+						await Promise.race([Promise.allSettled([...inflight]), timeout]);
+					} finally {
+						if (timerHandle !== void 0) clearTimeout(timerHandle);
+					}
+					if (timedOut && inflight.size > 0) console.warn(`rine: defineAgent.stop() grace period (${STOP_GRACE_MS}ms) elapsed with ${inflight.size} handler(s) still running`);
+				}
+			})();
+			return stopPromise;
+		},
+		async [Symbol.asyncDispose]() {
+			await agent.stop();
+		}
+	};
+	if (opts.autoStart !== false) agent.start();
+	return agent;
+}
+//#endregion
+export { APIConnectionError, AgentCardSchema, AgentProfileSchema, AgentReadSchema, AgentSummarySchema, AsyncRineClient, AuthenticationError, AuthorizationError, ConfigError, ConflictError, ConversationScope, ConversationStatus, CryptoError, CursorPage, DecryptedMessageSchema, EncryptionVersion, ErasureResultSchema, GroupMemberSchema, GroupReadSchema, GroupSummarySchema, InternalServerError, InviteResultSchema, JoinRequestReadSchema, JoinRequestStatus, JoinResultSchema, MessageReadSchema, MessageType, NotFoundError, OrgQuotasSchema, OrgReadSchema, PollTokenResponseSchema, QuotaEntrySchema, RESERVED_MESSAGE_TYPES, RateLimitError, RineApiError, RineError, RineEventSchema, RineTimeoutError, SchemaValidationError, SendAndWaitResultSchema, ServiceUnavailableError, ValidationError, VoteChoice, VoteResponseSchema, WebhookCreatedSchema, WebhookDeliveryReadSchema, WebhookJobStatus, WebhookReadSchema, WhoAmISchema, anySignal, asAgentUuid, asGroupUuid, asMessageUuid, asOrgUuid, asWebhookUuid, composeMiddleware, cursorPageSchema, defineAgent, isAgentHandle, isGroupHandle, isValidMessageType, loggingMiddleware, parse, parseCursorPage, parseMessagePlaintext, parsePlaintext, register, timeoutSignal, toAsyncIter, validateSlug, z };