@parall/sdk 1.31.0 → 1.32.1

package/src/types.ts

@@ -104,15 +104,22 @@ export interface TransferChatOwnershipRequest {
 export interface UnreadEntry {
   count: number;
   mentions: number;
+  since?: string;
+}
+
+export interface ThreadUnreadEntry {
+  unread: number;
+  total: number;
+  since: string | null;
 }
 
 export type MessageType =
   | 'text'
-  | 'file'          // deprecated: attachments are now schema-level on Message
-  | 'tool_call'       // deprecated: use AgentStep
-  | 'tool_result'     // deprecated: use AgentStep
-  | 'approval_card'   // deprecated: use 'card' with card_type='approval'
-  | 'state_delta'     // deprecated: use AgentStep
+  | 'file' // deprecated: attachments are now schema-level on Message
+  | 'tool_call' // deprecated: use AgentStep
+  | 'tool_result' // deprecated: use AgentStep
+  | 'approval_card' // deprecated: use 'card' with card_type='approval'
+  | 'state_delta' // deprecated: use AgentStep
   | 'card'
   | 'system';
 
@@ -197,7 +204,13 @@ export type CardContent =
   | ApprovalCardContent
   | { card_type: string; entity_id?: string; data?: Record<string, unknown> };
 
-export type AgentState = 'thinking' | 'tool_calling' | 'streaming' | 'waiting_approval' | 'completed' | 'error';
+export type AgentState =
+  | 'thinking'
+  | 'tool_calling'
+  | 'streaming'
+  | 'waiting_approval'
+  | 'completed'
+  | 'error';
 
 export interface StateDeltaContent {
   state: AgentState;
@@ -317,6 +330,9 @@ export interface Organization {
   created_at: string;
   /** Per-member flag: true when the user has dismissed the onboarding popup for this org. */
   onboarding_dismissed: boolean;
+  /** Caller's membership role in this org (owner/admin/member). Present on the
+   *  GET /orgs list response; omitted on single-org fetches that don't join membership. */
+  role?: OrgMemberRole;
 }
 
 export interface OrgInviteCode {
@@ -375,6 +391,7 @@ export interface OrgInviteLink {
   org_id: string;
   token: string;
   require_approval: boolean;
+  expires_at: string;
   created_at: string;
   regenerated_at: string;
 }
@@ -675,7 +692,14 @@ export interface UpdateAgentRequest {
 
 // ---- Machine types ----
 
-export type MachineStatus = 'provisioning' | 'starting' | 'restarting' | 'running' | 'stopped' | 'error' | 'terminated';
+export type MachineStatus =
+  | 'provisioning'
+  | 'starting'
+  | 'restarting'
+  | 'running'
+  | 'stopped'
+  | 'error'
+  | 'terminated';
 
 export interface Machine {
   id: string;
@@ -863,6 +887,13 @@ export interface MachineUpdateData {
   reason?: string;
 }
 
+export interface MachineClipInstallData {
+  clip_id: string;
+  alias: string;
+  source_ref: string;
+  version?: string;
+}
+
 export interface AgentNewSessionData {
   previous_session_id?: string;
 }
@@ -928,8 +959,20 @@ export interface AvatarUploadResponse {
 
 export type TaskStatus = 'todo' | 'in_progress' | 'in_review' | 'done' | 'canceled';
 export type TaskPriority = 'high' | 'normal' | 'low';
-export type TaskRelationTargetType = 'task' | 'message' | 'chat' | 'agent_session' | 'wiki_changeset';
-export type TaskRelationType = 'blocks' | 'related' | 'duplicate' | 'source' | 'reference' | 'discussion' | 'execution';
+export type TaskRelationTargetType =
+  | 'task'
+  | 'message'
+  | 'chat'
+  | 'agent_session'
+  | 'wiki_changeset';
+export type TaskRelationType =
+  | 'blocks'
+  | 'related'
+  | 'duplicate'
+  | 'source'
+  | 'reference'
+  | 'discussion'
+  | 'execution';
 
 export interface Task {
   id: string;
@@ -1096,6 +1139,8 @@ export interface Schedule {
   attached_to_uri: string | null;
   name: string;
   description: string;
+  attachment_ids: string[];
+  attachments?: Attachment[];
   spec_type: ScheduleSpecType;
   cron_expr: string | null;
   interval_seconds: number | null;
@@ -1124,6 +1169,8 @@ export interface ScheduleRun {
   status: ScheduleRunStatus;
   fired_description: string | null;
   fired_attached_uri: string | null;
+  fired_attachment_ids: string[];
+  fired_attachments?: Attachment[];
   error: string | null;
   created_at: string;
 }
@@ -1133,6 +1180,7 @@ export interface CreateScheduleInput {
   description: string;
   target_ids: string[];
   attached_to_uri?: string;
+  attachment_ids?: string[];
   spec_type: ScheduleSpecType;
   cron_expr?: string;
   interval_seconds?: number;
@@ -1152,6 +1200,9 @@ export interface UpdateScheduleInput {
   attached_to_uri?: string;
   /** Explicitly clear attached_to_uri. Server honors this over `attached_to_uri`. */
   attached_to_uri_clear?: boolean;
+  attachment_ids?: string[];
+  /** Explicitly clear attachment_ids. Server honors this over `attachment_ids`. */
+  attachment_ids_clear?: boolean;
   cron_expr?: string;
   interval_seconds?: number;
   run_at?: string;
@@ -1631,7 +1682,23 @@ export interface ChatCreatedData extends Chat {}
 
 export interface ChatUpdateData {
   chat_id: string;
-  changes: Partial<Pick<Chat, 'name' | 'avatar_url' | 'description' | 'visibility' | 'agent_routing_mode' | 'smart_routing_strategy' | 'smart_routing_agent_id' | 'last_message_at' | 'last_message_preview' | 'last_message_sender' | 'archived_at' | 'deleted_at'>>;
+  changes: Partial<
+    Pick<
+      Chat,
+      | 'name'
+      | 'avatar_url'
+      | 'description'
+      | 'visibility'
+      | 'agent_routing_mode'
+      | 'smart_routing_strategy'
+      | 'smart_routing_agent_id'
+      | 'last_message_at'
+      | 'last_message_preview'
+      | 'last_message_sender'
+      | 'archived_at'
+      | 'deleted_at'
+    >
+  >;
 }
 
 export interface ChatDeletedData {
@@ -1736,7 +1803,7 @@ export interface AgentSessionDB {
   id: string;
   agent_id: string;
   org_id: string;
-  status: string;          // open | closed | failed | cancelled | superseded
+  status: string; // open | closed | failed | cancelled | superseded
   runtime_type: string;
   runtime_key: string | null;
   runtime_lane_key: string;
@@ -1832,6 +1899,7 @@ export interface Comment {
 export interface CreateCommentRequest {
   target_uri: string;
   body: string;
+  parent_id?: string;
 }
 
 export interface UpdateCommentRequest {
@@ -1851,9 +1919,14 @@ export interface CommentDeletedData {
 // ============================================================
 
 export type InboxItemType =
-  | 'mention' | 'task_assign' | 'task_update'
-  | 'task_comment' | 'approval_request'
-  | 'agent_alert' | 'invitation' | 'schedule_fire'
+  | 'mention'
+  | 'task_assign'
+  | 'task_update'
+  | 'task_comment'
+  | 'approval_request'
+  | 'agent_alert'
+  | 'invitation'
+  | 'schedule_fire'
   | 'thread_reply';
 
 export interface InboxItem {
@@ -1885,8 +1958,15 @@ export interface InboxItem {
 // Dispatch Types (agent event delivery)
 // ============================================================
 
-export type DispatchEventType = 'message' | 'task_assign' | 'task_update' | 'task_comment' | 'schedule.fire' | 'approval_decided';
-export type DispatchStatus = 'pending' | 'acked';
+export type DispatchEventType =
+  | 'message'
+  | 'task_assign'
+  | 'task_update'
+  | 'task_comment'
+  | 'wiki_comment'
+  | 'schedule.fire'
+  | 'approval_decided';
+export type DispatchStatus = 'pending' | 'received' | 'acked';
 export type DispatchDeliveryReason = 'mention' | 'watcher' | 'assignee' | 'creator';
 
 export interface DispatchEvent {
@@ -1919,6 +1999,16 @@ export interface DispatchEvent {
 
 export type DispatchNewData = DispatchEvent;
 
+export interface DispatchReceivedData {
+  agent_id: string;
+  event_type: string;
+  source_type: string;
+  source_id: string;
+  chat_id?: string | null;
+  task_id?: string | null;
+  org_id: string;
+}
+
 export type InboxNewData = InboxItem;
 
 export interface InboxUpdateData {
@@ -1950,7 +2040,7 @@ export interface NotificationAlertData {
 }
 
 export type WsEventMap = {
-  'hello': HelloData;
+  hello: HelloData;
   'message.new': MessageNewData;
   'message.patch': MessagePatchData;
   'message.edit': MessageEditData;
@@ -1962,8 +2052,8 @@ export type WsEventMap = {
   'approval.update': ApprovalUpdateData; // deprecated, kept for backward compat
   'card.update': CardUpdateData;
   'recovery.overflow': RecoveryOverflowData;
-  'watching': WatchingData;
-  'pong': { ts: number };
+  watching: WatchingData;
+  pong: { ts: number };
   'membership.changed': MembershipChangedData;
   'task.created': TaskCreatedData;
   'task.updated': TaskUpdatedData;
@@ -1997,6 +2087,7 @@ export type WsEventMap = {
   'inbox.bulk_update': InboxBulkUpdateData;
   'read_position.updated': ReadPositionUpdateData;
   'dispatch.new': DispatchNewData;
+  'dispatch.received': DispatchReceivedData;
   'schedule.created': ScheduleCreatedData;
   'schedule.updated': ScheduleUpdatedData;
   'schedule.deleted': ScheduleDeletedData;
@@ -2014,6 +2105,10 @@ export type WsEventMap = {
   'machine.stop': MachineStopData;
   'machine.filesystem.browse': MachineFilesystemBrowseData;
   'machine.update': MachineUpdateData;
+  'machine.clip.install': MachineClipInstallData;
+  'clip.installed': ClipInstalledData;
+  'clip.removed': ClipRemovedData;
+  'clip.updated': ClipUpdatedData;
   'agent.new_session': AgentNewSessionData;
 };
 
@@ -2285,7 +2380,17 @@ export interface CreditWallet {
 export interface CreditTransaction {
   id: string;
   org_id: string;
-  type: 'topup' | 'auto_reload' | 'llm_deduct' | 'compute_deduct' | 'compute_hold' | 'compute_settle' | 'adjustment' | 'refund' | 'grant' | 'grant_expire';
+  type:
+    | 'topup'
+    | 'auto_reload'
+    | 'llm_deduct'
+    | 'compute_deduct'
+    | 'compute_hold'
+    | 'compute_settle'
+    | 'adjustment'
+    | 'refund'
+    | 'grant'
+    | 'grant_expire';
   amount: number;
   balance_after: number;
   grant_id: string | null;
@@ -2442,3 +2547,132 @@ export interface BillingMachineStoppedEvent {
 export interface BillingInsufficientEvent {
   org_id: string;
 }
+
+// ============================================================
+// Clip Types
+// ============================================================
+
+export type ClipSourceType = 'registry' | 'custom' | 'builtin';
+export type ClipStatus = 'active' | 'disabled';
+
+export interface Clip {
+  id: string;
+  org_id: string;
+  alias: string;
+  name: string;
+  description: string | null;
+  manifest: Record<string, unknown>;
+  source_type: ClipSourceType;
+  source_ref: string | null;
+  version: string | null;
+  status: ClipStatus;
+  created_by: string | null;
+  /** Registry clip that reconciles onto every org machine, including machines
+   * that join after creation. Targeted installs leave this false and persist
+   * per-machine pending clip_instances instead. */
+  install_on_all_machines: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface AgentClip {
+  agent_id: string;
+  clip_id: string;
+  config: Record<string, unknown> | null;
+  created_at: string;
+}
+
+export interface CreateClipRequest {
+  alias: string;
+  name: string;
+  description?: string;
+  manifest: Record<string, unknown>;
+  source_type?: ClipSourceType;
+  source_ref?: string;
+  version?: string;
+  target_machine_ids?: string[];
+}
+
+export interface UpdateClipRequest {
+  name?: string;
+  description?: string;
+  manifest?: Record<string, unknown>;
+  status?: ClipStatus;
+  version?: string;
+}
+
+export interface BindAgentClipRequest {
+  clip_id: string;
+  config?: Record<string, unknown>;
+}
+
+export interface InvokeClipRequest {
+  alias: string;
+  command: string;
+  input?: unknown;
+  timeout_ms?: number;
+}
+
+export interface InvokeClipResponse {
+  output: unknown;
+  error: string | null;
+}
+
+export type ClipInstanceStatus = 'pending' | 'installed' | 'running' | 'stopped' | 'error';
+
+export interface ClipInstance {
+  id: string;
+  clip_id: string;
+  machine_id: string | null;
+  status: ClipInstanceStatus;
+  version: string | null;
+  error_msg: string | null;
+  last_seen: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface OnlineClipInfo {
+  alias: string;
+  name: string;
+  version: string;
+  commands: Array<{ name: string; description: string }>;
+  provider_name: string;
+}
+
+// Durable install reconcile — a registry clip the machine should install.
+export interface MachineClipInstall {
+  clip_id: string;
+  alias: string;
+  source_ref?: string;
+  version?: string;
+}
+
+// Pinix registry catalog clip info (from GET /clip/v1/registry/clips,
+// which proxies the public Pinix registry GET /search).
+export interface RegistryCommandInfo {
+  name: string;
+  description: string;
+  input?: string;
+  output?: string;
+}
+
+export interface RegistryClipInfo {
+  name: string; // @scope/name (canonical package id)
+  package: string; // @scope/name (alias derivation + install source_ref)
+  version: string;
+  type: string; // registry package type (e.g. "clip")
+  description?: string;
+  domain?: string;
+  author?: string;
+  commands: RegistryCommandInfo[];
+  dependencies: string[];
+}
+
+// Clip WS event data types
+export type ClipInstalledData = Clip;
+export type ClipUpdatedData = Clip;
+export interface ClipRemovedData {
+  clip_id: string;
+  org_id: string;
+}

package/src/ws.ts

@@ -5,9 +5,9 @@ export type WsEventType = keyof WsEventMap;
 export type WsEventHandler<T extends WsEventType> = (data: WsEventMap[T], seq?: number) => void;
 
 export type WsClientEventMap = {
-  'ping': { ts: number };
-  'typing': { chat_id: string; thread_root_id: string | null; action: 'start' | 'stop' };
-  'watch': { chat_ids: string[] };
+  ping: { ts: number };
+  typing: { chat_id: string; thread_root_id: string | null; action: 'start' | 'stop' };
+  watch: { chat_ids: string[] };
   'agent.heartbeat': { session_id: string; telemetry?: Record<string, unknown> };
 };
 
@@ -26,10 +26,10 @@ export interface ParallWsOptions {
 
 function isRetryableNetworkError(err: unknown): boolean {
   return (
-    err instanceof Error
-    && err.name === 'ApiError'
-    && 'status' in err
-    && (err as { status?: unknown }).status === 0
+    err instanceof Error &&
+    err.name === 'ApiError' &&
+    'status' in err &&
+    (err as { status?: unknown }).status === 0
   );
 }
 
@@ -39,7 +39,11 @@ function isBrowserRuntime(): boolean {
 
 export class ParallWs {
   private ws: WebSocket | null = null;
-  private options: ParallWsOptions & { reconnect: boolean; reconnectInterval: number; maxReconnectInterval: number };
+  private options: ParallWsOptions & {
+    reconnect: boolean;
+    reconnectInterval: number;
+    maxReconnectInterval: number;
+  };
   private listeners = new Map<string, Set<WsEventHandler<WsEventType>>>();
   private stateListeners = new Set<(state: WsConnectionState) => void>();
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
@@ -115,7 +119,11 @@ export class ParallWs {
       ws.onclose = null;
       ws.onopen = null;
       ws.onerror = null;
-      try { ws.close(); } catch { /* ignore */ }
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
       // Only reconnect if this socket is still the active one.
       // If connect() was called again, a newer socket owns the lifecycle.
       if (ws !== this.ws) return;
@@ -271,7 +279,10 @@ export class ParallWs {
       // event-loop stalls. Probe with a 5s timeout rather than force-
       // reconnecting, so healthy connections that were merely timer-starved
       // survive while genuinely dead sockets are caught quickly.
-      if (this.lastReceivedAt > 0 && Date.now() - this.lastReceivedAt > this.heartbeatIntervalMs * 1.5) {
+      if (
+        this.lastReceivedAt > 0 &&
+        Date.now() - this.lastReceivedAt > this.heartbeatIntervalMs * 1.5
+      ) {
         this.probeConnection();
         return;
       }
@@ -320,7 +331,11 @@ export class ParallWs {
       this.ws.onopen = null;
       this.ws.onerror = null;
       this.ws.onmessage = null;
-      try { this.ws.close(); } catch { /* ignore */ }
+      try {
+        this.ws.close();
+      } catch {
+        /* ignore */
+      }
       this.ws = null;
     }
     if (this.options.reconnect && !this.intentionalClose) {