@parall/sdk 1.34.0 → 1.35.0

package/src/client.ts

@@ -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,
@@ -103,6 +105,8 @@ import type {
   CreateWikiChangesetRequest,
   UpdateWikiChangesetRequest,
   CreateWikiPathScopeRequest,
+  WikiPathRestriction,
+  CreateWikiPathRestrictionRequest,
   CreateWikiAccessRequest,
   Comment,
   CreateCommentRequest,
@@ -148,6 +152,7 @@ import type {
   AgentClip,
   CreateClipRequest,
   UpdateClipRequest,
+  BulkUpdateClipMetadataRequest,
   BindAgentClipRequest,
   InvokeClipRequest,
   InvokeClipResponse,
@@ -160,6 +165,8 @@ import type {
   CreateBrowserProfileRequest,
   UpdateBrowserProfileRequest,
   BrowserProfileLifecycleRequest,
+  BrowserViewerCommandRequest,
+  BrowserViewerCommandResponse,
   GrantBrowserProfileConsentRequest,
 } from './types.js';
 
@@ -312,7 +319,7 @@ 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) {
@@ -349,6 +356,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);
@@ -580,6 +590,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',
@@ -1007,6 +1022,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 +1274,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 +1366,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 +1527,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,
@@ -2018,7 +2099,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 +2110,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);
   }
@@ -2228,6 +2312,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 +2617,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));
   }

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`,
@@ -617,6 +629,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 +722,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 +744,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 +827,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',

package/src/types.ts

@@ -362,6 +362,17 @@ export interface OrgMember {
   user?: User;
 }
 
+// Team — a named group of org members, referenced in wiki ACLs as `@slug`.
+export interface Team {
+  id: string;
+  org_id: string;
+  name: string;
+  slug: string;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
 // Invitation
 
 export type InvitationStatus = 'pending' | 'accepted' | 'declined' | 'revoked';
@@ -441,11 +452,11 @@ export interface CreateInvitationRequest {
   role?: OrgMemberRole;
 }
 
+// Response of agent API key create/regenerate. The plaintext `api_key` is
+// returned exactly once at mint time and can never be fetched again.
 export interface ApiKey {
   id: string;
-  key: string;
-  agent_id: string;
-  created_at: string;
+  api_key: string;
 }
 
 export interface CreateAgentResponse {
@@ -708,6 +719,10 @@ export type MachineStatus =
   | 'error'
   | 'terminated';
 
+// What a Machine can provide. Composable (a BYOC daemon is typically both) and
+// orthogonal to compute_mode. See hosted-browser-provider-design.md.
+export type MachineCapability = 'agent_host' | 'browser_provider';
+
 export interface Machine {
   id: string;
   org_id: string;
@@ -725,6 +740,13 @@ export interface Machine {
   daemon_mode: boolean;
   llm_source?: string;
   compute_mode: 'hosted' | 'local';
+  // What this machine can provide — composable and orthogonal to compute_mode
+  // (which is lifecycle handoff, not BYOC/role). A BYOC daemon is typically
+  // agent_host + browser_provider; a hosted browser provider pod is browser-only.
+  // Filter agent-host pickers by includes('agent_host') — never by excluding
+  // 'browser_provider'. Absent on servers predating the field. See
+  // docs/engineering-design/hosted-browser-provider-design.md.
+  capabilities?: MachineCapability[];
   // Whether the machine contributes its local clips as a hub provider
   // (org-admin-toggleable via PATCH /machines/{id}/provider-enabled). Absent on
   // servers predating the field → treat as true (default-on). See
@@ -929,6 +951,21 @@ export interface MachineBrowserProfileLifecycleData {
   start_url?: string;
 }
 
+/**
+ * Live-viewer control command relayed to the host daemon over `machine:{id}`.
+ * One command per WebRTC signaling / tab-nav step; the daemon replies via
+ * `POST /machines/me/browser-profiles/viewer-response/{request_id}`.
+ */
+export interface MachineBrowserProfileViewerData {
+  request_id: string;
+  profile_id: string;
+  session_id: string;
+  command: string;
+  input?: Record<string, unknown>;
+  /** Short-lived managed TURN/ICE credentials, minted server-side per stream.start. */
+  turn?: { url: string; username?: string; credential?: string };
+}
+
 export interface AgentNewSessionData {
   previous_session_id?: string;
 }
@@ -1370,6 +1407,10 @@ export interface WikiNodeSection {
   start_line: number;
   end_line: number;
   content: string;
+  /** Frontmatter metadata (OKF-inspired, file-level, all optional). */
+  type?: string;
+  description?: string;
+  tags?: string[];
 }
 
 export interface WikiNodeSectionArtifact {
@@ -1506,15 +1547,24 @@ export interface CreateWikiRequest {
   default_branch?: string;
 }
 
+export interface WikiFileChangeInput {
+  path: string;
+  action: 'create' | 'update' | 'delete';
+  content_base64?: string;
+  base_version?: number;
+  /**
+   * Git blob SHA of the default-branch version this change was authored
+   * against. When set on update/delete, the server rejects the changeset
+   * with 409 STALE_BASE if the file has since changed on the default branch
+   * (prevents silently overwriting concurrent edits).
+   */
+  base_sha?: string;
+}
+
 export interface CreateWikiChangesetRequest {
   title: string;
   message?: string;
-  file_changes: Array<{
-    path: string;
-    action: 'create' | 'update' | 'delete';
-    content_base64?: string;
-    base_version?: number;
-  }>;
+  file_changes: WikiFileChangeInput[];
   source_chat_id?: string;
   source_message_id?: string;
   source_run_id?: string;
@@ -1523,12 +1573,15 @@ export interface CreateWikiChangesetRequest {
 export interface UpdateWikiChangesetRequest {
   title?: string;
   message?: string;
-  file_changes?: Array<{
-    path: string;
-    action: 'create' | 'update' | 'delete';
-    content_base64?: string;
-    base_version?: number;
-  }>;
+  file_changes?: WikiFileChangeInput[];
+  /**
+   * When true, file_changes define the changeset's FULL content: the server
+   * resets the feature branch to the current default-branch HEAD before
+   * applying, so previously-proposed changes that are not re-sent are
+   * dropped. Used by CLI re-propose (`changeset create --update`). Default
+   * false preserves incremental merge semantics (binary-upload flow).
+   */
+  replace_files?: boolean;
 }
 
 export interface WikiCommit {
@@ -1572,11 +1625,42 @@ export interface CreateWikiPathScopeRequest {
   admins?: unknown;
 }
 
+// Narrowing ACL layer — gates a path subtree to `subjects`. Org owners/admins
+// are bound for CONTENT access too, and must be listed to view/edit restricted
+// content. They always keep rule management so they can add themselves, edit, or
+// delete the rule. `apply_to_admins` is retained for wire/data compatibility.
+// `level: read` = fully private folder. See authorization-design.md § Wiki.
+export interface WikiPathRestriction {
+  id: string;
+  wiki_id: string;
+  path: string;
+  level: 'read' | 'maintain' | 'admin';
+  subjects: string[];
+  apply_to_admins: boolean;
+  created_by: string;
+  created_at: string;
+}
+
+export interface CreateWikiPathRestrictionRequest {
+  path: string;
+  level?: 'read' | 'maintain' | 'admin';
+  subjects: string[];
+  apply_to_admins?: boolean;
+}
+
 export interface WikiAccessStatus {
   path: string;
   read: boolean;
   maintain: boolean;
   admin: boolean;
+  // Management-surface capability on the requested path: true for org
+  // owners/admins regardless of content restrictions (which narrow content
+  // access above, never rule management). Gates the Activity tab (root-scoped
+  // operation log).
+  acl_manage: boolean;
+  // True when the caller can administer at least one path in the wiki —
+  // includes delegated sub-tree admins. Gates the Access tab.
+  acl_manage_any: boolean;
 }
 
 export interface CreateWikiAccessRequest {
@@ -2157,6 +2241,7 @@ export type WsEventMap = {
   'machine.update': MachineUpdateData;
   'machine.clip.sync': MachineClipSyncData;
   'machine.browser_profile.lifecycle': MachineBrowserProfileLifecycleData;
+  'machine.browser_profile.viewer': MachineBrowserProfileViewerData;
   'clip.created': ClipCreatedData;
   'clip.removed': ClipRemovedData;
   'clip.updated': ClipUpdatedData;
@@ -2648,6 +2733,8 @@ export interface CreateClipRequest {
 }
 
 export interface UpdateClipRequest {
+  /** Rename the clip's org-local alias; uniqueness enforced per org. */
+  alias?: string;
   name?: string;
   display_name?: string;
   description?: string;
@@ -2659,6 +2746,18 @@ export interface UpdateClipRequest {
   browser_profile_id?: string;
 }
 
+/**
+ * Atomically set application-level metadata (`display_name` and/or
+ * `description`) on every clip instance of an application. All-or-nothing on the
+ * server (one transaction). At least one field must be present; omitted leaves
+ * it unchanged, an empty `description` clears it.
+ */
+export interface BulkUpdateClipMetadataRequest {
+  clip_ids: string[];
+  display_name?: string;
+  description?: string;
+}
+
 export interface BindAgentClipRequest {
   clip_id: string;
   config?: Record<string, unknown>;
@@ -2722,6 +2821,44 @@ export interface BrowserProfileLifecycleRequest {
   start_url?: string;
 }
 
+/** A WebRTC ICE server (STUN/TURN) for the live-viewer peer connection. */
+export interface BrowserViewerIceServer {
+  urls: string[];
+  username?: string;
+  credential?: string;
+}
+
+/** A serialized ICE candidate exchanged during live-viewer signaling. */
+export interface BrowserViewerIceCandidate {
+  candidate: string;
+  sdpMLineIndex?: number | null;
+  sdpMid?: string | null;
+}
+
+/**
+ * One live-viewer control command. The web client drives the WebRTC handshake
+ * (`stream.start` → `stream.answer` → `stream.close`/`stream.switch`) and tab
+ * navigation (`tab_list`/`tab_new`/`open`/`reload`/`back`/`forward`) through a
+ * single endpoint; api-server forwards `command` to the host daemon.
+ */
+export interface BrowserViewerCommandRequest {
+  /** Correlates a viewer session. Omit on `stream.start`; the server returns one. */
+  session_id?: string;
+  command: string;
+  input?: Record<string, unknown>;
+}
+
+export interface BrowserViewerCommandResponse {
+  session_id: string;
+  /**
+   * Command-specific result. For `stream.start`:
+   * `{ offer_sdp: string, candidates: BrowserViewerIceCandidate[], ice_servers: BrowserViewerIceServer[] }`.
+   * May be `null` on the wire — a nil Go result map serializes as JSON null; the
+   * viewer client coalesces it to `{}`.
+   */
+  result: Record<string, unknown> | null;
+}
+
 export interface GrantBrowserProfileConsentRequest {
   clip_id: string;
 }
@@ -2820,6 +2957,10 @@ export interface SearchWikiResult {
   heading_path: string[];
   content_snippet: string;
   score: number;
+  /** Frontmatter document type (OKF facet label), when the file declares one. */
+  type?: string;
+  /** Frontmatter summary; clients may prefer it over content_snippet. */
+  description?: string;
 }
 
 export interface SearchResponse {