@parall/sdk 1.56.1 → 1.57.1

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;
@@ -710,11 +729,35 @@ export interface CreateInvitationRequest {
   role?: OrgMemberRole;
 }
 
-// Response of agent API key create/regenerate. The plaintext `api_key` is
-// returned exactly once at mint time and can never be fetched again.
+// Response of API key create/regenerate (agent keys and personal keys alike).
+// The plaintext `api_key` is returned exactly once at mint time and can never
+// be fetched again. Personal keys additionally echo the org they are bound to.
 export interface ApiKey {
   id: string;
   api_key: string;
+  org_id?: string;
+}
+
+// A personal API key row as listed by GET /users/me/api-keys. Personal keys
+// are org-scoped ("org_full"): the user's permissions inside org_id only.
+// Managed Clip keys have their own surface; the key hash never leaves the
+// server.
+export interface PersonalApiKey {
+  id: string;
+  user_id: string;
+  name?: string;
+  org_id: string;
+  last_used_at?: string;
+  expires_at?: string;
+  created_at: string;
+}
+
+export interface CreatePersonalApiKeyRequest {
+  name?: string;
+  /** The org this key is bound to; the caller must be a member. */
+  org_id: string;
+  /** RFC3339; must be in the future. Omit for a non-expiring key. */
+  expires_at?: string;
 }
 
 export interface CreateAgentResponse {
@@ -1057,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;
 }
@@ -1797,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>" —
@@ -1811,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;
 }
 
@@ -2391,6 +2436,10 @@ export interface WikiChangeset {
   title: string;
   message: string | null;
   status: WikiChangesetStatus;
+  /** Present on current servers; optional keeps older mocked/client data source-compatible. */
+  head_branch?: string | null;
+  /** Present on current servers; optional keeps older mocked/client data source-compatible. */
+  base_commit?: string | null;
   merge_commit: string | null;
   file_changes: WikiFileChange[];
   changed_paths: string[];
@@ -2658,6 +2707,8 @@ export interface CreateWikiChangesetRequest {
   title: string;
   message?: string;
   file_changes: WikiFileChangeInput[];
+  /** Omit for the server default (`proposed`); pass `draft` for staged uploads. */
+  status?: 'draft' | 'proposed';
   source_chat_id?: string;
   source_message_id?: string;
   source_run_id?: string;
@@ -2667,6 +2718,8 @@ export interface UpdateWikiChangesetRequest {
   title?: string;
   message?: string;
   file_changes?: WikiFileChangeInput[];
+  /** Author-settable transitions currently include `proposed` and `closed`. */
+  status?: 'proposed' | 'closed';
   /**
    * When true, file_changes define the changeset's FULL content: the server
    * resets the feature branch to the current default-branch HEAD before
@@ -2832,17 +2885,6 @@ export interface WikiBlob {
   signed_url_expires_at?: string;
 }
 
-export type WikiStoredAs = 'git_blob' | 'lfs_pointer';
-
-/** Response from POST /uploads or POST /changesets/{csId}/files. */
-export interface WikiFileUploadResponse {
-  path: string;
-  size: number;
-  stored_as: WikiStoredAs;
-  commit_sha: string;
-  content_sha: string;
-}
-
 /** Response from POST /files/preview-url — short-lived signed URL for
  * browser `<img>`/`<video>`/`<iframe>` src. TTL is 5 minutes by default. */
 export interface WikiFilePreviewUrlResponse {
@@ -3365,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;
@@ -4161,6 +4204,8 @@ export interface ResolvedRef {
   type: string;
   exists: boolean;
   restricted?: boolean;
+  /** The target could not be resolved because a dependency failed temporarily. */
+  unavailable?: boolean;
 
   // User fields
   display_name?: string;
@@ -5496,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

package/src/wiki-changeset.ts

@@ -0,0 +1,13 @@
+import type { WikiChangeset } from './types.js';
+
+/** Normalize fields that older wiki-service responses may omit. */
+export function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
+  return {
+    ...changeset,
+    head_branch: changeset.head_branch ?? null,
+    base_commit: changeset.base_commit ?? null,
+    merge_commit: changeset.merge_commit ?? null,
+    changed_paths: changeset.changed_paths ?? [],
+    file_changes: changeset.file_changes ?? [],
+  };
+}

package/src/wiki-upload.ts

@@ -0,0 +1,142 @@
+interface WikiFileUploadParamsBase {
+  path: string;
+  file: Blob;
+  message?: string;
+  /** Stable per-file retry key; replays return the original successful path. */
+  uploadId?: string;
+  /** Preserve the legacy 409 by default, or atomically choose `name (N).ext`. */
+  conflict?: 'error' | 'rename';
+  signal?: AbortSignal;
+  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+}
+
+export type WikiStoredAs = 'git_blob' | 'lfs_pointer';
+
+/** Response from POST /uploads or POST /changesets/{csId}/files. */
+export interface WikiFileUploadResponse {
+  path: string;
+  size: number;
+  stored_as: WikiStoredAs;
+  commit_sha: string;
+  content_sha: string;
+}
+
+/** Parameters for the maintain-only direct upload endpoint. */
+export type WikiFileUploadParams = WikiFileUploadParamsBase;
+
+/** Parameters for a changeset-scoped multipart upload. */
+export interface WikiChangesetFileUploadParams extends WikiFileUploadParamsBase {
+  /** `auto` accepts reviewable text as a Git blob on the changeset branch. */
+  contentRoute?: 'binary' | 'auto';
+}
+
+export function createWikiUploadFormData(
+  params: WikiFileUploadParams | WikiChangesetFileUploadParams,
+): FormData {
+  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;
+}
+
+interface MultipartTransportOptions {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: FormData;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+}
+
+/** 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: MultipartTransportOptions): Promise<Response> {
+  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: MultipartTransportOptions,
+  onProgress: (uploadedBytes: number, totalBytes: number) => void,
+): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    let settled = false;
+
+    const finish = (fn: () => void) => {
+      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);
+  });
+}