@parall/sdk 1.48.0 → 1.50.0

package/src/types.ts

@@ -111,6 +111,12 @@ export interface TransferChatOwnershipRequest {
 export interface UnreadEntry {
   count: number;
   mentions: number;
+  /** Share of `count` contributed by unread thread replies (only present when
+   *  the unread fetch opted into `include_thread_replies`). Top-level timeline
+   *  unread = count - (thread_count ?? 0). */
+  thread_count?: number;
+  /** Share of `mentions` contributed by unread thread replies. */
+  thread_mentions?: number;
   since?: string;
 }
 
@@ -132,6 +138,38 @@ export type MessageType =
 
 export const MENTION_ALL_USER_ID = 'all';
 
+/**
+ * Member-type-filtered variants of the @all broadcast mention (group chats
+ * only): identical notification semantics, recipient set limited to human /
+ * agent members respectively.
+ */
+export const MENTION_ALL_HUMANS_USER_ID = 'allhuman';
+export const MENTION_ALL_AGENTS_USER_ID = 'allagent';
+
+/** True when a mention user_id is a broadcast token rather than a usr_ id. */
+export function isBroadcastMentionId(userId: string): boolean {
+  return (
+    userId === MENTION_ALL_USER_ID ||
+    userId === MENTION_ALL_HUMANS_USER_ID ||
+    userId === MENTION_ALL_AGENTS_USER_ID
+  );
+}
+
+/**
+ * True when a mention user_id addresses the given viewer — either their own
+ * usr_ id, @all, or the typed broadcast matching their user type.
+ */
+export function mentionTargetsUser(
+  mentionUserId: string,
+  userId: string,
+  userType: UserType,
+): boolean {
+  if (mentionUserId === userId || mentionUserId === MENTION_ALL_USER_ID) return true;
+  if (mentionUserId === MENTION_ALL_HUMANS_USER_ID) return userType === 'human';
+  if (mentionUserId === MENTION_ALL_AGENTS_USER_ID) return userType === 'agent';
+  return false;
+}
+
 export interface Mention {
   user_id: string;
   offset: number;
@@ -273,6 +311,12 @@ export interface Message {
    * absent from the stack. A reload re-derives it from the server's view.
    */
   recent_repliers?: User[];
+  /**
+   * Per-viewer count of thread replies newer than the viewer's thread read
+   * cursor, excluding the viewer's own replies (root only). Populated on
+   * top-level list responses; omitted when zero.
+   */
+  unread_reply_count?: number;
   edited_at: string | null;
   deleted_at: string | null;
   created_at: string;
@@ -281,6 +325,27 @@ export interface Message {
   agent_session_id?: string | null;
   hints?: MessageHints | null;
   attachments?: Attachment[];
+  reactions?: ReactionSummary[];
+}
+
+/**
+ * Aggregated reactions for one emoji on a message.
+ *
+ * `has_reacted` is viewer-relative in REST responses. In
+ * `message.reaction.updated` WS broadcasts it is computed for the ACTOR who
+ * triggered the toggle — subscribers must recompute their own state from
+ * `user_ids` (see docs/engineering-design/ws-protocol.md).
+ */
+export interface ReactionSummary {
+  emoji: string;
+  count: number;
+  user_ids: string[];
+  has_reacted: boolean;
+}
+
+export interface ToggleReactionResponse {
+  added: boolean;
+  reactions: ReactionSummary[];
 }
 
 export interface Attachment {
@@ -368,9 +433,48 @@ export interface OrgMember {
   user_id: string;
   role: OrgMemberRole;
   joined_at: string;
+  // Org-scoped public profile projection. Missing profile row reads as
+  // empty strings with profile_version 0.
+  title: string;
+  description: string;
+  profile_version: number;
   user?: User;
 }
 
+// Org-scoped public member profile (Human and Agent alike). Never carries
+// private agent Instructions.
+export interface MemberProfile {
+  user_id: string;
+  display_name: string;
+  type: UserType;
+  title: string;
+  description: string;
+  profile_version: number;
+}
+
+// Full-replacement update over {title, description} with a version CAS.
+// expected_version 0 = first write (no profile row yet). A stale version
+// gets 409 PROFILE_VERSION_CONFLICT with error.details.current_version.
+export interface UpdateMemberProfileRequest {
+  title: string;
+  description: string;
+  expected_version: number;
+}
+
+// Private agent Instructions — org-admin maintained runtime context.
+export interface AgentInstructions {
+  agent_user_id: string;
+  instructions: string;
+  version: number;
+  updated_at?: string;
+  updated_by?: string;
+}
+
+export interface UpdateAgentInstructionsRequest {
+  instructions: string;
+  expected_version: number;
+}
+
 // Team — a named group of org members, referenced in wiki ACLs as `@slug`.
 export interface Team {
   id: string;
@@ -528,6 +632,159 @@ export interface FeatureFlagsResponse {
   flags: Record<string, boolean | string | number>;
 }
 
+// ============================================================
+// Team Template Types
+// ============================================================
+
+export type TemplateParameterInputType = 'text' | 'select' | 'multi';
+export type TemplateParameterValue = string | string[];
+
+export interface TemplateParameter {
+  key: string;
+  label: string;
+  input_type: TemplateParameterInputType;
+  options?: string[];
+  default?: TemplateParameterValue;
+  required?: boolean;
+}
+
+export interface TemplateDependency {
+  type: 'clip';
+  ref: string;
+  required?: boolean;
+  degraded_note?: string;
+}
+
+export interface TemplateAgentPublicProfile {
+  title: string;
+  description: string;
+}
+
+export interface TemplateAgentSpec {
+  key: string;
+  display_name: string;
+  public_profile: TemplateAgentPublicProfile;
+  instructions: string;
+  runtime_type?: string;
+  model?: string | null;
+  compute?: {
+    machine_type: 'cloud';
+    machine_label?: string;
+  } | null;
+  dependencies?: TemplateDependency[];
+}
+
+export interface TemplateWorkspaceScaffold {
+  channels: Array<{
+    purpose?: string;
+    name_pattern: string;
+  }>;
+  schedules?: Array<{
+    agent_key: string;
+    name: string;
+    cron: string;
+    description: string;
+  }>;
+  project?: {
+    name_pattern: string;
+  } | null;
+}
+
+export interface TemplateDefinition {
+  name: string;
+  mission: string;
+  scope_tags?: string[];
+  outcomes?: string[];
+  agents: TemplateAgentSpec[];
+  workspace_scaffold: TemplateWorkspaceScaffold;
+  parameters?: TemplateParameter[];
+}
+
+// Explicit organization catalog projection. It intentionally does not extend
+// the authoring types: future authoring fields must never become public by
+// inheritance. Instructions, runtime/model/compute, and workspace seed data
+// stay on the cluster-internal CRUD and server-side deployment path.
+export interface TemplateCatalogAgentSpec {
+  key: string;
+  display_name: string;
+  public_profile: TemplateAgentPublicProfile;
+  dependencies?: Array<Pick<TemplateDependency, 'type' | 'ref' | 'required'>>;
+}
+
+export interface TemplateCatalogDefinition {
+  name: string;
+  mission: string;
+  scope_tags?: string[];
+  outcomes?: string[];
+  agents: TemplateCatalogAgentSpec[];
+  parameters?: TemplateParameter[];
+}
+
+// Resolved in the target organization at catalog-read time. This is not part
+// of the persisted authoring definition and carries no readiness/connection
+// state.
+export interface TemplateDependencyMetadata {
+  type: 'clip';
+  ref: string;
+  display_name: string;
+}
+
+export interface Template {
+  id: string;
+  version: string;
+  /** Opaque token pinning the version + exact definition shown to the user. */
+  revision: string;
+  name: string;
+  definition: TemplateCatalogDefinition;
+  dependency_metadata?: TemplateDependencyMetadata[];
+  status: 'active' | 'archived';
+  created_at: string;
+  updated_at: string;
+}
+
+export interface DeployTemplateRequest {
+  template_id: string;
+  template_revision: string;
+  parameter_values?: Record<string, TemplateParameterValue>;
+}
+
+export type TemplateDeploymentAgentState = 'up' | 'provisioning' | 'error';
+
+export interface TemplateDeploymentReport {
+  deployment_id: string;
+  status: 'deployed';
+  team: {
+    name: string;
+    main_chat_id: string;
+  };
+  agents: Array<{
+    key: string;
+    agent_id: string;
+    display_name: string;
+    public_profile: TemplateAgentPublicProfile;
+    runtime: string;
+    state: TemplateDeploymentAgentState;
+  }>;
+  resources: {
+    chats: Array<{ id: string; name: string }>;
+    schedules: Array<{ id: string; name: string }>;
+    project_id?: string;
+  };
+  dependencies: Array<{
+    type: 'clip';
+    ref: string;
+    name?: string;
+    required: boolean;
+    connected: boolean;
+    declared_by: string[];
+  }>;
+  kickoff: {
+    sent: boolean;
+    message_id?: string;
+    error?: string;
+  };
+}
+
 // ============================================================
 // API Request Types
 // ============================================================
@@ -666,6 +923,9 @@ export interface CreateAgentRequest {
   thinking_effort?: string; // model-dependent: "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
   agent_permissions?: string[];
   runtime_type?: string; // "openclaw" | "claude-code" | "codex"; default "openclaw"
+  // Preferred write field for the agent's private instruction text.
+  instructions?: string;
+  /** @deprecated Same-value alias of `instructions`; loses when both are set. */
   description?: string;
   machine_type?: string;
   machine_label?: string; // preset: "lite" | "standard" | "pro" | "custom"
@@ -762,6 +1022,9 @@ export interface UpdateAgentRequest {
   agent_model?: string;
   model_management?: string;
   agent_permissions?: string[];
+  // Preferred write field for the agent's private instruction text.
+  instructions?: string;
+  /** @deprecated Same-value alias of `instructions`; loses when both are set. */
   description?: string;
   thinking_effort?: string;
 }
@@ -919,7 +1182,18 @@ export interface AgentProfile {
   machine_id: string | null;
   hosting_mode?: 'hosted' | 'self_hosted' | 'platform_runtime';
   runtime_type: string;
+  /**
+   * @deprecated Alias of `instructions` kept for pre-rename readers; the
+   * server keeps both byte-identical. Use `instructions` (and the
+   * dedicated instructions endpoints) instead.
+   */
   description: string | null;
+  // Private Instructions (admin-maintained runtime context). Redacted for
+  // non-admin viewers on list surfaces, same as description.
+  instructions?: string | null;
+  instructions_version?: number;
+  instructions_updated_at?: string | null;
+  instructions_updated_by?: string | null;
   thinking_effort: string | null;
   run_config?: RunConfig;
   created_by: string;
@@ -939,6 +1213,10 @@ export interface AgentPresence {
 
 export interface AgentWithRuntime extends User {
   agent_profile?: AgentProfile | null;
+  // Org-scoped public profile (title / public description) for the org the
+  // request is scoped to. Runtimes read it from /agents/me to build the
+  // public identity prompt section.
+  public_profile?: MemberProfile | null;
   machine?: Machine | null;
   presence?: AgentPresence | null;
 }
@@ -1159,6 +1437,13 @@ export interface Task {
   seq_number: number | null;
   identifier: string | null;
   sort_order: number;
+  /**
+   * Planned start date, YYYY-MM-DD (calendar date, timezone-free) — the
+   * planned schedule's left edge, independent of started_at (when work
+   * actually began). Absent on servers older than migration 145. When both
+   * dates are set, planned_start_date <= due_date.
+   */
+  planned_start_date?: string | null;
   /** Planned completion date, YYYY-MM-DD (calendar date, timezone-free). */
   due_date: string | null;
   assignee?: User;
@@ -1246,6 +1531,8 @@ export interface CreateTaskRequest {
   project_id?: string;
   source_chat_id?: string;
   sort_order?: number;
+  /** Planned start date, YYYY-MM-DD. Must be <= due_date when both are set. */
+  planned_start_date?: string;
   /** Planned completion date, YYYY-MM-DD. */
   due_date?: string;
 }
@@ -1266,6 +1553,12 @@ export interface UpdateTaskRequest {
    * full column. Mutually exclusive with sort_order.
    */
   placement?: 'end';
+  /**
+   * Planned start date, YYYY-MM-DD; explicit null clears it. The post-patch
+   * state must satisfy planned_start_date <= due_date when both are set
+   * (400 INVALID_DATE_RANGE otherwise).
+   */
+  planned_start_date?: string | null;
   /** Planned completion date, YYYY-MM-DD; explicit null clears it. */
   due_date?: string | null;
   /**
@@ -2179,6 +2472,20 @@ export interface MessageDeleteData {
   thread_root_id?: string;
 }
 
+/**
+ * Payload of the `message.reaction.updated` WS broadcast. `reactions` is the
+ * full aggregated snapshot for the message; its `has_reacted` flags are
+ * actor-relative (see {@link ReactionSummary}) — recompute from `user_ids`.
+ */
+export interface ReactionUpdatedData {
+  message_id: string;
+  chat_id: string;
+  emoji: string;
+  user_id: string;
+  added: boolean;
+  reactions: ReactionSummary[];
+}
+
 export interface TypingUpdateData {
   chat_id: string;
   thread_root_id: string | null;
@@ -3073,6 +3380,13 @@ export interface ReadPositionUpdateData {
   last_read_message_id: string;
 }
 
+/** Per-thread read cursor sync across the user's devices. */
+export interface ThreadReadPositionUpdateData {
+  chat_id: string;
+  thread_root_id: string;
+  last_read_reply_id: string;
+}
+
 export interface NotificationAlertData {
   title: string;
   body: string;
@@ -3087,6 +3401,7 @@ export type WsEventMap = {
   'message.patch': MessagePatchData;
   'message.edit': MessageEditData;
   'message.delete': MessageDeleteData;
+  'message.reaction.updated': ReactionUpdatedData;
   'typing.update': TypingUpdateData;
   'chat.created': ChatCreatedData;
   'chat.update': ChatUpdateData;
@@ -3131,6 +3446,7 @@ export type WsEventMap = {
   'inbox.update': InboxUpdateData;
   'inbox.bulk_update': InboxBulkUpdateData;
   'read_position.updated': ReadPositionUpdateData;
+  'thread_read_position.updated': ThreadReadPositionUpdateData;
   'dispatch.new': DispatchNewData;
   'dispatch.received': DispatchReceivedData;
   'dispatch.resolved': DispatchResolvedData;
@@ -3335,6 +3651,37 @@ export interface BacklinksResponse {
   next_cursor?: string;
 }
 
+/**
+ * Request for POST /orgs/{orgId}/refs/outbound — two mutually exclusive
+ * forms, modeled as a union so an invalid mixed shape fails at compile time:
+ * `thread_root_id` resolves a thread's message set server-side (root + ALL
+ * non-deleted replies — the client's reply window may be partial), while
+ * `source_type` + `source_ids` lists explicit sources (max 500; v1 accepts
+ * only `message` sources).
+ */
+export type OutboundRefsRequest =
+  | { thread_root_id: string; source_type?: never; source_ids?: never }
+  | { source_type: string; source_ids: string[]; thread_root_id?: never };
+
+/** One raw ref_links row; dedupe/grouping is a client concern. */
+export interface OutboundRefItem {
+  uri: string;
+  target_type: string;
+  target_id: string;
+  target_path?: string;
+  target_frag?: string;
+  context?: string;
+  source_type: string;
+  source_id: string;
+  position: number;
+}
+
+export interface OutboundRefsResponse {
+  data: OutboundRefItem[];
+  /** Set when the server-side sanity cap dropped the tail of the row set. */
+  truncated?: boolean;
+}
+
 /**
  * One entity in a multi-hop ref-graph traversal (GET /refs/graph). `id`/`uri` are
  * the ref_links endpoint identifier: a bare prll:// entity id for most nodes
@@ -3976,6 +4323,29 @@ export interface BrowserViewerCommandResponse {
   result: Record<string, unknown> | null;
 }
 
+/**
+ * Cloud Edge live viewer (V1b, design §6). Same request/reply shape as the v2
+ * browser-profile viewer — the transport-agnostic `BrowserViewer` client drives
+ * either — but a distinct type so the edge viewer surface never depends on the
+ * v2 browser-profile viewer symbols.
+ */
+export interface EdgeViewerCommandRequest {
+  /** Correlates a viewer session. Omit on `stream.start`; the server returns one. */
+  session_id?: string;
+  command: string;
+  input?: Record<string, unknown>;
+}
+
+export interface EdgeViewerCommandResponse {
+  session_id: string;
+  /**
+   * Command-specific result. For `stream.start`:
+   * `{ offer_sdp, candidates, ice_servers, streamed_tab_id }`. May be `null` on
+   * the wire (a nil Go result map serializes as JSON null); coalesce to `{}`.
+   */
+  result: Record<string, unknown> | null;
+}
+
 export interface GrantBrowserProfileConsentRequest {
   clip_id: string;
 }
@@ -4187,6 +4557,45 @@ export interface EdgeBrowserProfile {
   is_default: boolean;
   created_at: string;
   updated_at: string;
+  /**
+   * True when the profile has a fixed egress proxy configured (hosted Cloud
+   * Profiles). Presence flag only — endpoint/username/password are readable
+   * exclusively by managers via the dedicated proxy endpoint, and the password
+   * never leaves the server.
+   */
+  proxy_configured?: boolean;
+}
+
+/**
+ * Sanitized per-profile egress proxy status (hosted Cloud Profiles) — the GET
+ * response and the PUT/DELETE result. NEVER carries the password; `password_set`
+ * is the only trace of it.
+ */
+export interface EdgeProfileProxyStatus {
+  configured: boolean;
+  server?: string;
+  username?: string;
+  password_set: boolean;
+  /** Opaque compare-and-swap token for conditional PUT/DELETE. */
+  version: string;
+  /** Authoritative mutation gate; false whenever a non-released lease exists. */
+  can_mutate: boolean;
+  /** Actual lease state blocking a mutation (never inferred from device status). */
+  lease_status?: 'pending' | 'assigned' | 'active' | 'releasing' | 'repair';
+  /** Suggested delay before re-reading authoritative state. */
+  retry_after_seconds?: number;
+}
+
+/**
+ * PUT body for a profile's egress proxy: the FULL triple every time (no
+ * tri-state merge — the stored blob is encrypted, so replace always re-supplies
+ * complete credentials). Clearing is DELETE, never an empty PUT. Username and
+ * password go together or not at all.
+ */
+export interface SetEdgeProfileProxyRequest {
+  server: string;
+  username?: string;
+  password?: string;
 }
 
 export interface ClipConnection {