@parall/sdk 1.55.3 → 1.55.4

package/src/client.ts

@@ -1,6 +1,6 @@
 import { type BrowserViewerRequestOptions, browserViewerRequestOptions } from './browser-viewer.js';
 import { API_BASE, ENDPOINTS, WIKI_BASE } from './constants.js';
-import { TaskLabelClient } from './task-label-client.js';
+import { WechatClient } from './wechat-client.js';
 import type {
   AddTeamMemberRequest,
   AgentClip,
@@ -233,9 +233,6 @@ import type {
   UpdateTeamRequest,
   UpdateWikiChangesetRequest,
   User,
-  WechatContactsPage,
-  WechatProfileView,
-  WechatStatusView,
   Wiki,
   WikiAccessStatus,
   WikiAnchorResolveRequest,
@@ -282,7 +279,7 @@ export interface ParallClientOptions {
   getFeatureFlagOverrides?: () => string | null | undefined;
 }
 
-export class ParallClient extends TaskLabelClient {
+export class ParallClient extends WechatClient {
   private baseUrl: string;
   private wikiBaseUrl: string;
   private token: string | null;
@@ -2541,31 +2538,6 @@ export class ParallClient extends TaskLabelClient {
     await this.request('POST', ENDPOINTS.SLACK_STATUS(orgId), input);
   }
 
-  /**
-   * WeChat tier-B read verb (agent-only; internal research preview): the
-   * account's address book — friends/chatrooms enriched with display names,
-   * followed official accounts. Same live gate as the send verb.
-   */
-  async listWechatContacts(orgId: string): Promise<WechatContactsPage> {
-    return this.request('GET', ENDPOINTS.WECHAT_CONTACTS(orgId));
-  }
-
-  /**
-   * WeChat tier-B read verb (agent-only): the connected account's identity
-   * (wxid / alias / nickName / app id).
-   */
-  async wechatProfile(orgId: string): Promise<WechatProfileView> {
-    return this.request('GET', ENDPOINTS.WECHAT_PROFILE(orgId));
-  }
-
-  /**
-   * WeChat tier-B read verb (agent-only): live online probe + identity +
-   * the platform's offline record.
-   */
-  async wechatStatus(orgId: string): Promise<WechatStatusView> {
-    return this.request('GET', ENDPOINTS.WECHAT_STATUS(orgId));
-  }
-
   async listChannelConversations(
     orgId: string,
     connectionId: string,
@@ -3162,13 +3134,13 @@ export class ParallClient extends TaskLabelClient {
   async resolveRefs(
     orgId: string,
     refs: string[],
-    options?: { sourceMessageId?: string },
+    options?: { sourceMessageId?: string; full?: boolean },
   ): Promise<ResolveRefsResponse> {
-    const body: Record<string, unknown> = { refs };
-    if (options?.sourceMessageId) {
-      body.source_message_id = options.sourceMessageId;
-    }
-    return this.request('POST', ENDPOINTS.REFS_RESOLVE(orgId), body);
+    return this.request('POST', ENDPOINTS.REFS_RESOLVE(orgId), {
+      refs,
+      source_message_id: options?.sourceMessageId,
+      full: options?.full || undefined,
+    });
   }
 
   async getBacklinks(

package/src/constants.ts

@@ -686,6 +686,7 @@ export const ENDPOINTS = {
   SLACK_STATUS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/status`,
   // WeChat tier-B read verbs (agent-only; internal research preview).
   WECHAT_CONTACTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/contacts`,
+  WECHAT_HISTORY: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/history`,
   WECHAT_PROFILE: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/profile`,
   WECHAT_STATUS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/status`,
 

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './constants.js';
 export * from './subject.js';
 export * from './task-label-types.js';
 export * from './types.js';
+export * from './wechat-types.js';
 export type {
   ParallWsOptions,
   WsClientEventMap,

package/src/types.ts

@@ -1000,6 +1000,13 @@ export interface SendMessageRequest {
 export interface MessageDispatchSource {
   source_type: string;
   source_id: string;
+  /**
+   * Conversation generation of the sending execution (parel v2 invocation
+   * context). Required by the server for agents on the direct_session_v2
+   * transport; a value older than the current New Session barrier is
+   * rejected (STALE_GENERATION).
+   */
+  generation?: number;
 }
 
 /** One WorkItem source pointer for the by-source complete surface. */
@@ -1730,16 +1737,25 @@ export interface UpdateTaskRequest {
    */
   label_ids?: string[] | null;
   /**
-   * 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
+   * Dispatch binding (agent senders during a typed dispatch turn).
+   * Lane-bound form (v1 consumers): dispatch_lane + dispatch_event_id bind
+   * the update to the claimed typed lane (incumbency-checked).
+   * By-id form (parel v2 converged consumers — no lane exists):
+   * dispatch_event_id + dispatch_generation bind the update to the WorkItem
+   * directly under the conversation-generation fence.
+   * In both forms dispatch_effect_key additionally commits the update as
    * the dispatch's idempotent Effect and resolves the WorkItem in the same
-   * transaction (first update only).
+   * transaction. Lane-bound: exactly "task_update:<dispatch_event_id>" —
+   * first update only; later updates go fenced keyless (the CLI sidecar
+   * arbitrates). By-id: "task_update:<dispatch_event_id>:<payload-hash>" —
+   * content-addressed, every distinct update carries its own key; the first
+   * resolves the WorkItem and later keys land as their own Effects against
+   * the already-resolved row.
    */
   dispatch_lane?: string;
   dispatch_event_id?: string;
   dispatch_effect_key?: string;
+  dispatch_generation?: number;
 }
 
 export interface CreateTaskRelationRequest {
@@ -4006,6 +4022,7 @@ export interface PresenceUpdateData {
 export interface ResolveRefsRequest {
   refs: string[];
   source_message_id?: string;
+  full?: boolean;
 }
 
 export interface ResolvedRef {

package/src/wechat-client.ts

@@ -0,0 +1,35 @@
+import { ENDPOINTS } from './constants.js';
+import { TaskLabelClient } from './task-label-client.js';
+import type { WechatContactsPage, WechatProfileView, WechatStatusView } from './types.js';
+import type { WechatHistoryPage, WechatHistoryQuery } from './wechat-types.js';
+
+/** WeChat channel read methods shared by every ParallClient instance. */
+export abstract class WechatClient extends TaskLabelClient {
+  /** Address book enriched with display names. */
+  async listWechatContacts(orgId: string): Promise<WechatContactsPage> {
+    return this.request('GET', ENDPOINTS.WECHAT_CONTACTS(orgId));
+  }
+
+  /** Platform-retained context in chronological page order. */
+  async wechatHistory(
+    orgId: string,
+    conversation: string,
+    query?: WechatHistoryQuery,
+  ): Promise<WechatHistoryPage> {
+    const params = new URLSearchParams({ conversation });
+    if (query?.before) params.set('before', query.before);
+    if (query?.since) params.set('since', query.since);
+    if (query?.limit !== undefined) params.set('limit', String(query.limit));
+    return this.request('GET', `${ENDPOINTS.WECHAT_HISTORY(orgId)}?${params.toString()}`);
+  }
+
+  /** Connected WeChat account identity. */
+  async wechatProfile(orgId: string): Promise<WechatProfileView> {
+    return this.request('GET', ENDPOINTS.WECHAT_PROFILE(orgId));
+  }
+
+  /** Live online probe, identity, and platform offline record. */
+  async wechatStatus(orgId: string): Promise<WechatStatusView> {
+    return this.request('GET', ENDPOINTS.WECHAT_STATUS(orgId));
+  }
+}

package/src/wechat-types.ts

@@ -0,0 +1,28 @@
+/** Query for platform-retained WeChat context. */
+export interface WechatHistoryQuery {
+  /** External message id returned as next_before by a previous page. */
+  before?: string;
+  /** Inclusive RFC3339 timestamp or YYYY-MM-DD (UTC midnight). */
+  since?: string;
+  /** Page size; defaults to 20 and is capped at 100. */
+  limit?: number;
+}
+
+export interface WechatHistoryMessage {
+  /** Vendor external message id. */
+  id: string;
+  direction: 'inbound' | 'outbound';
+  sender_wxid: string;
+  sender_name: string;
+  text: string;
+  occurred_at: string;
+}
+
+export interface WechatHistoryPage {
+  conversation: string;
+  /** Chronological order: oldest to newest within this page. */
+  messages: WechatHistoryMessage[];
+  has_more: boolean;
+  /** Pass back as before to continue toward older messages. */
+  next_before?: string;
+}