@parall/sdk 1.34.0 → 1.36.0

package/src/client.ts

@@ -1,4 +1,4 @@
-import { ENDPOINTS } from './constants.js';
+import { ENDPOINTS, WIKI_BASE } from './constants.js';
 import type {
   AuthTokens,
   AvatarUploadResponse,
@@ -11,6 +11,7 @@ import type {
   Organization,
   OrgMember,
   OrgMemberRole,
+  Team,
   Chat,
   ChatMember,
   ChatMemberRole,
@@ -34,6 +35,7 @@ import type {
   ApiKey,
   WsTicketResponse,
   Machine,
+  MachineCapability,
   ResizeMachineRequest,
   MachineKey,
   MachineRuntimeAuthState,
@@ -68,6 +70,19 @@ import type {
   UpdateScheduleInput,
   ScheduleFilters,
   ScheduleRunFilters,
+  ExternalConnection,
+  CreateExternalConnectionInput,
+  UpdateExternalConnectionInput,
+  ExternalConnectionFilters,
+  ExternalIngressEvent,
+  ExternalIngressEventFilters,
+  ExternalTrigger,
+  CreateExternalTriggerInput,
+  UpdateExternalTriggerInput,
+  ExternalTriggerFilters,
+  ExternalTriggerRun,
+  ExternalTriggerRunFilters,
+  ExternalTriggerSchema,
   AgentSessionDB,
   AgentStep,
   CreateAgentSessionRequest,
@@ -103,6 +118,8 @@ import type {
   CreateWikiChangesetRequest,
   UpdateWikiChangesetRequest,
   CreateWikiPathScopeRequest,
+  WikiPathRestriction,
+  CreateWikiPathRestrictionRequest,
   CreateWikiAccessRequest,
   Comment,
   CreateCommentRequest,
@@ -148,6 +165,7 @@ import type {
   AgentClip,
   CreateClipRequest,
   UpdateClipRequest,
+  BulkUpdateClipMetadataRequest,
   BindAgentClipRequest,
   InvokeClipRequest,
   InvokeClipResponse,
@@ -155,16 +173,28 @@ import type {
   RegistryClipInfo,
   MachineClip,
   BrowserProfile,
+  BrowserProfileListItem,
   BrowserProfileStatus,
   BrowserProfileConsent,
   CreateBrowserProfileRequest,
   UpdateBrowserProfileRequest,
   BrowserProfileLifecycleRequest,
+  BrowserViewerCommandRequest,
+  BrowserViewerCommandResponse,
   GrantBrowserProfileConsentRequest,
 } from './types.js';
 
 export interface ParallClientOptions {
   baseUrl?: string;
+  /**
+   * Base URL for wiki-service endpoints (paths under `/wiki/v1`). Defaults to
+   * `baseUrl`. Wiki endpoints are served by a separate service from the rest of
+   * the API; in staging/prod one gateway fronts both (so `baseUrl` alone is
+   * correct), but local dev runs api-server (:8080) and wiki-service (:8090)
+   * separately. Set this so wiki calls reach wiki-service while everything else
+   * (chat, tasks, comments, refs) keeps using `baseUrl`.
+   */
+  wikiBaseUrl?: string;
   token?: string;
   onTokenExpired?: () => void;
   getRefreshToken?: () => string | null;
@@ -174,6 +204,7 @@ export interface ParallClientOptions {
 
 export class ParallClient {
   private baseUrl: string;
+  private wikiBaseUrl: string;
   private token: string | null;
   private onTokenExpired?: () => void;
   private getRefreshToken?: () => string | null;
@@ -235,6 +266,10 @@ export class ParallClient {
 
   constructor(options: ParallClientOptions = {}) {
     this.baseUrl = options.baseUrl ?? '';
+    // Defaults to baseUrl so existing single-origin consumers (web, desktop,
+    // hosted agents behind one gateway) are unchanged; only split api/wiki
+    // deployments (local dev) need to set it.
+    this.wikiBaseUrl = options.wikiBaseUrl ?? this.baseUrl;
     this.token = options.token ?? null;
     this.onTokenExpired = options.onTokenExpired;
     this.getRefreshToken = options.getRefreshToken;
@@ -242,6 +277,16 @@ export class ParallClient {
     this.swimlaneName = options.swimlaneName;
   }
 
+  /**
+   * Pick the origin for a request path: wiki-service base for `/wiki/v1`
+   * endpoints, api base for everything else. The path itself (from ENDPOINTS)
+   * is authoritative, so wiki vs api routing can't drift from how a caller
+   * happens to invoke the client.
+   */
+  private baseUrlFor(path: string): string {
+    return path.startsWith(WIKI_BASE) ? this.wikiBaseUrl : this.baseUrl;
+  }
+
   setToken(token: string | null) {
     this.token = token;
   }
@@ -312,14 +357,14 @@ export class ParallClient {
     body?: unknown,
     query?: Record<string, string | number | boolean | undefined>,
     retried = false,
-    opts?: { timeoutMs?: number; signal?: AbortSignal },
+    opts?: { timeoutMs?: number; signal?: AbortSignal; keepalive?: boolean },
   ): Promise<T> {
     // Proactive refresh: block until token is fresh (no-op if still valid)
     if (!retried) {
       await this.ensureFreshToken(path);
     }
 
-    let url = `${this.baseUrl}${path}`;
+    let url = `${this.baseUrlFor(path)}${path}`;
 
     if (query) {
       const params = new URLSearchParams();
@@ -349,6 +394,9 @@ export class ParallClient {
         headers,
         body: body ? JSON.stringify(body) : undefined,
         signal,
+        // keepalive lets a request fired during page unload (e.g. the browser
+        // viewer's stream.close on pagehide) outlive the document.
+        keepalive: opts?.keepalive,
       });
     } catch (err) {
       throw ParallClient.normalizeFetchError(err);
@@ -409,7 +457,7 @@ export class ParallClient {
 
     let res: Response;
     try {
-      res = await fetch(`${this.baseUrl}${path}`, {
+      res = await fetch(`${this.baseUrlFor(path)}${path}`, {
         method,
         headers,
         body,
@@ -580,6 +628,11 @@ export class ParallClient {
     return res.data;
   }
 
+  async getTeams(orgId: string): Promise<Team[]> {
+    const res = await this.request<{ data: Team[] }>('GET', ENDPOINTS.TEAMS(orgId));
+    return res.data;
+  }
+
   async getOnlineMembers(orgId: string): Promise<string[]> {
     const res = await this.request<{ user_ids: string[] }>(
       'GET',
@@ -639,6 +692,22 @@ export class ParallClient {
     );
   }
 
+  // Auto-paginated variant of getMemberTasks: fetches ALL pending tasks
+  // (todo + in_progress) assigned to a member, including subtasks (the
+  // endpoint does not filter parent_id). Powers the CLI `tasks assigned`
+  // command so an agent answering "what's on X's plate" sees the full
+  // backlog, not just the first page.
+  async getMemberTasksAll(orgId: string, memberId: string): Promise<Task[]> {
+    const all: Task[] = [];
+    let cursor: string | undefined;
+    do {
+      const res = await this.getMemberTasks(orgId, memberId, { cursor, limit: 100 });
+      all.push(...res.data);
+      cursor = res.has_more ? res.next_cursor : undefined;
+    } while (cursor);
+    return all;
+  }
+
   // ---- Invitations ----
 
   async createInvitation(
@@ -1007,6 +1076,11 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.AGENT_API_KEYS(orgId, agentId));
   }
 
+  /** Revokes all of the agent's active API keys and mints a replacement. */
+  async regenerateAgentApiKey(orgId: string, agentId: string): Promise<ApiKey> {
+    return this.request('POST', ENDPOINTS.AGENT_API_KEY_REGENERATE(orgId, agentId));
+  }
+
   async revokeAgentApiKey(orgId: string, agentId: string, key: string): Promise<void> {
     return this.request('DELETE', ENDPOINTS.AGENT_API_KEY(orgId, agentId, key));
   }
@@ -1254,7 +1328,15 @@ export class ParallClient {
    */
   async createMachine(
     orgId: string,
-    opts: { label?: string; compute_mode: 'local'; llm_source?: 'parall' | 'runtime_auth' },
+    opts: {
+      label?: string;
+      compute_mode: 'local';
+      llm_source?: 'parall' | 'runtime_auth';
+      // Omit for the default BYOC daemon (agent_host + browser_provider). Pass an
+      // explicit set for a single-purpose host, e.g. ['browser_provider'] for a
+      // platform-hosted bb-browser + Chromium provider.
+      capabilities?: MachineCapability[];
+    },
   ): Promise<{
     machine: Machine;
     machine_key: string;
@@ -1338,6 +1420,22 @@ export class ParallClient {
     });
   }
 
+  /**
+   * Replace the machine's capability set (admin). Primary use: healing a
+   * machine that registered without `browser_provider` during the capability
+   * migration's rolling-deploy window. Removing `agent_host` is rejected by the
+   * server while agents are attached (409 AGENTS_STILL_ATTACHED).
+   */
+  async patchMachineCapabilities(
+    orgId: string,
+    machineId: string,
+    capabilities: MachineCapability[],
+  ): Promise<Machine> {
+    return this.request('PATCH', ENDPOINTS.MACHINE_CAPABILITIES(orgId, machineId), {
+      capabilities,
+    });
+  }
+
   /** Get machine-level runtime auth state. */
   async getMachineRuntimeAuth(orgId: string, machineId: string): Promise<MachineRuntimeAuthState> {
     return this.request('GET', ENDPOINTS.MACHINE_RUNTIME_AUTH(orgId, machineId));
@@ -1483,6 +1581,43 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.MACHINES_ME_BROWSE_RESPONSE(requestId), response);
   }
 
+  /**
+   * `POST /machines/me/browser-profiles/viewer-response/{requestId}` — daemon
+   * reply to a `machine.browser_profile.viewer` control command. Wakes the
+   * api-server request/reply bridge (mirrors {@link postBrowseResponse}).
+   */
+  async postBrowserProfileViewerResponse(
+    requestId: string,
+    response: { result?: Record<string, unknown>; error?: { message: string } },
+  ): Promise<void> {
+    return this.request(
+      'POST',
+      ENDPOINTS.MACHINES_ME_BROWSER_PROFILE_VIEWER_RESPONSE(requestId),
+      response,
+    );
+  }
+
+  /**
+   * `POST /orgs/{orgId}/browser-profiles/{profileId}/viewer/command` — drive the
+   * hosted browser live viewer (WebRTC signaling + tab nav). Authz: profile
+   * owner or org admin. api-server brokers the command to the host daemon.
+   */
+  async browserViewerCommand(
+    orgId: string,
+    profileId: string,
+    req: BrowserViewerCommandRequest,
+    opts?: { timeoutMs?: number; keepalive?: boolean },
+  ): Promise<BrowserViewerCommandResponse> {
+    return this.request(
+      'POST',
+      ENDPOINTS.BROWSER_PROFILE_VIEWER_COMMAND(orgId, profileId),
+      req,
+      undefined,
+      false,
+      opts,
+    );
+  }
+
   async resizeMachine(
     orgId: string,
     machineId: string,
@@ -1666,7 +1801,7 @@ export class ParallClient {
    * Returns null when the server responds with 304 (config unchanged).
    */
   async getPlatformConfig(currentVersion?: string): Promise<PlatformConfigResponse | null> {
-    const url = `${this.baseUrl}${ENDPOINTS.PLATFORM_CONFIG}`;
+    const url = `${this.baseUrlFor(ENDPOINTS.PLATFORM_CONFIG)}${ENDPOINTS.PLATFORM_CONFIG}`;
     const extra: Record<string, string> = {};
     if (currentVersion !== undefined) {
       extra['If-None-Match'] = currentVersion;
@@ -1977,6 +2112,127 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.SCHEDULE_RUN(orgId, runId));
   }
 
+  // ---- External triggers (org-scoped) ----
+
+  async createExternalConnection(
+    orgId: string,
+    input: CreateExternalConnectionInput,
+  ): Promise<ExternalConnection> {
+    return this.request('POST', ENDPOINTS.EXTERNAL_CONNECTIONS(orgId), input);
+  }
+
+  async listExternalConnections(
+    orgId: string,
+    filters?: ExternalConnectionFilters,
+  ): Promise<PaginatedResponse<ExternalConnection>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_CONNECTIONS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalConnection(orgId: string, connectionId: string): Promise<ExternalConnection> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+
+  async updateExternalConnection(
+    orgId: string,
+    connectionId: string,
+    patch: UpdateExternalConnectionInput,
+  ): Promise<ExternalConnection> {
+    return this.request('PATCH', ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId), patch);
+  }
+
+  async regenerateExternalConnectionIngressToken(
+    orgId: string,
+    connectionId: string,
+  ): Promise<ExternalConnection> {
+    return this.request(
+      'POST',
+      ENDPOINTS.EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE(orgId, connectionId),
+    );
+  }
+
+  async deleteExternalConnection(orgId: string, connectionId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+
+  async getExternalTriggerSchema(
+    orgId: string,
+    connectionId: string,
+  ): Promise<ExternalTriggerSchema> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_TRIGGER_SCHEMA(orgId, connectionId));
+  }
+
+  async listExternalIngressEvents(
+    orgId: string,
+    filters?: ExternalIngressEventFilters,
+  ): Promise<PaginatedResponse<ExternalIngressEvent>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_INGRESS_EVENTS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalIngressEvent(orgId: string, eventId: string): Promise<ExternalIngressEvent> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_INGRESS_EVENT(orgId, eventId));
+  }
+
+  async createExternalTrigger(
+    orgId: string,
+    input: CreateExternalTriggerInput,
+  ): Promise<ExternalTrigger> {
+    return this.request('POST', ENDPOINTS.EXTERNAL_TRIGGERS(orgId), input);
+  }
+
+  async listExternalTriggers(
+    orgId: string,
+    filters?: ExternalTriggerFilters,
+  ): Promise<PaginatedResponse<ExternalTrigger>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_TRIGGERS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalTrigger(orgId: string, triggerId: string): Promise<ExternalTrigger> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+
+  async updateExternalTrigger(
+    orgId: string,
+    triggerId: string,
+    patch: UpdateExternalTriggerInput,
+  ): Promise<ExternalTrigger> {
+    return this.request('PATCH', ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId), patch);
+  }
+
+  async deleteExternalTrigger(orgId: string, triggerId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+
+  async listExternalTriggerRuns(
+    orgId: string,
+    filters?: ExternalTriggerRunFilters,
+  ): Promise<PaginatedResponse<ExternalTriggerRun>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_TRIGGER_RUNS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalTriggerRun(orgId: string, runId: string): Promise<ExternalTriggerRun> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_TRIGGER_RUN(orgId, runId));
+  }
+
   // ---- Wikis (org-scoped) ----
 
   async createWiki(orgId: string, data: CreateWikiRequest): Promise<Wiki> {
@@ -2000,12 +2256,43 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.WIKI_TREE(orgId, wikiId), undefined, params);
   }
 
+  /**
+   * Resolve a server-returned, host-relative media URL (a wiki `signed_url`
+   * like `/wiki/v1/signed/files?token=...`) against this client's base origin,
+   * so it can be dropped straight into a browser `<img>`/`<video>`/`<iframe>`
+   * `src`.
+   *
+   * wiki-service returns these relative on purpose — it doesn't know its own
+   * public origin. A relative `src` resolves against the *page* origin, which
+   * only works when the page and wiki-service share an origin (local dev:
+   * same-origin + Next.js `/wiki/*` proxy). In deployed envs the app
+   * (app.parall.com) and wiki-service (api.parall.com) are different origins,
+   * so `app.parall.com/wiki/v1/signed/files` hits the SPA's own `/wiki/[...]`
+   * catch-all route — an `<iframe>` then recursively renders the whole app
+   * instead of the file. Prefixing with the wiki base (the exact origin every
+   * wiki API request already uses — `baseUrlFor` resolves `/wiki/v1` paths to
+   * `wikiBaseUrl`) makes the URL absolute against the origin that actually
+   * serves the bytes. An empty base (local dev, same-origin proxy) leaves it
+   * relative, preserving the proxy path.
+   */
+  private absoluteMediaUrl(url: string): string {
+    if (/^https?:\/\//i.test(url)) return url; // already absolute — leave as-is
+    return `${this.baseUrlFor(url)}${url}`;
+  }
+
   async getWikiBlob(
     orgId: string,
     wikiId: string,
     params: { path: string; ref?: string },
   ): Promise<WikiBlob> {
-    return this.request('GET', ENDPOINTS.WIKI_BLOB(orgId, wikiId), undefined, params);
+    const blob = await this.request<WikiBlob>(
+      'GET',
+      ENDPOINTS.WIKI_BLOB(orgId, wikiId),
+      undefined,
+      params,
+    );
+    if (blob.signed_url) blob.signed_url = this.absoluteMediaUrl(blob.signed_url);
+    return blob;
   }
 
   async getWikiNodeSections(
@@ -2018,7 +2305,9 @@ export class ParallClient {
 
   async search(
     orgId: string,
-    params: { q: string; types?: string; chat_id?: string; limit?: number },
+    // `types` selects entities (message/task/wiki); `wiki_type` is the distinct
+    // wiki document-type facet (frontmatter `type`) — the two never overlap.
+    params: { q: string; types?: string; chat_id?: string; limit?: number; wiki_type?: string },
     opts?: { signal?: AbortSignal },
   ): Promise<SearchResponse> {
     return this.request('GET', ENDPOINTS.SEARCH(orgId), undefined, params, false, opts);
@@ -2027,7 +2316,8 @@ export class ParallClient {
   async searchWiki(
     orgId: string,
     wikiId: string,
-    params: { q: string; limit?: number; path_prefix?: string; ref?: string },
+    // `type` is the wiki document-type facet (frontmatter `type`).
+    params: { q: string; limit?: number; path_prefix?: string; ref?: string; type?: string },
   ): Promise<WikiSearchResponse> {
     return this.request('GET', ENDPOINTS.WIKI_SEARCH(orgId, wikiId), undefined, params);
   }
@@ -2203,7 +2493,13 @@ export class ParallClient {
     wikiId: string,
     params: { path: string; ref?: string },
   ): Promise<WikiFilePreviewUrlResponse> {
-    return this.request('POST', ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
+    const res = await this.request<WikiFilePreviewUrlResponse>(
+      'POST',
+      ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId),
+      params,
+    );
+    if (res.url) res.url = this.absoluteMediaUrl(res.url);
+    return res;
   }
 
   // ---- Wiki Path Scopes (AFCS ACL) ----
@@ -2228,6 +2524,28 @@ export class ParallClient {
     await this.request('DELETE', ENDPOINTS.WIKI_PATH_SCOPE(orgId, wikiId, scopeId));
   }
 
+  // ---- Wiki Path Restrictions (narrowing ACL — private subtrees) ----
+
+  async getWikiRestrictions(orgId: string, wikiId: string): Promise<WikiPathRestriction[]> {
+    const res = await this.request<{ data: WikiPathRestriction[] }>(
+      'GET',
+      ENDPOINTS.WIKI_RESTRICTIONS(orgId, wikiId),
+    );
+    return res.data;
+  }
+
+  async createWikiRestriction(
+    orgId: string,
+    wikiId: string,
+    data: CreateWikiPathRestrictionRequest,
+  ): Promise<WikiPathRestriction> {
+    return this.request('POST', ENDPOINTS.WIKI_RESTRICTIONS(orgId, wikiId), data);
+  }
+
+  async deleteWikiRestriction(orgId: string, wikiId: string, restrictionId: string): Promise<void> {
+    await this.request('DELETE', ENDPOINTS.WIKI_RESTRICTION(orgId, wikiId, restrictionId));
+  }
+
   async getWikiAccessStatus(
     orgId: string,
     wikiId: string,
@@ -2511,6 +2829,11 @@ export class ParallClient {
     return this.request('PATCH', ENDPOINTS.CLIP(orgId, clipId), req);
   }
 
+  /** Atomically set display_name and/or description on multiple clip instances (application metadata). */
+  async bulkUpdateClipMetadata(orgId: string, req: BulkUpdateClipMetadataRequest): Promise<Clip[]> {
+    return this.request('POST', ENDPOINTS.CLIPS_BULK_METADATA(orgId), req);
+  }
+
   async deleteClip(orgId: string, clipId: string): Promise<void> {
     await this.request('DELETE', ENDPOINTS.CLIP(orgId, clipId));
   }
@@ -2554,8 +2877,11 @@ export class ParallClient {
     return resp.data;
   }
 
-  async listBrowserProfiles(orgId: string): Promise<BrowserProfile[]> {
-    const resp = await this.request<{ data: BrowserProfile[] }>(
+  /** Org-wide browser-profile discovery list. Returns the sanitized
+   *  {@link BrowserProfileListItem} shape (not the full domain model), each row
+   *  carrying a per-viewer `can_open` control hint. */
+  async listBrowserProfiles(orgId: string): Promise<BrowserProfileListItem[]> {
+    const resp = await this.request<{ data: BrowserProfileListItem[] }>(
       'GET',
       ENDPOINTS.BROWSER_PROFILES(orgId),
     );

package/src/constants.ts

@@ -347,6 +347,7 @@ export const ENDPOINTS = {
   // Org-scoped
   ORG: (orgId: string) => `${API_BASE}/orgs/${orgId}`,
   ORG_MEMBERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/members`,
+  TEAMS: (orgId: string) => `${API_BASE}/orgs/${orgId}/teams`,
   ORG_MEMBERS_ONLINE: (orgId: string) => `${API_BASE}/orgs/${orgId}/members/online`,
   ORG_MEMBER: (orgId: string, userId: string) => `${API_BASE}/orgs/${orgId}/members/${userId}`,
   ORG_MEMBER_CHATS: (orgId: string, memberId: string) =>
@@ -409,6 +410,8 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys`,
   AGENT_API_KEY: (orgId: string, agentId: string, key: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/${key}`,
+  AGENT_API_KEY_REGENERATE: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/regenerate`,
   AGENT_AVATAR: (orgId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/avatar`,
   AGENT_ACTIVITY: (orgId: string, agentId: string) =>
@@ -479,6 +482,8 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/llm-source`,
   MACHINE_PROVIDER_ENABLED: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/provider-enabled`,
+  MACHINE_CAPABILITIES: (orgId: string, machineId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/capabilities`,
   MACHINE_RUNTIME_AUTH: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth`,
   MACHINE_KEYS: (orgId: string, machineId: string) =>
@@ -511,6 +516,13 @@ export const ENDPOINTS = {
   MACHINES_ME_WS_TICKET: `${API_BASE}/machines/me/ws/ticket`,
   MACHINES_ME_BROWSE_RESPONSE: (requestId: string) =>
     `${API_BASE}/machines/me/browse-response/${requestId}`,
+  // Hosted browser live-viewer control plane (api-server, NOT clip-service):
+  // the web client drives WebRTC signaling + tab nav through VIEWER_COMMAND;
+  // api-server brokers each command to the host daemon via the machine:{id}
+  // request/reply bridge (mirrors filesystem browse), and the daemon replies on
+  // VIEWER_RESPONSE. See docs/engineering-design/hosted-browser-provider-design.md.
+  MACHINES_ME_BROWSER_PROFILE_VIEWER_RESPONSE: (requestId: string) =>
+    `${API_BASE}/machines/me/browser-profiles/viewer-response/${requestId}`,
 
   // Tasks (org-scoped)
   TASKS: (orgId: string) => `${API_BASE}/orgs/${orgId}/tasks`,
@@ -554,6 +566,24 @@ export const ENDPOINTS = {
   SCHEDULE_RUN: (orgId: string, runId: string) =>
     `${API_BASE}/orgs/${orgId}/schedule_runs/${runId}`,
 
+  // External triggers (org-scoped incoming integration primitive)
+  EXTERNAL_CONNECTIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-connections`,
+  EXTERNAL_CONNECTION: (orgId: string, connectionId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}`,
+  EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE: (orgId: string, connectionId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/ingress-token/regenerate`,
+  EXTERNAL_TRIGGER_SCHEMA: (orgId: string, connectionId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/trigger-schema`,
+  EXTERNAL_INGRESS_EVENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-ingress-events`,
+  EXTERNAL_INGRESS_EVENT: (orgId: string, eventId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-ingress-events/${eventId}`,
+  EXTERNAL_TRIGGERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-triggers`,
+  EXTERNAL_TRIGGER: (orgId: string, triggerId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-triggers/${triggerId}`,
+  EXTERNAL_TRIGGER_RUNS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-trigger-runs`,
+  EXTERNAL_TRIGGER_RUN: (orgId: string, runId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-trigger-runs/${runId}`,
+
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
   ORG_INVITATION: (orgId: string, invId: string) =>
@@ -617,6 +647,11 @@ export const ENDPOINTS = {
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/path-scopes`,
   WIKI_PATH_SCOPE: (orgId: string, wikiId: string, scopeId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/path-scopes/${scopeId}`,
+  // Wiki Path Restrictions (AFCS narrowing ACL — private subtrees)
+  WIKI_RESTRICTIONS: (orgId: string, wikiId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/restrictions`,
+  WIKI_RESTRICTION: (orgId: string, wikiId: string, restrictionId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/restrictions/${restrictionId}`,
   WIKI_ACCESS_STATUS: (orgId: string, wikiId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/access-status`,
   WIKI_ACCESS_REQUESTS: (orgId: string, wikiId: string) =>
@@ -705,6 +740,7 @@ export const ENDPOINTS = {
   // Clips (org-scoped, served by clip-service)
   CLIPS: (orgId: string) => `${CLIP_BASE}/orgs/${orgId}/clips`,
   CLIP: (orgId: string, clipId: string) => `${CLIP_BASE}/orgs/${orgId}/clips/${clipId}`,
+  CLIPS_BULK_METADATA: (orgId: string) => `${CLIP_BASE}/orgs/${orgId}/clips/bulk-metadata`,
   CLIP_AGENTS: (orgId: string, clipId: string) =>
     `${CLIP_BASE}/orgs/${orgId}/clips/${clipId}/agents`,
   AGENT_CLIPS: (orgId: string, agentId: string) =>
@@ -726,6 +762,10 @@ export const ENDPOINTS = {
     `${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}`,
+  // Live viewer command — on api-server (API_BASE), not clip-service: it rides
+  // the machine control-plane request/reply bridge that lives in api-server.
+  BROWSER_PROFILE_VIEWER_COMMAND: (orgId: string, profileId: string) =>
+    `${API_BASE}/orgs/${orgId}/browser-profiles/${profileId}/viewer/command`,
 
   // Clip registry (global, served by clip-service → Pinix Hub proxy)
   CLIP_REGISTRY: () => `${CLIP_BASE}/registry/clips`,
@@ -805,6 +845,7 @@ export const WS_EVENTS = {
   MACHINE_CONFIG_UPDATED: 'machine.config.updated',
   MACHINE_CLIP_SYNC: 'machine.clip.sync',
   MACHINE_BROWSER_PROFILE_LIFECYCLE: 'machine.browser_profile.lifecycle',
+  MACHINE_BROWSER_PROFILE_VIEWER: 'machine.browser_profile.viewer',
   AGENT_NEW_SESSION: 'agent.new_session',
   CLIP_CREATED: 'clip.created',
   CLIP_REMOVED: 'clip.removed',