@parall/sdk 1.34.0 → 1.36.0

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;
@@ -362,6 +371,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 +461,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 +728,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 +749,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 +960,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;
 }
@@ -1271,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;
@@ -1370,6 +1596,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 +1736,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 +1762,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 +1814,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 {
@@ -2001,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';
@@ -2157,6 +2431,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;
@@ -2288,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;
@@ -2648,6 +2925,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 +2938,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>;
@@ -2679,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;
@@ -2694,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 {
@@ -2708,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;
 }
@@ -2722,6 +3058,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 +3194,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 {