@recursiv/sdk 0.7.79 → 0.7.81

package/dist/index.d.ts

@@ -66,6 +66,7 @@ import { BookmarksResource } from './resources/bookmarks.js';
 import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { SignalsResource } from './resources/signals.js';
+import { SealedResource } from './resources/sealed.js';
 import { RealtimeClient } from './realtime.js';
 import type { RecursivConfig } from './types.js';
 export declare class Recursiv {
@@ -141,6 +142,8 @@ export declare class Recursiv {
     readonly accounts: AccountsResource;
     /** The member's engagement signals (views, dwell, hides, "More like this") for their own ranking. */
     readonly signals: SignalsResource;
+    /** Sealed mode's config and transport: targets, models, allowance, the attestation relay and the sealed send (no crypto; flag-gated). */
+    readonly sealed: SealedResource;
     readonly realtime: RealtimeClient;
     constructor(config?: Partial<RecursivConfig>);
     /**
@@ -219,6 +222,8 @@ export type { BookmarkCollection, BookmarkCollectionInput, BookmarkCollectionKin
 export { AccountsResource } from './resources/accounts.js';
 export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
 export type { SignalBatchResult, SignalEventInput, SignalEventType, SignalNotRecordedReason, SignalRecordResult, SignalSendOptions, } from './resources/signals.js';
+export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
+export type { SealedAllowance, SealedAttestationInput, SealedConfig, SealedModel, SealedSendInput, SealedTarget, SealedTargetKind, SealedTransportErrorCode, } from './resources/sealed.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';
 export type { LinkPreview, LinkPreviewResponse, } from './resources/link-preview.js';
 export type { AgentCapabilityConsentRequirement, AgentCapabilityDataSensitivity, AgentCapabilityDomain, AgentCapabilityExportBoundary, AgentCapabilityRetentionClass, AgentCapabilitySubdomain, AgentCapabilitySubject, AgentCapabilityTrustTier, AgentToolAudience, AgentToolScope, BrowserUseRunTaskInput, ProjectBrainSettings, ProjectToolBundleClassification, ProjectToolBundleKey, ProjectToolPermission, ProjectToolPermissionOverrides, UpdateProjectSettingsInput, } from './resources/project-brain.js';

package/dist/index.js

@@ -67,6 +67,7 @@ import { BookmarksResource } from './resources/bookmarks.js';
 import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { SignalsResource } from './resources/signals.js';
+import { SealedResource } from './resources/sealed.js';
 import { RealtimeClient } from './realtime.js';
 export class Recursiv {
     /** Shared transport, kept so the client name can be set after construction. */
@@ -142,6 +143,8 @@ export class Recursiv {
     accounts;
     /** The member's engagement signals (views, dwell, hides, "More like this") for their own ranking. */
     signals;
+    /** Sealed mode's config and transport: targets, models, allowance, the attestation relay and the sealed send (no crypto; flag-gated). */
+    sealed;
     realtime;
     constructor(config) {
         const client = new HttpClient(config);
@@ -210,6 +213,7 @@ export class Recursiv {
         this.bookmarks = new BookmarksResource(client);
         this.accounts = new AccountsResource(client);
         this.signals = new SignalsResource(client);
+        this.sealed = new SealedResource(client);
         this.realtime = new RealtimeClient(client);
         this.#http = client;
     }
@@ -271,6 +275,7 @@ export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, BookmarksResourc
 export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export { AccountsResource } from './resources/accounts.js';
 export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
+export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';
 export { OrganizationSecurityResource } from './resources/organization-security.js';

package/dist/realtime.d.ts

@@ -14,7 +14,7 @@ export interface ChatMessageEvent {
         isAi?: boolean;
     };
     createdAt: string;
-    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request (MessageMetadata). */
+    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request, and an agent's reply carries `ai`, its AiTurnStamp (MessageMetadata). */
     metadata?: Record<string, unknown>;
 }
 export interface ChatMessageEditEvent {

package/dist/resources/discovery-first-screen.js

@@ -1,4 +1,4 @@
-import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, discoveryLeadable, discoveryModuleLane, discoveryShowsMedia, discoveryTopPlace, isColumnModule, isDiscoveryPostModule, poolDiscoveryGalleries, promotedDiscoveryVideoItems, } from './discovery-merge.js';
+import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, discoveryLeadable, discoveryModuleEngaged, discoveryModuleLane, discoveryShowsMedia, discoveryTopPlace, isColumnModule, isDiscoveryPostModule, poolDiscoveryGalleries, promotedDiscoveryVideoItems, } from './discovery-merge.js';
 // ──────────────────────────────────────────────────────────────────────────
 // Discover's first screen, composed from every source that answered in time.
 // Ported from the Minds app (lib/firstScreen, 2026-10-04).
@@ -15,7 +15,14 @@ import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, di
 //    gallery whose first card has one), from the best of the screen by
 //    engagement (FIRST_SCREEN_LEAD_WINDOW). A story, a suggestion rail, a
 //    video strip or a conversation never leads, and neither does a sensitive
-//    Minds post or an open-network post that links a porn site;
+//    Minds post or an open-network post that links a porn site. Nor does a post
+//    with no picture or clip that nobody engaged with, while the screen holds a
+//    post with either: live (Minds, 2026-10-05, 375x812) Gaming opened on an IGN
+//    link with no votes and a text post nobody had engaged with, both under two
+//    hours old, while it held a voted clip. Fresh posts with no engagement score
+//    as half a typical post, so nine of them ahead of a day-old voted clip put it
+//    past the lead's window. Then the best post with media and engagement leads,
+//    else the best with media, else the best with engagement;
 //  - then the posts by engagement, every source's together
 //    (DiscoveryEngagementMerge), with the network mix as a soft constraint. A
 //    column of several posts goes in from FIRST_SCREEN_FEATURE_SLOT on;
@@ -108,12 +115,22 @@ export function composeFirstScreen(parts, { keepLead = false, now = Date.now() }
     const stories = pooled.filter(module => module !== kept && discoveryModuleLane(module) === DISCOVERY_STORY_LANE);
     const rails = pooled.filter(module => module !== kept && discoveryModuleLane(module) === DISCOVERY_RAIL_LANE);
     // The lead: the top's first post when it is a video that can play; else the best post near the top of the screen's
-    // engagement order that opens on a picture or a video; else the best single post; else the best post.
+    // engagement order that opens on a picture or a video; else the best single post; else the best post. That one is
+    // passed over when it has no picture or clip and nobody engaged with it, for the best post with media and engagement,
+    // else with media, else with engagement, wherever it is in the order.
     const best = merge.rest().filter(mayLead);
-    const lead = kept
-        ?? discoveryTopVideoLead(pooled)
+    const quiet = (module) => !moduleOpensOnPicture(module) && !discoveryModuleEngaged(module);
+    // A kept lead, and the top's playable video, lead as they are: the engagement lanes own the top's order.
+    const owned = kept ?? discoveryTopVideoLead(pooled);
+    const pick = owned
         ?? best.slice(0, FIRST_SCREEN_LEAD_WINDOW).find(moduleOpensOnPicture)
         ?? best.find(module => !isColumnModule(module)) ?? best[0];
+    const lead = !owned && pick && quiet(pick)
+        ? best.find(module => moduleOpensOnPicture(module) && discoveryModuleEngaged(module))
+            ?? best.find(moduleOpensOnPicture)
+            ?? best.find(module => !isColumnModule(module) && discoveryModuleEngaged(module))
+            ?? pick
+        : pick;
     const out = [];
     if (lead) {
         merge.remove(lead);

package/dist/resources/discovery-merge.d.ts

@@ -98,6 +98,8 @@ export declare function isColumnModule(module: DiscoveryModule): boolean;
  * as it is stays as it is. `keep`: a module never pooled (a screen's lead).
  */
 export declare function poolDiscoveryGalleries(modules: readonly DiscoveryModule[], now: number, keep?: DiscoveryModule): DiscoveryModule[];
+/** Someone engaged with one of the module's posts: its counts are known and above zero (an unknown count is no engagement). */
+export declare function discoveryModuleEngaged(module: DiscoveryModule): boolean;
 /**
  * A batch of post modules, taken best first under the network mix's soft constraints (the rules above). Each `take`
  * reads the rows above the place it fills, so it fits the rows a feed already shows.
@@ -127,6 +129,16 @@ export declare class DiscoveryEngagementMerge {
         singles?: boolean;
         newNetwork?: boolean;
     }): DiscoveryModule | undefined;
+    /**
+     * The module for the first post row of a feed, or of the feed it turned to below a line. It opens a feed, so the rows
+     * above it (another feed's, or none) set none of take's network-mix rules: after five rows of another feed with no
+     * Minds post, the home network's floor would put this feed's quiet Minds post first. The floor and the mix hold again
+     * from the row under it. The top of the feed's posts lead in their order, as take has them. Otherwise the best post
+     * the reader may be shown first leads, unless it has no picture or clip and nobody engaged with it while the batch
+     * holds a post that has either: then the best post with media and engagement leads, else the best with media, else
+     * the best with engagement. A column never leads while a single post may.
+     */
+    takeLead(): DiscoveryModule | undefined;
 }
 /** Rows that arrive woven in one by one with the rows not seen yet, below the place a reader has reached: for a feed of one source. */
 export declare function weaveDiscoveryArrival<T extends {
@@ -137,7 +149,9 @@ export declare function weaveDiscoveryArrival<T extends {
  * moves: they go after the last row seen (`reached`, by id, and one more for a row only peeking in), never above `floor`;
  * with nothing seen yet, at the end. Below that place the arriving rows and the rows not seen yet are merged: the rows
  * that are not posts (a story, a rail, a row of the client's own) take the places they would have had woven in one by
- * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge).
+ * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge). The first
+ * post at the top of the feed, or below the line where it turned (`floor`), leads what comes under it (takeLead): never
+ * a post with no picture or clip that nobody engaged with while the batch holds one with either.
  */
 export declare function mergeDiscoveryArrival<T extends {
     id: string;

package/dist/resources/discovery-merge.js

@@ -359,6 +359,21 @@ export function poolDiscoveryGalleries(modules, now, keep) {
     return replaced.size ? modules.flatMap(module => replaced.get(module) ?? [module]) : [...modules];
 }
 const laneOfRow = (row) => (isDiscoveryPostModule(row) ? discoveryModuleLane(row) : null);
+/** A module of posts only, each one the reader may be shown first, never a strip of clips. */
+function mayLeadModule(module) {
+    const presentation = module.presentation;
+    const posts = module.items.filter(isPostItem);
+    return presentation !== 'video' && posts.length > 0 && posts.length === module.items.length && posts.every(discoveryLeadable);
+}
+/** The module opens on a picture or a clip: its first post shows one. */
+function opensOnMedia(module) {
+    const first = module.items[0];
+    return !!first && isPostItem(first) && discoveryShowsMedia(first);
+}
+/** Someone engaged with one of the module's posts: its counts are known and above zero (an unknown count is no engagement). */
+export function discoveryModuleEngaged(module) {
+    return module.items.some(item => isPostItem(item) && (discoveryEngagementPoints(item) ?? 0) > 0);
+}
 /**
  * A batch of post modules, taken best first under the network mix's soft constraints (the rules above). Each `take`
  * reads the rows above the place it fills, so it fits the rows a feed already shows.
@@ -373,7 +388,7 @@ export class DiscoveryEngagementMerge {
         this.left = modules.map((module, index) => {
             const rank = rankDiscoveryModule(module, reference, now) ?? { tier: 1, score: 0 };
             return { module, lane: discoveryModuleLane(module), title: discoveryRowTitle(module), column: isColumnModule(module), top: discoveryTopPlace(module),
-                tier: rank.tier, score: rank.score, order: order ? order(module, index) : index };
+                tier: rank.tier, score: rank.score, order: order ? order(module, index) : index, leads: mayLeadModule(module), media: opensOnMedia(module), engaged: discoveryModuleEngaged(module) };
         }).sort((a, b) => (a.top ?? Number.POSITIVE_INFINITY) - (b.top ?? Number.POSITIVE_INFINITY) || a.tier - b.tier || b.score - a.score || a.order - b.order);
     }
     get size() { return this.left.length; }
@@ -423,6 +438,30 @@ export class DiscoveryEngagementMerge {
             ?? pool[0];
         return pick(chosen);
     }
+    /**
+     * The module for the first post row of a feed, or of the feed it turned to below a line. It opens a feed, so the rows
+     * above it (another feed's, or none) set none of take's network-mix rules: after five rows of another feed with no
+     * Minds post, the home network's floor would put this feed's quiet Minds post first. The floor and the mix hold again
+     * from the row under it. The top of the feed's posts lead in their order, as take has them. Otherwise the best post
+     * the reader may be shown first leads, unless it has no picture or clip and nobody engaged with it while the batch
+     * holds a post that has either: then the best post with media and engagement leads, else the best with media, else
+     * the best with engagement. A column never leads while a single post may.
+     */
+    takeLead() {
+        if (this.left.some(candidate => candidate.top !== null))
+            return this.take([]);
+        const leads = this.left.filter(candidate => candidate.leads && !candidate.column);
+        const best = leads[0];
+        if (!best)
+            return this.take([], { singles: true });
+        const chosen = best.media || best.engaged ? best
+            : leads.find(candidate => candidate.media && candidate.engaged)
+                ?? leads.find(candidate => candidate.media) ?? leads.find(candidate => candidate.engaged);
+        if (!chosen)
+            return this.take([], { singles: true });
+        this.left.splice(this.left.indexOf(chosen), 1);
+        return chosen.module;
+    }
 }
 function weave(first, second) {
     const out = [];
@@ -451,7 +490,9 @@ export function weaveDiscoveryArrival(rows, arriving, reached, floor = 0) {
  * moves: they go after the last row seen (`reached`, by id, and one more for a row only peeking in), never above `floor`;
  * with nothing seen yet, at the end. Below that place the arriving rows and the rows not seen yet are merged: the rows
  * that are not posts (a story, a rail, a row of the client's own) take the places they would have had woven in one by
- * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge).
+ * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge). The first
+ * post at the top of the feed, or below the line where it turned (`floor`), leads what comes under it (takeLead): never
+ * a post with no picture or clip that nobody engaged with while the batch holds one with either.
  */
 export function mergeDiscoveryArrival(rows, arriving, reached, floor = 0, now = Date.now()) {
     const at = arrivalPlace(rows, reached, floor);
@@ -464,12 +505,14 @@ export function mergeDiscoveryArrival(rows, arriving, reached, floor = 0, now =
     const place = new Map(posts.map((module, index) => [module, index]));
     const merge = new DiscoveryEngagementMerge(pooled, { now, order: (module, index) => place.get(module) ?? posts.length + index });
     const out = [...head];
+    let leading = !head.slice(Math.min(floor, head.length)).some(isDiscoveryPostModule);
     for (const row of below) {
         if (!isDiscoveryPostModule(row)) {
             out.push(row);
             continue;
         }
-        const next = merge.take(out);
+        const next = leading ? merge.takeLead() : merge.take(out);
+        leading = false;
         if (next)
             out.push(next);
     }

package/dist/resources/protocols.d.ts

@@ -1721,8 +1721,16 @@ export interface SocialConversation {
     focus: SocialPost;
     /** Oldest available ancestor first, ending with the immediate parent. */
     ancestors: SocialPost[];
-    /** Available direct replies to focus, not all descendants. */
+    /** Available direct replies to focus, not all descendants (from 0.7.81, without `thread`'s first part). */
     replies: SocialPost[];
+    /**
+     * The focus author's own thread below the post, oldest first (0.7.81): a "1/" post's 2/, 3/, 4/ ..., at each level
+     * the earliest reply by the same author, at most 20 parts. Its first part is a direct reply, served here and not in
+     * `replies`, so render `focus`, then `thread`, then `replies`. Each part passes the same app moderation, member
+     * controls and network labels as a reply. It stops at a part this reader does not show (`limited`). Empty when the
+     * author wrote none and on a read of the post alone (`replies: 'none'`); absent from APIs before 0.7.81.
+     */
+    thread?: SocialPost[];
     coverage: 'public_provider_window';
     limited: boolean;
     /**

package/dist/resources/sealed.d.ts

@@ -0,0 +1,144 @@
+import type { HttpClient } from '../client.js';
+/**
+ * Sealed mode's config and transport: where the app sends a sealed request, which targets and models it may use, and
+ * the member's allowance. No crypto lives here, so the SDK stays dependency-free: the app fetches a target's
+ * attestation document through the gateway (`attestation()`), verifies it and seals the body with Recursiv's verifier
+ * (packages/e2ee attest), then hands this resource the sealed bytes. The gateway relays them to the target without
+ * opening them.
+ *
+ * Off unless the API runs with SEALED_GATEWAY_ENABLED and SEALED_GATEWAY_PROJECTS names the app the key is bound to:
+ * until then `config()`, `attestation()` and `send()` throw NotFoundError.
+ *
+ * React Native: the global fetch there (whatwg-fetch) cannot stream. It has no `response.body`, so a streamed answer
+ * cannot be read as it arrives, and it posts a ReadableStream body as the text "[object ReadableStream]". Pass a fetch
+ * that streams, such as expo/fetch's, as `send({ fetch })` for streamed answers or a ReadableStream body.
+ */
+/**
+ * What a target is, which decides how the app attests and seals to it. `router`: Tinfoil's router, which opens the
+ * request inside its enclave and passes it to a model server it picks. The only kind today. A later kind (Tinfoil's
+ * gateway that cannot open bodies, sealing to one model server) may be added: an app must skip a target whose kind it
+ * does not know rather than seal to it.
+ */
+export type SealedTargetKind = 'router';
+/** A server the gateway forwards to. */
+export interface SealedTarget {
+    /** Exact origin, e.g. `https://router-0.tinfoil.sh`. */
+    origin: string;
+    kind: SealedTargetKind;
+}
+/** A model the app offers in Sealed. */
+export interface SealedModel {
+    /** e.g. `gemma4-31b`. */
+    id: string;
+    /**
+     * The targets that serve this model, a subset of `SealedConfig.targets`. The app attests one of these, seals a
+     * request for this model to the key that attestation proves, and names it in `send()`. Lists differ between models
+     * when one has moved to another target, so read it per model.
+     */
+    targets: SealedTarget[];
+}
+/** What `config()` returns. */
+export interface SealedConfig {
+    /** The chat route, relative to the API base: `/sealed/v1/chat/completions`. */
+    chat_completions_path: string;
+    /** The attestation relay, relative to the API base: `/sealed/attestation`. */
+    attestation_path: string;
+    /** Every target the gateway forwards to, chat and attestation alike. */
+    targets: SealedTarget[];
+    /** The models the app offers in Sealed, each with the targets that serve it. */
+    models: SealedModel[];
+    /** The attestation policy version the app's verifier must pin; an older pinned policy means the app needs updating. */
+    verifier_policy_version: number;
+    allowance: SealedAllowance;
+}
+export interface SealedAllowance {
+    requests_per_day: number;
+    requests_per_minute: number;
+    max_concurrent: number;
+    /** The cap on one sealed request body, in bytes. */
+    max_request_bytes: number;
+}
+export interface SealedSendInput {
+    /** The router the app verified and sealed to: the origin of a `router` target from `config()`, exactly. */
+    enclaveOrigin: string;
+    /** The EHBP encapsulated key from sealing the body: 64 hex characters. */
+    encapsulatedKey: string;
+    /** The EHBP-framed sealed body. */
+    body: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
+    /** Ask for a streamed (server-sent events) answer. */
+    stream?: boolean;
+    /** The targets from a config already read. When omitted, `send()` reads the config first. */
+    targets?: readonly SealedTarget[];
+    signal?: AbortSignal;
+    /**
+     * The fetch to send with; the global fetch when omitted. On React Native pass one that streams (expo/fetch's): the
+     * global one there cannot read a streamed answer as it arrives or send a ReadableStream body.
+     */
+    fetch?: typeof fetch;
+}
+export interface SealedAttestationInput {
+    /** The target whose document to fetch: the origin of one of `config().targets`, exactly. */
+    target: string;
+    /** The verifier's fresh challenge: 32 bytes as 64 hex characters. The document must answer it. */
+    nonce: string;
+    /** The targets from a config already read. When omitted, `attestation()` reads the config first. */
+    targets?: readonly SealedTarget[];
+    signal?: AbortSignal;
+}
+/** Why `send()` or `attestation()` refused before or after the request, with nothing shown as the model's words. */
+export type SealedTransportErrorCode = 
+/** The router or target is not one the gateway lists: nothing was sent. */
+'enclave_not_allowed'
+/** The encapsulated key is not 32 bytes of hex: nothing was sent. */
+ | 'bad_encapsulated_key'
+/** The attestation nonce is not 32 bytes of hex: nothing was sent. */
+ | 'bad_nonce'
+/** A 2xx answer without a valid Ehbp-Response-Nonce: its body was discarded unread. */
+ | 'unsealed_answer';
+export declare class SealedTransportError extends Error {
+    readonly code: SealedTransportErrorCode;
+    constructor(code: SealedTransportErrorCode, message: string);
+}
+/** Set on a refusal the gateway wrote itself; a relayed router answer never carries it. */
+export declare const SEALED_REFUSAL_HEADER = "x-sealed-gateway-refusal";
+/**
+ * Requests left in the member's allowance today. The gateway sets it on every answer it relayed from the router and on
+ * no other, and the router cannot set it, so an error without it is one the API (or an edge in front of it) wrote.
+ */
+export declare const SEALED_ALLOWANCE_REMAINING_HEADER = "x-sealed-allowance-remaining";
+export declare class SealedResource {
+    private client;
+    constructor(client: HttpClient);
+    /** The targets, models, verifier policy version and allowance the app needs before it seals anything. */
+    config(): Promise<SealedConfig>;
+    /**
+     * A target's attestation document, fetched through the gateway so Tinfoil sees the gateway's address rather than the
+     * phone's. Returns the document's bytes exactly as the target served them, for the verifier (packages/e2ee attest),
+     * which checks that they answer `nonce`; nothing here reads or trusts them. Asked once, never retried: to try again,
+     * call it again with a fresh nonce.
+     *
+     * Throws SealedTransportError before sending anything when the target is not listed or the nonce is malformed, and a
+     * RecursivError for every answer that is not a document: RateLimitError past the per-minute check limit,
+     * NotFoundError while Sealed is off or not on for this app, and a 502 when the target could not be reached or did not
+     * answer with a document.
+     */
+    attestation(input: SealedAttestationInput): Promise<Uint8Array>;
+    /** The URL `send()` posts to. */
+    chatCompletionsUrl(): string;
+    /**
+     * Sends one sealed chat request through the gateway, once. It never retries: a repeated request runs and is billed
+     * again, and Sealed never falls back to anything else.
+     *
+     * Returns the gateway's Response:
+     * - a sealed answer (`Ehbp-Response-Nonce` set): open it with the context that sealed the request;
+     * - a router error the gateway relayed (it carries X-Sealed-Allowance-Remaining): unauthenticated plaintext when it
+     *   has no nonce, never to be shown as the model's words.
+     *
+     * Throws a RecursivError for every error the API wrote rather than relayed, whether or not it is marked
+     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used` or
+     * `sealed_too_many_requests`) or the API's own per-IP limit (`rate_limited`), AuthenticationError for a revoked or
+     * expired key, NotFoundError while Sealed is off or not on for this app. Throws SealedTransportError when the router
+     * is not listed, the key is malformed, or a 2xx answer came back unsealed.
+     */
+    send(input: SealedSendInput): Promise<Response>;
+}

package/dist/resources/sealed.js

@@ -0,0 +1,195 @@
+import { AuthenticationError, AuthorizationError, NotFoundError, RateLimitError, RecursivError, ValidationError, errorBodyFromResponse, rateLimitDetailsFromResponse, } from '../errors.js';
+export class SealedTransportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SealedTransportError';
+        this.code = code;
+    }
+}
+/** Set on a refusal the gateway wrote itself; a relayed router answer never carries it. */
+export const SEALED_REFUSAL_HEADER = 'x-sealed-gateway-refusal';
+/**
+ * Requests left in the member's allowance today. The gateway sets it on every answer it relayed from the router and on
+ * no other, and the router cannot set it, so an error without it is one the API (or an edge in front of it) wrote.
+ */
+export const SEALED_ALLOWANCE_REMAINING_HEADER = 'x-sealed-allowance-remaining';
+const HEX_32_BYTES = /^[0-9a-fA-F]{64}$/;
+function exactOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+export class SealedResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The targets, models, verifier policy version and allowance the app needs before it seals anything. */
+    async config() {
+        return this.client.get('/sealed/config');
+    }
+    /**
+     * A target's attestation document, fetched through the gateway so Tinfoil sees the gateway's address rather than the
+     * phone's. Returns the document's bytes exactly as the target served them, for the verifier (packages/e2ee attest),
+     * which checks that they answer `nonce`; nothing here reads or trusts them. Asked once, never retried: to try again,
+     * call it again with a fresh nonce.
+     *
+     * Throws SealedTransportError before sending anything when the target is not listed or the nonce is malformed, and a
+     * RecursivError for every answer that is not a document: RateLimitError past the per-minute check limit,
+     * NotFoundError while Sealed is off or not on for this app, and a 502 when the target could not be reached or did not
+     * answer with a document.
+     */
+    async attestation(input) {
+        // Malformed input is refused here, before the config is read, so it never turns into a network error.
+        const origin = exactOrigin(input.target);
+        if (!origin) {
+            throw new SealedTransportError('enclave_not_allowed', 'That server is not one the gateway forwards to. Nothing was sent.');
+        }
+        if (!HEX_32_BYTES.test(input.nonce)) {
+            throw new SealedTransportError('bad_nonce', 'The nonce must be 32 bytes of hex. Nothing was sent.');
+        }
+        const targets = input.targets ?? (await this.config()).targets;
+        if (!targets.some((target) => target.origin === origin)) {
+            throw new SealedTransportError('enclave_not_allowed', 'That server is not one the gateway forwards to. Nothing was sent.');
+        }
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort(input.signal?.reason);
+        if (input.signal?.aborted)
+            controller.abort(input.signal.reason);
+        else
+            input.signal?.addEventListener('abort', onCallerAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(), this.client.requestTimeoutMs);
+        try {
+            const response = await fetch(this.client.buildUrl('/sealed/attestation', { nonce: input.nonce, target: origin }), {
+                method: 'GET',
+                headers: { ...this.client.apiKeyAuthHeader(), Accept: 'application/json' },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw await gatewayRefusal(response);
+            return new Uint8Array(await response.arrayBuffer());
+        }
+        finally {
+            clearTimeout(timer);
+            input.signal?.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    /** The URL `send()` posts to. */
+    chatCompletionsUrl() {
+        return this.client.buildUrl('/sealed/v1/chat/completions');
+    }
+    /**
+     * Sends one sealed chat request through the gateway, once. It never retries: a repeated request runs and is billed
+     * again, and Sealed never falls back to anything else.
+     *
+     * Returns the gateway's Response:
+     * - a sealed answer (`Ehbp-Response-Nonce` set): open it with the context that sealed the request;
+     * - a router error the gateway relayed (it carries X-Sealed-Allowance-Remaining): unauthenticated plaintext when it
+     *   has no nonce, never to be shown as the model's words.
+     *
+     * Throws a RecursivError for every error the API wrote rather than relayed, whether or not it is marked
+     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used` or
+     * `sealed_too_many_requests`) or the API's own per-IP limit (`rate_limited`), AuthenticationError for a revoked or
+     * expired key, NotFoundError while Sealed is off or not on for this app. Throws SealedTransportError when the router
+     * is not listed, the key is malformed, or a 2xx answer came back unsealed.
+     */
+    async send(input) {
+        // Malformed input is refused here, before the config is read, so it never turns into a network error.
+        const origin = exactOrigin(input.enclaveOrigin);
+        if (!origin) {
+            throw new SealedTransportError('enclave_not_allowed', 'That router is not one the gateway forwards to. Nothing was sent.');
+        }
+        if (!HEX_32_BYTES.test(input.encapsulatedKey)) {
+            throw new SealedTransportError('bad_encapsulated_key', 'The encapsulated key must be 32 bytes of hex. Nothing was sent.');
+        }
+        const targets = input.targets ?? (await this.config()).targets;
+        if (!targets.some((target) => target.origin === origin && target.kind === 'router')) {
+            throw new SealedTransportError('enclave_not_allowed', 'That router is not one the gateway forwards to. Nothing was sent.');
+        }
+        // Time out waiting for the answer to start; once it has, a long stream runs until it ends or the caller aborts.
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort(input.signal?.reason);
+        if (input.signal?.aborted)
+            controller.abort(input.signal.reason);
+        else
+            input.signal?.addEventListener('abort', onCallerAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(), this.client.requestTimeoutMs);
+        const fetchImpl = input.fetch ?? fetch;
+        const streamedBody = typeof ReadableStream !== 'undefined' && input.body instanceof ReadableStream;
+        let response;
+        try {
+            response = await fetchImpl(this.chatCompletionsUrl(), {
+                method: 'POST',
+                headers: {
+                    ...this.client.apiKeyAuthHeader(),
+                    'Content-Type': 'application/json',
+                    Accept: input.stream ? 'text/event-stream' : 'application/json',
+                    'Ehbp-Encapsulated-Key': input.encapsulatedKey,
+                    'X-Tinfoil-Enclave-Url': origin,
+                    // For the planned privacy_tier_mismatch 409 (S28 in the Minds AI choices spec): a Standard AI path that
+                    // receives a request marked Sealed is meant to refuse it. No server path reads this header yet, so nothing
+                    // enforces that today; the Sealed gateway strips it before the router.
+                    'X-Recursiv-Privacy-Tier': 'sealed',
+                },
+                body: input.body,
+                signal: controller.signal,
+                ...(streamedBody ? { duplex: 'half' } : {}),
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const detach = () => input.signal?.removeEventListener('abort', onCallerAbort);
+        if (response.headers.has(SEALED_REFUSAL_HEADER)) {
+            detach();
+            throw await gatewayRefusal(response);
+        }
+        const nonce = response.headers.get('ehbp-response-nonce');
+        if (response.ok && (!nonce || !HEX_32_BYTES.test(nonce))) {
+            detach();
+            await response.body?.cancel().catch(() => { });
+            throw new SealedTransportError('unsealed_answer', 'The answer was not sealed, so it was discarded unread.');
+        }
+        // An error the gateway did not relay: the API's 404 while Sealed is off or not on for this app, apiKeyAuth's 401
+        // for a revoked or expired key, the API's per-IP 429, or an edge's own error. None of these is the router's.
+        if (!response.ok && !response.headers.has(SEALED_ALLOWANCE_REMAINING_HEADER)) {
+            detach();
+            throw await gatewayRefusal(response);
+        }
+        if (!response.body)
+            detach();
+        return response;
+    }
+}
+/** A typed error for an answer the API wrote itself (the gateway's refusals and the API's own errors). */
+async function gatewayRefusal(response) {
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Fall through to the generic body for the status.
+    }
+    const err = errorBodyFromResponse(response.status, response.statusText, body);
+    switch (response.status) {
+        case 400:
+            return new ValidationError(err);
+        case 401:
+            return new AuthenticationError(err);
+        case 403:
+            return new AuthorizationError(err);
+        case 404:
+            return new NotFoundError(err);
+        case 429:
+            return new RateLimitError(err, rateLimitDetailsFromResponse(response.headers, err));
+        default:
+            return new RecursivError(response.status, err);
+    }
+}

package/dist/types.d.ts

@@ -723,6 +723,12 @@ export type ConversationEncryptionPolicy = {
 export interface Conversation {
     /** Missing on older APIs: treat as unknown, never as plaintext permission. */
     encryption?: ConversationEncryptionPolicy;
+    /**
+     * Who can read it now, computed by the server from its current members: see
+     * PrivacyTier. Null when no member is an AI agent now; an agent that has left
+     * may have read earlier messages. Omitted by older APIs.
+     */
+    privacy_tier?: PrivacyTier | null;
     id: string;
     type: string;
     name: string | null;
@@ -773,6 +779,8 @@ export interface LeaveConversationResult {
 export interface ConversationDetail {
     /** Missing on older APIs: treat as unknown, never as plaintext permission. */
     encryption?: ConversationEncryptionPolicy;
+    /** As `Conversation.privacy_tier`. Omitted by `createGroup()` and by older APIs. */
+    privacy_tier?: PrivacyTier | null;
     id: string;
     type: string;
     name: string | null;
@@ -914,10 +922,86 @@ export interface MessageMedia {
  *   not encrypted; a withdrawn one leaves the history. The person who did not
  *   ask answers it by starting encryption as usual, from their own device.
  */
-export interface MessageMetadata {
+export interface EncryptionRequestMessageMetadata {
     kind: 'e2ee_start_request';
     v: number;
+    ai?: undefined;
+}
+/**
+ * Who can read a conversation or message now, as the server computes it from
+ * the conversation's current members. Render a label from this value, never
+ * from what the member picked. It is not a history: null says no AI agent is a
+ * member now, not that none ever read the messages, so never show null as
+ * "only people saw this".
+ * - `standard`: an AI agent is in the conversation. The app, Recursiv and the
+ *   AI companies that route and answer each turn can read what is sent there.
+ * - `e2ee`: the conversation carries the MLS transport (`encryption.mode`
+ *   `mls_v2`). Served on the conversation; a `Message` row is never MLS
+ *   content, so a message is never `e2ee`.
+ * - `members_only`, `sealed`, `on_device`: reserved; no API serves them yet.
+ */
+export type PrivacyTier = 'standard' | 'members_only' | 'e2ee' | 'sealed' | 'on_device';
+/** Where a tool's data can go (the same values as `AgentCapabilityExportBoundary`). */
+export type ExportBoundary = 'none' | 'org_internal' | 'third_party_processor' | 'public_network';
+/** One tool the model called on a turn. */
+export interface AiTurnStampTool {
+    name: string;
+    export_boundary: ExportBoundary;
+}
+/**
+ * What answered an agent's reply, written by the server when it saves a reply
+ * a model wrote through its provider chain (`Message.metadata.ai`). Label
+ * replies from this, not from the model the member picked. Some agent
+ * messages carry none (server-written notices and limit replies, messages an
+ * agent sends outside a model turn): read a missing stamp as unknown.
+ */
+export interface AiTurnStamp {
+    /** `standard` for every reply the server runs. */
+    tier: PrivacyTier;
+    /** The model that answered, as `maker/model`, e.g. `google/gemini-3.5-flash`. */
+    model: string;
+    /** The model's maker as its id names it (the part before `/`), or `unknown`. */
+    maker: string;
+    /**
+     * `openrouter`: through OpenRouter, a routing service. `direct`: straight to
+     * the model's maker (Google, Anthropic or OpenAI) at its own API. `other`:
+     * through a service the stamp cannot name, such as an address the app's
+     * operator configured or a host that did not make the model.
+     */
+    route: 'openrouter' | 'direct' | 'other';
+    /** The agent's usage tier on the turn. */
+    budget_tier: 'full' | 'standard' | 'economy' | 'hibernation';
+    /**
+     * Set when a different model answered than the one picked: `budget`, a
+     * smaller one because of usage limits (`model` is that smaller one);
+     * `fallback`, because `from` was not available (the picked model, or the
+     * smaller one a usage limit chose). Null when the picked model answered.
+     */
+    substituted: null | {
+        from: string;
+        reason: 'budget' | 'fallback';
+    };
+    /** Something Minds AI saved (facts, or parts of other chats) went with the turn. */
+    memory_used: boolean;
+    /** Parts of the member's other chats, their summaries or decisions went with the turn. */
+    recall_used: boolean;
+    /** The member's activity (follows, votes, groups, interests) went with the turn. */
+    activity_used: boolean;
+    /**
+     * Every tool the model called on the turn up to this reply, in call order:
+     * page tools and any others, by name, with no arguments (so no addresses). A
+     * tool the server has not classified reads `public_network`.
+     */
+    tools: AiTurnStampTool[];
+}
+/** An agent's reply: what answered it. Served only on a message from an agent (`sender.is_ai`). */
+export interface AgentReplyMessageMetadata {
+    ai: AiTurnStamp;
+    kind?: undefined;
+    v?: undefined;
 }
+/** A message's `metadata`: an encryption request's, or an agent reply's turn stamp. */
+export type MessageMetadata = EncryptionRequestMessageMetadata | AgentReplyMessageMetadata;
 export interface Message {
     id: string;
     content: string;
@@ -928,6 +1012,14 @@ export interface Message {
     created_at: string;
     /** Absent on a person's own message, and from older APIs: see MessageMetadata. */
     metadata?: MessageMetadata;
+    /**
+     * Who can read it now: see PrivacyTier. `standard` on an agent's message, or
+     * while an AI agent is a member of the conversation. Null otherwise, which
+     * does not mean only people read it: a message sent while an agent was a
+     * member went to the AI companies with that agent's turns, and reads null
+     * once the agent leaves. Omitted by older APIs.
+     */
+    privacy_tier?: PrivacyTier | null;
 }
 export interface SendMessageInput {
     conversation_id: string;
@@ -947,7 +1039,7 @@ export interface ChatMessageEvent {
         isAi?: boolean;
     };
     createdAt: string;
-    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request (MessageMetadata). */
+    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request, and an agent's reply carries `ai`, its AiTurnStamp (MessageMetadata). */
     metadata?: Record<string, unknown>;
 }
 export interface ChatMessageEditEvent {

package/llm.md

@@ -512,6 +512,8 @@ Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a
 
 Activity time (0.7.67): conversation rows, `communityConversation()` and `conversation(id)` carry `last_activity_at`, the time `conversations()` sorts by: the newest message, or, in an end-to-end encrypted (`mls_v2`) conversation, the relay's receive time of its newest encrypted message when that is later (membership and key changes and quiet events such as reactions do not move it); its creation when it has no messages. In any other conversation, deleting the newest message moves it back to the previous message (or the creation), so do not keep the later of a cached and a served value. A time only, never content: show it on a row the device cannot decrypt. Omitted by older APIs, and by `conversation(id)` to a member who declined the request.
 
+Who can read it now: conversation rows, `communityConversation()`, `conversation(id)` and each of `messages()` carry `privacy_tier` (`PrivacyTier`), computed by the server from the current members: `standard` where an AI agent is a member, and on an agent's own message (the app, Recursiv and the AI companies that route and answer each turn can read it), `e2ee` for an `mls_v2` conversation (never on a message row), and null when no AI agent is a member now. Null is not a history: messages sent while an agent was a member went to the AI companies with its turns and read null once it leaves, so never show null as "only people saw this". `members_only`, `sealed` and `on_device` are reserved. An agent's reply written by a model through the server's provider chain carries `metadata.ai`, its `AiTurnStamp`: the model that answered and its maker, the route (`openrouter`, `direct` to the maker, or `other`, a service the stamp cannot name), the usage tier, `substituted` (a smaller model for usage limits, or a fallback), whether saved memory, other chats or activity went with the turn, and each tool called by name with its `export_boundary` (no arguments or addresses; an unclassified tool reads `public_network`). Some agent messages carry no stamp (server-written notices, limit replies, messages an agent sends outside a model turn): read a missing stamp as unknown. Label a reply from the stamp, never from the model the member picked. Omitted by older APIs.
+
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
 Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag (otherwise `feature_disabled`) and a key acting as the account owner (agent-scoped keys get `agent_key_not_allowed`). The realm is the network id. Only a direct conversation between two people with an accepted request can start encryption (`conversation_not_eligible` otherwise), and every later append to it is checked the same way again (both people still accepted, still in the pilot, still only the two of them), so a client need not read the policy before each send; a resend of an event already stored still returns `duplicate: true`, even once a Welcome's target device is gone; blocks apply (`blocked`), to resends too; commits must send `expected_commit_seq`.
@@ -829,11 +831,11 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 - Native follows: `nativeFollowState({ accountId, protocol, nativeId })`, `prepareNativeFollow({ clientMutationId, accountId, protocol, nativeId, action: "follow" | "unfollow" })`, `submitNativeFollow(id, { approve: true, event? })`, `nativeFollowStatus(id)`. Show the acting identity and native following/requested/unfollowed state separately from the Minds feed subscription. Nostr must sign the complete review event without dropping other contacts; stale lists require a fresh review. Keep mutation IDs and reconcile ambiguous outcomes without replay. Requires current follow scopes and API `NATIVE_SOCIAL_FOLLOW_PROJECTS` plus source controls.
 - Native reposts: `nativeRepostState({ accountId, protocol, nativeId })`, `prepareNativeRepost({ clientMutationId, accountId, protocol, nativeId, action: "repost" | "unrepost" })`, `submitNativeRepost(id, { approve: true, event? })`, `nativeRepostStatus(id)`. Requires `NATIVE_SOCIAL_REPOST_PROJECTS`, account capability and explicit approval; Nostr signs the exact review (kind 6 or own kind 5). Unknown attempts only reconcile. Bluesky connections need the new repost scope; ActivityPub uses write:statuses. Native likes: `nativeLikeState({ accountId, protocol, nativeId })`, `prepareNativeLike({ clientMutationId, accountId, protocol, nativeId, action: "like" | "unlike" })`, `submitNativeLike(id, { approve: true, event? })`, and `nativeLikeStatus(id)`. Display the selected account, source and action before approval. Only Nostr supplies `event`: sign the exact public `signing.event` in the review; never transmit a private key. Preserve mutation IDs on ambiguous responses and refresh unknown results instead of resending. Read capabilities before offering actions; old reply-only connections need reconnecting for likes. Nostr results describe the connected relay, not every public relay. The app-specific `NATIVE_SOCIAL_LIKE_PROJECTS` switch and source controls must be enabled on the API.
 - Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, media?, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source, exact `wireText` and every reviewed `media` item with its alt text; connection is not publication approval. `media` takes the same `NativeMediaInput[]` as `prepareNativePost` and needs the account's `publish_media` capability. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
-- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. A card (a post shared into a chat, a link preview) asks for the post alone, 0.7.78: `getPublicConversation({ protocol, post, replies: 'none' })` (also `getSharedConversation` and `getConnectedSocialConversation`) answers `focus` with no `ancestors` or `replies` and `repliesStatus: 'not_requested'`; a Nostr note answers from one relay read instead of a whole thread's. An older API answers 400 `invalid_input`: read without it. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
+- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. The author's own thread (0.7.81): `thread` holds the focus author's continuation below the post, oldest first (a "1/" post's 2/, 3/, 4/ ..., at most 20 parts, each held to the same moderation and member controls as a reply); its first part is not repeated in `replies`, so render `focus`, `thread`, then `replies` (`thread ?? []`: older APIs omit it, and a `replies: 'none'` read answers none). A card (a post shared into a chat, a link preview) asks for the post alone, 0.7.78: `getPublicConversation({ protocol, post, replies: 'none' })` (also `getSharedConversation` and `getConnectedSocialConversation`) answers `focus` with no `ancestors` or `replies` and `repliesStatus: 'not_requested'`; a Nostr note answers from one relay read instead of a whole thread's. An older API answers 400 `invalid_input`: read without it. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
   - Native Nostr: `const { data: preview } = await r.protocols.prepareNativeNostr(identityId, { action: "publish", content: draft })`; review and sign the exact public event, then `submitNativeNostr(identityId, { intent: preview.intent, event, approve: true })`. Preparation/submission never auto-retry. After uncertainty, use `getNativeNostrPost(identityId, preview.postId ?? preview.eventId)` before a user-selected retry of the identical intent/event: deletion checks the original note's `postId`, publication checks `eventId`. Check `nativeNostrAccount()` enablement first; keys stay with the signer. For replies, after `nativeNostrAccount()` advertises `reply_text_note`, use `prepareNativeNostr(identityId, { action: "reply", content: draft, parentId: post.nativeId })`. Review returned parent/root/participants/relay and exact event, sign with the connected client signer, then `submitNativeNostr(identityId, { intent, event, approve: true })`. Requires users:read, posts:read and posts:write. Kind1 public notes only; reply enablement and shared UI/live proof remain pending. Do not inherit arbitrary notification tags or relay hints. Signing mutations never auto-retry; check `getNativeNostrPost(identityId, eventId)` after uncertainty before a user-selected identical-event retry.
   - Hosted Bluesky account on the app's own PDS: `const { data } = await r.protocols.createHostedIdentity({ protocol: 'atproto', handle: 'alice', email })`. Only the label is sent; `data.handle` carries the domain and `data.password` is returned this once, never stored. Never auto-retried. Either the account is finished or it is removed again. 409 `handle_unavailable` = choose another label; 503 `handle_dns_unavailable`/`handle_unresolvable`/`handle_unverified` = operator setup, retry later unchanged.
   - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows. Category depth: `r.posts.list({ category: 'science', sort: 'hot', discovery: true })` pages the hot window by offset and then by keyset (`meta.next` is `{ offset }`, `{ cursor }` or `null`; pass a cursor back as `cursor`); when a stage ends, `meta.fallover` lists the next feeds in order (`category_older`, `category_network`, `category` with `via`, `for_you`, `all`; `feed` with `ref` is declared in 0.7.60 but not sent yet, so skip kinds you cannot open). One call for a category's modules: `const { data } = await r.discovery.category({ category: 'science' })` returns `stories`, `network`, `clips`, `people`, `groups`, each `{ items, ms, reason? }`. Watch's Minds videos: `const { data, meta } = await r.discovery.videos({ limit: 12 })` returns public video posts in hot order from a list shared per app (rebuilt about once a minute), each re-checked per call for the viewer; page on `meta.next_cursor`. With no category about one row in four is an open-network clip (0.7.78): `isWatchNetworkClip(row)` tells `{ kind: 'social', id, post: SocialPost }` from a `Post`; open and react to it as the network's post (its `id` is never a Minds id).
-  - Progressive Discover feed (0.7.71): `const feed = r.discovery.createProgressiveFeed({ networks, category, recommend, top: { ref: 'builtin:all' }, seen, seenClusters }); const round = await feed.next(part => draw(part))` opens one `createFeed` session per source (Minds with the radar and suggestions, one per network with `public_trends`) and hands each source's page on as a `DiscoveryPart` (`{ source, round, modules, composed?, mixed? }`) the moment it lands, instead of a page that waits for its slowest network (up to 15 s); a round waits `DISCOVERY_STRAGGLER_MS` past its first answer and rejects only when every source failed. The first load is held until Minds and one other network answered (or `FIRST_SCREEN_MS`, 2.5 s, after the first answer; `firstScreenMs: VISITOR_FIRST_SCREEN_MS` for a visitor) and arrives as one `composed: true` part from `composeFirstScreen`: the top's first post when it is a playable video, else a picture lead from the best 8 by engagement (never a story, rail, video strip, column, `isSensitivePost` post or `linksAdultSite` porn link), then every network's posts by engagement (`DiscoveryEngagementMerge`) with row 2 from another network than the lead's when one is left (`FIRST_SCREEN_NETWORK_ROWS`), a story as row 3 and a rail as row 5, nothing dropped. Merge later `mixed` parts with `mergeDiscoveryArrival(rows, arriving, reachedIds)`. `top`/`seen`/`seenClusters`/`bucket` reach every session; the top is read once per open. Also `retryFailed()`, `onStatus(listener)`, `setNetworks(catalog)`; settings `perSource`, `firstScreen`, `onLanded`. For you: `createProgressiveFeed({ createFeed: o => r.discovery.createPersonalFeed(o) }, options, { perSource: false })`. A session's `seen` now also leaves seen network posts out of trend pages, previews and topic pages; in a category a topic page with nothing new ends its topic and after `DISCOVERY_EMPTY_TOPIC_PAGES` (3) in a row the network's other topics are skipped.
+  - Progressive Discover feed (0.7.71): `const feed = r.discovery.createProgressiveFeed({ networks, category, recommend, top: { ref: 'builtin:all' }, seen, seenClusters }); const round = await feed.next(part => draw(part))` opens one `createFeed` session per source (Minds with the radar and suggestions, one per network with `public_trends`) and hands each source's page on as a `DiscoveryPart` (`{ source, round, modules, composed?, mixed? }`) the moment it lands, instead of a page that waits for its slowest network (up to 15 s); a round waits `DISCOVERY_STRAGGLER_MS` past its first answer and rejects only when every source failed. The first load is held until Minds and one other network answered (or `FIRST_SCREEN_MS`, 2.5 s, after the first answer; `firstScreenMs: VISITOR_FIRST_SCREEN_MS` for a visitor) and arrives as one `composed: true` part from `composeFirstScreen`: the top's first post when it is a playable video, else a picture lead from the best 8 by engagement (never a story, rail, video strip, column, `isSensitivePost` post or `linksAdultSite` porn link; 0.7.80: never a post with no picture or clip and no engagement while the screen holds one with either, which then leads: media and engagement, else media, else engagement, as `mergeDiscoveryArrival` leads a feed's top and the feed after a line), then every network's posts by engagement (`DiscoveryEngagementMerge`) with row 2 from another network than the lead's when one is left (`FIRST_SCREEN_NETWORK_ROWS`), a story as row 3 and a rail as row 5, nothing dropped. Merge later `mixed` parts with `mergeDiscoveryArrival(rows, arriving, reachedIds)`. `top`/`seen`/`seenClusters`/`bucket` reach every session; the top is read once per open. Also `retryFailed()`, `onStatus(listener)`, `setNetworks(catalog)`; settings `perSource`, `firstScreen`, `onLanded`. For you: `createProgressiveFeed({ createFeed: o => r.discovery.createPersonalFeed(o) }, options, { perSource: false })`. A session's `seen` now also leaves seen network posts out of trend pages, previews and topic pages; in a category a topic page with nothing new ends its topic and after `DISCOVERY_EMPTY_TOPIC_PAGES` (3) in a row the network's other topics are skipped.
   - Viral read (0.7.59; off until the server enables it for the app): `const { data } = await r.protocols.getPublicViral({ media: 'video', category: 'science', limit: 20 })` (member key, users:read + posts:read, never cached) or keyless `visitor.protocols.getSharedViral(projectId, { media: 'video', compass: 'hide' })` (visitors send compass `all` or `hide` only). Params, all optional: `network` (all, minds, bluesky, activitypub, nostr), `category`, `media: 'video'`, `limit` 5/10/20/40, `cursor` (the last page's; a cursor whose 30-minute build expired ends the list), `compass`. Each item: `key` (stable; drop ones already shown), `protocol`, `post` (checking `protocol` narrows it: `ViralMindsCard` for minds, open at /post/:id; otherwise a `SocialPost`), `label` viral/rising/hot, `score`, `rank`, `category`, `velocity` (show counts with `countsReportedBy` as reported, never verified), `spread`. A visitor's read serves media only where the server cleared it, so even with `media: 'video'` some items arrive with the video withheld (empty `media`): `import { viralItemHasVideo } from '@recursiv/sdk'` and keep `data.items.filter(viralItemHasVideo)` before a vertical video player. `status` ok/building/screening/off: off resolves with no items, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401/403 (never off), so catch it and skip that step.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor?, compass?, media? })` (`compass: 'hide'` leaves out politics, 0.7.62; `media: 'video'`, 0.7.73, Bluesky: the network's own window of video posts, a `kind: posts` page paged by its cursor, no category or layout, 404 `unsupported_protocol` for a network without one, 400 on an API that predates it; keyless `getSharedTrends(projectId, { ..., media: 'video' })` holds only clips a visitor may see and counts the rest in `mediaFilter.withheld`); render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.
   - One outlet count per story (0.7.71): a radar story (list, story read, archive), a World Today story (`outlets`, with `outlet_count` its total and `lane_mix` its lanes), a category strip story, a `feeds.top`/`feeds.stories` story and a search story carry `outlets: { total, mainstream, independent, other }`, the distinct outlets of the articles the story lists (an allow-listed outlet once, an unlisted host in `other`; the buckets sum to `total`). Show `outlets.total`; `sources.outlet` counts articles. `DiscoveryCluster.outletCount` reads it. An older server omits it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.79",
+  "version": "0.7.81",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",