@pnds/sdk 1.8.0 → 1.10.0

package/src/types.ts

@@ -41,6 +41,26 @@ export type ChatMemberRole = 'owner' | 'admin' | 'member';
 
 export type NotificationLevel = 'all' | 'mentions_only' | 'none';
 
+// Push notification subscription
+export interface PushSubscribeRequest {
+  platform: 'web' | 'ios' | 'android';
+  token: string;
+  device_id?: string;
+}
+
+// Notification preferences
+export interface NotifPrefs {
+  dm?: boolean;
+  mention?: boolean;
+  task_assign?: boolean;
+}
+
+export interface NotificationPreferences {
+  scope: string;
+  prefs: NotifPrefs;
+  updated_at: string;
+}
+
 export interface ChatMember {
   chat_id: string;
   user_id: string;
@@ -184,7 +204,7 @@ export interface Message {
   deleted_at: string | null;
   created_at: string;
   idempotency_key: string | null;
-  agent_run_id?: string | null;
+  agent_step_id?: string | null;
   hints?: MessageHints | null;
 }
 
@@ -365,7 +385,7 @@ export interface SendMessageRequest {
   content: MessageContent;
   thread_root_id?: string;
   idempotency_key?: string;
-  agent_run_id?: string;
+  agent_step_id?: string;
   hints?: MessageHints;
 }
 
@@ -375,7 +395,7 @@ export interface SendDirectMessageRequest {
   content: MessageContent;
   thread_root_id?: string;
   idempotency_key?: string;
-  agent_run_id?: string;
+  agent_step_id?: string;
   hints?: MessageHints;
 }
 
@@ -446,17 +466,10 @@ export interface AgentProfile {
   created_at: string;
 }
 
-export interface AgentRun {
-  target_id: string;
-  status: string;
-  started_at: string;
-}
-
 export interface AgentPresence {
   online: boolean;
   status: string; // "online" | "busy" | "error" | "offline"
   session_id?: string;
-  run?: AgentRun;
   telemetry?: Record<string, unknown>;
 }
 
@@ -483,7 +496,7 @@ export interface FileUrlResponse {
 
 export type TaskStatus = 'todo' | 'in_progress' | 'in_review' | 'done' | 'canceled';
 export type TaskPriority = 'high' | 'normal' | 'low';
-export type TaskRelationTargetType = 'task' | 'message' | 'chat' | 'agent_run';
+export type TaskRelationTargetType = 'task' | 'message' | 'chat' | 'agent_session';
 export type TaskRelationType = 'blocks' | 'related' | 'duplicate' | 'source' | 'reference' | 'discussion' | 'execution';
 
 export interface Task {
@@ -698,6 +711,82 @@ export interface WikiNodeSectionArtifact {
   nodes: WikiNodeSection[];
 }
 
+export interface WikiSearchResult {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  node_id: string;
+  path: string;
+  title: string;
+  heading_path?: string[];
+  section_path: string;
+  level: number;
+  start_line: number;
+  end_line: number;
+  score: number;
+  snippet: string;
+}
+
+export interface WikiSearchResponse {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  query: string;
+  ref: string;
+  results: WikiSearchResult[];
+}
+
+export interface WikiPageIndexEntry {
+  path: string;
+  title: string;
+  top_headings: string[];
+  size_bytes: number;
+  section_count: number;
+}
+
+export interface WikiPageIndex {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  generated_at: string;
+  page_count: number;
+  pages: WikiPageIndexEntry[];
+}
+
+export interface WikiFileRef {
+  source_path: string;
+  uri: string;
+  context?: string;
+  prefix: string;
+  entity_id: string;
+  target_path?: string;
+  fragment?: string;
+  line: number;
+}
+
+export interface WikiRefsResponse {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  total: number;
+  refs: WikiFileRef[];
+}
+
+export interface WikiBrokenRef extends WikiFileRef {
+  reason: string;
+}
+
+export interface WikiRefsCheckResponse {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  total: number;
+  broken: WikiBrokenRef[];
+}
+
 export interface WikiDiffFile {
   path: string;
   action?: string; // "create" | "update" | "delete"
@@ -858,7 +947,7 @@ export interface MessageNewData {
   edited_at?: string | null;
   deleted_at?: string | null;
   idempotency_key?: string | null;
-  agent_run_id?: string | null;
+  agent_step_id?: string | null;
   hints?: MessageHints | null;
 }
 
@@ -932,7 +1021,7 @@ export interface TaskComment {
   author_id: string;
   body: string;
   mentions?: Mention[];
-  agent_run_id?: string | null;
+  agent_step_id?: string | null;
   created_at: string;
   updated_at: string;
   author?: User;
@@ -984,17 +1073,16 @@ export interface ProjectDeletedData {
   org_id: string;
 }
 
-// ---- Agent Run / Step ----
+// ---- Agent Session / Step ----
 
-export interface AgentRunDB {
+export interface AgentSessionDB {
   id: string;
   agent_id: string;
   org_id: string;
-  status: string;
-  trigger_type: string;
-  trigger_ref: Record<string, unknown> | null;
-  default_target_type: string;
-  default_target_id: string | null;
+  status: string;          // active | completed | failed | cancelled
+  runtime_type: string;
+  runtime_key: string | null;
+  runtime_ref: Record<string, unknown> | null;
   started_at: string;
   finished_at: string | null;
   created_at: string;
@@ -1002,47 +1090,48 @@ export interface AgentRunDB {
 
 export interface AgentStep {
   id: string;
-  run_id: string;
+  session_id: string;
   step_type: string;
+  target_type: string;
+  target_id: string | null;
   content: Record<string, unknown>;
+  group_key: string | null;
+  runtime_key: string | null;
   idempotency_key?: string;
   created_at: string;
 }
 
-export interface CreateAgentRunRequest {
-  trigger_type: string;
-  trigger_ref?: Record<string, unknown>;
-  chat_id?: string; // backward compat alias for default_target_type=chat
-  default_target_type?: string;
-  default_target_id?: string;
+export interface CreateAgentSessionRequest {
+  runtime_type?: string;
+  runtime_key?: string;
+  runtime_ref?: Record<string, unknown>;
 }
 
 export interface CreateAgentStepRequest {
   step_type: string;
   content: Record<string, unknown>;
+  target_type?: string;
+  target_id?: string;
+  group_key?: string;
+  runtime_key?: string;
   idempotency_key?: string;
-  projection?: boolean;
-  chat_projection?: boolean; // backward compat alias for projection
+  projection?: boolean; // project text steps to chat message or task comment (controlled by agent's run_config)
 }
 
-export interface UpdateAgentRunRequest {
+export interface UpdateAgentSessionRequest {
   status: string;
-  emit_fallback_message?: boolean;
 }
 
-// Agent run WS event data
-export type AgentRunNewData = AgentRunDB;
+// Agent session WS event data
+export type AgentSessionNewData = AgentSessionDB;
 
-export interface AgentRunUpdateData {
-  run_id: string;
+export interface AgentSessionUpdateData {
+  session_id: string;
   status: string;
   finished_at?: string;
 }
 
-export interface AgentStepNewData extends AgentStep {
-  target_type?: string;
-  target_id?: string;
-}
+export interface AgentStepNewData extends AgentStep {}
 
 export type WikiChangesetCreatedData = WikiChangeset & { org_id: string };
 export type WikiChangesetUpdatedData = WikiChangeset & { org_id: string };
@@ -1054,13 +1143,7 @@ export type WikiChangesetUpdatedData = WikiChangeset & { org_id: string };
 export type InboxItemType =
   | 'mention' | 'task_assign' | 'task_update'
   | 'task_comment' | 'approval_request'
-  | 'agent_alert' | 'invitation'
-  | 'agent_dm' | 'agent_route';
-
-export type InboxItemReason =
-  | 'assigned' | 'mentioned' | 'authored'
-  | 'subscribed' | 'approval_requested'
-  | 'dm_received' | 'routed';
+  | 'agent_alert' | 'invitation';
 
 export interface InboxItem {
   id: string;
@@ -1068,7 +1151,6 @@ export interface InboxItem {
   recipient_id: string;
   actor_id: string | null;
   type: InboxItemType;
-  reason: InboxItemReason;
   entity_type: string;
   entity_id: string;
   group_key: string;
@@ -1085,16 +1167,40 @@ export interface InboxItem {
   updated_at: string;
 }
 
-export type NotificationNewData = InboxItem;
+// ============================================================
+// Dispatch Types (agent event delivery)
+// ============================================================
+
+export type DispatchEventType = 'message' | 'task_assign';
+export type DispatchStatus = 'pending' | 'acked';
 
-export interface NotificationUpdateData {
+export interface DispatchEvent {
+  id: string;
+  org_id: string;
+  agent_id: string;
+  event_type: DispatchEventType;
+  source_type: string;
+  source_id: string;
+  chat_id: string | null;
+  task_id: string | null;
+  actor_id: string | null;
+  status: DispatchStatus;
+  acked_at: string | null;
+  created_at: string;
+}
+
+export type DispatchNewData = DispatchEvent;
+
+export type InboxNewData = InboxItem;
+
+export interface InboxUpdateData {
   id: string;
   read_at?: string | null;
   archived_at?: string | null;
   snoozed_until?: string | null;
 }
 
-export interface NotificationBulkUpdateData {
+export interface InboxBulkUpdateData {
   action: 'mark_all_read' | 'archive_all';
 }
 
@@ -1102,6 +1208,11 @@ export interface InboxUnreadCountResponse {
   count: number;
 }
 
+export interface ReadPositionUpdateData {
+  chat_id: string;
+  last_read_message_id: string;
+}
+
 export type WsEventMap = {
   'hello': HelloData;
   'message.new': MessageNewData;
@@ -1127,8 +1238,8 @@ export type WsEventMap = {
   'project.created': ProjectCreatedData;
   'project.updated': ProjectUpdatedData;
   'project.deleted': ProjectDeletedData;
-  'agent_run.new': AgentRunNewData;
-  'agent_run.update': AgentRunUpdateData;
+  'agent_session.new': AgentSessionNewData;
+  'agent_session.update': AgentSessionUpdateData;
   'agent_step.new': AgentStepNewData;
   'invitation.new': InvitationNewEventData;
   'invitation.accepted': InvitationAcceptedEventData;
@@ -1137,9 +1248,11 @@ export type WsEventMap = {
   'presence.update': PresenceUpdateData;
   'wiki.changeset.created': WikiChangesetCreatedData;
   'wiki.changeset.updated': WikiChangesetUpdatedData;
-  'notification.new': NotificationNewData;
-  'notification.update': NotificationUpdateData;
-  'notification.bulk_update': NotificationBulkUpdateData;
+  'inbox.new': InboxNewData;
+  'inbox.update': InboxUpdateData;
+  'inbox.bulk_update': InboxBulkUpdateData;
+  'read_position.updated': ReadPositionUpdateData;
+  'dispatch.new': DispatchNewData;
 };
 
 // Invitation WS event data

package/src/ws.ts

@@ -7,8 +7,6 @@ export type WsEventHandler<T extends WsEventType> = (data: WsEventMap[T], seq?:
 export type WsClientEventMap = {
   'ping': { ts: number };
   'typing': { chat_id: string; thread_root_id: string | null; action: 'start' | 'stop' };
-  'ack': { message_id: string };
-  'read': { chat_id: string; last_read_id: string };
   'watch': { chat_ids: string[] };
   'agent.heartbeat': { session_id: string; telemetry?: Record<string, unknown> };
 };
@@ -81,12 +79,15 @@ export class PondWs {
       return;
     }
 
-    const params = new URLSearchParams({ ticket: ticket.ticket });
+    // wsUrl may already contain query params (e.g. ?swimlane=pr-42 for
+    // swimlane routing). Use URL API to merge params correctly.
+    const url = new URL(wsUrl);
+    url.searchParams.set('ticket', ticket.ticket);
     if (this.lastSeq > 0) {
-      params.set('last_seq', String(this.lastSeq));
+      url.searchParams.set('last_seq', String(this.lastSeq));
     }
 
-    this.ws = new WebSocket(`${wsUrl}?${params.toString()}`);
+    this.ws = new WebSocket(url.toString());
 
     // Force-reconnect if not connected within 15s.
     // Handles edge case where Node 22 WebSocket transitions to CLOSED without
@@ -171,14 +172,6 @@ export class PondWs {
     });
   }
 
-  sendAck(messageId: string) {
-    this.send({ type: WS_EVENTS.ACK, data: { message_id: messageId } });
-  }
-
-  sendRead(chatId: string, lastReadId: string) {
-    this.send({ type: WS_EVENTS.READ, data: { chat_id: chatId, last_read_id: lastReadId } });
-  }
-
   /** Send an agent heartbeat with telemetry data. */
   sendAgentHeartbeat(sessionId: string, telemetry?: Record<string, unknown>) {
     this.send({