@parall/sdk 1.35.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,
@@ -70,6 +70,19 @@ import type {
   UpdateScheduleInput,
   ScheduleFilters,
   ScheduleRunFilters,
+  ExternalConnection,
+  CreateExternalConnectionInput,
+  UpdateExternalConnectionInput,
+  ExternalConnectionFilters,
+  ExternalIngressEvent,
+  ExternalIngressEventFilters,
+  ExternalTrigger,
+  CreateExternalTriggerInput,
+  UpdateExternalTriggerInput,
+  ExternalTriggerFilters,
+  ExternalTriggerRun,
+  ExternalTriggerRunFilters,
+  ExternalTriggerSchema,
   AgentSessionDB,
   AgentStep,
   CreateAgentSessionRequest,
@@ -160,6 +173,7 @@ import type {
   RegistryClipInfo,
   MachineClip,
   BrowserProfile,
+  BrowserProfileListItem,
   BrowserProfileStatus,
   BrowserProfileConsent,
   CreateBrowserProfileRequest,
@@ -172,6 +186,15 @@ import type {
 
 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;
@@ -181,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;
@@ -242,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;
@@ -249,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;
   }
@@ -326,7 +364,7 @@ export class ParallClient {
       await this.ensureFreshToken(path);
     }
 
-    let url = `${this.baseUrl}${path}`;
+    let url = `${this.baseUrlFor(path)}${path}`;
 
     if (query) {
       const params = new URLSearchParams();
@@ -419,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,
@@ -654,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(
@@ -1747,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;
@@ -2058,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> {
@@ -2081,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(
@@ -2287,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) ----
@@ -2665,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

@@ -566,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) =>

package/src/types.ts

@@ -264,6 +264,15 @@ export interface Message {
   content: MessageContent;
   version: number;
   reply_count: number;
+  /** Timestamp of the most recent reply in this message's thread (root only). */
+  last_reply_at?: string | null;
+  /**
+   * Most-recent distinct reply authors, newest-first (root only, capped at 3).
+   * Approximate: derived from the newest ~30 replies per root, so on very long
+   * threads dominated by a few recent senders, older distinct authors may be
+   * absent from the stack. A reload re-derives it from the server's view.
+   */
+  recent_repliers?: User[];
   edited_at: string | null;
   deleted_at: string | null;
   created_at: string;
@@ -1308,6 +1317,186 @@ export interface ScheduleRunFilters {
   limit?: number;
 }
 
+// ============================================================
+// External Trigger Types
+// ============================================================
+
+export type ExternalConnectionStatus = 'active' | 'disabled';
+export type ExternalIngressEventStatus = 'received' | 'processed' | 'failed';
+export type ExternalTriggerStatus = 'active' | 'paused';
+export type ExternalTriggerEffectiveStatus = 'active' | 'inactive';
+export type ExternalTriggerInactiveReason =
+  | 'connection_disabled'
+  | 'connection_archived'
+  | 'trigger_paused'
+  | 'trigger_archived'
+  | 'expired'
+  | 'max_runs_reached';
+export type ExternalTriggerRunStatus = 'delivered' | 'failed';
+
+export interface ExternalConnection {
+  id: string;
+  org_id: string;
+  source_type: string;
+  display_name: string;
+  owner_id: string;
+  status: ExternalConnectionStatus;
+  auth_config: Record<string, unknown>;
+  archived_at: string | null;
+  archive_reason: string | null;
+  ingress_url?: string;
+  ingress_token?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateExternalConnectionInput {
+  source_type?: string;
+  display_name: string;
+}
+
+export interface UpdateExternalConnectionInput {
+  display_name?: string;
+  status?: ExternalConnectionStatus;
+}
+
+export interface ExternalIngressEvent {
+  id: string;
+  org_id: string;
+  connection_id: string;
+  status: ExternalIngressEventStatus;
+  dedupe_key: string | null;
+  event_type: string;
+  request_snapshot: Record<string, unknown>;
+  body_snapshot: Record<string, unknown>;
+  envelope_snapshot: Record<string, unknown>;
+  raw_body_sha256: string;
+  body_size: number;
+  error_code: string | null;
+  error_message: string | null;
+  received_at: string;
+  processed_at: string | null;
+}
+
+export interface ExternalTrigger {
+  id: string;
+  org_id: string;
+  connection_id: string;
+  creator_id: string;
+  name: string;
+  description: string;
+  status: ExternalTriggerStatus;
+  effective_status: ExternalTriggerEffectiveStatus;
+  inactive_reason?: ExternalTriggerInactiveReason;
+  archived_at: string | null;
+  archive_reason: string | null;
+  attached_to_uri: string | null;
+  filter_language: 'cel';
+  filter_profile: 'parall_cel_v1';
+  filter_expr: string;
+  filter_display_metadata: Record<string, unknown>;
+  template_language: 'liquid';
+  template_profile: 'parall_safe_v1';
+  agent_input_template: string;
+  max_runs: number | null;
+  run_count: number;
+  expires_at: string | null;
+  client_context: Record<string, unknown>;
+  target_agent_ids: string[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateExternalTriggerInput {
+  connection_id: string;
+  name: string;
+  description?: string;
+  target_agent_ids: string[];
+  attached_to_uri?: string;
+  filter_expr: string;
+  filter_display_metadata?: Record<string, unknown>;
+  agent_input_template: string;
+  max_runs?: number;
+  expires_at?: string;
+  client_context?: Record<string, unknown>;
+}
+
+export interface UpdateExternalTriggerInput {
+  name?: string;
+  description?: string;
+  status?: ExternalTriggerStatus;
+  target_agent_ids?: string[];
+  attached_to_uri?: string;
+  attached_to_uri_clear?: boolean;
+  filter_expr?: string;
+  filter_display_metadata?: Record<string, unknown>;
+  agent_input_template?: string;
+  max_runs?: number;
+  max_runs_clear?: boolean;
+  expires_at?: string;
+  expires_at_clear?: boolean;
+  client_context?: Record<string, unknown>;
+}
+
+export interface ExternalTriggerRun {
+  id: string;
+  org_id: string;
+  connection_id: string;
+  ingress_event_id: string;
+  trigger_id: string;
+  status: ExternalTriggerRunStatus;
+  failure_stage: string | null;
+  error_code: string | null;
+  error_message: string | null;
+  agent_input_body: string | null;
+  trigger_snapshot: Record<string, unknown>;
+  configured_target_agent_ids: string[];
+  eligible_target_agent_ids: string[];
+  skipped_target_agent_ids: string[];
+  dispatch_event_ids: string[];
+  trigger_name?: string;
+  connection_source_type?: string;
+  connection_display_name?: string;
+  ingress_event_type?: string;
+  created_at: string;
+  delivered_at: string | null;
+}
+
+export interface ExternalConnectionFilters {
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ExternalTriggerFilters {
+  connection_id?: string;
+  creator_id?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ExternalIngressEventFilters {
+  connection_id?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ExternalTriggerRunFilters {
+  trigger_id?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ExternalTriggerSchema {
+  filter_language: 'cel';
+  filter_profile: 'parall_cel_v1';
+  template_language: 'liquid';
+  template_profile: 'parall_safe_v1';
+  filter_variables: string[];
+  template_variables: string[];
+  template_filters: string[];
+  examples: Record<string, string>;
+}
+
 // Schedule WS event data
 export type ScheduleCreatedData = Schedule;
 export type ScheduleUpdatedData = Schedule;
@@ -2085,6 +2274,7 @@ export type DispatchEventType =
   | 'task_comment'
   | 'wiki_comment'
   | 'schedule.fire'
+  | 'external_trigger'
   | 'approval_decided';
 export type DispatchStatus = 'pending' | 'received' | 'acked';
 export type DispatchDeliveryReason = 'mention' | 'watcher' | 'assignee' | 'creator';
@@ -2373,6 +2563,8 @@ export interface ResolvedRef {
   // Wiki fields
   file_name?: string;
   wiki_name?: string;
+  /** Frontmatter description of the referenced wiki page (OKF), when present. */
+  wiki_description?: string;
   fragment_exists?: boolean;
   anchor_kind?: string;
   anchor_exists?: boolean;
@@ -2778,13 +2970,28 @@ export interface InvokeClipResponse {
   error: string | null;
 }
 
-export type BrowserProfileStatus = 'pending' | 'running' | 'stopped' | 'error';
+/**
+ * profile.status is owner INTENT only, never runtime readiness:
+ *   - BYOC:   pending | running | stopped | error
+ *   - hosted: idle | stopped | error  (idle = enabled, activates lazily on invoke/viewer)
+ * Whether a hosted pod is registered + routable is the lease/controller/provider's
+ * runtime state, NOT profile status — hosted profiles are never `active`.
+ */
+export type BrowserProfileStatus = 'pending' | 'running' | 'stopped' | 'error' | 'idle';
+
+/**
+ * Routing/identity discriminant: `byoc` runs on a user machine (machine_id
+ * required), `hosted` runs on the platform pool (machine_id null).
+ */
+export type BrowserPlacement = 'byoc' | 'hosted';
 
 export interface BrowserProfile {
   id: string;
   org_id: string;
-  /** Host machine where the profile's cookies / bb-browser account live. */
-  machine_id: string;
+  /** byoc = user machine, hosted = platform pool. */
+  placement: BrowserPlacement;
+  /** Host machine for byoc profiles; null for hosted (the platform pool owns the pod). */
+  machine_id: string | null;
   owner_user_id: string;
   display_name: string;
   status: BrowserProfileStatus;
@@ -2793,6 +3000,34 @@ export interface BrowserProfile {
   created_by?: string | null;
   created_at: string;
   updated_at: string;
+  /** Control hint on the single-profile responses (create / get / lifecycle) —
+   *  always true, since reaching those endpoints means the caller passed the read
+   *  or control gate and owner/admin can always control. The org-wide list uses
+   *  {@link BrowserProfileListItem.can_open} (per-viewer) instead. */
+  can_open?: boolean;
+}
+
+/** Sanitized row from `GET /orgs/{orgId}/browser-profiles` (org-wide discovery).
+ *  Carries only the fields the Browser Profiles tab needs to render + gate
+ *  actions — the full domain model (provenance, timestamps) is never returned
+ *  org-wide. `error_msg` / `last_seen` are present only for readers (the profile
+ *  owner or an org admin), not merely for own-local host owners who can `can_open`. */
+export interface BrowserProfileListItem {
+  id: string;
+  org_id: string;
+  /** byoc = user machine, hosted = platform pool. */
+  placement: BrowserPlacement;
+  /** Host machine for byoc; null for hosted (the platform pool owns the pod). */
+  machine_id: string | null;
+  owner_user_id: string;
+  display_name: string;
+  status: BrowserProfileStatus;
+  /** Per-viewer control hint computed by the server (owner / org admin / own
+   *  local host machine). Optional only for forward-compat with an older
+   *  clip-service mid web-first rollout; the current server always sets it. */
+  can_open?: boolean;
+  error_msg?: string | null;
+  last_seen?: string | null;
 }
 
 export interface BrowserProfileConsent {
@@ -2807,8 +3042,10 @@ export interface BrowserProfileConsent {
 }
 
 export interface CreateBrowserProfileRequest {
-  /** Host machine that runs the BrowserProfile (cookies / bb-browser account). */
-  machine_id: string;
+  /** Defaults to `byoc` when omitted (backward compatible). */
+  placement?: BrowserPlacement;
+  /** Required for byoc; omitted for hosted (the platform pool assigns a pod). */
+  machine_id?: string | null;
   owner_user_id: string;
   display_name: string;
 }