@recursiv/sdk 0.7.13 → 0.7.15

package/dist/resources/organization-settings.d.ts

@@ -45,6 +45,22 @@ export interface AllowPublicSignupResult {
     allow_public_signup: boolean;
     updated_at: string;
 }
+/**
+ * "How do we know its work is done?" — the org's answer for every task:
+ * `off` takes the agent's word, `warn` runs the task's checks and records a
+ * warning on failure without blocking, `require` refuses a close until every
+ * thresholded check passes.
+ */
+export type TaskClosePolicy = 'off' | 'warn' | 'require';
+export interface SetTaskClosePolicyInput {
+    task_close_policy: TaskClosePolicy;
+}
+export interface TaskClosePolicyResult {
+    id: string;
+    organization_id: string;
+    task_close_policy: TaskClosePolicy;
+    updated_at: string;
+}
 export interface SetPreferredContactEmailInput {
     preferred_contact_email: string | null;
 }
@@ -84,6 +100,8 @@ export declare class OrganizationSettingsResource {
     constructor(client: HttpClient);
     /** Get organization settings */
     get(organizationId: string): Promise<SingleResponse<OrganizationSettingsData | null>>;
+    /** Set how the org treats a task's checks at close: off | warn | require. Owner only. */
+    setTaskClosePolicy(organizationId: string, input: SetTaskClosePolicyInput): Promise<SingleResponse<TaskClosePolicyResult>>;
     /** Set default template for the organization */
     setDefaultTemplate(organizationId: string, input: SetDefaultTemplateInput): Promise<SingleResponse<DefaultTemplateResult>>;
     /** Set global content access for the organization */
@@ -112,4 +130,3 @@ export declare class OrganizationSettingsResource {
         success: true;
     }>>;
 }
-//# sourceMappingURL=organization-settings.d.ts.map

package/dist/resources/organization-settings.js

@@ -7,6 +7,10 @@ export class OrganizationSettingsResource {
     get(organizationId) {
         return this.client.get(`/organization-settings/${organizationId}/settings`);
     }
+    /** Set how the org treats a task's checks at close: off | warn | require. Owner only. */
+    setTaskClosePolicy(organizationId, input) {
+        return this.client.put(`/organization-settings/${organizationId}/settings/task-close-policy`, input);
+    }
     /** Set default template for the organization */
     setDefaultTemplate(organizationId, input) {
         return this.client.put(`/organization-settings/${organizationId}/settings/default-template`, input);
@@ -49,4 +53,3 @@ export class OrganizationSettingsResource {
         return this.client.post(`/organization-settings/${organizationId}/settings/github/disconnect`);
     }
 }
-//# sourceMappingURL=organization-settings.js.map

package/dist/resources/organizations.d.ts

@@ -120,4 +120,3 @@ interface ProvisionedAgent {
     username: string;
 }
 export {};
-//# sourceMappingURL=organizations.d.ts.map

package/dist/resources/organizations.js

@@ -82,4 +82,3 @@ export class OrganizationsResource {
         return this.client.delete(`/organizations/${id}/provision-agents`);
     }
 }
-//# sourceMappingURL=organizations.js.map

package/dist/resources/posts.d.ts

@@ -27,4 +27,3 @@ export declare class PostsResource {
         success: true;
     }>>;
 }
-//# sourceMappingURL=posts.d.ts.map

package/dist/resources/posts.js

@@ -40,4 +40,3 @@ export class PostsResource {
         return this.client.delete(`/posts/${postId}/reactions`);
     }
 }
-//# sourceMappingURL=posts.js.map

package/dist/resources/profiles.d.ts

@@ -36,10 +36,17 @@ export declare class ProfilesResource {
     isFollowing(userId: string): Promise<SingleResponse<{
         is_following: boolean;
     }>>;
+    /**
+     * Channels related to a profile, ranked by co-follow: accounts that the
+     * profile's followees also follow. Suggestion list, so the caller's own
+     * follows are left out.
+     */
+    related(userId: string, params?: {
+        limit?: number;
+    }): Promise<PaginatedResponse<LeaderboardEntry>>;
     /** Get engagement leaderboard */
     leaderboard(params?: {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedResponse<LeaderboardEntry>>;
 }
-//# sourceMappingURL=profiles.d.ts.map

package/dist/resources/profiles.js

@@ -47,9 +47,16 @@ export class ProfilesResource {
     isFollowing(userId) {
         return this.client.get(`/profiles/${userId}/is-following`);
     }
+    /**
+     * Channels related to a profile, ranked by co-follow: accounts that the
+     * profile's followees also follow. Suggestion list, so the caller's own
+     * follows are left out.
+     */
+    related(userId, params) {
+        return this.client.get(`/profiles/${userId}/related`, params);
+    }
     /** Get engagement leaderboard */
     leaderboard(params) {
         return this.client.get('/profiles/leaderboard', params);
     }
 }
-//# sourceMappingURL=profiles.js.map

package/dist/resources/project-brain.d.ts

@@ -246,6 +246,24 @@ export declare class ProjectBrainResource {
     sandboxUrl(projectId: string, params?: {
         port?: number;
     }): Promise<SingleResponse<unknown>>;
+    /**
+     * Run one shell command in the project sandbox and return what it printed.
+     *
+     * The operator's window into their own sandbox. `execute_command` is a prompt
+     * runner for agents; this is a shell for the human who owns the project —
+     * ground truth about the checkout, the processes, and the logs without
+     * routing every question through an AI.
+     */
+    sandboxShell(projectId: string, input: {
+        command: string;
+        cwd?: string;
+        timeout_ms?: number;
+    }): Promise<SingleResponse<{
+        exit_code: number;
+        stdout: string;
+        stderr: string;
+        truncated: boolean;
+    }>>;
     /** Get project settings */
     getSettings(projectId: string): Promise<SingleResponse<ProjectBrainSettings>>;
     /** Inspect a rendered web page in a real browser */
@@ -289,4 +307,3 @@ export declare class ProjectBrainResource {
     /** Get project usage stats */
     usage(projectId: string): Promise<SingleResponse<ProjectUsage>>;
 }
-//# sourceMappingURL=project-brain.d.ts.map

package/dist/resources/project-brain.js

@@ -35,6 +35,17 @@ export class ProjectBrainResource {
     sandboxUrl(projectId, params) {
         return this.client.get(`/projects/${projectId}/brain/sandbox-url`, params);
     }
+    /**
+     * Run one shell command in the project sandbox and return what it printed.
+     *
+     * The operator's window into their own sandbox. `execute_command` is a prompt
+     * runner for agents; this is a shell for the human who owns the project —
+     * ground truth about the checkout, the processes, and the logs without
+     * routing every question through an AI.
+     */
+    sandboxShell(projectId, input) {
+        return this.client.post(`/projects/${projectId}/brain/sandbox-shell`, input);
+    }
     /** Get project settings */
     getSettings(projectId) {
         return this.client.get(`/projects/${projectId}/brain/settings`);
@@ -84,4 +95,3 @@ export class ProjectBrainResource {
         return this.client.get(`/projects/${projectId}/brain/usage`);
     }
 }
-//# sourceMappingURL=project-brain.js.map

package/dist/resources/project-settings.d.ts

@@ -51,4 +51,3 @@ export declare class ProjectSettingsResource {
      */
     setAllowPublicSignup(projectId: string, input: SetAllowPublicSignupInput): Promise<SingleResponse<AllowPublicSignupResult>>;
 }
-//# sourceMappingURL=project-settings.d.ts.map

package/dist/resources/project-settings.js

@@ -26,4 +26,3 @@ export class ProjectSettingsResource {
         return this.client.put(`/projects/${projectId}/settings/allow-public-signup`, input);
     }
 }
-//# sourceMappingURL=project-settings.js.map

package/dist/resources/projects.d.ts

@@ -42,4 +42,3 @@ export declare class ProjectsResource {
     }): Promise<SingleResponse<DeploymentLogs>>;
 }
 export {};
-//# sourceMappingURL=projects.d.ts.map

package/dist/resources/projects.js

@@ -56,4 +56,3 @@ export class ProjectsResource {
         return this.client.get(`/projects/${projectId}/deployments/${deploymentId}/logs`, params);
     }
 }
-//# sourceMappingURL=projects.js.map

package/dist/resources/protocols.d.ts

@@ -76,6 +76,47 @@ export interface ProtocolCollectionStatus {
     last_collected: string | null;
     candidate_count: number;
 }
+/** A bounded, unpublished source preview. Render content as plain text, not HTML. */
+export interface ProtocolQuarantinedCandidate {
+    id: string;
+    provider: string;
+    /** Safe IDs are byte-exact; null means unsafe or malformed provenance was withheld. */
+    external_id: string | null;
+    state: 'quarantined';
+    title: string | null;
+    content: string;
+    content_format: 'plain';
+    content_truncated: boolean;
+    source_url: string | null;
+    author: {
+        /** Null when absent or withheld as unsafe/malformed; never a synthesized identity. */
+        native_id: string | null;
+        handle: string | null;
+        display_name: string | null;
+        profile_url: string | null;
+    };
+    published_at: string | null;
+    observed_at: string;
+    created_at: string;
+}
+/** App/network scope comes only from the authenticated project-bound key. */
+export interface ListProtocolCandidatesParams {
+    protocol?: string;
+    /** Page size, default 20 and maximum 50; enforced by the API. */
+    limit?: number;
+    /** Opaque cursor from this endpoint's previous page; never an offset. */
+    cursor?: string;
+}
+/** Candidate reads use cursor-only pagination, not the SDK's offset PaginationMeta. */
+export interface ProtocolCandidatePageMeta {
+    limit: number;
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface ProtocolCandidateListResponse {
+    data: ProtocolQuarantinedCandidate[];
+    meta: ProtocolCandidatePageMeta;
+}
 export interface ProtocolSettingsUpdateResult {
     success: true;
     protocol_settings: Omit<ProtocolSettings, 'available_protocols'>;
@@ -87,6 +128,19 @@ export declare class ProtocolsResource {
     list(): Promise<SingleResponse<ProtocolAdapterMetadata[]>>;
     /** Get project-scoped unpublished candidate status (admin) */
     status(): Promise<SingleResponse<ProtocolCollectionStatus[]>>;
+    /**
+     * Read quarantined candidates for the key's app. Requires admin scope, a
+     * project-bound key, a live admin role, and existing project-admin access.
+     * Does not collect, publish, or change settings. API errors (including an
+     * unsupported deployed route) propagate; they are never an empty page.
+     */
+    listCandidates(params?: ListProtocolCandidatesParams): Promise<ProtocolCandidateListResponse>;
+    /**
+     * Read one quarantined candidate under the same authorization as listCandidates.
+     * Empty and URL dot-segment IDs reject with ValidationError before any request;
+     * all other IDs are encoded as one path segment and validated by the API.
+     */
+    getCandidate(id: string): Promise<SingleResponse<ProtocolQuarantinedCandidate>>;
     /** Cross-protocol full-text search */
     search(params: SearchParams): Promise<PaginatedResponse<ProtocolSearchResult>>;
     /** Get protocol settings for the authenticated project (admin) */
@@ -97,4 +151,3 @@ export declare class ProtocolsResource {
     updateSettings(input: UpdateSettingsInput): Promise<SingleResponse<ProtocolSettingsUpdateResult>>;
 }
 export {};
-//# sourceMappingURL=protocols.d.ts.map

package/dist/resources/protocols.js

@@ -1,3 +1,4 @@
+import { ValidationError } from '../errors.js';
 /** Canonical protocol operation names returned by the adapter registry. */
 export const PROTOCOL_CAPABILITY_OPERATIONS = Object.freeze([
     'discover',
@@ -40,6 +41,34 @@ export class ProtocolsResource {
     status() {
         return this.client.get('/protocols/status');
     }
+    /**
+     * Read quarantined candidates for the key's app. Requires admin scope, a
+     * project-bound key, a live admin role, and existing project-admin access.
+     * Does not collect, publish, or change settings. API errors (including an
+     * unsupported deployed route) propagate; they are never an empty page.
+     */
+    listCandidates(params) {
+        return this.client.get('/protocols/candidates', params ? {
+            protocol: params.protocol,
+            limit: params.limit,
+            cursor: params.cursor,
+        } : undefined);
+    }
+    /**
+     * Read one quarantined candidate under the same authorization as listCandidates.
+     * Empty and URL dot-segment IDs reject with ValidationError before any request;
+     * all other IDs are encoded as one path segment and validated by the API.
+     */
+    async getCandidate(id) {
+        if (typeof id !== 'string' || !id.trim() || id === '.' || id === '..') {
+            throw new ValidationError({
+                type: 'validation_error',
+                code: 'invalid_candidate_id',
+                message: 'Candidate ID must be a non-empty identifier, not a URL dot segment.',
+            });
+        }
+        return this.client.get(`/protocols/candidates/${encodeURIComponent(id)}`);
+    }
     /** Cross-protocol full-text search */
     search(params) {
         return this.client.get('/protocols/search', params);
@@ -57,4 +86,3 @@ export class ProtocolsResource {
         return this.client.put('/protocols/settings', input);
     }
 }
-//# sourceMappingURL=protocols.js.map

package/dist/resources/reports.d.ts

@@ -48,4 +48,3 @@ export declare class ReportsResource {
         success: true;
     }>>;
 }
-//# sourceMappingURL=reports.d.ts.map

package/dist/resources/reports.js

@@ -24,4 +24,3 @@ export class ReportsResource {
         return this.client.post(`/reports/${encodeURIComponent(reportId)}/dismiss`);
     }
 }
-//# sourceMappingURL=reports.js.map

package/dist/resources/sandbox.d.ts

@@ -9,4 +9,3 @@ export declare class SandboxResource {
      */
     execute(input: SandboxExecuteInput): Promise<SandboxResponse>;
 }
-//# sourceMappingURL=sandbox.d.ts.map

package/dist/resources/sandbox.js

@@ -11,4 +11,3 @@ export class SandboxResource {
         return this.client.post('/sandbox/try', input);
     }
 }
-//# sourceMappingURL=sandbox.js.map

package/dist/resources/settings.d.ts

@@ -63,4 +63,3 @@ export declare class SettingsResource {
         offset?: number;
     }): Promise<PaginatedResponse<LoginHistoryEntry>>;
 }
-//# sourceMappingURL=settings.d.ts.map

package/dist/resources/settings.js

@@ -93,4 +93,3 @@ export class SettingsResource {
         return this.client.get('/settings/login-history', params);
     }
 }
-//# sourceMappingURL=settings.js.map

package/dist/resources/simulator.d.ts

@@ -17,4 +17,3 @@ export declare class SimulatorResource {
     failures(): Promise<SingleResponse<unknown>>;
 }
 export {};
-//# sourceMappingURL=simulator.d.ts.map

package/dist/resources/simulator.js

@@ -20,4 +20,3 @@ export class SimulatorResource {
         return this.client.get('/simulator/failures');
     }
 }
-//# sourceMappingURL=simulator.js.map

package/dist/resources/storage.d.ts

@@ -94,4 +94,3 @@ export declare class StorageResource {
     /** Delete an object or folder from a bucket */
     deleteObject(params: DeleteObjectParams): Promise<SuccessResponse>;
 }
-//# sourceMappingURL=storage.d.ts.map

package/dist/resources/storage.js

@@ -40,4 +40,3 @@ export class StorageResource {
         return this.client.delete(`/storage/objects?project_id=${params.project_id}&bucket_name=${params.bucket_name}&key=${encodeURIComponent(params.key)}`);
     }
 }
-//# sourceMappingURL=storage.js.map

package/dist/resources/swarms.d.ts

@@ -107,4 +107,3 @@ export declare class SwarmsResource {
     /** Cancel a scheduled task */
     cancelSchedule(taskId: string, agentId: string): Promise<SingleResponse<ScheduledTask>>;
 }
-//# sourceMappingURL=swarms.d.ts.map

package/dist/resources/swarms.js

@@ -57,4 +57,3 @@ export class SwarmsResource {
         return this.client.post(`/swarms/schedules/${taskId}/cancel`, { agent_id: agentId });
     }
 }
-//# sourceMappingURL=swarms.js.map

package/dist/resources/tags.d.ts

@@ -16,4 +16,3 @@ export declare class TagsResource {
     delete(id: string): Promise<DeleteResponse>;
 }
 export {};
-//# sourceMappingURL=tags.d.ts.map

package/dist/resources/tags.js

@@ -20,4 +20,3 @@ export class TagsResource {
         return this.client.delete(`/tags/${id}`);
     }
 }
-//# sourceMappingURL=tags.js.map

package/dist/resources/templates.d.ts

@@ -59,4 +59,3 @@ export declare class TemplatesResource {
         author_agent_id?: string;
     }): Promise<SingleResponse<Template>>;
 }
-//# sourceMappingURL=templates.d.ts.map

package/dist/resources/templates.js

@@ -33,4 +33,3 @@ export class TemplatesResource {
         return this.client.post(`/templates/${id}/fork`, input ?? {});
     }
 }
-//# sourceMappingURL=templates.js.map

package/dist/resources/uploads.d.ts

@@ -61,4 +61,3 @@ export declare class UploadsResource {
     confirmOrgLogoUpload(organizationId: string, key: string): Promise<SingleResponse<ConfirmResult>>;
 }
 export {};
-//# sourceMappingURL=uploads.d.ts.map

package/dist/resources/uploads.js

@@ -103,4 +103,3 @@ export class UploadsResource {
         return this.client.post('/uploads/org-logo-confirm', { organization_id: organizationId, key });
     }
 }
-//# sourceMappingURL=uploads.js.map

package/dist/resources/users.d.ts

@@ -12,4 +12,3 @@ export declare class UsersResource {
     /** List users that a user is following */
     following(id: string, params?: PaginationParams): Promise<PaginatedResponse<FollowUser>>;
 }
-//# sourceMappingURL=users.d.ts.map

package/dist/resources/users.js

@@ -20,4 +20,3 @@ export class UsersResource {
         return this.client.get(`/users/${id}/following`, params);
     }
 }
-//# sourceMappingURL=users.js.map

package/dist/resources/video.d.ts

@@ -49,4 +49,3 @@ export declare class VideoResource {
         data: VideoPlaybackToken;
     }>;
 }
-//# sourceMappingURL=video.d.ts.map

package/dist/resources/video.js

@@ -20,4 +20,3 @@ export class VideoResource {
         return this.client.post(`/video/${playbackId}/playback-token`);
     }
 }
-//# sourceMappingURL=video.js.map

package/dist/resources/wallet.d.ts

@@ -31,6 +31,12 @@ interface MasterAddressResult {
 interface MnemonicResult {
     mnemonic: string;
 }
+export interface PayoutState {
+    status: 'none' | 'pending' | 'eligible' | 'restricted';
+    details_submitted: boolean;
+    payouts_enabled: boolean;
+    country: string | null;
+}
 export declare class WalletResource {
     private client;
     constructor(client: HttpClient);
@@ -38,6 +44,16 @@ export declare class WalletResource {
     getMyWallet(): Promise<SingleResponse<WalletInfo>>;
     /** Get wallet balance for the current user */
     getBalance(): Promise<SingleResponse<WalletBalance>>;
+    /** USD payout eligibility for the current app user (Stripe Connect). */
+    getPayouts(): Promise<SingleResponse<PayoutState>>;
+    /** Start or resume payout onboarding. Open the returned URL in a browser. */
+    startPayoutOnboarding(returnUrl: string, refreshUrl: string): Promise<SingleResponse<{
+        url: string;
+    }>>;
+    /** One-time link to the Stripe Express dashboard for an onboarded user. */
+    payoutLoginLink(): Promise<SingleResponse<{
+        url: string;
+    }>>;
     /** Send ETH from the current user's wallet */
     send(toAddress: string, amountEth: string): Promise<SingleResponse<unknown>>;
     /** Check wallet system configuration (admin) */
@@ -54,4 +70,3 @@ export declare class WalletResource {
     generateMnemonic(): Promise<SingleResponse<MnemonicResult>>;
 }
 export {};
-//# sourceMappingURL=wallet.d.ts.map

package/dist/resources/wallet.js

@@ -11,6 +11,18 @@ export class WalletResource {
     getBalance() {
         return this.client.get('/wallet/balance');
     }
+    /** USD payout eligibility for the current app user (Stripe Connect). */
+    getPayouts() {
+        return this.client.get('/wallet/payouts');
+    }
+    /** Start or resume payout onboarding. Open the returned URL in a browser. */
+    startPayoutOnboarding(returnUrl, refreshUrl) {
+        return this.client.post('/wallet/payouts/onboard', { return_url: returnUrl, refresh_url: refreshUrl });
+    }
+    /** One-time link to the Stripe Express dashboard for an onboarded user. */
+    payoutLoginLink() {
+        return this.client.post('/wallet/payouts/login-link', {});
+    }
     /** Send ETH from the current user's wallet */
     send(toAddress, amountEth) {
         return this.client.post('/wallet/send', { to_address: toAddress, amount_eth: amountEth });
@@ -40,4 +52,3 @@ export class WalletResource {
         return this.client.post('/wallet/generate-mnemonic');
     }
 }
-//# sourceMappingURL=wallet.js.map

package/dist/resources/webhooks.d.ts

@@ -26,4 +26,3 @@ export declare class WebhooksResource {
     /** Delete a webhook registration */
     delete(id: string): Promise<DeleteResponse>;
 }
-//# sourceMappingURL=webhooks.d.ts.map

package/dist/resources/webhooks.js

@@ -16,4 +16,3 @@ export class WebhooksResource {
         return this.client.delete(`/webhooks/${id}`);
     }
 }
-//# sourceMappingURL=webhooks.js.map

package/dist/types.d.ts

@@ -204,6 +204,15 @@ export interface Community {
     member_count: number;
     created_at: string;
 }
+/** Filters accepted by the communities directory. */
+export interface ListCommunitiesParams extends PaginationParams {
+    /** Restrict the result to communities the authenticated caller has joined. */
+    member?: boolean;
+    /** Restrict personal keys to one organization. Project-bound keys are already scoped. */
+    organization_id?: string;
+    /** Server-side directory ordering. */
+    sort?: 'members' | 'active' | 'newest';
+}
 export interface CommunityDetail extends Community {
     post_count: number;
 }
@@ -217,6 +226,17 @@ export interface CommunityMember {
     role: string;
     joined_at: string;
 }
+export interface CommunityBannedMember {
+    id: string;
+    name: string;
+    username: string;
+    image: string | null;
+    bio: string | null;
+    is_ai: boolean;
+    role: string;
+    banned_at: string;
+    banned_reason: string | null;
+}
 export interface CreateCommunityInput {
     name: string;
     slug: string;
@@ -615,6 +635,20 @@ export interface AgentConversation {
     } | null;
     created_at: string;
 }
+/** One message in an agent conversation, as returned by `conversationMessages`. */
+export interface AgentConversationMessage {
+    id: string;
+    content: string | null;
+    /** Tool calls and structured data. Usually where a failure's real cause is recorded. */
+    metadata: unknown | null;
+    sender: {
+        id: string;
+        name: string;
+        username: string;
+        is_ai: boolean;
+    } | null;
+    created_at: string;
+}
 export interface CreateTagInput {
     name: string;
     description?: string;
@@ -824,4 +858,3 @@ export interface RecursivConfig {
      */
     clientName?: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,3 +1,2 @@
 // ── Shared ──
 export {};
-//# sourceMappingURL=types.js.map

package/llm.md

@@ -228,7 +228,28 @@ const { data: step } = await r.evidence.recordDetail({ type: 'swarm', id: swarmI
 //       tool_call  → { toolName, args, result, success }
 ```
 
-Methods: `createEval` (code | judge | match | consensus), `simulate`, `listRuns`, `getRun`, `summary`, `records`, `recordDetail`. Eval types: `code` (rule), `judge` (rubric, reference-free — use a different model family), `match` (vs known answer), `consensus` (cross-model agreement; premium). `records` is the continuous activity ledger (every model + tool call); `recordDetail` is the drill-down behind one event (exact prompt/reasoning, or exact tool inputs/outputs).
+### Task checks — how the org knows a task's work is done
+
+```typescript
+// Declare the proof when the task is created (Index vocabulary):
+// machine_checked | expert_graded | scenario_tested | field_tested | exempt
+const { data: task } = await r.dispatcher.createTask({ title: 'Fix the login redirect', proof_type: 'machine_checked' })
+
+// Attach a check to the task at claim time, before the work, so it runs RED first.
+// `check` reads GitHub: the PR named in the close evidence must be merged and the named CI check green.
+await r.evidence.createEval({ target: { type: 'task', id: task.id }, name: 'ci', type: 'check', definition: { check: 'unit-tests' }, threshold: 100 })
+await r.evidence.runTaskChecks(task.id)            // { passed, failed, errored, results } — red now
+// ...do the work, release with pr_urls, then:
+await r.evidence.runTaskChecks(task.id)            // green once the PR merged and CI passed
+await r.dispatcher.complete(task.id, { notes: 'PR #123 merged' })
+// Under the org's "Check and block" policy a close with a failing check is refused with 409 and the names;
+// under "Check and flag" it closes and `data.check_warnings` lists them; under "Take its word" checks are not consulted.
+// A check counts as passed only if an earlier run of it failed on the same task (red-first).
+await r.dispatcher.complete(task.id, { override_reason: 'check misconfigured; work verified by hand' }) // closes anyway, logged permanently
+await r.organizationSettings.setTaskClosePolicy(orgId, 'warn')  // off | warn | require
+```
+
+Methods: `createEval` (code | judge | match | consensus | check), `runTaskChecks`, `simulate`, `listRuns` (`target_type: 'task'` for a task's runs), `getRun`, `summary`, `records`, `recordDetail`. Eval types: `code` (rule), `judge` (rubric, reference-free — use a different model family), `match` (vs known answer), `consensus` (cross-model agreement; premium). `records` is the continuous activity ledger (every model + tool call); `recordDetail` is the drill-down behind one event (exact prompt/reasoning, or exact tool inputs/outputs).
 
 ---
 
@@ -459,6 +480,8 @@ Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `
 
 Provides persistent real-time streaming and chat presence, useful for building frontends (e.g. React Native, Web).
 
+Requires the optional peer `socket.io-client` (`npm install socket.io-client`). Nothing else in the SDK needs it; `connect()` throws a clear error if it is missing.
+
 ```typescript
 // Establish WebSocket connection using short-lived session tokens
 await r.realtime.connect()
@@ -596,7 +619,11 @@ if (subscription.active) {
 - `r.admin` — Admin operations (user management, stats, network settings); content reports: `listReports({ status? })`, `resolveReport(id)`, `dismissReport(id)` (project-bound keys see only their app's reports)
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration
-- `r.protocols` — 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`, `search`, `getSettings`, `refresh`, `updateSettings`.
+- `r.protocols` — 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`.
+  - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.
+  - Lists return `{ data: ProtocolQuarantinedCandidate[], meta: { limit, has_more, next_cursor } }`; use the opaque `next_cursor`, not offset pagination. The API defaults `limit` to 20 and permits at most 50. Details return `{ data: ProtocolQuarantinedCandidate }`. Every candidate has `state: 'quarantined'` and `content_format: 'plain'`; render its bounded `content` as text, respect `content_truncated`, and distinguish upstream `published_at` from local `observed_at` / `created_at`.
+  - Safe source IDs are preserved byte-exact. `external_id: null` means unsafe or malformed provenance was withheld, not an invented ID; `author.native_id` may likewise be absent or withheld. Preserve nulls in both list and detail views, and use the candidate's own `id` for `getCandidate`.
+  - API authorization/validation/not-found/service errors propagate as normal SDK errors, including when the deployed API does not yet support these routes. Never substitute synthetic candidates or turn these failures into an empty queue. `getCandidate` rejects empty/whitespace and URL dot-segment IDs with `ValidationError` before sending; other IDs are encoded and validated by the server.
 - `r.inbox` — Notification feed
 - `r.network` — Federation/network config
 - `r.simulator` — Simulation/testing