@parall/sdk 1.56.2 → 1.57.1

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

@@ -769,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> {

package/src/constants.ts

@@ -381,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,8 +1,10 @@
 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';

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;
+  }
+}

package/src/llm-provider-types.ts

@@ -0,0 +1,104 @@
+/**
+ * Org-configured model providers (BYOK) and the model rows bound to them.
+ *
+ * Design: docs/engineering-design/org-llm-provider-byok-design.md
+ */
+
+/** Inbound protocol a provider can serve. */
+export type LLMProviderEndpoint = 'chat_completions' | 'messages' | 'responses';
+
+export type LLMProviderStatus = 'active' | 'disabled';
+
+/**
+ * A provider as the server returns it. The credential is never echoed back —
+ * `api_key_set` is the only thing a client learns about it.
+ */
+export interface LLMProvider {
+  id: string;
+  name: string;
+  base_url: string;
+  api_key_set: boolean;
+  endpoints: LLMProviderEndpoint[];
+  status: LLMProviderStatus;
+  is_platform: boolean;
+  /**
+   * Runtime types whose protocol this provider can actually serve. Anything
+   * absent here silently uses the platform provider — surface this, or an
+   * operator will assume their credential covers every agent.
+   */
+  runtimes: string[];
+  /** Most recent fallback-worthy failure, if any. */
+  last_error_at?: string | null;
+  last_error_status?: number | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateLLMProviderRequest {
+  name: string;
+  base_url: string;
+  api_key: string;
+  endpoints: LLMProviderEndpoint[];
+}
+
+/** Omitting `api_key` leaves the stored credential untouched. */
+export interface UpdateLLMProviderRequest {
+  name?: string;
+  base_url?: string;
+  api_key?: string;
+  endpoints?: LLMProviderEndpoint[];
+  status?: LLMProviderStatus;
+}
+
+/**
+ * One org's row for a model. Overriding a platform model and adding a new one
+ * are the same shape: `overrides_platform` is derived by the server from
+ * whether the platform catalog knows this id, never stored.
+ */
+export interface OrgLLMModel {
+  id: string;
+  model_id: string;
+  provider_id: string;
+  upstream_model_id: string;
+  display_name?: string | null;
+  context_window?: number | null;
+  max_tokens?: number | null;
+  overrides_platform: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateOrgLLMModelRequest {
+  model_id: string;
+  provider_id: string;
+  /** The name to send to this provider, which differs per provider. */
+  upstream_model_id: string;
+  /** Required when `model_id` is not in the platform catalog. */
+  display_name?: string;
+  context_window?: number;
+  max_tokens?: number;
+  effort_levels?: string[];
+  input_modalities?: string[];
+}
+
+/**
+ * Everything about a model row except its identity. `model_id` is what agents
+ * pin to, so changing it is a delete-and-recreate the operator performs
+ * deliberately; the server rejects it here.
+ */
+export interface UpdateOrgLLMModelRequest {
+  provider_id?: string;
+  upstream_model_id?: string;
+  /**
+   * Metadata fields accept `null` to clear the org's value and go back to
+   * inheriting the platform entry's. Omitting a field leaves it as it is —
+   * the two are different requests, so do not send `undefined` meaning
+   * "clear". A model the platform does not have cannot clear these: it has
+   * nothing to inherit from, and the server rejects it.
+   */
+  display_name?: string | null;
+  context_window?: number | null;
+  max_tokens?: number | null;
+  effort_levels?: string[] | null;
+  input_modalities?: string[] | null;
+}

package/src/types.ts

@@ -481,6 +481,25 @@ export interface Organization {
   onboarding_agent_id: string | null;
   /** Org-level IANA timezone (e.g. "America/New_York"). Defaults to "UTC". */
   timezone: string;
+  /**
+   * Whether this org may configure its own LLM providers (BYOK). Absent means
+   * it inherits the platform default, which is off.
+   *
+   * An entitlement, not a feature flag: only a platform admin changes it, and
+   * it is expected to become plan-driven. Turning it off also stops existing
+   * provider configuration from taking effect.
+   */
+  llm_byok_enabled?: boolean | null;
+  /**
+   * When an org's own model provider fails at run time, retry once on the
+   * platform provider — billed to this org's credit balance. Defaults to off,
+   * so "no fallback" is the default state and fallback is opted into.
+   * Does NOT gate the capability fallback: a provider that cannot serve a
+   * runtime's protocol always defers to the platform regardless.
+   * Current servers populate this field; it remains optional for source
+   * compatibility with cached and rolling-upgrade organization payloads.
+   */
+  llm_byok_fallback_enabled?: boolean;
   created_at: string;
   /** Per-member flag: true when the user has dismissed the onboarding popup for this org. */
   onboarding_dismissed: boolean;
@@ -1081,10 +1100,8 @@ export interface MessageDispatchSource {
   source_type: string;
   source_id: string;
   /**
-   * Conversation generation of the sending execution (parel v2 invocation
-   * context). Required by the server for agents on the direct_session_v2
-   * transport; a value older than the current New Session barrier is
-   * rejected (STALE_GENERATION).
+   * @deprecated Ignored by current servers. Retained so clients compiled
+   * against older SDKs can upgrade without source changes.
    */
   generation?: number;
 }
@@ -1821,8 +1838,8 @@ export interface UpdateTaskRequest {
    * Lane-bound form (v1 consumers): dispatch_lane + dispatch_event_id bind
    * the update to the claimed typed lane (incumbency-checked).
    * By-id form (parel v2 converged consumers — no lane exists):
-   * dispatch_event_id + dispatch_generation bind the update to the WorkItem
-   * directly under the conversation-generation fence.
+   * dispatch_event_id alone binds the update to the WorkItem; the server
+   * admits it on the binding's transport and deletion state alone.
    * In both forms dispatch_effect_key additionally commits the update as
    * the dispatch's idempotent Effect and resolves the WorkItem in the same
    * transaction. Lane-bound: exactly "task_update:<dispatch_event_id>" —
@@ -1835,6 +1852,10 @@ export interface UpdateTaskRequest {
   dispatch_lane?: string;
   dispatch_event_id?: string;
   dispatch_effect_key?: string;
+  /**
+   * @deprecated Ignored by current servers. Retained so clients compiled
+   * against older SDKs can upgrade without source changes.
+   */
   dispatch_generation?: number;
 }
 
@@ -3386,6 +3407,7 @@ export interface ChannelConversation {
   agent_id: string;
   agent_session_id?: string | null;
   external_conversation_id: string;
+  external_conversation_name?: string;
   external_thread_id: string;
   conversation_type: string;
   external_user_id: string;
@@ -5519,88 +5541,25 @@ export interface BrowserAliasExecutionReceipt {
   updated_at: string;
 }
 
-export type BrowserUseAction =
-  | 'read'
-  | 'tabs'
-  | 'wait'
-  | 'snapshot'
-  | 'get'
-  | 'screenshot'
-  | 'open'
-  | 'navigate'
-  | 'viewport'
-  | 'click'
-  | 'fill'
-  | 'type'
-  | 'press'
-  | 'scroll'
-  | 'close'
-  | 'recover'
-  | 'eval';
-
-export interface BrowserUseTarget {
-  tab_id?: string;
-  browser_generation?: number;
-  document_generation?: number;
-  snapshot_id?: string;
-  ref?: string;
-}
-
-export interface BrowserUseOperationRequest {
-  contract_version: 'browser-use-operation-v1';
-  request_id: string;
-  profile_id: string;
-  action: BrowserUseAction;
-  target?: BrowserUseTarget;
-  params: Record<string, unknown>;
-  /** Canonical RFC3339 UTC instant, no more than two minutes in the future. */
-  deadline: string;
-}
-
-export type BrowserUseOperationPhase =
-  | 'accepted'
-  | 'started'
-  | 'succeeded'
-  | 'failed'
-  | 'outcome_unknown';
-
-export interface BrowserUseOperationError {
-  code: string;
-  message?: string;
-  hint?: string;
-}
-
-/** 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 BrowserUseOperationReceipt {
-  contract_version: 'browser-use-operation-v1';
-  operation_id: string;
-  request_id: string;
-  profile_id: string;
-  profile_version: number;
-  profile_config_revision: number;
-  action: BrowserUseAction;
-  required_grant: 'browser.read' | 'browser.interact' | 'browser.advanced';
-  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;
-  data?: unknown;
-  error?: BrowserUseOperationError;
-  deadline: string;
-  accepted_at: string;
-  started_at?: string;
-  terminal_at?: string;
-  updated_at: string;
-}
+export type {
+  BrowserUseAction,
+  BrowserUseActionRequest,
+  BrowserUseArticle,
+  BrowserUseGrant,
+  BrowserUseOperationError,
+  BrowserUseOperationPhase,
+  BrowserUseOperationReceipt,
+  BrowserUseOperationReceiptBase,
+  BrowserUseOperationReceiptFor,
+  BrowserUseOperationRequest,
+  BrowserUseRefTarget,
+  BrowserUseSuccessDataMap,
+  BrowserUseTabState,
+  BrowserUseTabSummary,
+  BrowserUseTabTarget,
+  BrowserUseTarget,
+  BrowserUseViewport,
+} from './browser-use.js';
 
 /**
  * Sanitized per-profile egress proxy status (hosted Cloud Profiles) — the GET