@parall/sdk 1.32.0 → 1.33.0

package/src/client.ts

@@ -111,6 +111,7 @@ import type {
   InboxItem,
   InboxUnreadCountResponse,
   DispatchEvent,
+  DispatchExpireResult,
   ResolveRefsResponse,
   BacklinksResponse,
   BrokenRefsResponse,
@@ -151,7 +152,14 @@ import type {
   InvokeClipResponse,
   OnlineClipInfo,
   RegistryClipInfo,
-  MachineClipInstall,
+  MachineClip,
+  BrowserProfile,
+  BrowserProfileStatus,
+  BrowserProfileConsent,
+  CreateBrowserProfileRequest,
+  UpdateBrowserProfileRequest,
+  BrowserProfileLifecycleRequest,
+  GrantBrowserProfileConsentRequest,
 } from './types.js';
 
 export interface ParallClientOptions {
@@ -353,22 +361,7 @@ export class ParallClient {
 
     if (!res.ok) {
       const rawErrorBody = await res.json().catch(() => ({}));
-      const errorBody =
-        rawErrorBody !== null && typeof rawErrorBody === 'object'
-          ? (rawErrorBody as Record<string, unknown>)
-          : {};
-      const errorObj =
-        errorBody?.error && typeof errorBody.error === 'object'
-          ? (errorBody.error as { message?: string; code?: string })
-          : undefined;
-      const errMsg =
-        errorObj?.message ?? (typeof errorBody?.error === 'string' ? errorBody.error : undefined);
-      const errCode =
-        errorObj?.code ?? (typeof errorBody?.code === 'string' ? errorBody.code : undefined);
-      const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
-      const { error: _e, code: _c, message: _m, ...extras } = errorBody;
-      if (Object.keys(extras).length > 0) apiError.extras = extras;
-      throw apiError;
+      throw buildApiError(res, rawErrorBody);
     }
 
     if (res.status === 204) return undefined as T;
@@ -430,22 +423,7 @@ export class ParallClient {
 
     if (!res.ok) {
       const rawErrorBody = await res.json().catch(() => ({}));
-      const errorBody =
-        rawErrorBody !== null && typeof rawErrorBody === 'object'
-          ? (rawErrorBody as Record<string, unknown>)
-          : {};
-      const errorObj =
-        errorBody?.error && typeof errorBody.error === 'object'
-          ? (errorBody.error as { message?: string; code?: string })
-          : undefined;
-      const errMsg =
-        errorObj?.message ?? (typeof errorBody?.error === 'string' ? errorBody.error : undefined);
-      const errCode =
-        errorObj?.code ?? (typeof errorBody?.code === 'string' ? errorBody.code : undefined);
-      const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
-      const { error: _e, code: _c, message: _m, ...extras } = errorBody;
-      if (Object.keys(extras).length > 0) apiError.extras = extras;
-      throw apiError;
+      throw buildApiError(res, rawErrorBody);
     }
 
     if (res.status === 204) return undefined as T;
@@ -791,6 +769,7 @@ export class ParallClient {
         | 'agent_routing_mode'
         | 'smart_routing_strategy'
         | 'smart_routing_agent_id'
+        | 'member_invite_policy'
       >
     >,
   ): Promise<Chat> {
@@ -841,8 +820,8 @@ export class ParallClient {
     return res.data;
   }
 
-  async addChatMember(orgId: string, chatId: string, userId: string, role?: string): Promise<void> {
-    return this.request('POST', ENDPOINTS.CHAT_MEMBERS(orgId, chatId), { user_id: userId, role });
+  async addChatMember(orgId: string, chatId: string, userId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.CHAT_MEMBERS(orgId, chatId), { user_id: userId });
   }
 
   async removeChatMember(orgId: string, chatId: string, userId: string): Promise<void> {
@@ -1332,6 +1311,21 @@ export class ParallClient {
     });
   }
 
+  /**
+   * Toggle whether the machine contributes its local clips as a hub provider
+   * — org-admin-gated (RequireOrgAdmin), like all machine management. See
+   * docs/engineering-design/clip-provider-sharing-design.md.
+   */
+  async patchMachineProviderEnabled(
+    orgId: string,
+    machineId: string,
+    providerEnabled: boolean,
+  ): Promise<Machine> {
+    return this.request('PATCH', ENDPOINTS.MACHINE_PROVIDER_ENABLED(orgId, machineId), {
+      provider_enabled: providerEnabled,
+    });
+  }
+
   /** Get machine-level runtime auth state. */
   async getMachineRuntimeAuth(orgId: string, machineId: string): Promise<MachineRuntimeAuthState> {
     return this.request('GET', ENDPOINTS.MACHINE_RUNTIME_AUTH(orgId, machineId));
@@ -1385,34 +1379,54 @@ export class ParallClient {
     return res.data;
   }
 
-  /** `GET /machines/me/clip-installs` — registry clips this machine should
-   * install but hasn't yet (durable reconcile, mck_-authed). */
-  async listClipInstalls(): Promise<MachineClipInstall[]> {
-    const res = await this.request<{ data: MachineClipInstall[] }>(
+  /** `GET /machines/me/clips` — executable Clip definitions assigned to this machine. */
+  async listMachineClips(): Promise<MachineClip[]> {
+    const res = await this.request<{ data: MachineClip[] }>('GET', ENDPOINTS.MACHINES_ME_CLIPS);
+    return res.data;
+  }
+
+  /** `GET /machines/me/browser-profiles` — browser profiles hosted by this machine. */
+  async listMachineBrowserProfiles(): Promise<BrowserProfile[]> {
+    const res = await this.request<{ data: BrowserProfile[] }>(
       'GET',
-      ENDPOINTS.MACHINES_ME_CLIP_INSTALLS,
+      ENDPOINTS.MACHINES_ME_BROWSER_PROFILES,
     );
     return res.data;
   }
 
-  /** `POST /machines/me/clip-installs/{clipId}/installed` — report a finished install. */
-  async reportClipInstall(clipId: string, version?: string): Promise<void> {
-    return this.request(
-      'POST',
-      ENDPOINTS.MACHINES_ME_CLIP_INSTALL_DONE(clipId),
-      version ? { version } : undefined,
-    );
+  /** `POST /machines/me/browser-profiles/{profileId}/status` — report runtime status. */
+  async reportBrowserProfileStatus(
+    profileId: string,
+    status: BrowserProfileStatus,
+    errorMsg?: string,
+  ): Promise<void> {
+    await this.request('POST', ENDPOINTS.MACHINES_ME_BROWSER_PROFILE_STATUS(profileId), {
+      status,
+      ...(errorMsg ? { error_msg: errorMsg } : {}),
+    });
   }
 
   /**
-   * `POST /machines/me/health` — bump the Machine's `updated_at` to now.
-   * Body is intentionally empty; the server ignores any payload. The
-   * daemon should call this on a fixed cadence (e.g. every 30s) so an
-   * external observer can detect a wedged supervisor.
+   * `POST /machines/me/health` — bump the Machine's `updated_at` to now and
+   * report daemon state. The daemon should call this on a fixed cadence (e.g.
+   * every 30s) so an external observer can detect a wedged supervisor. Both
+   * fields are optional and only persisted when changed:
+   *  - `daemonVersion` — the running bundle/launcher version.
+   *  - `selfUpdateCapable` — whether the daemon can act on a machine.update
+   *    signal (true under a service manager, false for bare `npx` foreground).
    */
-  async postMachineHeartbeat(daemonVersion?: string): Promise<void> {
-    const body = daemonVersion ? { daemon_version: daemonVersion } : undefined;
-    return this.request('POST', ENDPOINTS.MACHINES_ME_HEALTH, body);
+  async postMachineHeartbeat(opts?: {
+    daemonVersion?: string;
+    selfUpdateCapable?: boolean;
+  }): Promise<void> {
+    const body: Record<string, unknown> = {};
+    if (opts?.daemonVersion) body.daemon_version = opts.daemonVersion;
+    if (opts?.selfUpdateCapable !== undefined) body.self_update_capable = opts.selfUpdateCapable;
+    return this.request(
+      'POST',
+      ENDPOINTS.MACHINES_ME_HEALTH,
+      Object.keys(body).length > 0 ? body : undefined,
+    );
   }
 
   async reportAgentWorkspaceState(
@@ -1613,6 +1627,11 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.DISPATCH_ACK_BY_ID(orgId, id));
   }
 
+  async expireDispatch(orgId: string, maxAgeHours?: number): Promise<DispatchExpireResult> {
+    const params = maxAgeHours !== undefined ? { max_age_hours: String(maxAgeHours) } : undefined;
+    return this.request('POST', ENDPOINTS.DISPATCH_EXPIRE(orgId), undefined, params);
+  }
+
   async getDispatchByMessages(
     orgId: string,
     chatId: string,
@@ -1657,22 +1676,7 @@ export class ParallClient {
 
     if (!res.ok) {
       const rawErrorBody = await res.json().catch(() => ({}));
-      const errorBody =
-        rawErrorBody !== null && typeof rawErrorBody === 'object'
-          ? (rawErrorBody as Record<string, unknown>)
-          : {};
-      const errorObj =
-        errorBody?.error && typeof errorBody.error === 'object'
-          ? (errorBody.error as { message?: string; code?: string })
-          : undefined;
-      const errMsg =
-        errorObj?.message ?? (typeof errorBody?.error === 'string' ? errorBody.error : undefined);
-      const errCode =
-        errorObj?.code ?? (typeof errorBody?.code === 'string' ? errorBody.code : undefined);
-      const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
-      const { error: _e, code: _c, message: _m, ...extras } = errorBody;
-      if (Object.keys(extras).length > 0) apiError.extras = extras;
-      throw apiError;
+      throw buildApiError(res, rawErrorBody);
     }
 
     return res.json() as Promise<PlatformConfigResponse>;
@@ -2530,6 +2534,80 @@ export class ParallClient {
     return resp.data;
   }
 
+  async listBrowserProfiles(orgId: string): Promise<BrowserProfile[]> {
+    const resp = await this.request<{ data: BrowserProfile[] }>(
+      'GET',
+      ENDPOINTS.BROWSER_PROFILES(orgId),
+    );
+    return resp.data;
+  }
+
+  async createBrowserProfile(
+    orgId: string,
+    req: CreateBrowserProfileRequest,
+  ): Promise<BrowserProfile> {
+    return this.request('POST', ENDPOINTS.BROWSER_PROFILES(orgId), req);
+  }
+
+  async getBrowserProfile(orgId: string, profileId: string): Promise<BrowserProfile> {
+    return this.request('GET', ENDPOINTS.BROWSER_PROFILE(orgId, profileId));
+  }
+
+  async updateBrowserProfile(
+    orgId: string,
+    profileId: string,
+    req: UpdateBrowserProfileRequest,
+  ): Promise<BrowserProfile> {
+    return this.request('PATCH', ENDPOINTS.BROWSER_PROFILE(orgId, profileId), req);
+  }
+
+  async deleteBrowserProfile(orgId: string, profileId: string): Promise<void> {
+    await this.request('DELETE', ENDPOINTS.BROWSER_PROFILE(orgId, profileId));
+  }
+
+  async openBrowserProfile(
+    orgId: string,
+    profileId: string,
+    req: BrowserProfileLifecycleRequest = {},
+  ): Promise<BrowserProfile> {
+    return this.request('POST', ENDPOINTS.BROWSER_PROFILE_OPEN(orgId, profileId), req);
+  }
+
+  async stopBrowserProfile(orgId: string, profileId: string): Promise<BrowserProfile> {
+    return this.request('POST', ENDPOINTS.BROWSER_PROFILE_STOP(orgId, profileId), {});
+  }
+
+  async resetBrowserProfile(orgId: string, profileId: string): Promise<BrowserProfile> {
+    return this.request('POST', ENDPOINTS.BROWSER_PROFILE_RESET(orgId, profileId));
+  }
+
+  async listBrowserProfileConsents(
+    orgId: string,
+    profileId: string,
+  ): Promise<BrowserProfileConsent[]> {
+    const resp = await this.request<{ data: BrowserProfileConsent[] }>(
+      'GET',
+      ENDPOINTS.BROWSER_PROFILE_CONSENTS(orgId, profileId),
+    );
+    return resp.data;
+  }
+
+  async grantBrowserProfileConsent(
+    orgId: string,
+    profileId: string,
+    req: GrantBrowserProfileConsentRequest,
+  ): Promise<BrowserProfileConsent> {
+    return this.request('POST', ENDPOINTS.BROWSER_PROFILE_CONSENTS(orgId, profileId), req);
+  }
+
+  async revokeBrowserProfileConsent(
+    orgId: string,
+    profileId: string,
+    clipId: string,
+  ): Promise<void> {
+    await this.request('DELETE', ENDPOINTS.BROWSER_PROFILE_CONSENT(orgId, profileId, clipId));
+  }
+
   async listRegistryClips(q?: string): Promise<RegistryClipInfo[]> {
     const url = ENDPOINTS.CLIP_REGISTRY() + (q ? `?q=${encodeURIComponent(q)}` : '');
     const resp = await this.request<{ data: RegistryClipInfo[] }>('GET', url);
@@ -2547,6 +2625,12 @@ function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
 
 export class ApiError extends Error {
   extras?: Record<string, unknown>;
+  /** Attempted action (authorization denials) — e.g. "chat.add_member". */
+  action?: string;
+  /** Target resource URI that was evaluated — e.g. "prll://cht_…". */
+  resourceUri?: string;
+  /** Whether the action is approval-executable (PERMISSION_DENIED only). */
+  approvable?: boolean;
 
   constructor(
     public status: number,
@@ -2557,3 +2641,57 @@ export class ApiError extends Error {
     this.name = 'ApiError';
   }
 }
+
+/**
+ * Parse a non-2xx response body into a typed ApiError, losslessly.
+ *
+ * The wire envelope is `{ "error": { code, message, status, action?,
+ * resource_uri?, approvable? } }`. We read message/code/anchors from the
+ * nested `error` object, with a fallback to a legacy flat shape, and never
+ * silently drop to HTTP status text when a real message is present.
+ * See docs/engineering-design/error-contract-design.md
+ */
+function buildApiError(
+  res: { status: number; statusText: string },
+  rawErrorBody: unknown,
+): ApiError {
+  const errorBody =
+    rawErrorBody !== null && typeof rawErrorBody === 'object'
+      ? (rawErrorBody as Record<string, unknown>)
+      : {};
+  const errorObj =
+    errorBody.error && typeof errorBody.error === 'object'
+      ? (errorBody.error as Record<string, unknown>)
+      : undefined;
+  // message/code live under `error`. Tolerate two legacy shapes from
+  // not-yet-migrated services: a flat `{code, message, ...}` (read top-level
+  // message/code) and a bare `{error: "text"}`. Never silently drop to
+  // res.statusText when the server provided a real message.
+  const errMsg =
+    (typeof errorObj?.message === 'string' ? errorObj.message : undefined) ??
+    (typeof errorBody.message === 'string' ? (errorBody.message as string) : undefined) ??
+    (typeof errorBody.error === 'string' ? (errorBody.error as string) : undefined);
+  const errCode =
+    (typeof errorObj?.code === 'string' ? errorObj.code : undefined) ??
+    (typeof errorBody.code === 'string' ? (errorBody.code as string) : undefined);
+  const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
+  // Machine anchors: present under `error`, with a legacy flat fallback.
+  const anchors = errorObj ?? errorBody;
+  if (typeof anchors.action === 'string') apiError.action = anchors.action;
+  if (typeof anchors.resource_uri === 'string') apiError.resourceUri = anchors.resource_uri;
+  if (typeof anchors.approvable === 'boolean') apiError.approvable = anchors.approvable as boolean;
+  // Preserve any other fields — from both the top level and the nested `error`
+  // object — so additive/unknown server fields survive (transparent mirror;
+  // keeps ApiError.extras meaningful for third-party consumers).
+  // The anchors (action/resource_uri/approvable) are exposed as typed fields
+  // above but ALSO kept in `extras` for one compatibility window, so consumers
+  // written against the old `err.extras?.action` shape don't break on upgrade.
+  // Only the envelope-structural keys are excluded.
+  const structural = new Set(['error', 'code', 'message', 'status']);
+  const extras: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(errorBody)) if (!structural.has(k)) extras[k] = v;
+  if (errorObj)
+    for (const [k, v] of Object.entries(errorObj)) if (!structural.has(k)) extras[k] = v;
+  if (Object.keys(extras).length > 0) apiError.extras = extras;
+  return apiError;
+}

package/src/constants.ts

@@ -415,6 +415,8 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}/workspace/setup`,
   MACHINE_LLM_SOURCE: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/llm-source`,
+  MACHINE_PROVIDER_ENABLED: (orgId: string, machineId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/provider-enabled`,
   MACHINE_RUNTIME_AUTH: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth`,
   MACHINE_KEYS: (orgId: string, machineId: string) =>
@@ -436,9 +438,10 @@ export const ENDPOINTS = {
   MACHINES_ME: `${API_BASE}/machines/me`,
   MACHINES_ME_AGENTS: `${API_BASE}/machines/me/agents`,
   MACHINES_ME_HEALTH: `${API_BASE}/machines/me/health`,
-  MACHINES_ME_CLIP_INSTALLS: `${API_BASE}/machines/me/clip-installs`,
-  MACHINES_ME_CLIP_INSTALL_DONE: (clipId: string) =>
-    `${API_BASE}/machines/me/clip-installs/${clipId}/installed`,
+  MACHINES_ME_CLIPS: `${API_BASE}/machines/me/clips`,
+  MACHINES_ME_BROWSER_PROFILES: `${API_BASE}/machines/me/browser-profiles`,
+  MACHINES_ME_BROWSER_PROFILE_STATUS: (profileId: string) =>
+    `${API_BASE}/machines/me/browser-profiles/${profileId}/status`,
   MACHINES_ME_AGENT_LAUNCH_CREDENTIAL: (agentId: string) =>
     `${API_BASE}/machines/me/agents/${agentId}/launch-credential`,
   MACHINES_ME_AGENT_WORKSPACE_STATE: (agentId: string) =>
@@ -593,6 +596,7 @@ export const ENDPOINTS = {
   DISPATCH_RECEIVED: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/received`,
   DISPATCH_ACK: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/ack`,
   DISPATCH_ACK_BY_ID: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/dispatch/${id}/ack`,
+  DISPATCH_EXPIRE: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/expire`,
   DISPATCH_BY_MESSAGES: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/by-messages`,
 
   // Unread
@@ -644,6 +648,19 @@ export const ENDPOINTS = {
     `${CLIP_BASE}/orgs/${orgId}/agents/${agentId}/clips/${clipId}`,
   CLIP_INVOKE: (orgId: string) => `${CLIP_BASE}/orgs/${orgId}/invoke`,
   CLIP_ONLINE: (orgId: string) => `${CLIP_BASE}/orgs/${orgId}/online`,
+  BROWSER_PROFILES: (orgId: string) => `${CLIP_BASE}/orgs/${orgId}/browser-profiles`,
+  BROWSER_PROFILE: (orgId: string, profileId: string) =>
+    `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}`,
+  BROWSER_PROFILE_OPEN: (orgId: string, profileId: string) =>
+    `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/open`,
+  BROWSER_PROFILE_STOP: (orgId: string, profileId: string) =>
+    `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/stop`,
+  BROWSER_PROFILE_RESET: (orgId: string, profileId: string) =>
+    `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/reset`,
+  BROWSER_PROFILE_CONSENTS: (orgId: string, profileId: string) =>
+    `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/consents`,
+  BROWSER_PROFILE_CONSENT: (orgId: string, profileId: string, clipId: string) =>
+    `${CLIP_BASE}/orgs/${orgId}/browser-profiles/${profileId}/consents/${clipId}`,
 
   // Clip registry (global, served by clip-service → Pinix Hub proxy)
   CLIP_REGISTRY: () => `${CLIP_BASE}/registry/clips`,
@@ -721,9 +738,10 @@ export const WS_EVENTS = {
   MACHINE_FILESYSTEM_BROWSE: 'machine.filesystem.browse',
   MACHINE_UPDATE: 'machine.update',
   MACHINE_CONFIG_UPDATED: 'machine.config.updated',
-  MACHINE_CLIP_INSTALL: 'machine.clip.install',
+  MACHINE_CLIP_SYNC: 'machine.clip.sync',
+  MACHINE_BROWSER_PROFILE_LIFECYCLE: 'machine.browser_profile.lifecycle',
   AGENT_NEW_SESSION: 'agent.new_session',
-  CLIP_INSTALLED: 'clip.installed',
+  CLIP_CREATED: 'clip.created',
   CLIP_REMOVED: 'clip.removed',
   CLIP_UPDATED: 'clip.updated',
 } as const;