@parall/sdk 1.31.0 → 1.32.1

package/src/client.ts

@@ -130,6 +130,7 @@ import type {
   TransferChatOwnershipRequest,
   UpdateChatMemberRequest,
   UnreadEntry,
+  ThreadUnreadEntry,
   BillingSummary,
   CreditTransaction,
   CreditTransactionAgentGroup,
@@ -141,6 +142,16 @@ import type {
   UpdateAutoReloadRequest,
   ComputePricing,
   ComputePricingResponse,
+  Clip,
+  AgentClip,
+  CreateClipRequest,
+  UpdateClipRequest,
+  BindAgentClipRequest,
+  InvokeClipRequest,
+  InvokeClipResponse,
+  OnlineClipInfo,
+  RegistryClipInfo,
+  MachineClipInstall,
 } from './types.js';
 
 export interface ParallClientOptions {
@@ -163,16 +174,26 @@ export class ParallClient {
 
   /** Auth endpoints excluded from automatic 401 refresh to prevent recursion. */
   private static readonly AUTH_PATHS = new Set([
-    '/auth/login', '/auth/register', '/auth/refresh', '/auth/logout',
-    '/auth/verify-email', '/auth/resend-code', '/auth/check-email',
-    '/auth/forgot-password', '/auth/reset-password',
+    '/auth/login',
+    '/auth/register',
+    '/auth/refresh',
+    '/auth/logout',
+    '/auth/verify-email',
+    '/auth/resend-code',
+    '/auth/check-email',
+    '/auth/forgot-password',
+    '/auth/reset-password',
   ]);
 
   /** Proactive refresh when token expires within this window (seconds). */
   private static readonly REFRESH_THRESHOLD_S = 5 * 60;
 
   private static normalizeFetchError(err: unknown): ApiError {
-    if (typeof DOMException !== 'undefined' && err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+    if (
+      typeof DOMException !== 'undefined' &&
+      err instanceof DOMException &&
+      (err.name === 'TimeoutError' || err.name === 'AbortError')
+    ) {
       // The SDK only creates internal timeout signals today. If caller-owned
       // cancellation is added later, AbortError should get its own code.
       return new ApiError(0, 'Request timed out', 'REQUEST_TIMEOUT');
@@ -332,14 +353,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;
@@ -401,14 +415,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;
@@ -454,7 +461,10 @@ export class ParallClient {
   }
 
   async resetPassword(token: string, newPassword: string): Promise<AuthTokens> {
-    return this.request('POST', ENDPOINTS.AUTH_RESET_PASSWORD, { token, new_password: newPassword });
+    return this.request('POST', ENDPOINTS.AUTH_RESET_PASSWORD, {
+      token,
+      new_password: newPassword,
+    });
   }
 
   // ---- WebSocket ----
@@ -487,7 +497,11 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.USER_AVATAR);
   }
 
-  async uploadAgentAvatar(orgId: string, agentId: string, file: File | Blob): Promise<AvatarUploadResponse> {
+  async uploadAgentAvatar(
+    orgId: string,
+    agentId: string,
+    file: File | Blob,
+  ): Promise<AvatarUploadResponse> {
     const fd = new FormData();
     fd.append('file', file);
     return this.multipartRequest('POST', ENDPOINTS.AGENT_AVATAR(orgId, agentId), fd);
@@ -501,10 +515,13 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.USER(id));
   }
 
-
   // ---- Organizations ----
 
-  async createOrg(data: { name: string; invite_code: string; avatar_url?: string }): Promise<Organization> {
+  async createOrg(data: {
+    name: string;
+    invite_code: string;
+    avatar_url?: string;
+  }): Promise<Organization> {
     return this.request('POST', ENDPOINTS.ORGS, data);
   }
 
@@ -524,7 +541,12 @@ export class ParallClient {
    */
   async updateOrg(
     orgId: string,
-    data: Partial<Pick<Organization, 'name' | 'avatar_url' | 'smart_routing_strategy' | 'smart_routing_agent_id'>>,
+    data: Partial<
+      Pick<
+        Organization,
+        'name' | 'avatar_url' | 'smart_routing_strategy' | 'smart_routing_agent_id'
+      >
+    >,
   ): Promise<Organization> {
     return this.request('PATCH', ENDPOINTS.ORG(orgId), data);
   }
@@ -539,7 +561,10 @@ export class ParallClient {
   }
 
   async getOnlineMembers(orgId: string): Promise<string[]> {
-    const res = await this.request<{ user_ids: string[] }>('GET', ENDPOINTS.ORG_MEMBERS_ONLINE(orgId));
+    const res = await this.request<{ user_ids: string[] }>(
+      'GET',
+      ENDPOINTS.ORG_MEMBERS_ONLINE(orgId),
+    );
     return res.user_ids ?? [];
   }
 
@@ -596,12 +621,19 @@ export class ParallClient {
 
   // ---- Invitations ----
 
-  async createInvitation(orgId: string, email: string, role?: OrgMemberRole): Promise<OrgInvitation> {
+  async createInvitation(
+    orgId: string,
+    email: string,
+    role?: OrgMemberRole,
+  ): Promise<OrgInvitation> {
     return this.request('POST', ENDPOINTS.ORG_INVITATIONS(orgId), { email, role });
   }
 
   async getOrgInvitations(orgId: string): Promise<OrgInvitation[]> {
-    const res = await this.request<{ data: OrgInvitation[] }>('GET', ENDPOINTS.ORG_INVITATIONS(orgId));
+    const res = await this.request<{ data: OrgInvitation[] }>(
+      'GET',
+      ENDPOINTS.ORG_INVITATIONS(orgId),
+    );
     return res.data;
   }
 
@@ -672,16 +704,17 @@ export class ParallClient {
     jrId: string,
     decision: 'approve' | 'reject',
   ): Promise<OrgJoinRequest> {
-    return this.request(
-      'POST',
-      ENDPOINTS.ORG_INVITE_LINK_JOIN_REQUEST_DECIDE(orgId, jrId),
-      { decision },
-    );
+    return this.request('POST', ENDPOINTS.ORG_INVITE_LINK_JOIN_REQUEST_DECIDE(orgId, jrId), {
+      decision,
+    });
   }
 
   // ---- Direct Messages (org-scoped) ----
 
-  async sendDirectMessage(orgId: string, req: SendDirectMessageRequest): Promise<DirectMessageResponse> {
+  async sendDirectMessage(
+    orgId: string,
+    req: SendDirectMessageRequest,
+  ): Promise<DirectMessageResponse> {
     return this.request('POST', ENDPOINTS.DM(orgId), req);
   }
 
@@ -715,7 +748,22 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.CHAT(orgId, chatId));
   }
 
-  async updateChat(orgId: string, chatId: string, data: Partial<Pick<Chat, 'name' | 'avatar_url' | 'description' | 'visibility' | 'agent_routing_mode' | 'smart_routing_strategy' | 'smart_routing_agent_id'>>): Promise<Chat> {
+  async updateChat(
+    orgId: string,
+    chatId: string,
+    data: Partial<
+      Pick<
+        Chat,
+        | 'name'
+        | 'avatar_url'
+        | 'description'
+        | 'visibility'
+        | 'agent_routing_mode'
+        | 'smart_routing_strategy'
+        | 'smart_routing_agent_id'
+      >
+    >,
+  ): Promise<Chat> {
     return this.request('PATCH', ENDPOINTS.CHAT(orgId, chatId), data);
   }
 
@@ -737,7 +785,12 @@ export class ParallClient {
   }
 
   async deleteChat(orgId: string, chatId: string, opts?: { force?: boolean }): Promise<void> {
-    return this.request('DELETE', ENDPOINTS.CHAT(orgId, chatId), undefined, opts?.force ? { force: 'true' } : undefined);
+    return this.request(
+      'DELETE',
+      ENDPOINTS.CHAT(orgId, chatId),
+      undefined,
+      opts?.force ? { force: 'true' } : undefined,
+    );
   }
 
   async archiveChat(orgId: string, chatId: string): Promise<void> {
@@ -751,7 +804,10 @@ export class ParallClient {
   // ---- Chat Members ----
 
   async getChatMembers(orgId: string, chatId: string): Promise<ChatMember[]> {
-    const res = await this.request<{ data: ChatMember[] }>('GET', ENDPOINTS.CHAT_MEMBERS(orgId, chatId));
+    const res = await this.request<{ data: ChatMember[] }>(
+      'GET',
+      ENDPOINTS.CHAT_MEMBERS(orgId, chatId),
+    );
     return res.data;
   }
 
@@ -763,15 +819,29 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.CHAT_MEMBER(orgId, chatId, userId));
   }
 
-  async updateChatMemberRole(orgId: string, chatId: string, userId: string, role: ChatMemberRole): Promise<void> {
+  async updateChatMemberRole(
+    orgId: string,
+    chatId: string,
+    userId: string,
+    role: ChatMemberRole,
+  ): Promise<void> {
     return this.request('PATCH', ENDPOINTS.CHAT_MEMBER(orgId, chatId, userId), { role });
   }
 
-  async updateChatMember(orgId: string, chatId: string, userId: string, req: UpdateChatMemberRequest): Promise<ChatMember> {
+  async updateChatMember(
+    orgId: string,
+    chatId: string,
+    userId: string,
+    req: UpdateChatMemberRequest,
+  ): Promise<ChatMember> {
     return this.request('PATCH', ENDPOINTS.CHAT_MEMBER(orgId, chatId, userId), req);
   }
 
-  async transferChatOwnership(orgId: string, chatId: string, req: TransferChatOwnershipRequest): Promise<void> {
+  async transferChatOwnership(
+    orgId: string,
+    chatId: string,
+    req: TransferChatOwnershipRequest,
+  ): Promise<void> {
     return this.request('POST', ENDPOINTS.CHAT_TRANSFER_OWNERSHIP(orgId, chatId), req);
   }
 
@@ -792,7 +862,12 @@ export class ParallClient {
       top_level?: boolean;
     },
   ): Promise<PaginatedResponse<Message>> {
-    return this.request('GET', ENDPOINTS.CHAT_MESSAGES(orgId, chatId), undefined, params as Record<string, string | number | boolean | undefined>);
+    return this.request(
+      'GET',
+      ENDPOINTS.CHAT_MESSAGES(orgId, chatId),
+      undefined,
+      params as Record<string, string | number | boolean | undefined>,
+    );
   }
 
   async getMessage(id: string): Promise<Message> {
@@ -825,7 +900,12 @@ export class ParallClient {
   }
 
   async getFileUrl(id: string, opts?: { download?: boolean }): Promise<FileUrlResponse> {
-    return this.request('GET', ENDPOINTS.FILE(id), undefined, opts?.download ? { download: true } : undefined);
+    return this.request(
+      'GET',
+      ENDPOINTS.FILE(id),
+      undefined,
+      opts?.download ? { download: true } : undefined,
+    );
   }
 
   // ---- Approvals ----
@@ -858,7 +938,11 @@ export class ParallClient {
 
   // ---- Agents (org-scoped) ----
 
-  async createAgent(orgId: string, req: CreateAgentRequest, opts?: { timeoutMs?: number }): Promise<CreateAgentResponse> {
+  async createAgent(
+    orgId: string,
+    req: CreateAgentRequest,
+    opts?: { timeoutMs?: number },
+  ): Promise<CreateAgentResponse> {
     return this.request('POST', ENDPOINTS.AGENTS(orgId), req, undefined, false, opts);
   }
 
@@ -877,10 +961,7 @@ export class ParallClient {
    * topology metadata (base URL → provider / tenant) to non-admins,
    * so this dedicated endpoint is the only read path.
    */
-  async getAgentProviderConfig(
-    orgId: string,
-    agentId: string,
-  ): Promise<AgentProviderConfigRead> {
+  async getAgentProviderConfig(orgId: string, agentId: string): Promise<AgentProviderConfigRead> {
     return this.request('GET', ENDPOINTS.AGENT_PROVIDER_CONFIG(orgId, agentId));
   }
 
@@ -909,13 +990,25 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.AGENT_API_KEY(orgId, agentId, key));
   }
 
-  async getAgentActivity(orgId: string, agentId: string, params?: { limit?: number }): Promise<Message[]> {
-    const res = await this.request<{ data: Message[] }>('GET', ENDPOINTS.AGENT_ACTIVITY(orgId, agentId), undefined, params);
+  async getAgentActivity(
+    orgId: string,
+    agentId: string,
+    params?: { limit?: number },
+  ): Promise<Message[]> {
+    const res = await this.request<{ data: Message[] }>(
+      'GET',
+      ENDPOINTS.AGENT_ACTIVITY(orgId, agentId),
+      undefined,
+      params,
+    );
     return res.data;
   }
 
   async getAgentMonitor(orgId: string, agentId: string): Promise<unknown> {
-    const res = await this.request<{ data: unknown }>('GET', ENDPOINTS.AGENT_MONITOR(orgId, agentId));
+    const res = await this.request<{ data: unknown }>(
+      'GET',
+      ENDPOINTS.AGENT_MONITOR(orgId, agentId),
+    );
     return res.data;
   }
 
@@ -931,7 +1024,11 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.AGENT_NEW_SESSION(orgId, agentId));
   }
 
-  async createAgentSession(orgId: string, agentId: string, req: CreateAgentSessionRequest): Promise<AgentSessionDB> {
+  async createAgentSession(
+    orgId: string,
+    agentId: string,
+    req: CreateAgentSessionRequest,
+  ): Promise<AgentSessionDB> {
     return this.request('POST', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), req);
   }
 
@@ -939,27 +1036,60 @@ export class ParallClient {
    * List agent sessions.
    * @param params.status - Comma-separated status filter (e.g., `'open'`).
    */
-  async getAgentSessions(orgId: string, agentId: string, params?: { limit?: number; status?: string; cursor?: string }): Promise<PaginatedResponse<AgentSessionDB>> {
+  async getAgentSessions(
+    orgId: string,
+    agentId: string,
+    params?: { limit?: number; status?: string; cursor?: string },
+  ): Promise<PaginatedResponse<AgentSessionDB>> {
     return this.request('GET', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), undefined, params);
   }
 
-  async getAgentSession(orgId: string, agentId: string, sessionId: string): Promise<AgentSessionDB> {
+  async getAgentSession(
+    orgId: string,
+    agentId: string,
+    sessionId: string,
+  ): Promise<AgentSessionDB> {
     return this.request('GET', ENDPOINTS.AGENT_SESSION(orgId, agentId, sessionId));
   }
 
-  async updateAgentSession(orgId: string, agentId: string, sessionId: string, req: UpdateAgentSessionRequest): Promise<AgentSessionDB> {
+  async updateAgentSession(
+    orgId: string,
+    agentId: string,
+    sessionId: string,
+    req: UpdateAgentSessionRequest,
+  ): Promise<AgentSessionDB> {
     return this.request('PATCH', ENDPOINTS.AGENT_SESSION(orgId, agentId, sessionId), req);
   }
 
-  async createAgentStep(orgId: string, agentId: string, sessionId: string, req: CreateAgentStepRequest): Promise<AgentStep> {
+  async createAgentStep(
+    orgId: string,
+    agentId: string,
+    sessionId: string,
+    req: CreateAgentStepRequest,
+  ): Promise<AgentStep> {
     return this.request('POST', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), req);
   }
 
-  async getAgentSessionSteps(orgId: string, agentId: string, sessionId: string, params?: { limit?: number; cursor?: string }): Promise<PaginatedResponse<AgentStep>> {
-    return this.request('GET', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), undefined, params);
+  async getAgentSessionSteps(
+    orgId: string,
+    agentId: string,
+    sessionId: string,
+    params?: { limit?: number; cursor?: string },
+  ): Promise<PaginatedResponse<AgentStep>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId),
+      undefined,
+      params,
+    );
   }
 
-  async getAgentSessionStep(orgId: string, agentId: string, sessionId: string, stepId: string): Promise<AgentStep> {
+  async getAgentSessionStep(
+    orgId: string,
+    agentId: string,
+    sessionId: string,
+    stepId: string,
+  ): Promise<AgentStep> {
     return this.request('GET', ENDPOINTS.AGENT_SESSION_STEP(orgId, agentId, sessionId, stepId));
   }
 
@@ -978,11 +1108,7 @@ export class ParallClient {
     agentId: string,
     req: StartRuntimeAuthSessionRequest = {},
   ): Promise<RuntimeAuthSession> {
-    return this.request(
-      'POST',
-      ENDPOINTS.AGENT_RUNTIME_AUTH_SESSIONS(orgId, agentId),
-      req,
-    );
+    return this.request('POST', ENDPOINTS.AGENT_RUNTIME_AUTH_SESSIONS(orgId, agentId), req);
   }
 
   async completeAgentRuntimeAuthSession(
@@ -1042,7 +1168,12 @@ export class ParallClient {
     do {
       const params: Record<string, string> = { limit: '100' };
       if (cursor) params.cursor = cursor;
-      const res = await this.request<PaginatedResponse<Task>>('GET', ENDPOINTS.AGENT_TASKS(orgId, agentId), undefined, params);
+      const res = await this.request<PaginatedResponse<Task>>(
+        'GET',
+        ENDPOINTS.AGENT_TASKS(orgId, agentId),
+        undefined,
+        params,
+      );
       all.push(...res.data);
       cursor = res.has_more ? res.next_cursor : undefined;
     } while (cursor);
@@ -1080,11 +1211,17 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.MACHINE_LOGS(orgId, machineId), undefined, { lines });
   }
 
-  async restartMachine(orgId: string, machineId: string): Promise<{ machine_id: string; command_id: string }> {
+  async restartMachine(
+    orgId: string,
+    machineId: string,
+  ): Promise<{ machine_id: string; command_id: string }> {
     return this.request('POST', ENDPOINTS.MACHINE_RESTART(orgId, machineId));
   }
 
-  async restartAllMachines(orgId: string): Promise<{ data: Array<{ machine_id: string; command_id?: string; status: string; error?: string }>; total: number }> {
+  async restartAllMachines(orgId: string): Promise<{
+    data: Array<{ machine_id: string; command_id?: string; status: string; error?: string }>;
+    total: number;
+  }> {
     return this.request('POST', ENDPOINTS.MACHINE_RESTART_ALL(orgId));
   }
 
@@ -1094,7 +1231,10 @@ export class ParallClient {
    * Create a new self-hosted daemon-mode Machine. Returns the Machine row +
    * one-shot mck_ token.
    */
-  async createMachine(orgId: string, opts: { label?: string; compute_mode: 'local' }): Promise<{
+  async createMachine(
+    orgId: string,
+    opts: { label?: string; compute_mode: 'local'; llm_source?: 'parall' | 'runtime_auth' },
+  ): Promise<{
     machine: Machine;
     machine_key: string;
     key_id: string;
@@ -1109,11 +1249,18 @@ export class ParallClient {
    */
   async getDaemonMachines(orgId: string): Promise<Machine[]> {
     const all = await this.getMachines(orgId);
-    return all.filter((m) => m.daemon_mode && m.compute_mode === 'local' && m.status !== 'terminated');
+    return all.filter(
+      (m) => m.daemon_mode && m.compute_mode === 'local' && m.status !== 'terminated',
+    );
   }
 
   /** Attach an agent to a daemon-mode Machine. */
-  async attachAgent(orgId: string, machineId: string, agentId: string, opts?: AttachAgentRequest): Promise<{ status: string; machine_id: string; agent_id: string }> {
+  async attachAgent(
+    orgId: string,
+    machineId: string,
+    agentId: string,
+    opts?: AttachAgentRequest,
+  ): Promise<{ status: string; machine_id: string; agent_id: string }> {
     return this.request('POST', ENDPOINTS.MACHINE_ATTACH_AGENT(orgId, machineId, agentId), opts);
   }
 
@@ -1123,20 +1270,36 @@ export class ParallClient {
   }
 
   async listAgentWorkspaceStates(orgId: string, machineId: string): Promise<AgentWorkspaceState[]> {
-    const res = await this.request<{ data: AgentWorkspaceState[] }>('GET', ENDPOINTS.MACHINE_WORKSPACE_STATES(orgId, machineId));
+    const res = await this.request<{ data: AgentWorkspaceState[] }>(
+      'GET',
+      ENDPOINTS.MACHINE_WORKSPACE_STATES(orgId, machineId),
+    );
     return res.data;
   }
 
-  async patchAgentDaemonConfig(orgId: string, machineId: string, agentId: string, daemonConfig: DaemonAgentConfig): Promise<void> {
-    return this.request('PATCH', ENDPOINTS.MACHINE_AGENT_DAEMON_CONFIG(orgId, machineId, agentId), { daemon_config: daemonConfig });
+  async patchAgentDaemonConfig(
+    orgId: string,
+    machineId: string,
+    agentId: string,
+    daemonConfig: DaemonAgentConfig,
+  ): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.MACHINE_AGENT_DAEMON_CONFIG(orgId, machineId, agentId), {
+      daemon_config: daemonConfig,
+    });
   }
 
   async retryAgentWorkspaceSetup(orgId: string, machineId: string, agentId: string): Promise<void> {
     return this.request('POST', ENDPOINTS.MACHINE_AGENT_WORKSPACE_SETUP(orgId, machineId, agentId));
   }
 
-  async patchMachineLLMSource(orgId: string, machineId: string, llmSource: string): Promise<Machine> {
-    return this.request('PATCH', ENDPOINTS.MACHINE_LLM_SOURCE(orgId, machineId), { llm_source: llmSource });
+  async patchMachineLLMSource(
+    orgId: string,
+    machineId: string,
+    llmSource: string,
+  ): Promise<Machine> {
+    return this.request('PATCH', ENDPOINTS.MACHINE_LLM_SOURCE(orgId, machineId), {
+      llm_source: llmSource,
+    });
   }
 
   /** Get machine-level runtime auth state. */
@@ -1158,7 +1321,11 @@ export class ParallClient {
     sessionId: string,
     req: CompleteRuntimeAuthSessionRequest,
   ): Promise<RuntimeAuthSession> {
-    return this.request('POST', ENDPOINTS.MACHINE_RUNTIME_AUTH_SESSION_COMPLETE(orgId, machineId, sessionId), req);
+    return this.request(
+      'POST',
+      ENDPOINTS.MACHINE_RUNTIME_AUTH_SESSION_COMPLETE(orgId, machineId, sessionId),
+      req,
+    );
   }
 
   async disconnectMachineRuntimeAuth(orgId: string, machineId: string): Promise<void> {
@@ -1188,6 +1355,25 @@ 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',
+      ENDPOINTS.MACHINES_ME_CLIP_INSTALLS,
+    );
+    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/health` — bump the Machine's `updated_at` to now.
    * Body is intentionally empty; the server ignores any payload. The
@@ -1199,13 +1385,20 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.MACHINES_ME_HEALTH, body);
   }
 
-  async reportAgentWorkspaceState(agentId: string, state: {
-    config_hash: string;
-    status: AgentWorkspaceReportStatus;
-    last_error?: string | null;
-    output_tail?: string | null;
-  }): Promise<void> {
-    const res = await this.request<{ status?: string }>('PUT', ENDPOINTS.MACHINES_ME_AGENT_WORKSPACE_STATE(agentId), state);
+  async reportAgentWorkspaceState(
+    agentId: string,
+    state: {
+      config_hash: string;
+      status: AgentWorkspaceReportStatus;
+      last_error?: string | null;
+      output_tail?: string | null;
+    },
+  ): Promise<void> {
+    const res = await this.request<{ status?: string }>(
+      'PUT',
+      ENDPOINTS.MACHINES_ME_AGENT_WORKSPACE_STATE(agentId),
+      state,
+    );
     if (res?.status === 'ignored_stale') {
       throw new ApiError(409, 'Workspace state report ignored as stale', 'STALE_WORKSPACE_STATE');
     }
@@ -1227,11 +1420,18 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.MACHINES_ME_WS_TICKET);
   }
 
-  async postBrowseResponse(requestId: string, response: { request_id: string; path: string; entries: FilesystemEntry[]; error?: string }): Promise<void> {
+  async postBrowseResponse(
+    requestId: string,
+    response: { request_id: string; path: string; entries: FilesystemEntry[]; error?: string },
+  ): Promise<void> {
     return this.request('POST', ENDPOINTS.MACHINES_ME_BROWSE_RESPONSE(requestId), response);
   }
 
-  async resizeMachine(orgId: string, machineId: string, spec: ResizeMachineRequest): Promise<Machine> {
+  async resizeMachine(
+    orgId: string,
+    machineId: string,
+    spec: ResizeMachineRequest,
+  ): Promise<Machine> {
     return this.request('PATCH', ENDPOINTS.MACHINE_SPEC(orgId, machineId), spec);
   }
 
@@ -1240,13 +1440,32 @@ export class ParallClient {
     await this.request('POST', ENDPOINTS.MACHINE_REQUEST_UPDATE(orgId, machineId), { mandatory });
   }
 
-  async browseMachineFilesystem(orgId: string, machineId: string, path: string): Promise<BrowseMachineFilesystemResponse> {
-    return this.request('POST', ENDPOINTS.MACHINE_BROWSE(orgId, machineId), { path }, undefined, false, { timeoutMs: 15_000 });
+  async browseMachineFilesystem(
+    orgId: string,
+    machineId: string,
+    path: string,
+  ): Promise<BrowseMachineFilesystemResponse> {
+    return this.request(
+      'POST',
+      ENDPOINTS.MACHINE_BROWSE(orgId, machineId),
+      { path },
+      undefined,
+      false,
+      { timeoutMs: 15_000 },
+    );
   }
 
   /** Create a new machine key. Returns the raw key string (shown once) + metadata. */
-  async createMachineKey(orgId: string, machineId: string, name?: string): Promise<{ machine_key: string; key_id: string; key: MachineKey }> {
-    return this.request('POST', ENDPOINTS.MACHINE_KEYS(orgId, machineId), name ? { name } : undefined);
+  async createMachineKey(
+    orgId: string,
+    machineId: string,
+    name?: string,
+  ): Promise<{ machine_key: string; key_id: string; key: MachineKey }> {
+    return this.request(
+      'POST',
+      ENDPOINTS.MACHINE_KEYS(orgId, machineId),
+      name ? { name } : undefined,
+    );
   }
 
   /** Revoke (soft-delete) a machine key by ID. */
@@ -1268,12 +1487,25 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHAT_READ(orgId, chatId), { message_id: messageId });
   }
 
+  async getThreadUnread(
+    orgId: string,
+    chatId: string,
+    threadRootId: string,
+  ): Promise<ThreadUnreadEntry> {
+    return this.request('GET', ENDPOINTS.THREAD_UNREAD(orgId, chatId, threadRootId));
+  }
+
   // ---- Inbox ----
 
-  async getInbox(orgId: string, params?: {
-    type?: string; read?: string;
-    limit?: number; cursor?: string;
-  }): Promise<PaginatedResponse<InboxItem>> {
+  async getInbox(
+    orgId: string,
+    params?: {
+      type?: string;
+      read?: string;
+      limit?: number;
+      cursor?: string;
+    },
+  ): Promise<PaginatedResponse<InboxItem>> {
     return this.request('GET', ENDPOINTS.INBOX(orgId), undefined, params as Record<string, string>);
   }
 
@@ -1314,17 +1546,36 @@ export class ParallClient {
 
   // ---- Dispatch (agent event delivery) ----
 
-  async getDispatch(orgId: string, params?: {
-    limit?: number; cursor?: string;
-  }): Promise<PaginatedResponse<DispatchEvent>> {
-    return this.request('GET', ENDPOINTS.DISPATCH(orgId), undefined, params as Record<string, string>);
+  async getDispatch(
+    orgId: string,
+    params?: {
+      limit?: number;
+      cursor?: string;
+    },
+  ): Promise<PaginatedResponse<DispatchEvent>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.DISPATCH(orgId),
+      undefined,
+      params as Record<string, string>,
+    );
   }
 
   async getDispatchPendingCount(orgId: string): Promise<{ count: number }> {
     return this.request('GET', ENDPOINTS.DISPATCH_PENDING_COUNT(orgId));
   }
 
-  async ackDispatch(orgId: string, source: { source_type: string; source_id: string }): Promise<void> {
+  async markDispatchReceived(
+    orgId: string,
+    source: { source_type: string; source_id: string },
+  ): Promise<void> {
+    return this.request('POST', ENDPOINTS.DISPATCH_RECEIVED(orgId), source);
+  }
+
+  async ackDispatch(
+    orgId: string,
+    source: { source_type: string; source_id: string },
+  ): Promise<void> {
     return this.request('POST', ENDPOINTS.DISPATCH_ACK(orgId), source);
   }
 
@@ -1332,6 +1583,20 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.DISPATCH_ACK_BY_ID(orgId, id));
   }
 
+  async getDispatchByMessages(
+    orgId: string,
+    chatId: string,
+    messageIds: string[],
+  ): Promise<{ data: DispatchEvent[] }> {
+    const params = { chat_id: chatId, message_ids: messageIds.join(',') };
+    return this.request(
+      'GET',
+      ENDPOINTS.DISPATCH_BY_MESSAGES(orgId),
+      undefined,
+      params as unknown as Record<string, string>,
+    );
+  }
+
   // ---- Platform Config ----
 
   /**
@@ -1362,14 +1627,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>;
@@ -1381,18 +1639,22 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.TASKS(orgId), data);
   }
 
-  async getTasks(orgId: string, params?: {
-    status?: string;
-    priority?: string;
-    assignee_id?: string;
-    parent_id?: string;
-    project_id?: string;
-    limit?: number;
-    cursor?: string;
-    sort?: string;
-    order?: string;
-    scope?: 'active' | 'archived' | 'all';
-  }): Promise<PaginatedResponse<Task>> {
+  async getTasks(
+    orgId: string,
+    params?: {
+      q?: string;
+      status?: string;
+      priority?: string;
+      assignee_id?: string;
+      parent_id?: string;
+      project_id?: string;
+      limit?: number;
+      cursor?: string;
+      sort?: string;
+      order?: string;
+      scope?: 'active' | 'archived' | 'all';
+    },
+  ): Promise<PaginatedResponse<Task>> {
     return this.request('GET', ENDPOINTS.TASKS(orgId), undefined, params);
   }
 
@@ -1405,7 +1667,12 @@ export class ParallClient {
   }
 
   async deleteTask(orgId: string, taskId: string, opts?: { force?: boolean }): Promise<void> {
-    return this.request('DELETE', ENDPOINTS.TASK(orgId, taskId), undefined, opts?.force ? { force: 'true' } : undefined);
+    return this.request(
+      'DELETE',
+      ENDPOINTS.TASK(orgId, taskId),
+      undefined,
+      opts?.force ? { force: 'true' } : undefined,
+    );
   }
 
   async archiveTask(orgId: string, taskId: string): Promise<void> {
@@ -1425,10 +1692,21 @@ export class ParallClient {
   }
 
   async getTaskWatchers(orgId: string, taskId: string): Promise<TaskWatcher[]> {
-    const res = await this.request<{ data: TaskWatcher[] }>('GET', ENDPOINTS.TASK_WATCHERS(orgId, taskId));
+    const res = await this.request<{ data: TaskWatcher[] }>(
+      'GET',
+      ENDPOINTS.TASK_WATCHERS(orgId, taskId),
+    );
     return res.data;
   }
 
+  async subscribeTaskMember(orgId: string, taskId: string, userId: string): Promise<void> {
+    return this.request('PUT', ENDPOINTS.TASK_SUBSCRIBER(orgId, taskId, userId));
+  }
+
+  async unsubscribeTaskMember(orgId: string, taskId: string, userId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK_SUBSCRIBER(orgId, taskId, userId));
+  }
+
   async watchThread(threadRootId: string): Promise<void> {
     return this.request('POST', ENDPOINTS.MESSAGE_WATCH(threadRootId));
   }
@@ -1438,26 +1716,42 @@ export class ParallClient {
   }
 
   async getThreadWatchers(threadRootId: string): Promise<ThreadWatcher[]> {
-    const res = await this.request<{ data: ThreadWatcher[] }>('GET', ENDPOINTS.MESSAGE_WATCHERS(threadRootId));
+    const res = await this.request<{ data: ThreadWatcher[] }>(
+      'GET',
+      ENDPOINTS.MESSAGE_WATCHERS(threadRootId),
+    );
     return res.data;
   }
 
   async isWatchingThread(threadRootId: string): Promise<boolean> {
-    const res = await this.request<{ watching: boolean }>('GET', ENDPOINTS.MESSAGE_WATCHING(threadRootId));
+    const res = await this.request<{ watching: boolean }>(
+      'GET',
+      ENDPOINTS.MESSAGE_WATCHING(threadRootId),
+    );
     return res.watching;
   }
 
   async getSubtasks(orgId: string, taskId: string): Promise<Task[]> {
-    const res = await this.request<PaginatedResponse<Task>>('GET', ENDPOINTS.TASK_SUBTASKS(orgId, taskId));
+    const res = await this.request<PaginatedResponse<Task>>(
+      'GET',
+      ENDPOINTS.TASK_SUBTASKS(orgId, taskId),
+    );
     return res.data;
   }
 
-  async createTaskRelation(orgId: string, taskId: string, data: CreateTaskRelationRequest): Promise<TaskRelation> {
+  async createTaskRelation(
+    orgId: string,
+    taskId: string,
+    data: CreateTaskRelationRequest,
+  ): Promise<TaskRelation> {
     return this.request('POST', ENDPOINTS.TASK_RELATIONS(orgId, taskId), data);
   }
 
   async getTaskRelations(orgId: string, taskId: string): Promise<TaskRelation[]> {
-    const res = await this.request<{ data: TaskRelation[] }>('GET', ENDPOINTS.TASK_RELATIONS(orgId, taskId));
+    const res = await this.request<{ data: TaskRelation[] }>(
+      'GET',
+      ENDPOINTS.TASK_RELATIONS(orgId, taskId),
+    );
     return res.data;
   }
 
@@ -1482,9 +1776,15 @@ export class ParallClient {
 
   // ---- Task Comments ----
 
-  async getTaskComments(orgId: string, taskId: string, params?: {
-    limit?: number; cursor?: string; order?: string;
-  }): Promise<PaginatedResponse<TaskComment>> {
+  async getTaskComments(
+    orgId: string,
+    taskId: string,
+    params?: {
+      limit?: number;
+      cursor?: string;
+      order?: string;
+    },
+  ): Promise<PaginatedResponse<TaskComment>> {
     return this.request('GET', ENDPOINTS.TASK_COMMENTS(orgId, taskId), undefined, params);
   }
 
@@ -1492,11 +1792,20 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.TASK_COMMENT(orgId, taskId, commentId));
   }
 
-  async createTaskComment(orgId: string, taskId: string, data: CreateTaskCommentRequest): Promise<TaskComment> {
+  async createTaskComment(
+    orgId: string,
+    taskId: string,
+    data: CreateTaskCommentRequest,
+  ): Promise<TaskComment> {
     return this.request('POST', ENDPOINTS.TASK_COMMENTS(orgId, taskId), data);
   }
 
-  async updateTaskComment(orgId: string, taskId: string, commentId: string, data: UpdateTaskCommentRequest): Promise<TaskComment> {
+  async updateTaskComment(
+    orgId: string,
+    taskId: string,
+    commentId: string,
+    data: UpdateTaskCommentRequest,
+  ): Promise<TaskComment> {
     return this.request('PATCH', ENDPOINTS.TASK_COMMENT(orgId, taskId, commentId), data);
   }
 
@@ -1506,9 +1815,14 @@ export class ParallClient {
 
   // ---- Task Activities ----
 
-  async getTaskActivities(orgId: string, taskId: string, params?: {
-    limit?: number; cursor?: string;
-  }): Promise<PaginatedResponse<TaskActivity>> {
+  async getTaskActivities(
+    orgId: string,
+    taskId: string,
+    params?: {
+      limit?: number;
+      cursor?: string;
+    },
+  ): Promise<PaginatedResponse<TaskActivity>> {
     return this.request('GET', ENDPOINTS.TASK_ACTIVITIES(orgId, taskId), undefined, params);
   }
 
@@ -1527,7 +1841,11 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.PROJECT(orgId, projectId));
   }
 
-  async updateProject(orgId: string, projectId: string, data: UpdateProjectRequest): Promise<Project> {
+  async updateProject(
+    orgId: string,
+    projectId: string,
+    data: UpdateProjectRequest,
+  ): Promise<Project> {
     return this.request('PATCH', ENDPOINTS.PROJECT(orgId, projectId), data);
   }
 
@@ -1541,15 +1859,27 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.SCHEDULES(orgId), input);
   }
 
-  async listSchedules(orgId: string, filters?: ScheduleFilters): Promise<PaginatedResponse<Schedule>> {
-    return this.request('GET', ENDPOINTS.SCHEDULES(orgId), undefined, filters as Record<string, string | number | undefined>);
+  async listSchedules(
+    orgId: string,
+    filters?: ScheduleFilters,
+  ): Promise<PaginatedResponse<Schedule>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.SCHEDULES(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
   }
 
   async getSchedule(orgId: string, scheduleId: string): Promise<Schedule> {
     return this.request('GET', ENDPOINTS.SCHEDULE(orgId, scheduleId));
   }
 
-  async updateSchedule(orgId: string, scheduleId: string, patch: UpdateScheduleInput): Promise<Schedule> {
+  async updateSchedule(
+    orgId: string,
+    scheduleId: string,
+    patch: UpdateScheduleInput,
+  ): Promise<Schedule> {
     return this.request('PATCH', ENDPOINTS.SCHEDULE(orgId, scheduleId), patch);
   }
 
@@ -1601,31 +1931,59 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.WIKI(orgId, wikiId));
   }
 
-  async getWikiTree(orgId: string, wikiId: string, params?: { ref?: string; path?: string }): Promise<WikiTreeResponse> {
+  async getWikiTree(
+    orgId: string,
+    wikiId: string,
+    params?: { ref?: string; path?: string },
+  ): Promise<WikiTreeResponse> {
     return this.request('GET', ENDPOINTS.WIKI_TREE(orgId, wikiId), undefined, params);
   }
 
-  async getWikiBlob(orgId: string, wikiId: string, params: { path: string; ref?: string }): Promise<WikiBlob> {
+  async getWikiBlob(
+    orgId: string,
+    wikiId: string,
+    params: { path: string; ref?: string },
+  ): Promise<WikiBlob> {
     return this.request('GET', ENDPOINTS.WIKI_BLOB(orgId, wikiId), undefined, params);
   }
 
-  async getWikiNodeSections(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiNodeSectionArtifact> {
+  async getWikiNodeSections(
+    orgId: string,
+    wikiId: string,
+    params?: { ref?: string },
+  ): Promise<WikiNodeSectionArtifact> {
     return this.request('GET', ENDPOINTS.WIKI_NODE_SECTIONS(orgId, wikiId), undefined, params);
   }
 
-  async searchWiki(orgId: string, wikiId: string, params: { q: string; limit?: number; path_prefix?: string; ref?: string }): Promise<WikiSearchResponse> {
+  async searchWiki(
+    orgId: string,
+    wikiId: string,
+    params: { q: string; limit?: number; path_prefix?: string; ref?: string },
+  ): Promise<WikiSearchResponse> {
     return this.request('GET', ENDPOINTS.WIKI_SEARCH(orgId, wikiId), undefined, params);
   }
 
-  async getWikiPageIndex(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiPageIndex> {
+  async getWikiPageIndex(
+    orgId: string,
+    wikiId: string,
+    params?: { ref?: string },
+  ): Promise<WikiPageIndex> {
     return this.request('GET', ENDPOINTS.WIKI_PAGE_INDEX(orgId, wikiId), undefined, params);
   }
 
-  async getWikiRefs(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiRefsResponse> {
+  async getWikiRefs(
+    orgId: string,
+    wikiId: string,
+    params?: { ref?: string },
+  ): Promise<WikiRefsResponse> {
     return this.request('GET', ENDPOINTS.WIKI_REFS(orgId, wikiId), undefined, params);
   }
 
-  async checkWikiRefs(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiRefsCheckResponse> {
+  async checkWikiRefs(
+    orgId: string,
+    wikiId: string,
+    params?: { ref?: string },
+  ): Promise<WikiRefsCheckResponse> {
     return this.request('GET', ENDPOINTS.WIKI_REFS_CHECK(orgId, wikiId), undefined, params);
   }
 
@@ -1639,17 +1997,32 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.WIKI_ANCHOR_STATUS(orgId, wikiId), body);
   }
 
-  async createWikiChangeset(orgId: string, wikiId: string, data: CreateWikiChangesetRequest): Promise<WikiChangeset> {
-    return normalizeWikiChangeset(await this.request('POST', ENDPOINTS.WIKI_CHANGESETS(orgId, wikiId), data));
+  async createWikiChangeset(
+    orgId: string,
+    wikiId: string,
+    data: CreateWikiChangesetRequest,
+  ): Promise<WikiChangeset> {
+    return normalizeWikiChangeset(
+      await this.request('POST', ENDPOINTS.WIKI_CHANGESETS(orgId, wikiId), data),
+    );
   }
 
   async getWikiChangesets(orgId: string, wikiId: string): Promise<WikiChangeset[]> {
-    const res = await this.request<{ data: WikiChangeset[] }>('GET', ENDPOINTS.WIKI_CHANGESETS(orgId, wikiId));
+    const res = await this.request<{ data: WikiChangeset[] }>(
+      'GET',
+      ENDPOINTS.WIKI_CHANGESETS(orgId, wikiId),
+    );
     return res.data.map(normalizeWikiChangeset);
   }
 
-  async getWikiChangeset(orgId: string, wikiId: string, changesetId: string): Promise<WikiChangeset> {
-    return normalizeWikiChangeset(await this.request('GET', ENDPOINTS.WIKI_CHANGESET(orgId, wikiId, changesetId)));
+  async getWikiChangeset(
+    orgId: string,
+    wikiId: string,
+    changesetId: string,
+  ): Promise<WikiChangeset> {
+    return normalizeWikiChangeset(
+      await this.request('GET', ENDPOINTS.WIKI_CHANGESET(orgId, wikiId, changesetId)),
+    );
   }
 
   async updateWikiChangeset(
@@ -1658,19 +2031,37 @@ export class ParallClient {
     changesetId: string,
     data: UpdateWikiChangesetRequest,
   ): Promise<WikiChangeset> {
-    return normalizeWikiChangeset(await this.request('PATCH', ENDPOINTS.WIKI_CHANGESET(orgId, wikiId, changesetId), data));
+    return normalizeWikiChangeset(
+      await this.request('PATCH', ENDPOINTS.WIKI_CHANGESET(orgId, wikiId, changesetId), data),
+    );
   }
 
-  async getWikiChangesetDiff(orgId: string, wikiId: string, changesetId: string): Promise<WikiDiff> {
+  async getWikiChangesetDiff(
+    orgId: string,
+    wikiId: string,
+    changesetId: string,
+  ): Promise<WikiDiff> {
     return this.request('GET', ENDPOINTS.WIKI_CHANGESET_DIFF(orgId, wikiId, changesetId));
   }
 
-  async mergeWikiChangeset(orgId: string, wikiId: string, changesetId: string): Promise<WikiChangeset> {
-    return normalizeWikiChangeset(await this.request('POST', ENDPOINTS.WIKI_CHANGESET_MERGE(orgId, wikiId, changesetId)));
+  async mergeWikiChangeset(
+    orgId: string,
+    wikiId: string,
+    changesetId: string,
+  ): Promise<WikiChangeset> {
+    return normalizeWikiChangeset(
+      await this.request('POST', ENDPOINTS.WIKI_CHANGESET_MERGE(orgId, wikiId, changesetId)),
+    );
   }
 
-  async closeWikiChangeset(orgId: string, wikiId: string, changesetId: string): Promise<WikiChangeset> {
-    return normalizeWikiChangeset(await this.request('POST', ENDPOINTS.WIKI_CHANGESET_CLOSE(orgId, wikiId, changesetId)));
+  async closeWikiChangeset(
+    orgId: string,
+    wikiId: string,
+    changesetId: string,
+  ): Promise<WikiChangeset> {
+    return normalizeWikiChangeset(
+      await this.request('POST', ENDPOINTS.WIKI_CHANGESET_CLOSE(orgId, wikiId, changesetId)),
+    );
   }
 
   // ---- Wiki Binary Upload / Delete (Phase 2 of wiki-file-storage-design) ----
@@ -1727,12 +2118,10 @@ export class ParallClient {
     wikiId: string,
     params: { path: string; message?: string },
   ): Promise<void> {
-    await this.request(
-      'DELETE',
-      ENDPOINTS.WIKI_FILES(orgId, wikiId),
-      undefined,
-      { path: params.path, message: params.message },
-    );
+    await this.request('DELETE', ENDPOINTS.WIKI_FILES(orgId, wikiId), undefined, {
+      path: params.path,
+      message: params.message,
+    });
   }
 
   /**
@@ -1745,21 +2134,24 @@ export class ParallClient {
     wikiId: string,
     params: { path: string; ref?: string },
   ): Promise<WikiFilePreviewUrlResponse> {
-    return this.request(
-      'POST',
-      ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId),
-      params,
-    );
+    return this.request('POST', ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
   }
 
   // ---- Wiki Path Scopes (AFCS ACL) ----
 
   async getWikiPathScopes(orgId: string, wikiId: string): Promise<WikiPathScope[]> {
-    const res = await this.request<{ data: WikiPathScope[] }>('GET', ENDPOINTS.WIKI_PATH_SCOPES(orgId, wikiId));
+    const res = await this.request<{ data: WikiPathScope[] }>(
+      'GET',
+      ENDPOINTS.WIKI_PATH_SCOPES(orgId, wikiId),
+    );
     return res.data;
   }
 
-  async createWikiPathScope(orgId: string, wikiId: string, data: CreateWikiPathScopeRequest): Promise<WikiPathScope> {
+  async createWikiPathScope(
+    orgId: string,
+    wikiId: string,
+    data: CreateWikiPathScopeRequest,
+  ): Promise<WikiPathScope> {
     return this.request('POST', ENDPOINTS.WIKI_PATH_SCOPES(orgId, wikiId), data);
   }
 
@@ -1767,11 +2159,24 @@ export class ParallClient {
     await this.request('DELETE', ENDPOINTS.WIKI_PATH_SCOPE(orgId, wikiId, scopeId));
   }
 
-  async getWikiAccessStatus(orgId: string, wikiId: string, path?: string): Promise<WikiAccessStatus> {
-    return this.request('GET', ENDPOINTS.WIKI_ACCESS_STATUS(orgId, wikiId), undefined, path ? { path } : undefined);
+  async getWikiAccessStatus(
+    orgId: string,
+    wikiId: string,
+    path?: string,
+  ): Promise<WikiAccessStatus> {
+    return this.request(
+      'GET',
+      ENDPOINTS.WIKI_ACCESS_STATUS(orgId, wikiId),
+      undefined,
+      path ? { path } : undefined,
+    );
   }
 
-  async createWikiAccessRequest(orgId: string, wikiId: string, data: CreateWikiAccessRequest): Promise<void> {
+  async createWikiAccessRequest(
+    orgId: string,
+    wikiId: string,
+    data: CreateWikiAccessRequest,
+  ): Promise<void> {
     await this.request('POST', ENDPOINTS.WIKI_ACCESS_REQUESTS(orgId, wikiId), data);
   }
 
@@ -1791,7 +2196,10 @@ export class ParallClient {
     path: string,
     params?: { page?: number; limit?: number },
   ): Promise<{ data: WikiCommit[]; page: number; limit: number }> {
-    return this.request('GET', ENDPOINTS.WIKI_FILE_COMMITS(orgId, wikiId), undefined, { path, ...params });
+    return this.request('GET', ENDPOINTS.WIKI_FILE_COMMITS(orgId, wikiId), undefined, {
+      path,
+      ...params,
+    });
   }
 
   async getWikiBlame(
@@ -1826,8 +2234,20 @@ export class ParallClient {
   async getComments(
     orgId: string,
     params:
-      | { target_uri: string; target_prefix?: never; limit?: number; cursor?: string; order?: string }
-      | { target_prefix: string; target_uri?: never; limit?: number; cursor?: string; order?: string },
+      | {
+          target_uri: string;
+          target_prefix?: never;
+          limit?: number;
+          cursor?: string;
+          order?: string;
+        }
+      | {
+          target_prefix: string;
+          target_uri?: never;
+          limit?: number;
+          cursor?: string;
+          order?: string;
+        },
   ): Promise<PaginatedResponse<Comment>> {
     return this.request('GET', ENDPOINTS.COMMENTS(orgId), undefined, params);
   }
@@ -1840,7 +2260,11 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.COMMENTS(orgId), data);
   }
 
-  async updateComment(orgId: string, commentId: string, data: UpdateCommentRequest): Promise<Comment> {
+  async updateComment(
+    orgId: string,
+    commentId: string,
+    data: UpdateCommentRequest,
+  ): Promise<Comment> {
     return this.request('PATCH', ENDPOINTS.COMMENT(orgId, commentId), data);
   }
 
@@ -1850,7 +2274,11 @@ export class ParallClient {
 
   // ---- References ----
 
-  async resolveRefs(orgId: string, refs: string[], options?: { sourceMessageId?: string }): Promise<ResolveRefsResponse> {
+  async resolveRefs(
+    orgId: string,
+    refs: string[],
+    options?: { sourceMessageId?: string },
+  ): Promise<ResolveRefsResponse> {
     const body: Record<string, unknown> = { refs };
     if (options?.sourceMessageId) {
       body.source_message_id = options.sourceMessageId;
@@ -1889,7 +2317,9 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.NOTIFICATION_PREFERENCES);
   }
 
-  async updateNotificationPreferences(prefs: Partial<NotifPrefs>): Promise<NotificationPreferences> {
+  async updateNotificationPreferences(
+    prefs: Partial<NotifPrefs>,
+  ): Promise<NotificationPreferences> {
     return this.request('PATCH', ENDPOINTS.NOTIFICATION_PREFERENCES, { prefs });
   }
 
@@ -1905,7 +2335,20 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.BILLING(orgId));
   }
 
-  async listBillingTransactions(orgId: string, opts?: { cursor?: string; limit?: number; types?: string[]; user_id?: string; unresolved_actor?: boolean; machine_id?: string; unresolved_machine?: boolean; from?: string; to?: string }): Promise<{ items: CreditTransaction[]; next_cursor: string | null }> {
+  async listBillingTransactions(
+    orgId: string,
+    opts?: {
+      cursor?: string;
+      limit?: number;
+      types?: string[];
+      user_id?: string;
+      unresolved_actor?: boolean;
+      machine_id?: string;
+      unresolved_machine?: boolean;
+      from?: string;
+      to?: string;
+    },
+  ): Promise<{ items: CreditTransaction[]; next_cursor: string | null }> {
     const params = new URLSearchParams();
     if (opts?.cursor) params.set('cursor', opts.cursor);
     if (opts?.limit) params.set('limit', String(opts.limit));
@@ -1920,14 +2363,20 @@ export class ParallClient {
     return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}${qs ? `?${qs}` : ''}`);
   }
 
-  async listBillingTransactionAgentGroups(orgId: string, opts?: { from?: string; to?: string }): Promise<{ groups: CreditTransactionAgentGroup[] }> {
+  async listBillingTransactionAgentGroups(
+    orgId: string,
+    opts?: { from?: string; to?: string },
+  ): Promise<{ groups: CreditTransactionAgentGroup[] }> {
     const params = new URLSearchParams({ group_by: 'agent' });
     if (opts?.from) params.set('from', opts.from);
     if (opts?.to) params.set('to', opts.to);
     return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}?${params}`);
   }
 
-  async listBillingTransactionMachineGroups(orgId: string, opts?: { from?: string; to?: string }): Promise<{ groups: CreditTransactionMachineGroup[] }> {
+  async listBillingTransactionMachineGroups(
+    orgId: string,
+    opts?: { from?: string; to?: string },
+  ): Promise<{ groups: CreditTransactionMachineGroup[] }> {
     const params = new URLSearchParams({ group_by: 'machine' });
     if (opts?.from) params.set('from', opts.from);
     if (opts?.to) params.set('to', opts.to);
@@ -1953,7 +2402,10 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.BILLING_AUTO_RELOAD(orgId));
   }
 
-  async updateAutoReloadSettings(orgId: string, req: UpdateAutoReloadRequest): Promise<AutoReloadSettings> {
+  async updateAutoReloadSettings(
+    orgId: string,
+    req: UpdateAutoReloadRequest,
+  ): Promise<AutoReloadSettings> {
     return this.request('PUT', ENDPOINTS.BILLING_AUTO_RELOAD(orgId), req);
   }
 
@@ -1964,7 +2416,78 @@ export class ParallClient {
   // own thin client (`ts/admin/lib/api.ts`) that hits these directly.
 
   async getComputePricing(): Promise<ComputePricingResponse> {
-    const resp = await this.request<{ data: ComputePricingResponse }>('GET', ENDPOINTS.COMPUTE_PRICING());
+    const resp = await this.request<{ data: ComputePricingResponse }>(
+      'GET',
+      ENDPOINTS.COMPUTE_PRICING(),
+    );
+    return resp.data;
+  }
+
+  // ---- Clips ----
+
+  async listClips(orgId: string): Promise<Clip[]> {
+    const resp = await this.request<{ data: Clip[] }>('GET', ENDPOINTS.CLIPS(orgId));
+    return resp.data;
+  }
+
+  async createClip(orgId: string, req: CreateClipRequest): Promise<Clip> {
+    return this.request('POST', ENDPOINTS.CLIPS(orgId), req);
+  }
+
+  async getClip(orgId: string, clipId: string): Promise<Clip> {
+    return this.request('GET', ENDPOINTS.CLIP(orgId, clipId));
+  }
+
+  async updateClip(orgId: string, clipId: string, req: UpdateClipRequest): Promise<Clip> {
+    return this.request('PATCH', ENDPOINTS.CLIP(orgId, clipId), req);
+  }
+
+  async deleteClip(orgId: string, clipId: string): Promise<void> {
+    await this.request('DELETE', ENDPOINTS.CLIP(orgId, clipId));
+  }
+
+  async listClipAgents(orgId: string, clipId: string): Promise<AgentClip[]> {
+    const resp = await this.request<{ data: AgentClip[] }>(
+      'GET',
+      ENDPOINTS.CLIP_AGENTS(orgId, clipId),
+    );
+    return resp.data;
+  }
+
+  async listAgentClips(orgId: string, agentId: string): Promise<Clip[]> {
+    const resp = await this.request<{ data: Clip[] }>('GET', ENDPOINTS.AGENT_CLIPS(orgId, agentId));
+    return resp.data;
+  }
+
+  async bindAgentClip(
+    orgId: string,
+    agentId: string,
+    req: BindAgentClipRequest,
+  ): Promise<AgentClip> {
+    return this.request('POST', ENDPOINTS.AGENT_CLIPS(orgId, agentId), req);
+  }
+
+  async unbindAgentClip(orgId: string, agentId: string, clipId: string): Promise<void> {
+    await this.request('DELETE', ENDPOINTS.AGENT_CLIP(orgId, agentId, clipId));
+  }
+
+  async invokeClip(orgId: string, req: InvokeClipRequest): Promise<InvokeClipResponse> {
+    const serverTimeout = Math.max(req.timeout_ms ?? 30000, 1000);
+    const timeoutMs = serverTimeout + 5000;
+    return this.request('POST', ENDPOINTS.CLIP_INVOKE(orgId), req, undefined, false, { timeoutMs });
+  }
+
+  async listOnlineClips(orgId: string): Promise<OnlineClipInfo[]> {
+    const resp = await this.request<{ data: OnlineClipInfo[] }>(
+      'GET',
+      ENDPOINTS.CLIP_ONLINE(orgId),
+    );
+    return resp.data;
+  }
+
+  async listRegistryClips(q?: string): Promise<RegistryClipInfo[]> {
+    const url = ENDPOINTS.CLIP_REGISTRY() + (q ? `?q=${encodeURIComponent(q)}` : '');
+    const resp = await this.request<{ data: RegistryClipInfo[] }>('GET', url);
     return resp.data;
   }
 }
@@ -1979,6 +2502,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,
@@ -1989,3 +2518,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;
+}