@parall/sdk 1.46.0 → 1.48.0

package/src/client.ts

@@ -95,6 +95,13 @@ import type {
   CreateChannelConnectionInput,
   InitiateChannelProvisioningInput,
   SendChannelMessageInput,
+  SlackChannelsPage,
+  SlackHistoryPage,
+  SlackManifestLinkResult,
+  SlackMembersPage,
+  SlackReadPageQuery,
+  SlackStatusInput,
+  SlackUsersPage,
   SentChannelMessage,
   UpdateChannelConnectionInput,
   ExternalIngressEvent,
@@ -202,6 +209,8 @@ import type {
   InvokeClipResponse,
   OnlineClipInfo,
   RegistryClipInfo,
+  ClipRegistryEntry,
+  InstallRegistryClipResponse,
   MachineClip,
   BrowserProfile,
   MachineBrowserProfile,
@@ -220,6 +229,8 @@ import type {
   EdgeBrowserProfile,
   ClipConnection,
   EdgeOnboardingStatus,
+  ExecEdgeClipRequest,
+  EdgeClipExecResult,
 } from './types.js';
 
 export interface ParallClientOptions {
@@ -1754,11 +1765,17 @@ export class ParallClient {
     return this.request('PATCH', ENDPOINTS.MACHINE_SPEC(orgId, machineId), spec);
   }
 
-  /** Signal a local daemon-mode Machine to check for and apply an update. */
+  /** @deprecated Retired server-side (daemon-control-authorization §4.2):
+   *  daemons update autonomously (CDN poll + platform release signal). The
+   *  endpoint now answers 409 LOCAL_UPDATE_NOT_SUPPORTED unconditionally. */
   async requestMachineUpdate(orgId: string, machineId: string, mandatory = false): Promise<void> {
     await this.request('POST', ENDPOINTS.MACHINE_REQUEST_UPDATE(orgId, machineId), { mandatory });
   }
 
+  /** @deprecated Retired server-side (daemon-control-authorization §4.2):
+   *  remote filesystem browse of a member's machine was remote device access.
+   *  The endpoint now answers 409 LOCAL_BROWSE_NOT_SUPPORTED unconditionally;
+   *  workspace paths are typed in (or picked on the machine's own Desktop). */
   async browseMachineFilesystem(
     orgId: string,
     machineId: string,
@@ -1814,6 +1831,20 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.THREAD_UNREAD(orgId, chatId, threadRootId));
   }
 
+  /** Advance the per-thread read cursor (forward-only). The server auto-clears
+   *  thread-scoped inbox items (thread_reply + in-thread mentions) the cursor
+   *  now covers. */
+  async markThreadRead(
+    orgId: string,
+    chatId: string,
+    threadRootId: string,
+    messageId: string,
+  ): Promise<void> {
+    return this.request('POST', ENDPOINTS.THREAD_READ(orgId, chatId, threadRootId), {
+      message_id: messageId,
+    });
+  }
+
   // ---- Inbox ----
 
   async getInbox(
@@ -1854,9 +1885,15 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.INBOX_ARCHIVE_ALL(orgId));
   }
 
-  /** Mark an inbox item as read by its source (source_type + source_id) rather than inbox item ID. */
-  async ackInbox(orgId: string, source: { source_type: string; source_id: string }): Promise<void> {
-    return this.request('POST', ENDPOINTS.INBOX_ACK(orgId), source);
+  /** Mark inbox items as read by their source (source_type + source_id) or by
+   *  group_key, rather than by inbox item ID. The group_key form clears a whole
+   *  group at once (e.g. `task:{taskId}` — task_assign/task_update/task_comment
+   *  share it), used by the task detail view's auto-ack on open. */
+  async ackInbox(
+    orgId: string,
+    target: { source_type: string; source_id: string } | { group_key: string },
+  ): Promise<void> {
+    return this.request('POST', ENDPOINTS.INBOX_ACK(orgId), target);
   }
 
   async deleteInboxItem(orgId: string, id: string): Promise<void> {
@@ -2420,6 +2457,19 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHANNEL_PROVISIONING(orgId), input);
   }
 
+  /**
+   * Mint a pending slack connection + api.slack.com manifest-prefill link
+   * (guided manual path). Activate the returned connection_id with
+   * deliverChannelCredentials once the user brings back the bot token +
+   * signing secret.
+   */
+  async createSlackManifestLink(
+    orgId: string,
+    input: { agent_id: string },
+  ): Promise<SlackManifestLinkResult> {
+    return this.request('POST', ENDPOINTS.CHANNEL_SLACK_MANIFEST_LINK(orgId), input);
+  }
+
   /**
    * Lazy status poll — server-side this may forward one provider poll, so
    * call it at the session's `poll_interval_seconds` cadence, not faster.
@@ -2450,6 +2500,55 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHANNEL_SEND(orgId), input);
   }
 
+  private slackReadQuery(base: string, query?: SlackReadPageQuery, extra?: Record<string, string>) {
+    const params = new URLSearchParams();
+    if (query?.cursor) params.set('cursor', query.cursor);
+    if (query?.limit) params.set('limit', String(query.limit));
+    for (const [k, v] of Object.entries(extra ?? {})) params.set(k, v);
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+
+  /**
+   * Tier-B read verbs (agent-only): workspace visibility as the bot sees
+   * it. Same live gate as the send verb; authorization beyond it is the
+   * bot's own Slack permissions.
+   */
+  async listSlackChannels(orgId: string, query?: SlackReadPageQuery): Promise<SlackChannelsPage> {
+    return this.request('GET', this.slackReadQuery(ENDPOINTS.SLACK_CHANNELS(orgId), query));
+  }
+
+  async listSlackUsers(orgId: string, query?: SlackReadPageQuery): Promise<SlackUsersPage> {
+    return this.request('GET', this.slackReadQuery(ENDPOINTS.SLACK_USERS(orgId), query));
+  }
+
+  async slackHistory(
+    orgId: string,
+    conversationId: string,
+    query?: SlackReadPageQuery,
+  ): Promise<SlackHistoryPage> {
+    return this.request(
+      'GET',
+      this.slackReadQuery(ENDPOINTS.SLACK_HISTORY(orgId), query, { conversation: conversationId }),
+    );
+  }
+
+  async slackMembers(
+    orgId: string,
+    conversationId: string,
+    query?: SlackReadPageQuery,
+  ): Promise<SlackMembersPage> {
+    return this.request(
+      'GET',
+      this.slackReadQuery(ENDPOINTS.SLACK_MEMBERS(orgId), query, { conversation: conversationId }),
+    );
+  }
+
+  /** Set/clear the Agents-pane "typing…" indicator (best-effort cosmetic). */
+  async setSlackStatus(orgId: string, input: SlackStatusInput): Promise<void> {
+    await this.request('POST', ENDPOINTS.SLACK_STATUS(orgId), input);
+  }
+
   async listChannelConversations(
     orgId: string,
     connectionId: string,
@@ -3377,6 +3476,43 @@ export class ParallClient {
     return resp.data;
   }
 
+  // ---- Clip registry (v3, api-server org registry — `crg_` entries) ----
+
+  /**
+   * List registry clips visible to the org: its own plus public+approved
+   * cross-org entries. This is the surface `installRegistryClip` and clip
+   * connections operate on — NOT the Pinix catalog proxy
+   * ({@link listRegistryClips}), whose entries carry no `crg_` id.
+   */
+  async listOrgRegistryClips(orgId: string): Promise<ClipRegistryEntry[]> {
+    // Server default page is 50 (max 100); one max-size page covers today's
+    // catalogs — revisit with real pagination if registries outgrow it.
+    const resp = await this.request<ClipRegistryEntry[] | null>(
+      'GET',
+      `${ENDPOINTS.ORG_CLIP_REGISTRY(orgId)}?limit=100`,
+    );
+    return resp ?? [];
+  }
+
+  /**
+   * Install a registry clip into the org (a reference in `clip_installs`, not a
+   * copy). Idempotent: installing an already-installed clip returns the same
+   * `200 {ok:true}`. Fails closed with `403 CLIP_NOT_APPROVED` when the clip is
+   * not eligible (cross-org requires public + approved).
+   */
+  async installRegistryClip(orgId: string, clipId: string): Promise<InstallRegistryClipResponse> {
+    return this.request('POST', ENDPOINTS.ORG_CLIP_INSTALL(orgId), { clip_id: clipId });
+  }
+
+  /** List the org's installed registry clips (full entries). */
+  async listInstalledRegistryClips(orgId: string): Promise<ClipRegistryEntry[]> {
+    const resp = await this.request<ClipRegistryEntry[] | null>(
+      'GET',
+      ENDPOINTS.ORG_CLIPS_INSTALLED(orgId),
+    );
+    return resp ?? [];
+  }
+
   // ---- Edge devices ----
 
   async listEdgeDevices(orgId: string): Promise<{ data: EdgeDevice[] }> {
@@ -3400,8 +3536,8 @@ export class ParallClient {
   }
 
   /**
-   * Delete a hosted Cloud Profile. Hosted only — a BYOC device is removed by
-   * uninstalling Parall Clip on that machine (`400 EDGE_PLACEMENT_UNSUPPORTED`).
+   * Delete a hosted Cloud Profile. Hosted only — use {@link unregisterEdgeDevice}
+   * for an offline BYOC registration (`400 EDGE_PLACEMENT_UNSUPPORTED` here).
    *
    * Idempotent and ASYNC: returns `202` with `hosted_state: 'deleting'` on the first
    * call and on every repeat. The device stops being usable immediately (no exec, no
@@ -3412,6 +3548,17 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.ORG_EDGE_DEVICE(orgId, edgeId));
   }
 
+  /**
+   * Remove the interactive human caller's own offline BYOC registration.
+   *
+   * Synchronous and idempotent: a committed removal and a repeat after removal
+   * both resolve with no response body. A live connection returns `EDGE_ONLINE`;
+   * callers must not clear local device identity until this method resolves.
+   */
+  async unregisterEdgeDevice(orgId: string, edgeId: string): Promise<void> {
+    await this.request('DELETE', ENDPOINTS.ORG_EDGE_DEVICE_UNREGISTER(orgId, edgeId));
+  }
+
   async getEdgeOnboarding(orgId: string): Promise<EdgeOnboardingStatus> {
     return this.request('GET', ENDPOINTS.ORG_EDGE_ONBOARDING(orgId));
   }
@@ -3420,6 +3567,68 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.ORG_EDGE_PROFILES(orgId, edgeId));
   }
 
+  /**
+   * Execute a registry clip command on an Edge device.
+   *
+   * A hosted (Cloud Profile) device is reachable ONLY through an explicit
+   * `connection` (id `ccn_…` or alias) — there is no implicit route to an
+   * org-shared browser login. BYOC keeps its legacy selectors (`edge_id`, or
+   * nothing for the caller's own online device).
+   *
+   * Returns the result envelope on completion (`success` may be false when the
+   * command RAN and failed — `error`/`error_code` describe why). Everything
+   * else throws a typed {@link ApiError}; match on `err.code`:
+   *
+   * Safe to retry (guaranteed nothing was dispatched):
+   * - `EDGE_ACTIVATING` 503 + `Retry-After` — cold cloud profile is starting.
+   *   Bounded backoff, same `correlation_id` across the loop.
+   * - `EDGE_BUSY` 409 — the device is executing another request.
+   * - `EDGE_CONCURRENCY_LIMIT` 429 — org at its concurrent-session limit.
+   * - `EDGE_UNAVAILABLE` 503 — session torn down / replaced mid-dispatch.
+   *
+   * NOT retryable:
+   * - `OUTCOME_UNKNOWN` 504 — dispatched, but no result arrived. The command
+   *   MAY HAVE EXECUTED (posted, ordered, deleted…). Never retry
+   *   automatically: verify the effect first, then decide. The message carries
+   *   the request id for audit.
+   * - `EDGE_DEADLINE_EXCEEDED` 504 — arrived late, provably NOT executed.
+   * - `EDGE_HOSTED_DISABLED_FOR_ORG` 403, `EDGE_REPAIR` 503 (operator-held),
+   *   `EDGE_RUNTIME_UNAVAILABLE` 503 (deployment has no hosted runtime).
+   * - Routing errors: `HOSTED_CONNECTION_REQUIRED`, `CONNECTION_NOT_FOUND`,
+   *   `CONNECTION_CLIP_MISMATCH`, `CONNECTION_TARGET_GONE`,
+   *   `CONNECTION_PROFILE_MISMATCH`, `EDGE_DELETING`, `DEVICE_OFFLINE`.
+   */
+  async execEdgeClip(orgId: string, req: ExecEdgeClipRequest): Promise<EdgeClipExecResult> {
+    // The server holds the connection open for timeout + ~5s of result wait;
+    // give the HTTP layer headroom past that so a slow-but-successful exec is
+    // not chopped locally into a fake transport error. The effective value
+    // mirrors the SERVER's rule exactly (out-of-range → its 30s default): a
+    // local clamp that disagreed would abort the HTTP call while the server
+    // legitimately keeps executing — manufacturing a transport error for a
+    // request that may still succeed.
+    const t = req.timeout;
+    const serverTimeout = t !== undefined && t > 0 && t <= 120000 ? t : 30000;
+    const timeoutMs = serverTimeout + 10_000;
+    try {
+      return await this.request('POST', ENDPOINTS.ORG_EDGE_EXEC(orgId), req, undefined, false, {
+        timeoutMs,
+      });
+    } catch (err) {
+      // A 422 is the RESULT envelope (the command ran and failed), not the
+      // standard error envelope — lift its stable `error_code` into
+      // ApiError.code so callers match one field for every failure.
+      if (
+        err instanceof ApiError &&
+        err.status === 422 &&
+        !err.code &&
+        typeof err.extras?.error_code === 'string'
+      ) {
+        err.code = err.extras.error_code;
+      }
+      throw err;
+    }
+  }
+
   // ---- Clip connections ----
 
   async listClipConnections(orgId: string, clipId: string): Promise<{ data: ClipConnection[] }> {

package/src/constants.ts

@@ -628,12 +628,20 @@ export const ENDPOINTS = {
   CHANNEL_MESSAGE: (orgId: string, messageId: string) =>
     `${API_BASE}/orgs/${orgId}/channel-messages/${messageId}`,
   CHANNEL_PROVISIONING: (orgId: string) => `${API_BASE}/orgs/${orgId}/channel-provisioning`,
+  CHANNEL_SLACK_MANIFEST_LINK: (orgId: string) =>
+    `${API_BASE}/orgs/${orgId}/channel-provisioning/slack/manifest-link`,
   CHANNEL_PROVISIONING_SESSION: (orgId: string, sessionId: string) =>
     `${API_BASE}/orgs/${orgId}/channel-provisioning/${sessionId}`,
   CHANNEL_PROVISIONING_CANCEL: (orgId: string, sessionId: string) =>
     `${API_BASE}/orgs/${orgId}/channel-provisioning/${sessionId}/cancel`,
   // Tier-B platform verb (agent-only): send one message as the bound bot.
   CHANNEL_SEND: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/channel-send`,
+  // Tier-B read verbs (agent-only): workspace visibility as the bot sees it.
+  SLACK_CHANNELS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/channels`,
+  SLACK_USERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/users`,
+  SLACK_HISTORY: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/history`,
+  SLACK_MEMBERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/members`,
+  SLACK_STATUS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/status`,
 
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
@@ -774,6 +782,8 @@ export const ENDPOINTS = {
   CHAT_READ: (orgId: string, chatId: string) => `${API_BASE}/orgs/${orgId}/chats/${chatId}/read`,
   THREAD_UNREAD: (orgId: string, chatId: string, threadRootId: string) =>
     `${API_BASE}/orgs/${orgId}/chats/${chatId}/threads/${threadRootId}/unread`,
+  THREAD_READ: (orgId: string, chatId: string, threadRootId: string) =>
+    `${API_BASE}/orgs/${orgId}/chats/${chatId}/threads/${threadRootId}/read`,
 
   // References (org-scoped)
   REFS_RESOLVE: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/resolve`,
@@ -861,13 +871,22 @@ export const ENDPOINTS = {
   ORG_EDGE: (orgId: string) => `/api/v1/orgs/${orgId}/edge`,
   ORG_EDGE_DEVICES: (orgId: string) => `/api/v1/orgs/${orgId}/edge/devices`,
   ORG_EDGE_DEVICE: (orgId: string, edgeId: string) => `/api/v1/orgs/${orgId}/edge/${edgeId}`,
+  ORG_EDGE_DEVICE_UNREGISTER: (orgId: string, edgeId: string) =>
+    `/api/v1/orgs/${orgId}/edge/${edgeId}/unregister`,
   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`,
+  ORG_EDGE_EXEC: (orgId: string) => `/api/v1/orgs/${orgId}/edge/exec`,
   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}`,
+
+  // Clip registry (v3, org-scoped, served by api-server — `crg_` entries; the
+  // Pinix Hub catalog proxy above is a different, id-less surface)
+  ORG_CLIP_REGISTRY: (orgId: string) => `/api/v1/orgs/${orgId}/clip-registry`,
+  ORG_CLIP_INSTALL: (orgId: string) => `/api/v1/orgs/${orgId}/clips/install`,
+  ORG_CLIPS_INSTALLED: (orgId: string) => `/api/v1/orgs/${orgId}/clips/installed`,
 } as const;
 
 /**

package/src/types.ts

@@ -2497,6 +2497,14 @@ export interface InboxItem {
   grouping_priority: number;
   /** Number of events in this group. Populated by the grouped list query. */
   group_count: number;
+  /**
+   * True when ANY row in this item's group is unread — the same group-level
+   * definition the unread-count badge uses. The representative row's own
+   * `read_at` can be set while older rows in its group are still unread, so
+   * read-state display must key off this field. Optional: absent on locally
+   * cached rows written before the field shipped (fall back to `read_at`).
+   */
+  group_unread?: boolean;
   read_at: string | null;
   archived_at: string | null;
   snoozed_until: string | null;
@@ -2535,6 +2543,14 @@ export interface ChannelConnection {
   ingress_url?: string;
   /** Returned once at mint time (create / token regeneration). */
   ingress_token?: string;
+  /**
+   * The in-product scope-upgrade re-auth can act on this connection
+   * (slack, active, provisioned-family — its auth_config carries the
+   * OAuth client). Mirrors the upgrade endpoint's preconditions exactly.
+   * Manual-family connections upgrade via the Slack console; the UI
+   * hides the upgrade CTA when this is false/absent.
+   */
+  upgrade_eligible?: boolean;
   created_at: string;
   updated_at: string;
 }
@@ -2649,16 +2665,35 @@ export type InitiateChannelProvisioningInput =
       provider: 'slack';
       /**
        * The short-lived app-configuration token (12h, generated at
-       * api.slack.com/apps). Transits once into apps.manifest.create and is
-       * never stored.
+       * api.slack.com/apps). Transits once into apps.manifest.create/update
+       * and is never stored.
        */
       config_token: string;
+      /**
+       * Scope-upgrade re-auth: converge the agent's EXISTING active
+       * connection's app on the current manifest and re-authorize it (bot
+       * token replaced in place, app id preserved) instead of creating a
+       * new app.
+       */
+      upgrade?: boolean;
     }
   | {
       agent_id: string;
       provider: Exclude<ChannelProvider, 'slack'>;
     };
 
+/**
+ * Manifest-prefill link for the guided manual slack path: the platform
+ * mints a pending connection and returns an api.slack.com link that opens
+ * the create-app form with everything preset (events, scopes, this
+ * connection's webhook URL). The user installs the app themselves and
+ * activates the SAME connection by delivering bot token + signing secret.
+ */
+export interface SlackManifestLinkResult {
+  connection_id: string;
+  manifest_url: string;
+}
+
 /**
  * Tier-B platform verb request (agent-only): send as the bound bot.
  * Deliberately narrowed to 'slack' — the verb surface is per-vendor
@@ -2670,9 +2705,12 @@ export interface SendChannelMessageInput {
   /** Vendor-native conversation id from the inbound event (e.g. C…/D…). */
   conversation_id: string;
   /**
-   * External message id being answered (channel-domain format). REQUIRED
-   * for channel conversations (the reply lands in that message's thread);
-   * optional for DMs (always linear).
+   * External message id being answered (channel-domain format:
+   * `{channel}:{ts}`, thread children `{channel}:{root}#{ts}`). REQUIRED
+   * for channel conversations (the reply lands in that message's thread).
+   * In DMs the SESSION never forks, but reply POSITION follows the
+   * question: a thread-child id lands the reply inside that thread, a
+   * bare id (or omitting the field) keeps the flattened main flow.
    */
   reply_to?: string;
   text: string;
@@ -2681,12 +2719,94 @@ export interface SendChannelMessageInput {
 export interface SentChannelMessage {
   channel_type: 'slack';
   conversation_id: string;
-  /** Channel-domain external id ({channel}:{ts}) — usable as a reply_to. */
+  /**
+   * Channel-domain external id — `{channel}:{ts}` for top-level posts,
+   * `{channel}:{root}#{ts}` when the reply landed inside a thread — usable
+   * directly as a future reply_to.
+   */
   message_id: string;
   thread_anchor?: string;
   sent_at: string;
 }
 
+/**
+ * Tier-B read verbs (agent-only): workspace visibility as the bot sees it.
+ * Authorization is the bot's own Slack permissions (invite the bot to a
+ * channel to make its history readable) — reads have no external side
+ * effect, so the seen-conversation restriction of the send verb does not
+ * apply. Cursor pagination follows Slack's contract (empty = last page).
+ */
+export interface SlackChannelInfo {
+  id: string;
+  name: string;
+  is_private: boolean;
+  is_member: boolean;
+  num_members?: number;
+  topic?: string;
+}
+
+export interface SlackChannelsPage {
+  channels: SlackChannelInfo[];
+  next_cursor?: string;
+}
+
+export interface SlackUserInfo {
+  id: string;
+  name: string;
+  real_name?: string;
+  is_bot: boolean;
+  deleted?: boolean;
+}
+
+export interface SlackUsersPage {
+  users: SlackUserInfo[];
+  next_cursor?: string;
+}
+
+export interface SlackHistoryMessage {
+  /**
+   * Synthesized channel-domain id — `{conversation}:{ts}`, or
+   * `{conversation}:{root}#{ts}` for thread children — directly usable as
+   * the send verb's `reply_to` (no client-side root#child derivation).
+   */
+  message_id: string;
+  ts: string;
+  thread_ts?: string;
+  user?: string;
+  bot_id?: string;
+  text: string;
+}
+
+export interface SlackHistoryPage {
+  messages: SlackHistoryMessage[];
+  next_cursor?: string;
+}
+
+export interface SlackMembersPage {
+  /** Bare Slack user ids — resolve display names via the users verb. */
+  members: string[];
+  next_cursor?: string;
+}
+
+/**
+ * Slack-native pagination for the read verbs. Filters are deliberately
+ * FIXED server-side (channels: public+private, archived excluded) — the
+ * public contract is cursor/limit only; widening it is a deliberate scope
+ * decision, not a missing passthrough.
+ */
+export interface SlackReadPageQuery {
+  cursor?: string;
+  limit?: number;
+}
+
+/** Agents-pane "typing…" indicator for one assistant thread (empty status clears). */
+export interface SlackStatusInput {
+  conversation: string;
+  /** The assistant thread's root ts. */
+  thread_ts: string;
+  status?: string;
+}
+
 // ============================================================
 // Dispatch Types (agent event delivery)
 // ============================================================
@@ -4023,6 +4143,15 @@ export type EdgePlacement = 'byoc' | 'hosted';
  */
 export type EdgeHostedState = 'idle' | 'deleting';
 
+/** Stable API error codes returned by the BYOC unregister contract. */
+export type EdgeDeviceUnregisterErrorCode =
+  | 'JWT_REQUIRED'
+  | 'HUMAN_REQUIRED'
+  | 'FORBIDDEN'
+  | 'EDGE_PLACEMENT_UNSUPPORTED'
+  | 'EDGE_ONLINE'
+  | 'EDGE_INTEGRITY_ERROR';
+
 export interface EdgeDevice {
   id: string;
   org_id: string;
@@ -4073,6 +4202,102 @@ export interface ClipConnection {
   updated_at: string;
 }
 
+/**
+ * A clip in the api-server org registry (`crg_…`, table `clip_registry`) — the
+ * v3 registry that install and clip connections operate on. Distinct from
+ * {@link RegistryClipInfo}, which is the clip-service → Pinix Hub catalog proxy
+ * and carries no registry id.
+ */
+export interface ClipRegistryEntry {
+  id: string;
+  org_id: string;
+  name: string;
+  description?: string;
+  visibility: 'public' | 'private';
+  version?: string;
+  /** clip.json manifest. `type` absent/null means browser (predates the field). */
+  manifest: Record<string, unknown> | null;
+  author_id: string;
+  /** Reviewed snapshot served cross-org. Absent = never approved. */
+  approved_version_id?: string;
+  created_at: string;
+  updated_at: string;
+  /** Author-org-only computed fields (state of the latest submitted version). */
+  review_status?: string;
+  review_note?: string;
+}
+
+export interface InstallRegistryClipResponse {
+  ok: boolean;
+  clip_id: string;
+  name: string;
+}
+
+/**
+ * Execute a registry (Edge) clip command on an Edge device
+ * (`POST /orgs/{orgId}/edge/exec`).
+ *
+ * Routing is EXPLICIT — exactly one of:
+ * - `connection`: a clip connection id (`ccn_…`) or its org-local alias. The
+ *   ONLY route to a hosted (Cloud Profile) device: the connection its
+ *   maintainer bound IS the org-wide authorization. Also valid for BYOC.
+ * - `edge_id`: a BYOC desktop device the CALLER owns. Naming a hosted device
+ *   here is refused (`400 HOSTED_CONNECTION_REQUIRED`).
+ * - neither: legacy BYOC fallback — resolves only to the caller's OWN online
+ *   desktop device, never to a hosted one.
+ */
+export interface ExecEdgeClipRequest {
+  /**
+   * Clip name in the org's clip registry (or an installed marketplace clip).
+   * Exactly ONE of `clip` or `clip_id` is required — same identity contract as
+   * clip invoke: bare names keep the fail-closed collision behavior (own-org
+   * shadows installs; two installed namesakes → `409 CLIP_NAME_AMBIGUOUS`).
+   */
+  clip?: string;
+  /**
+   * Exact registry Clip id (`crg_…`). Selects the exact object without
+   * weakening execution trust (cross-org still requires public + approved +
+   * installed and runs only the approved snapshot).
+   */
+  clip_id?: string;
+  /** Command to run — resolves to `<command>.js` in the clip's files. */
+  command: string;
+  /** Command arguments, forwarded verbatim to the clip. */
+  args?: unknown;
+  /** Connection id (`ccn_…`) or alias. Required for hosted devices. */
+  connection?: string;
+  /** Owned BYOC device id. Mutually exclusive with `connection`. */
+  edge_id?: string;
+  /**
+   * Browser profile name. With `connection` it may only restate the profile
+   * that connection grants (`400 CONNECTION_PROFILE_MISMATCH` otherwise).
+   */
+  profile?: string;
+  /** Execution timeout in MILLISECONDS (default 30000, max 120000). */
+  timeout?: number;
+  /**
+   * Optional audit tag (≤128 chars). Keep the SAME id across an
+   * EDGE_ACTIVATING retry loop so the server's audit log reads the retries as
+   * one logical call. It is NOT an idempotency key — it deduplicates nothing.
+   */
+  correlation_id?: string;
+}
+
+/**
+ * A completed execution's result envelope (HTTP 200). Every non-success is
+ * thrown as a typed {@link ApiError} instead — see
+ * {@link ParallClient.execEdgeClip} for the full code table and, critically,
+ * which codes are safe to retry.
+ */
+export interface EdgeClipExecResult {
+  request_id: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  error_code?: string;
+  duration_ms: number;
+}
+
 /**
  * Two INDEPENDENT onboarding journeys. The original fields mean what they always
  * meant — "has this org set up the desktop journey?" — and hosted-backed state