@pnds/sdk 1.9.0 → 1.10.0

package/src/client.ts

@@ -42,11 +42,11 @@ import type {
   Project,
   CreateProjectRequest,
   UpdateProjectRequest,
-  AgentRunDB,
+  AgentSessionDB,
   AgentStep,
-  CreateAgentRunRequest,
+  CreateAgentSessionRequest,
   CreateAgentStepRequest,
-  UpdateAgentRunRequest,
+  UpdateAgentSessionRequest,
   OrgInvitation,
   InvitationPublicInfo,
   PlatformConfigResponse,
@@ -55,6 +55,10 @@ import type {
   WikiChangeset,
   WikiTreeResponse,
   WikiNodeSectionArtifact,
+  WikiSearchResponse,
+  WikiPageIndex,
+  WikiRefsResponse,
+  WikiRefsCheckResponse,
   WikiDiff,
   WikiPathScope,
   WikiAccessStatus,
@@ -73,6 +77,9 @@ import type {
   ResolveRefsResponse,
   BacklinksResponse,
   BrokenRefsResponse,
+  PushSubscribeRequest,
+  NotifPrefs,
+  NotificationPreferences,
 } from './types.js';
 
 export interface PondClientOptions {
@@ -81,6 +88,7 @@ export interface PondClientOptions {
   onTokenExpired?: () => void;
   getRefreshToken?: () => string | null;
   setTokens?: (tokens: { access_token: string; refresh_token: string }) => void;
+  swimlaneName?: string;
 }
 
 export class PondClient {
@@ -90,6 +98,7 @@ export class PondClient {
   private getRefreshToken?: () => string | null;
   private setTokens?: (tokens: { access_token: string; refresh_token: string }) => void;
   private refreshPromise: Promise<AuthTokens> | null = null;
+  private swimlaneName?: string;
 
   /** Auth endpoints excluded from automatic 401 refresh to prevent recursion. */
   private static readonly AUTH_PATHS = new Set([
@@ -100,12 +109,28 @@ export class PondClient {
   /** Proactive refresh when token expires within this window (seconds). */
   private static readonly REFRESH_THRESHOLD_S = 5 * 60;
 
+  /** Build headers common to all requests (auth, swimlane). */
+  private buildHeaders(extra?: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...extra,
+    };
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+    if (this.swimlaneName) {
+      headers['X-Pnds-Swimlane'] = this.swimlaneName;
+    }
+    return headers;
+  }
+
   constructor(options: PondClientOptions = {}) {
     this.baseUrl = options.baseUrl ?? '';
     this.token = options.token ?? null;
     this.onTokenExpired = options.onTokenExpired;
     this.getRefreshToken = options.getRefreshToken;
     this.setTokens = options.setTokens;
+    this.swimlaneName = options.swimlaneName;
   }
 
   setToken(token: string | null) {
@@ -197,12 +222,7 @@ export class PondClient {
       if (qs) url += `?${qs}`;
     }
 
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    };
-    if (this.token) {
-      headers['Authorization'] = `Bearer ${this.token}`;
-    }
+    const headers = this.buildHeaders();
 
     let res: Response;
     try {
@@ -535,31 +555,31 @@ export class PondClient {
     return this.request('GET', ENDPOINTS.AGENT_ME(orgId));
   }
 
-  // ---- Agent Runs (org-scoped) ----
+  // ---- Agent Sessions (org-scoped) ----
 
-  async createAgentRun(orgId: string, agentId: string, req: CreateAgentRunRequest): Promise<AgentRunDB> {
-    return this.request('POST', ENDPOINTS.AGENT_RUNS(orgId, agentId), req);
+  async createAgentSession(orgId: string, agentId: string, req: CreateAgentSessionRequest): Promise<AgentSessionDB> {
+    return this.request('POST', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), req);
   }
 
-  async getAgentRuns(orgId: string, agentId: string, params?: { limit?: number }): Promise<AgentRunDB[]> {
-    const res = await this.request<{ data: AgentRunDB[] }>('GET', ENDPOINTS.AGENT_RUNS(orgId, agentId), undefined, params);
+  async getAgentSessions(orgId: string, agentId: string, params?: { limit?: number; status?: string }): Promise<AgentSessionDB[]> {
+    const res = await this.request<{ data: AgentSessionDB[] }>('GET', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), undefined, params);
     return res.data;
   }
 
-  async getAgentRun(orgId: string, agentId: string, runId: string): Promise<AgentRunDB> {
-    return this.request('GET', ENDPOINTS.AGENT_RUN(orgId, agentId, runId));
+  async getAgentSession(orgId: string, agentId: string, sessionId: string): Promise<AgentSessionDB> {
+    return this.request('GET', ENDPOINTS.AGENT_SESSION(orgId, agentId, sessionId));
   }
 
-  async updateAgentRun(orgId: string, agentId: string, runId: string, req: UpdateAgentRunRequest): Promise<AgentRunDB> {
-    return this.request('PATCH', ENDPOINTS.AGENT_RUN(orgId, agentId, runId), req);
+  async updateAgentSession(orgId: string, agentId: string, sessionId: string, req: UpdateAgentSessionRequest): Promise<AgentSessionDB> {
+    return this.request('PATCH', ENDPOINTS.AGENT_SESSION(orgId, agentId, sessionId), req);
   }
 
-  async createAgentStep(orgId: string, agentId: string, runId: string, req: CreateAgentStepRequest): Promise<AgentStep> {
-    return this.request('POST', ENDPOINTS.AGENT_RUN_STEPS(orgId, agentId, runId), req);
+  async createAgentStep(orgId: string, agentId: string, sessionId: string, req: CreateAgentStepRequest): Promise<AgentStep> {
+    return this.request('POST', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), req);
   }
 
-  async getAgentRunSteps(orgId: string, agentId: string, runId: string, params?: { limit?: number }): Promise<AgentStep[]> {
-    const res = await this.request<{ data: AgentStep[] }>('GET', ENDPOINTS.AGENT_RUN_STEPS(orgId, agentId, runId), undefined, params);
+  async getAgentSessionSteps(orgId: string, agentId: string, sessionId: string, params?: { limit?: number }): Promise<AgentStep[]> {
+    const res = await this.request<{ data: AgentStep[] }>('GET', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), undefined, params);
     return res.data;
   }
 
@@ -702,15 +722,11 @@ export class PondClient {
    */
   async getPlatformConfig(currentVersion?: string): Promise<PlatformConfigResponse | null> {
     const url = `${this.baseUrl}${ENDPOINTS.PLATFORM_CONFIG}`;
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    };
-    if (this.token) {
-      headers['Authorization'] = `Bearer ${this.token}`;
-    }
+    const extra: Record<string, string> = {};
     if (currentVersion !== undefined) {
-      headers['If-None-Match'] = currentVersion;
+      extra['If-None-Match'] = currentVersion;
     }
+    const headers = this.buildHeaders(extra);
 
     const res = await fetch(url, {
       method: 'GET',
@@ -863,6 +879,22 @@ export class PondClient {
     return this.request('GET', ENDPOINTS.WIKI_NODE_SECTIONS(orgId, wikiId), undefined, params);
   }
 
+  async searchWiki(orgId: string, wikiId: string, params: { q: string; limit?: number; path_prefix?: string; ref?: string }): Promise<WikiSearchResponse> {
+    return this.request('GET', ENDPOINTS.WIKI_SEARCH(orgId, wikiId), undefined, params);
+  }
+
+  async getWikiPageIndex(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiPageIndex> {
+    return this.request('GET', ENDPOINTS.WIKI_PAGE_INDEX(orgId, wikiId), undefined, params);
+  }
+
+  async getWikiRefs(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiRefsResponse> {
+    return this.request('GET', ENDPOINTS.WIKI_REFS(orgId, wikiId), undefined, params);
+  }
+
+  async checkWikiRefs(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiRefsCheckResponse> {
+    return this.request('GET', ENDPOINTS.WIKI_REFS_CHECK(orgId, wikiId), undefined, params);
+  }
+
   async createWikiChangeset(orgId: string, wikiId: string, data: CreateWikiChangesetRequest): Promise<WikiChangeset> {
     return normalizeWikiChangeset(await this.request('POST', ENDPOINTS.WIKI_CHANGESETS(orgId, wikiId), data));
   }
@@ -982,6 +1014,30 @@ export class PondClient {
   async checkBrokenRefs(orgId: string): Promise<BrokenRefsResponse> {
     return this.request('GET', ENDPOINTS.REFS_CHECK(orgId));
   }
+
+  // ---- Push Notifications ----
+
+  async subscribePush(body: PushSubscribeRequest): Promise<void> {
+    return this.request('POST', ENDPOINTS.PUSH_SUBSCRIBE, body);
+  }
+
+  async unsubscribePush(token: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PUSH_UNSUBSCRIBE, { token });
+  }
+
+  async getVapidKey(): Promise<{ vapid_public_key: string }> {
+    return this.request('GET', ENDPOINTS.PUSH_VAPID_KEY);
+  }
+
+  // ---- Notification Preferences ----
+
+  async getNotificationPreferences(): Promise<NotificationPreferences> {
+    return this.request('GET', ENDPOINTS.NOTIFICATION_PREFERENCES);
+  }
+
+  async updateNotificationPreferences(prefs: Partial<NotifPrefs>): Promise<NotificationPreferences> {
+    return this.request('PATCH', ENDPOINTS.NOTIFICATION_PREFERENCES, { prefs });
+  }
 }
 
 function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {

package/src/constants.ts

@@ -70,12 +70,12 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/monitor`,
   AGENT_ME: (orgId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/me`,
-  AGENT_RUNS: (orgId: string, agentId: string) =>
-    `${API_BASE}/orgs/${orgId}/agents/${agentId}/runs`,
-  AGENT_RUN: (orgId: string, agentId: string, runId: string) =>
-    `${API_BASE}/orgs/${orgId}/agents/${agentId}/runs/${runId}`,
-  AGENT_RUN_STEPS: (orgId: string, agentId: string, runId: string) =>
-    `${API_BASE}/orgs/${orgId}/agents/${agentId}/runs/${runId}/steps`,
+  AGENT_SESSIONS: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions`,
+  AGENT_SESSION: (orgId: string, agentId: string, sessionId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}`,
+  AGENT_SESSION_STEPS: (orgId: string, agentId: string, sessionId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/steps`,
   AGENT_TASKS: (orgId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/tasks`,
   // Machines (org-scoped)
@@ -135,6 +135,10 @@ export const ENDPOINTS = {
   WIKI_TREE: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/tree`,
   WIKI_BLOB: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/blob`,
   WIKI_NODE_SECTIONS: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/node-sections`,
+  WIKI_SEARCH: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/search`,
+  WIKI_PAGE_INDEX: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/page-index`,
+  WIKI_REFS: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/refs`,
+  WIKI_REFS_CHECK: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/refs/check`,
   WIKI_CHANGESETS: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets`,
   WIKI_CHANGESET: (orgId: string, wikiId: string, changesetId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets/${changesetId}`,
@@ -199,6 +203,14 @@ export const ENDPOINTS = {
   // Platform config (agent-scoped, not org-scoped)
   PLATFORM_CONFIG: `${API_BASE}/agents/platform-config`,
 
+  // Push notifications
+  PUSH_SUBSCRIBE: `${API_BASE}/push/subscribe`,
+  PUSH_UNSUBSCRIBE: `${API_BASE}/push/unsubscribe`,
+  PUSH_VAPID_KEY: `${API_BASE}/push/vapid-key`,
+
+  // Notification preferences
+  NOTIFICATION_PREFERENCES: `${API_BASE}/notification-preferences`,
+
 } as const;
 
 // WebSocket event types
@@ -206,8 +218,6 @@ export const WS_EVENTS = {
   // Client -> Server
   PING: 'ping',
   TYPING: 'typing',
-  ACK: 'ack',
-  READ: 'read',
   WATCH: 'watch',
   AGENT_HEARTBEAT: 'agent.heartbeat',
 
@@ -234,8 +244,8 @@ export const WS_EVENTS = {
   PROJECT_CREATED: 'project.created',
   PROJECT_UPDATED: 'project.updated',
   PROJECT_DELETED: 'project.deleted',
-  AGENT_RUN_NEW: 'agent_run.new',
-  AGENT_RUN_UPDATE: 'agent_run.update',
+  AGENT_SESSION_NEW: 'agent_session.new',
+  AGENT_SESSION_UPDATE: 'agent_session.update',
   AGENT_STEP_NEW: 'agent_step.new',
   INVITATION_NEW: 'invitation.new',
   INVITATION_ACCEPTED: 'invitation.accepted',
@@ -247,5 +257,6 @@ export const WS_EVENTS = {
   INBOX_NEW: 'inbox.new',
   INBOX_UPDATE: 'inbox.update',
   INBOX_BULK_UPDATE: 'inbox.bulk_update',
+  READ_POSITION_UPDATED: 'read_position.updated',
   DISPATCH_NEW: 'dispatch.new',
 } as const;

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 };
@@ -1119,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;
@@ -1144,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;
@@ -1157,6 +1251,7 @@ export type WsEventMap = {
   'inbox.new': InboxNewData;
   'inbox.update': InboxUpdateData;
   'inbox.bulk_update': InboxBulkUpdateData;
+  'read_position.updated': ReadPositionUpdateData;
   'dispatch.new': DispatchNewData;
 };
 

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({