@parall/sdk 1.56.1 → 1.57.1

package/dist/wiki-upload.js

@@ -0,0 +1,87 @@
+export function createWikiUploadFormData(params) {
+    const form = new FormData();
+    form.append('path', params.path);
+    form.append('file', params.file);
+    if (params.message)
+        form.append('message', params.message);
+    if (params.uploadId)
+        form.append('upload_id', params.uploadId);
+    if (params.conflict)
+        form.append('conflict', params.conflict);
+    if ('contentRoute' in params && params.contentRoute) {
+        form.append('content_route', params.contentRoute);
+    }
+    return form;
+}
+/** Send one multipart request. XHR is used only when a browser caller asks
+ * for upload progress; fetch remains the transport everywhere else. Auth
+ * refresh and API error decoding stay in ParallClient above this boundary. */
+export function sendMultipartRequest(options) {
+    if (options.onProgress && typeof XMLHttpRequest !== 'undefined') {
+        return multipartXHR(options, options.onProgress);
+    }
+    const timeoutSignal = AbortSignal.timeout(options.timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+    return fetch(options.url, {
+        method: options.method,
+        headers: options.headers,
+        body: options.body,
+        signal,
+    });
+}
+function multipartXHR(options, onProgress) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            options.signal?.removeEventListener('abort', abortFromSignal);
+            fn();
+        };
+        const abortFromSignal = () => xhr.abort();
+        xhr.open(options.method, options.url, true);
+        xhr.timeout = options.timeoutMs;
+        for (const [name, value] of Object.entries(options.headers)) {
+            xhr.setRequestHeader(name, value);
+        }
+        xhr.upload.onprogress = (event) => {
+            try {
+                onProgress(event.loaded, event.lengthComputable ? event.total : 0);
+            }
+            catch {
+                // Observer failures must not cancel an otherwise healthy upload.
+            }
+        };
+        xhr.onload = () => finish(() => {
+            const responseHeaders = new Headers();
+            for (const line of xhr
+                .getAllResponseHeaders()
+                .trim()
+                .split(/[\r\n]+/)) {
+                if (!line)
+                    continue;
+                const separator = line.indexOf(':');
+                if (separator > 0) {
+                    responseHeaders.append(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+                }
+            }
+            const responseBody = xhr.status === 204 || xhr.responseText === '' ? null : xhr.responseText;
+            resolve(new Response(responseBody, {
+                status: xhr.status,
+                statusText: xhr.statusText,
+                headers: responseHeaders,
+            }));
+        });
+        xhr.onerror = () => finish(() => reject(new TypeError('Network request failed')));
+        xhr.ontimeout = () => finish(() => reject(new DOMException('Request timed out', 'TimeoutError')));
+        xhr.onabort = () => finish(() => reject(new DOMException('Request aborted', 'AbortError')));
+        if (options.signal?.aborted) {
+            finish(() => reject(new DOMException('Request aborted', 'AbortError')));
+            return;
+        }
+        options.signal?.addEventListener('abort', abortFromSignal, { once: true });
+        xhr.send(options.body);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/sdk",
-  "version": "1.56.1",
+  "version": "1.57.1",
   "description": "TypeScript client SDK for Parall — REST + WebSocket client, shared types",
   "license": "MIT",
   "repository": {

package/src/attachment-client.ts

@@ -5,7 +5,7 @@ import type {
   PresignUploadRequest,
 } from './attachment-types.js';
 import { ENDPOINTS } from './constants.js';
-import { WechatClient } from './wechat-client.js';
+import { LLMProviderClient } from './llm-provider-client.js';
 
 const COMPLETION_RETRY_DELAYS_MS = [250, 750] as const;
 
@@ -16,7 +16,7 @@ function isRetryableCompletionError(error: unknown): boolean {
 }
 
 /** Attachment upload lifecycle and download URL methods. */
-export abstract class AttachmentClient extends WechatClient {
+export abstract class AttachmentClient extends LLMProviderClient {
   async getUploadPresignUrl(orgId: string, req: PresignUploadRequest): Promise<PresignResponse> {
     return this.request('POST', ENDPOINTS.UPLOAD_PRESIGN(orgId), req);
   }

package/src/browser-use.ts

@@ -0,0 +1,217 @@
+export type BrowserUseAction =
+  | 'read'
+  | 'tabs'
+  | 'wait'
+  | 'snapshot'
+  | 'get'
+  | 'screenshot'
+  | 'open'
+  | 'navigate'
+  | 'viewport'
+  | 'click'
+  | 'fill'
+  | 'type'
+  | 'press'
+  | 'scroll'
+  | 'close'
+  | 'recover'
+  | 'eval';
+
+/** Org-scoped PostHog rollout gate. Missing, non-boolean, and false values are
+ * all disabled; Server admission remains authoritative after any UI check. */
+export const BROWSER_USE_FEATURE_FLAG = 'browser-use';
+
+export function isBrowserUseEnabled(flags: Record<string, unknown> | null | undefined): boolean {
+  return flags?.[BROWSER_USE_FEATURE_FLAG] === true;
+}
+
+export type BrowserUseGrant = 'browser.read' | 'browser.interact' | 'browser.advanced';
+
+export interface BrowserUseTabTarget {
+  tab_id: string;
+  browser_generation: number;
+  document_generation?: never;
+  snapshot_id?: never;
+  ref?: never;
+}
+
+export interface BrowserUseRefTarget {
+  tab_id: string;
+  browser_generation: number;
+  document_generation: number;
+  snapshot_id: string;
+  ref: string;
+}
+
+export type BrowserUseTarget = BrowserUseTabTarget | BrowserUseRefTarget;
+
+export interface BrowserUseViewport {
+  width: number;
+  height: number;
+}
+
+interface BrowserUseRequestBase {
+  contract_version: 'browser-use-operation-v1';
+  request_id: string;
+  profile_id: string;
+  /** Canonical RFC3339 UTC instant, no more than two minutes in the future. */
+  deadline: string;
+}
+
+type NoTarget = { target?: never };
+type TabTarget = { target: BrowserUseTabTarget };
+
+type BrowserUseLocator =
+  | { target: BrowserUseTabTarget; params: { selector: string } }
+  | { target: BrowserUseRefTarget; params: Record<string, never> };
+
+type BrowserUseTextLocator<T extends 'fill' | 'type'> =
+  | { action: T; target: BrowserUseTabTarget; params: { selector: string; text: string } }
+  | { action: T; target: BrowserUseRefTarget; params: { text: string } };
+
+export type BrowserUseActionRequest =
+  | ({ action: 'read'; params: { url: string } } & NoTarget)
+  | ({ action: 'read'; params: Record<string, never> } & TabTarget)
+  | ({ action: 'tabs'; params: Record<string, never> } & NoTarget)
+  | ({
+      action: 'wait';
+      params:
+        | { state: 'load'; timeout_ms?: number; selector?: never }
+        | {
+            selector: string;
+            state?: 'attached' | 'detached' | 'visible' | 'hidden';
+            timeout_ms?: number;
+          };
+    } & TabTarget)
+  | ({
+      action: 'snapshot';
+      params: { interactive?: boolean; compact?: boolean; depth?: number };
+    } & TabTarget)
+  | ({ action: 'get'; params: { prop: 'title' | 'url' } } & TabTarget)
+  | ({ action: 'get'; params: { prop: 'text' | 'html' | 'value'; selector: string } } & TabTarget)
+  | { action: 'get'; params: { prop: 'text' | 'html' | 'value' }; target: BrowserUseRefTarget }
+  | ({ action: 'get'; params: { prop: 'attr'; selector: string; name: string } } & TabTarget)
+  | { action: 'get'; params: { prop: 'attr'; name: string }; target: BrowserUseRefTarget }
+  | ({ action: 'screenshot'; params: Record<string, never> } & TabTarget)
+  | ({
+      action: 'open';
+      params: { url: string; hidden?: boolean; viewport?: BrowserUseViewport };
+    } & NoTarget)
+  | ({ action: 'navigate'; params: { url: string } } & TabTarget)
+  | ({ action: 'viewport'; params: BrowserUseViewport } & TabTarget)
+  | ({ action: 'click' } & BrowserUseLocator)
+  | BrowserUseTextLocator<'fill'>
+  | BrowserUseTextLocator<'type'>
+  | ({ action: 'press'; params: { key: string } } & TabTarget)
+  | ({
+      action: 'scroll';
+      params: { direction?: 'up' | 'down' | 'left' | 'right'; pixels?: number };
+    } & TabTarget)
+  | ({ action: 'close'; params: Record<string, never> } & TabTarget)
+  | ({ action: 'recover'; params: Record<string, never> } & TabTarget)
+  | ({ action: 'eval'; params: { expression: string; timeout_ms?: number } } & TabTarget);
+
+export type BrowserUseOperationRequest = BrowserUseRequestBase & BrowserUseActionRequest;
+
+export type BrowserUseOperationPhase =
+  | 'accepted'
+  | 'started'
+  | 'succeeded'
+  | 'failed'
+  | 'outcome_unknown';
+
+export interface BrowserUseOperationError {
+  code: string;
+  message?: string;
+  hint?: string;
+}
+
+export interface BrowserUseTabState {
+  tab_id: string;
+  profile_id: string;
+  browser_generation: number;
+  document_generation: number;
+  url: string;
+  title: string;
+}
+
+export interface BrowserUseTabSummary extends BrowserUseTabState {
+  loading: boolean;
+}
+
+export interface BrowserUseArticle {
+  title: string | null;
+  byline: string | null;
+  excerpt: string | null;
+  text: string;
+  published_time: string | null;
+  site_name: string | null;
+  length: number;
+}
+
+export interface BrowserUseSuccessDataMap {
+  read: {
+    profile_id: string;
+    url: string;
+    title: string;
+    article: BrowserUseArticle | null;
+  };
+  tabs: { tabs: BrowserUseTabSummary[] };
+  wait: BrowserUseTabState & { matched: true };
+  snapshot: BrowserUseTabState & { snapshot: string; snapshot_id: string };
+  get: BrowserUseTabState & { value: string | null };
+  screenshot: BrowserUseTabState & { format: 'png'; base64: string };
+  open: BrowserUseTabState;
+  navigate: BrowserUseTabState;
+  viewport: BrowserUseTabState & { viewport: BrowserUseViewport };
+  click: BrowserUseTabState & { clicked: true };
+  fill: BrowserUseTabState & { filled: true; characters: number };
+  type: BrowserUseTabState & { typed: true; characters: number };
+  press: BrowserUseTabState & { pressed: true };
+  scroll: BrowserUseTabState & { scrolled: true };
+  close: BrowserUseTabState & { closed: true };
+  recover: BrowserUseTabState & { recovered_from_tab_id: string };
+  eval: BrowserUseTabState & { value: unknown };
+}
+
+/** Durable Browser Use proof. `data` is encrypted/transient: it is present
+ * only while result_available is true and disappears after result_expires_at;
+ * the terminal receipt and result_digest remain durable. */
+export interface BrowserUseOperationReceiptBase {
+  contract_version: 'browser-use-operation-v1';
+  operation_id: string;
+  request_id: string;
+  profile_id: string;
+  profile_version: number;
+  profile_config_revision: number;
+  required_grant: BrowserUseGrant;
+  phase: BrowserUseOperationPhase;
+  dispatched?: boolean;
+  receipt_id?: string;
+  receipt_digest?: string;
+  occurred_at?: string;
+  tab_id?: string;
+  browser_generation?: number;
+  duration_ms?: number;
+  result_digest?: string;
+  result_available: boolean;
+  result_expires_at?: string;
+  error?: BrowserUseOperationError;
+  deadline: string;
+  accepted_at: string;
+  started_at?: string;
+  terminal_at?: string;
+  updated_at: string;
+}
+
+export type BrowserUseOperationReceiptFor<A extends BrowserUseAction> =
+  BrowserUseOperationReceiptBase & {
+    action: A;
+    data?: BrowserUseSuccessDataMap[A];
+  };
+
+/** Mapped union: checking `action` narrows `data` to that action's stable
+ * success shape instead of leaving the two fields independently unioned. */
+export type BrowserUseOperationReceipt<A extends BrowserUseAction = BrowserUseAction> = {
+  [K in A]: BrowserUseOperationReceiptFor<K>;
+}[A];

package/src/client.ts

@@ -1,6 +1,14 @@
 import { type BrowserViewerRequestOptions, browserViewerRequestOptions } from './browser-viewer.js';
 import { API_BASE, ENDPOINTS, WIKI_BASE } from './constants.js';
 import { AttachmentClient } from './attachment-client.js';
+import {
+  createWikiUploadFormData,
+  sendMultipartRequest,
+  type WikiChangesetFileUploadParams,
+  type WikiFileUploadParams,
+  type WikiFileUploadResponse,
+} from './wiki-upload.js';
+import { normalizeWikiChangeset } from './wiki-changeset.js';
 import type {
   AddTeamMemberRequest,
   AgentClip,
@@ -94,6 +102,7 @@ import type {
   CreateCommentRequest,
   CreateExternalConnectionInput,
   CreateExternalTriggerInput,
+  CreatePersonalApiKeyRequest,
   CreateScheduleInput,
   CreateSetupIntentResponse,
   CreateTeamRequest,
@@ -176,6 +185,7 @@ import type {
   OutboundRefsRequest,
   OutboundRefsResponse,
   PaginatedResponse,
+  PersonalApiKey,
   PlatformConfigResponse,
   PlatformModelsResponse,
   PublishRegistryClipRequest,
@@ -262,7 +272,6 @@ import type {
   WikiCommit,
   WikiDiff,
   WikiFilePreviewUrlResponse,
-  WikiFileUploadResponse,
   WikiNodeSectionArtifact,
   WikiOperation,
   WikiOperationsResponse,
@@ -551,7 +560,7 @@ export class ParallClient extends AttachmentClient {
    * Multipart upload variant of `request`. Same auth / refresh / error
    * handling, but lets the caller hand us a prepared `FormData` (file +
    * text fields) and skips the JSON content-type. Used by
-   * uploadWikiFile / uploadWikiFileToChangeset — wiki binary uploads can
+   * uploadWikiFile / uploadWikiFileToChangeset — wiki file uploads can
    * hit the 100 MiB cap, so a longer 5-minute timeout is used so a
    * 50 MiB blob on a slow connection doesn't get chopped at 15 s.
    */
@@ -560,6 +569,11 @@ export class ParallClient extends AttachmentClient {
     path: string,
     body: FormData,
     retried = false,
+    opts?: {
+      signal?: AbortSignal;
+      onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+      timeoutMs?: number;
+    },
   ): Promise<T> {
     if (!retried) {
       await this.ensureFreshToken(path);
@@ -568,13 +582,17 @@ export class ParallClient extends AttachmentClient {
     const { 'Content-Type': _drop, ...headers } = this.buildHeaders(path);
     void _drop;
 
+    const timeoutMs = opts?.timeoutMs ?? 5 * 60 * 1000;
     let res: Response;
     try {
-      res = await fetch(`${this.baseUrlFor(path)}${path}`, {
+      res = await sendMultipartRequest({
         method,
+        url: `${this.baseUrlFor(path)}${path}`,
         headers,
         body,
-        signal: AbortSignal.timeout(5 * 60 * 1000),
+        timeoutMs,
+        signal: opts?.signal,
+        onProgress: opts?.onProgress,
       });
     } catch (err) {
       throw ParallClient.normalizeFetchError(err);
@@ -586,7 +604,7 @@ export class ParallClient extends AttachmentClient {
       if (!retried && !isAuthPath && this.getRefreshToken) {
         const refreshed = await this.tryRefresh();
         if (refreshed) {
-          return this.multipartRequest<T>(method, path, body, true);
+          return this.multipartRequest<T>(method, path, body, true, opts);
         }
       }
       if (this.onTokenExpired && !isAuthPath) {
@@ -687,6 +705,22 @@ export class ParallClient extends AttachmentClient {
     return this.request('DELETE', ENDPOINTS.USER_AVATAR);
   }
 
+  // ---- Personal API keys (org-scoped; JWT session required) ----
+
+  /** Mints an org-scoped personal API key. The plaintext is returned once and never again. */
+  async createPersonalApiKey(req: CreatePersonalApiKeyRequest): Promise<ApiKey> {
+    return this.request('POST', ENDPOINTS.PERSONAL_API_KEYS, req);
+  }
+
+  async listPersonalApiKeys(): Promise<PersonalApiKey[]> {
+    const res = await this.request<{ data: PersonalApiKey[] }>('GET', ENDPOINTS.PERSONAL_API_KEYS);
+    return res.data;
+  }
+
+  async revokePersonalApiKey(keyId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PERSONAL_API_KEY(keyId));
+  }
+
   async uploadAgentAvatar(
     orgId: string,
     agentId: string,
@@ -735,7 +769,12 @@ export class ParallClient extends AttachmentClient {
     data: Partial<
       Pick<
         Organization,
-        'name' | 'avatar_url' | 'smart_routing_strategy' | 'smart_routing_agent_id' | 'timezone'
+        | 'name'
+        | 'avatar_url'
+        | 'smart_routing_strategy'
+        | 'smart_routing_agent_id'
+        | 'timezone'
+        | 'llm_byok_fallback_enabled'
       >
     >,
   ): Promise<Organization> {
@@ -2923,39 +2962,38 @@ export class ParallClient extends AttachmentClient {
   async uploadWikiFile(
     orgId: string,
     wikiId: string,
-    params: { path: string; file: Blob; message?: string },
+    params: WikiFileUploadParams,
   ): Promise<WikiFileUploadResponse> {
     // `POST /uploads` always writes to the wiki's default branch — the
-    // backend's parseUpload silently drops any `parent_ref` field, so
+    // backend's parseUpload does not accept a `parent_ref` field, so
     // surfacing one in this signature would mislead callers. To target
     // a feature branch, use uploadWikiFileToChangeset.
-    const fd = new FormData();
-    fd.append('path', params.path);
-    fd.append('file', params.file);
-    if (params.message) fd.append('message', params.message);
-    return this.multipartRequest('POST', ENDPOINTS.WIKI_UPLOADS(orgId, wikiId), fd);
+    const fd = createWikiUploadFormData(params);
+    return this.multipartRequest('POST', ENDPOINTS.WIKI_UPLOADS(orgId, wikiId), fd, false, {
+      signal: params.signal,
+      onProgress: params.onProgress,
+    });
   }
 
   /**
-   * Upload a binary file into a changeset's feature branch (read scope +
-   * author-only). Used by reader flow: propose a changeset, attach
-   * binary, PATCH markdown that references it. On merge the binary
-   * squashes into the default branch.
+   * Upload a file into a changeset's feature branch (read scope +
+   * author-only). The default remains binary-only; contentRoute `auto`
+   * opts into reviewable text for the Web library upload flow. On merge the
+   * branch contents squash into the default branch.
    */
   async uploadWikiFileToChangeset(
     orgId: string,
     wikiId: string,
     changesetId: string,
-    params: { path: string; file: Blob; message?: string },
+    params: WikiChangesetFileUploadParams,
   ): Promise<WikiFileUploadResponse> {
-    const fd = new FormData();
-    fd.append('path', params.path);
-    fd.append('file', params.file);
-    if (params.message) fd.append('message', params.message);
+    const fd = createWikiUploadFormData(params);
     return this.multipartRequest(
       'POST',
       ENDPOINTS.WIKI_CHANGESET_FILES(orgId, wikiId, changesetId),
       fd,
+      false,
+      { signal: params.signal, onProgress: params.onProgress },
     );
   }
 
@@ -4405,14 +4443,6 @@ export class ParallClient extends AttachmentClient {
   }
 }
 
-function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
-  return {
-    ...changeset,
-    changed_paths: changeset.changed_paths ?? [],
-    file_changes: changeset.file_changes ?? [],
-  };
-}
-
 export class ApiError extends Error {
   extras?: Record<string, unknown>;
   /** Retry-After delta seconds when the server supplies one. */

package/src/constants.ts

@@ -361,6 +361,8 @@ export const ENDPOINTS = {
   // Users
   USERS_ME: `${API_BASE}/users/me`,
   USER_AVATAR: `${API_BASE}/users/me/avatar`,
+  PERSONAL_API_KEYS: `${API_BASE}/users/me/api-keys`,
+  PERSONAL_API_KEY: (keyId: string) => `${API_BASE}/users/me/api-keys/${keyId}`,
   USER: (id: string) => `${API_BASE}/users/${id}`,
 
   // WebSocket ticket
@@ -379,6 +381,26 @@ export const ENDPOINTS = {
   TEAM_MEMBER: (orgId: string, teamId: string, userId: string) =>
     `${API_BASE}/orgs/${orgId}/teams/${teamId}/members/${userId}`,
   ORG_MEMBERS_ONLINE: (orgId: string) => `${API_BASE}/orgs/${orgId}/members/online`,
+  LLM_PROVIDERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/llm-providers`,
+  LLM_PROVIDER: (orgId: string, providerId: string) =>
+    `${API_BASE}/orgs/${orgId}/llm-providers/${providerId}`,
+  ORG_LLM_MODELS: (orgId: string) => `${API_BASE}/orgs/${orgId}/llm-models`,
+  ORG_LLM_MODEL: (orgId: string, modelRowId: string) =>
+    `${API_BASE}/orgs/${orgId}/llm-models/${modelRowId}`,
+  /**
+   * Platform catalog merged with this org's own model rows. Pass `runtime` to
+   * filter org-added models to the ones that runtime can actually reach —
+   * without it a picker can offer a model the write path rejects.
+   */
+  ORG_MODEL_CATALOG: (orgId: string, runtime?: string, includeModel?: string) => {
+    const params = new URLSearchParams();
+    if (runtime) params.set('runtime', runtime);
+    // include_model keeps a hidden legacy model the caller is still pinned to
+    // representable, matching the public catalog.
+    if (includeModel) params.set('include_model', includeModel);
+    const qs = params.toString();
+    return `${API_BASE}/orgs/${orgId}/models${qs ? `?${qs}` : ''}`;
+  },
   ORG_MEMBER: (orgId: string, userId: string) => `${API_BASE}/orgs/${orgId}/members/${userId}`,
   ORG_MEMBER_CHATS: (orgId: string, memberId: string) =>
     `${API_BASE}/orgs/${orgId}/members/${memberId}/chats`,

package/src/index.ts

@@ -1,12 +1,20 @@
 export * from './browser-viewer.js';
+export { BROWSER_USE_FEATURE_FLAG, isBrowserUseEnabled } from './browser-use.js';
 export * from './attachment-types.js';
 export type { ParallClientOptions } from './client.js';
 export { ApiError, ParallClient } from './client.js';
 export * from './constants.js';
+export * from './llm-provider-types.js';
 export * from './subject.js';
 export * from './task-label-types.js';
 export * from './types.js';
 export * from './wechat-types.js';
+export type {
+  WikiChangesetFileUploadParams,
+  WikiFileUploadParams,
+  WikiFileUploadResponse,
+  WikiStoredAs,
+} from './wiki-upload.js';
 export type {
   ParallWsOptions,
   WsClientEventMap,

package/src/llm-provider-client.ts

@@ -0,0 +1,96 @@
+import { ENDPOINTS } from './constants.js';
+import type {
+  CreateLLMProviderRequest,
+  CreateOrgLLMModelRequest,
+  LLMProvider,
+  OrgLLMModel,
+  UpdateOrgLLMModelRequest,
+  UpdateLLMProviderRequest,
+} from './llm-provider-types.js';
+import type { PlatformModelInfo } from './types.js';
+import { WechatClient } from './wechat-client.js';
+
+/**
+ * Org-configured model providers (BYOK) and the model rows bound to them.
+ *
+ * Writes are org-admin only server-side: a provider row carries a credential
+ * and decides where the org's LLM spend goes.
+ *
+ * Design: docs/engineering-design/org-llm-provider-byok-design.md
+ */
+export abstract class LLMProviderClient extends WechatClient {
+  async getLLMProviders(orgId: string): Promise<LLMProvider[]> {
+    const response = await this.request<{ data: LLMProvider[] }>(
+      'GET',
+      ENDPOINTS.LLM_PROVIDERS(orgId),
+    );
+    return response.data;
+  }
+
+  async createLLMProvider(orgId: string, data: CreateLLMProviderRequest): Promise<LLMProvider> {
+    return this.request('POST', ENDPOINTS.LLM_PROVIDERS(orgId), data);
+  }
+
+  /** Omitting `api_key` leaves the stored credential untouched. */
+  async updateLLMProvider(
+    orgId: string,
+    providerId: string,
+    data: UpdateLLMProviderRequest,
+  ): Promise<LLMProvider> {
+    return this.request('PATCH', ENDPOINTS.LLM_PROVIDER(orgId, providerId), data);
+  }
+
+  /** Fails with PROVIDER_IN_USE while model rows still point at it. */
+  async deleteLLMProvider(orgId: string, providerId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.LLM_PROVIDER(orgId, providerId));
+  }
+
+  async getOrgLLMModels(orgId: string): Promise<OrgLLMModel[]> {
+    const response = await this.request<{ data: OrgLLMModel[] }>(
+      'GET',
+      ENDPOINTS.ORG_LLM_MODELS(orgId),
+    );
+    return response.data;
+  }
+
+  async createOrgLLMModel(orgId: string, data: CreateOrgLLMModelRequest): Promise<OrgLLMModel> {
+    return this.request('POST', ENDPOINTS.ORG_LLM_MODELS(orgId), data);
+  }
+
+  /**
+   * Patches a model row in place. Repointing a provider or fixing an upstream
+   * name this way avoids the delete-and-recreate window, during which an
+   * org-only model has no upstream at all and its pinned agents fail.
+   */
+  async updateOrgLLMModel(
+    orgId: string,
+    modelRowId: string,
+    data: UpdateOrgLLMModelRequest,
+  ): Promise<OrgLLMModel> {
+    return this.request('PATCH', ENDPOINTS.ORG_LLM_MODEL(orgId, modelRowId), data);
+  }
+
+  async deleteOrgLLMModel(orgId: string, modelRowId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.ORG_LLM_MODEL(orgId, modelRowId));
+  }
+
+  /**
+   * The catalog as this org sees it: platform models with the org's rows
+   * merged in. Distinct from the public model catalog, which stays org-agnostic
+   * and cacheable — use this one wherever an org context exists.
+   *
+   * Pass `runtime` on a picker: org-added models are then filtered to what that
+   * runtime's protocol can reach, matching the server-side pin validation.
+   */
+  async getOrgModelCatalog(
+    orgId: string,
+    runtime?: string,
+    includeModel?: string,
+  ): Promise<PlatformModelInfo[]> {
+    const response = await this.request<{ data: PlatformModelInfo[] }>(
+      'GET',
+      ENDPOINTS.ORG_MODEL_CATALOG(orgId, runtime, includeModel),
+    );
+    return response.data;
+  }
+}