@parall/sdk 1.37.0 → 1.39.0

package/src/client.ts

@@ -1,5 +1,11 @@
 import { ENDPOINTS, WIKI_BASE } from './constants.js';
 import type {
+  ClaimDispatchRequest,
+  ClaimDispatchResponse,
+  SteerDispatchRequest,
+  SteerDispatchResponse,
+  CompleteDispatchRequest,
+  CompleteDispatchResult,
   AuthTokens,
   AvatarUploadResponse,
   RegisterRequest,
@@ -199,6 +205,10 @@ import type {
   BrowserViewerCommandRequest,
   BrowserViewerCommandResponse,
   GrantBrowserProfileConsentRequest,
+  EdgeDevice,
+  EdgeBrowserProfile,
+  ClipConnection,
+  EdgeOnboardingStatus,
 } from './types.js';
 
 export interface ParallClientOptions {
@@ -374,7 +384,13 @@ export class ParallClient {
     body?: unknown,
     query?: Record<string, string | number | boolean | undefined>,
     retried = false,
-    opts?: { timeoutMs?: number; signal?: AbortSignal; keepalive?: boolean },
+    opts?: {
+      timeoutMs?: number;
+      signal?: AbortSignal;
+      keepalive?: boolean;
+      /** Observes the final HTTP status of a successful request (e.g. 200-idempotent-replay vs 201-created). */
+      onStatus?: (status: number) => void;
+    },
   ): Promise<T> {
     // Proactive refresh: block until token is fresh (no-op if still valid)
     if (!retried) {
@@ -441,6 +457,7 @@ export class ParallClient {
       throw buildApiError(res, rawErrorBody);
     }
 
+    opts?.onStatus?.(res.status);
     if (res.status === 204) return undefined as T;
     // 202 Accepted may have an empty body (e.g., async restart) or a JSON body.
     if (res.status === 202) {
@@ -969,6 +986,33 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHAT_MESSAGES(orgId, chatId), req);
   }
 
+  /**
+   * sendMessage variant that also reports whether the server answered with an
+   * idempotent replay (HTTP 200 — the message already existed for this
+   * idempotency/effect key) instead of a fresh create (201). Used by the CLI
+   * to surface "already sent by a previous run (deduplicated)".
+   */
+  async sendMessageDetailed(
+    orgId: string,
+    chatId: string,
+    req: SendMessageRequest,
+  ): Promise<{ message: Message; deduplicated: boolean }> {
+    let status = 0;
+    const message = await this.request<Message>(
+      'POST',
+      ENDPOINTS.CHAT_MESSAGES(orgId, chatId),
+      req,
+      undefined,
+      false,
+      {
+        onStatus: (s) => {
+          status = s;
+        },
+      },
+    );
+    return { message, deduplicated: status === 200 };
+  }
+
   async getMessages(
     orgId: string,
     chatId: string,
@@ -1821,6 +1865,41 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.DISPATCH_EXPIRE(orgId), undefined, params);
   }
 
+  /**
+   * Claim a dispatch lane (explicit consume endpoint). Occupies the
+   * (agent, target, thread) lane and folds claimable WorkItems into it;
+   * `claimed: false` means a healthy incumbent holds the lane.
+   */
+  async claimDispatch(orgId: string, req: ClaimDispatchRequest): Promise<ClaimDispatchResponse> {
+    return this.request('POST', ENDPOINTS.DISPATCH_CLAIM(orgId), req);
+  }
+
+  /** Fold a pending same-target WorkItem into a live lane (409 STALE_LANE when dethroned). */
+  async steerDispatch(orgId: string, req: SteerDispatchRequest): Promise<SteerDispatchResponse> {
+    return this.request('POST', ENDPOINTS.DISPATCH_STEER(orgId), req);
+  }
+
+  /** End a turn: no_action sweep of the lane's members + lane release + re-drive check. */
+  async completeDispatch(
+    orgId: string,
+    req: CompleteDispatchRequest,
+  ): Promise<CompleteDispatchResult> {
+    return this.request('POST', ENDPOINTS.DISPATCH_COMPLETE(orgId), req);
+  }
+
+  /** Release a lane on graceful shutdown — members return to pending immediately. */
+  async releaseDispatchLane(orgId: string, lane: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.DISPATCH_RELEASE(orgId), { lane });
+  }
+
+  /** Renew a live lane's lease (long-turn keepalive). 409 STALE_LANE when dethroned. */
+  async heartbeatDispatchLane(
+    orgId: string,
+    req: { lane: string; target_uri: string; thread_root_id?: string },
+  ): Promise<{ lease_until?: string }> {
+    return this.request('POST', ENDPOINTS.DISPATCH_HEARTBEAT(orgId), req);
+  }
+
   async getDispatchByMessages(
     orgId: string,
     chatId: string,
@@ -3186,6 +3265,44 @@ export class ParallClient {
     const resp = await this.request<{ data: RegistryClipInfo[] }>('GET', url);
     return resp.data;
   }
+
+  // ---- Edge devices ----
+
+  async listEdgeDevices(orgId: string): Promise<{ data: EdgeDevice[] }> {
+    return this.request('GET', ENDPOINTS.ORG_EDGE_DEVICES(orgId));
+  }
+
+  async getEdgeOnboarding(orgId: string): Promise<EdgeOnboardingStatus> {
+    return this.request('GET', ENDPOINTS.ORG_EDGE_ONBOARDING(orgId));
+  }
+
+  async listEdgeProfiles(orgId: string, edgeId: string): Promise<EdgeBrowserProfile[]> {
+    return this.request('GET', ENDPOINTS.ORG_EDGE_PROFILES(orgId, edgeId));
+  }
+
+  // ---- Clip connections ----
+
+  async listClipConnections(orgId: string, clipId: string): Promise<{ data: ClipConnection[] }> {
+    return this.request('GET', ENDPOINTS.CLIP_CONNECTIONS(orgId, clipId));
+  }
+
+  async createClipConnection(
+    orgId: string,
+    clipId: string,
+    input: {
+      device_id?: string;
+      profile?: string;
+      mcp_config_id?: string;
+      alias?: string;
+      is_default?: boolean;
+    },
+  ): Promise<ClipConnection> {
+    return this.request('POST', ENDPOINTS.CLIP_CONNECTIONS(orgId, clipId), input);
+  }
+
+  async deleteClipConnection(orgId: string, connId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.CLIP_CONNECTION(orgId, connId));
+  }
 }
 
 function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {

package/src/constants.ts

@@ -749,6 +749,11 @@ export const ENDPOINTS = {
   DISPATCH_ACK_BY_ID: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/dispatch/${id}/ack`,
   DISPATCH_EXPIRE: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/expire`,
   DISPATCH_BY_MESSAGES: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/by-messages`,
+  DISPATCH_CLAIM: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/claim`,
+  DISPATCH_STEER: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/steer`,
+  DISPATCH_COMPLETE: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/complete`,
+  DISPATCH_RELEASE: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/release`,
+  DISPATCH_HEARTBEAT: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/heartbeat`,
 
   // Unread
   UNREAD: `${API_BASE}/me/unread`,
@@ -838,6 +843,16 @@ export const ENDPOINTS = {
 
   // Clip registry (global, served by clip-service → Pinix Hub proxy)
   CLIP_REGISTRY: () => `${CLIP_BASE}/registry/clips`,
+
+  // Edge device endpoints
+  ORG_EDGE_DEVICES: (orgId: string) => `/api/v1/orgs/${orgId}/edge/devices`,
+  ORG_EDGE_ONBOARDING: (orgId: string) => `/api/v1/orgs/${orgId}/edge/onboarding`,
+  ORG_EDGE_PROFILES: (orgId: string, edgeId: string) =>
+    `/api/v1/orgs/${orgId}/edge/${edgeId}/profiles`,
+  CLIP_CONNECTIONS: (orgId: string, clipId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/connections`,
+  CLIP_CONNECTION: (orgId: string, connId: string) =>
+    `/api/v1/orgs/${orgId}/clip-connections/${connId}`,
 } as const;
 
 /**
@@ -934,6 +949,7 @@ export const WS_EVENTS = {
   READ_POSITION_UPDATED: 'read_position.updated',
   DISPATCH_NEW: 'dispatch.new',
   DISPATCH_RECEIVED: 'dispatch.received',
+  DISPATCH_RESOLVED: 'dispatch.resolved',
   SCHEDULE_CREATED: 'schedule.created',
   SCHEDULE_UPDATED: 'schedule.updated',
   SCHEDULE_DELETED: 'schedule.deleted',

package/src/types.ts

@@ -583,6 +583,13 @@ export interface SendMessageRequest {
   agent_step_id?: string;
   agent_session_id?: string;
   hints?: MessageHints;
+  /**
+   * Binds this send to a claimed dispatch lane (agent senders only). Every
+   * lane-bound write passes the server's lane incumbency check; when
+   * idempotency_key carries a dispatch effect key ("reply:<dsp_id>") the
+   * write is arbitrated by the scoped dispatch effects ledger.
+   */
+  dispatch_lane?: string;
 }
 
 export interface SendDirectMessageRequest {
@@ -1198,6 +1205,17 @@ export interface UpdateTaskRequest {
   parent_id?: string | null;
   project_id?: string | null;
   sort_order?: number;
+  /**
+   * Dispatch lane binding (agent senders during a typed dispatch turn).
+   * dispatch_lane + dispatch_event_id bind the update to the claimed typed
+   * lane (incumbency-checked); dispatch_effect_key — exactly
+   * "task_update:<dispatch_event_id>" — additionally commits the update as
+   * the dispatch's idempotent Effect and resolves the WorkItem in the same
+   * transaction (first update only).
+   */
+  dispatch_lane?: string;
+  dispatch_event_id?: string;
+  dispatch_effect_key?: string;
 }
 
 export interface CreateTaskRelationRequest {
@@ -2181,7 +2199,15 @@ export interface UpdateTaskCommentRequest {
 export type TaskCreatedData = Task;
 export type TaskUpdatedData = Task;
 /** Sent to user:{agentID} channel when a task is assigned to an agent. Data is the full Task. */
-export type TaskAssignedData = Task;
+export type TaskAssignedData = Task & {
+  /**
+   * Exact typed WorkItem this assignment enqueued. The runtime claims and
+   * acks by it — never by the shared (task_activity, task_id) source tuple,
+   * which sibling task_update WorkItems from the same PATCH may also carry.
+   * Absent from older servers (fallback: claim by source).
+   */
+  dispatch_event_id?: string | null;
+};
 export interface TaskDeletedData {
   task_id: string;
   org_id: string;
@@ -2536,10 +2562,80 @@ export interface DispatchEvent {
    */
   delivery_reason: DispatchDeliveryReason | null;
   status: DispatchStatus;
+  /**
+   * Ledger fields (dispatch idempotency redesign). dedupe_key is the domain
+   * identity of the source fact; lease_owner points at the lane the WorkItem
+   * is folded into; target_uri / thread_root_id are queue-routing metadata
+   * for message WorkItems; resolution_kind / resolved_by_effect record the
+   * terminal outcome. Nullable — historical rows may predate the ledger.
+   */
+  dedupe_key?: string | null;
+  lease_owner?: string | null;
+  target_uri?: string | null;
+  thread_root_id?: string | null;
+  resolution_kind?: 'effect' | 'no_action' | 'cancelled' | 'legacy_ack' | null;
+  resolved_by_effect?: string | null;
+  /**
+   * Reply-message provenance ("prll://msg_x") of the resolving Effect.
+   * Populated only by GET /dispatch/by-messages (Effect join) on
+   * effect-resolved rows; absent elsewhere.
+   */
+  result_uri?: string | null;
   acked_at: string | null;
   created_at: string;
 }
 
+/** POST /dispatch/claim — occupy a lane and fold claimable WorkItems into it. */
+export interface ClaimDispatchRequest {
+  /** Message lane resource (e.g. "prll://cht_x"). Omit for typed claims. */
+  target_uri?: string;
+  thread_root_id?: string;
+  /** Typed WorkItem claim: the lane resource is the WorkItem itself. */
+  dispatch_event_id?: string;
+  /**
+   * Typed claim by source identity, for callers without the WorkItem id
+   * (the live task.assigned event). The dedupe arbiter guarantees at most
+   * one live WorkItem per source.
+   */
+  source_type?: string;
+  source_id?: string;
+  limit?: number;
+}
+
+export interface ClaimDispatchResponse {
+  claimed: boolean;
+  lane?: string;
+  lease_until?: string;
+  events?: DispatchEvent[];
+}
+
+/** POST /dispatch/steer — fold a pending same-target WorkItem into a live lane. */
+export interface SteerDispatchRequest {
+  lane: string;
+  target_uri: string;
+  thread_root_id?: string;
+  /** Either the WorkItem id or its (source_type, source_id) pair. */
+  dispatch_event_id?: string;
+  source_type?: string;
+  source_id?: string;
+}
+
+export interface SteerDispatchResponse {
+  dispatch_event_id: string;
+}
+
+/** POST /dispatch/complete — end a turn: no_action sweep + lane release + re-drive. */
+export interface CompleteDispatchRequest {
+  lane: string;
+  target_uri: string;
+  thread_root_id?: string;
+}
+
+export interface CompleteDispatchResult {
+  swept_no_action: number;
+  redriven: boolean;
+}
+
 export type DispatchNewData = DispatchEvent;
 
 export interface DispatchExpiredGroup {
@@ -2566,6 +2662,28 @@ export interface DispatchReceivedData {
   org_id: string;
 }
 
+/**
+ * Terminal counterpart of DispatchReceivedData: published on org:{orgId} when
+ * a message WorkItem reaches a terminal resolution, so the message-level
+ * Activity indicator flips active→done (or clears, for `cancelled`) without
+ * inferring completion from agent session state. Message WorkItems only.
+ */
+export interface DispatchResolvedData {
+  agent_id: string;
+  event_type: string;
+  source_type: string;
+  source_id: string;
+  chat_id?: string | null;
+  org_id: string;
+  resolution_kind: 'effect' | 'no_action' | 'cancelled' | 'legacy_ack';
+  /**
+   * Reply-message provenance ("prll://msg_x") for effect resolutions —
+   * the indicator's click-through resolves the agent session from this
+   * message. Absent for no_action / legacy_ack.
+   */
+  result_uri?: string | null;
+}
+
 export type InboxNewData = InboxItem;
 
 export interface InboxUpdateData {
@@ -2648,6 +2766,7 @@ export type WsEventMap = {
   'read_position.updated': ReadPositionUpdateData;
   'dispatch.new': DispatchNewData;
   'dispatch.received': DispatchReceivedData;
+  'dispatch.resolved': DispatchResolvedData;
   'schedule.created': ScheduleCreatedData;
   'schedule.updated': ScheduleUpdatedData;
   'schedule.deleted': ScheduleDeletedData;
@@ -3614,3 +3733,48 @@ export interface SearchResponse {
   /** Per-type flag: more results remain past the returned page (within the reachable pool). Lets a tabbed results UI page each type independently. Optional for resilience to older payloads; clients default to all-false. */
   has_more?: { messages: boolean; tasks: boolean; wiki: boolean };
 }
+
+// ============================================================
+// Edge Device Types
+// ============================================================
+
+export interface EdgeDevice {
+  id: string;
+  org_id: string;
+  owner_user_id?: string;
+  name: string;
+  status: 'online' | 'offline';
+  last_seen_at?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface EdgeBrowserProfile {
+  id: string;
+  edge_id: string;
+  name: string;
+  is_default: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ClipConnection {
+  id: string;
+  clip_id: string;
+  org_id: string;
+  device_id?: string;
+  profile?: string;
+  mcp_config_id?: string;
+  alias?: string;
+  is_default: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface EdgeOnboardingStatus {
+  device_registered: boolean;
+  device_online: boolean;
+  clip_installed: boolean;
+  connection_created: boolean;
+  profile_created: boolean;
+}