@parall/sdk 1.55.2 → 1.55.4

package/src/client.ts

@@ -1,10 +1,11 @@
 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,
   AgentInstructions,
+  AgentManager,
   AgentProviderConfigRead,
   AgentSessionDB,
   AgentStep,
@@ -211,6 +212,7 @@ import type {
   TransferChatOwnershipRequest,
   UnreadEntry,
   UpdateAgentInstructionsRequest,
+  UpdateAgentManagerRequest,
   UpdateAgentProviderConfigRequest,
   UpdateAgentRequest,
   UpdateAgentSessionRequest,
@@ -231,9 +233,6 @@ import type {
   UpdateTeamRequest,
   UpdateWikiChangesetRequest,
   User,
-  WechatContactsPage,
-  WechatProfileView,
-  WechatStatusView,
   Wiki,
   WikiAccessStatus,
   WikiAnchorResolveRequest,
@@ -280,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;
@@ -865,6 +864,25 @@ export class ParallClient extends TaskLabelClient {
     return this.request('PATCH', ENDPOINTS.AGENT_INSTRUCTIONS(orgId, agentId), req);
   }
 
+  /** Agent manager state — readable by every active member. */
+  async getAgentManager(orgId: string, agentId: string): Promise<AgentManager> {
+    return this.request('GET', ENDPOINTS.AGENT_MANAGER(orgId, agentId));
+  }
+
+  /**
+   * Assign / transfer / renounce the agent's manager (manager_user_id null =
+   * renounce). Human org admin/owner or the current manager only; a stale
+   * expected_version gets 409 MANAGER_VERSION_CONFLICT with
+   * error.details.current_version.
+   */
+  async updateAgentManager(
+    orgId: string,
+    agentId: string,
+    req: UpdateAgentManagerRequest,
+  ): Promise<AgentManager> {
+    return this.request('PATCH', ENDPOINTS.AGENT_MANAGER(orgId, agentId), req);
+  }
+
   // Member activity surfaces — chats the member participates in within this org,
   // ordered by most recent activity. Powers the member profile Activity tab.
   async getMemberChats(
@@ -2520,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,
@@ -3141,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

@@ -387,9 +387,13 @@ export const ENDPOINTS = {
   ORG_MEMBER_PROFILE: (orgId: string, userId: string) =>
     `${API_BASE}/orgs/${orgId}/members/${userId}/profile`,
   // Private agent Instructions — visibility gated server-side
-  // (agent self + Human org admin/owner). Never cached.
+  // (agent self + Human org admin/owner + the agent's manager). Never cached.
   AGENT_INSTRUCTIONS: (orgId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/instructions`,
+  // Agent manager (agent-global relation, org-scoped authorization).
+  // PATCH covers assign / transfer / renounce (manager_user_id null).
+  AGENT_MANAGER: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/manager`,
   REF_SEARCH: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/search`,
 
   // Direct messages (org-scoped, atomic find-or-create + send)
@@ -682,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

@@ -486,6 +486,31 @@ export interface UpdateAgentInstructionsRequest {
   expected_version: number;
 }
 
+// Agent manager state. Missing row = manager_user_id null, version 0 (legal
+// unmanaged state); renounce keeps the row and bumps the monotonic version.
+export interface AgentManager {
+  agent_user_id: string;
+  manager_user_id: string | null;
+  manager_display_name?: string;
+  version: number;
+  updated_at?: string;
+  updated_by?: string;
+}
+
+// Assign / transfer / renounce share this full-replacement CAS write
+// (manager_user_id null = renounce). A stale expected_version gets 409
+// MANAGER_VERSION_CONFLICT with error.details.current_version.
+export interface UpdateAgentManagerRequest {
+  manager_user_id: string | null;
+  expected_version: number;
+}
+
+// Compact manager projection on agent list/me rows; absent when unmanaged.
+export interface AgentManagerRef {
+  user_id: string;
+  display_name: string;
+}
+
 // Team — a named group of org members, referenced in ACL rosters by its ID.
 export type TeamRole = 'member' | 'manager';
 
@@ -975,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. */
@@ -1331,6 +1363,9 @@ export interface AgentWithRuntime extends User {
   // request is scoped to. Runtimes read it from /agents/me to build the
   // public identity prompt section.
   public_profile?: MemberProfile | null;
+  // Agent-manager projection — org-visible display data, absent when
+  // unmanaged. Runtimes read it from /agents/me for the Manager prompt line.
+  manager?: AgentManagerRef | null;
   machine?: Machine | null;
   presence?: AgentPresence | null;
 }
@@ -1702,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 {
@@ -3978,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;
+}