@parall/sdk 1.35.0 → 1.36.1

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;
@@ -2411,6 +2603,38 @@ export interface BacklinksResponse {
   next_cursor?: string;
 }
 
+/**
+ * One entity in a multi-hop ref-graph traversal (GET /refs/graph). `id`/`uri` are
+ * the ref_links endpoint identifier: a bare prll:// entity id for most nodes
+ * (`tsk_abc` → `prll://tsk_abc`), but a wiki_file source node carries its file
+ * path (`wik_abc/docs/a.md` → `prll://wik_abc/docs/a.md`, type `wik`). The query
+ * root must be entity-level (refined path/anchor URIs are rejected 400), yet
+ * interior wiki_file nodes can legitimately be path-bearing.
+ */
+export interface RefGraphNode {
+  uri: string; // prll://<id>; a wiki_file node's id includes its file path
+  type: string; // bare prefix: msg, tsk, wik, …
+  id: string; // ref_links endpoint id: bare entity id, or "<wikiID>/<path>" for wiki_file nodes
+  depth: number; // BFS distance from root (0 = root)
+}
+
+/** One directed prll:// reference between two nodes in the graph. */
+export interface RefGraphEdge {
+  source_uri: string;
+  target_uri: string;
+  source_type: string; // full word: message, task, …
+  target_type: string; // bare prefix: msg, tsk, …
+  context?: string;
+}
+
+export interface RefGraphResponse {
+  root: string; // prll://<rootId>
+  depth: number; // effective hop limit used (after server clamping)
+  nodes: RefGraphNode[];
+  edges: RefGraphEdge[];
+  truncated: boolean; // a node/edge cap clipped the result
+}
+
 export interface BrokenRefItem {
   ref_link_id: string;
   source_type: string;
@@ -2778,13 +3002,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 +3032,65 @@ 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;
+  /** Per-profile outbound proxy (BYO provider credentials). Returned to the owner /
+   *  org admin (Get) for the edit form. The password is NEVER returned —
+   *  {@link proxy_password_set} reports only whether one is configured. */
+  proxy_server?: string | null;
+  proxy_username?: string | null;
+  /** True when a proxy password is stored. Drives the edit form's "leave blank to
+   *  keep" affordance; the value itself is never sent to a human-facing client. */
+  proxy_password_set?: 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;
+  /** Non-sensitive discovery flag: does this profile egress through a proxy. The
+   *  proxy server / credentials are NOT in the org-wide list (owner/admin Get only). */
+  proxy_configured?: boolean;
+}
+
+/** Daemon-facing browser profile returned by `GET /machines/me/browser-profiles`
+ *  (mck_-authed, machine-scoped). Unlike {@link BrowserProfile} it carries
+ *  `proxy_password`: the local BYOC daemon must replay it to bb-browser. This is the
+ *  single intended channel for the credential to leave the server — never surface it
+ *  on a human-facing path. */
+export interface MachineBrowserProfile {
+  id: string;
+  org_id: string;
+  placement: BrowserPlacement;
+  machine_id: string | null;
+  owner_user_id: string;
+  display_name: string;
+  status: BrowserProfileStatus;
+  error_msg?: string | null;
+  last_seen?: string | null;
+  proxy_server?: string | null;
+  proxy_username?: string | null;
+  proxy_password?: string | null;
 }
 
 export interface BrowserProfileConsent {
@@ -2807,14 +3105,27 @@ 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;
+  /** Optional BYO proxy. Omit all for direct egress. proxy_server is `host:port`
+   *  (optional http/https/socks5 scheme); proxy_username/password are sent together. */
+  proxy_server?: string | null;
+  proxy_username?: string | null;
+  proxy_password?: string | null;
 }
 
 export interface UpdateBrowserProfileRequest {
   display_name?: string;
+  /** Per-field proxy edit (tri-state): omit = leave unchanged, "" = clear (an empty
+   *  proxy_server clears the whole proxy), value = set. Omitting proxy_password keeps
+   *  the stored one (never re-entered / echoed). */
+  proxy_server?: string | null;
+  proxy_username?: string | null;
+  proxy_password?: string | null;
 }
 
 export interface BrowserProfileLifecycleRequest {
@@ -2921,12 +3232,19 @@ export interface ClipRemovedData {
 
 // ─── Unified Search ───
 
-export interface SearchParams {
+// A type alias (not an interface) so it carries an implicit index signature and
+// can be passed straight to the query-string serializer in client.ts.
+export type SearchParams = {
   q: string;
+  /** Entity selector CSV: message / task / wiki. Distinct from `wiki_type`. */
   types?: string;
   chat_id?: string;
   limit?: number;
-}
+  /** Wiki document-type facet (frontmatter `type`) — a separate axis from `types`. */
+  wiki_type?: string;
+  /** RFC3339 or YYYY-MM-DD; narrows messages (created_at) and tasks (updated_at). Not applied to wiki. */
+  since?: string;
+};
 
 export interface SearchMessageResult {
   message_id: string;