@parall/sdk 1.36.1 → 1.38.0

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 {
@@ -774,12 +781,26 @@ export interface Machine {
   // foreground runs that can't load the overlay or restart after exit(42).
   // Reported on heartbeat; gates the "Check for Update" affordance + API.
   self_update_capable?: boolean;
+  // Daemon-reported runtime CLIs found on the host (heartbeat-refreshed).
+  // Absent/null = never reported (pre-detection daemon — UNKNOWN, do not warn);
+  // [] = detection ran and found nothing. A signal for pickers only — attach /
+  // create are never gated on it (a CLI can be installed at any time).
+  detected_runtimes?: DetectedRuntime[] | null;
   region: string | null;
   created_by: string;
   created_at: string;
   updated_at: string;
 }
 
+// One entry of Machine.detected_runtimes. status 'ok' = the CLI resolved and
+// executed (`--version` succeeded); 'broken' = it resolved on disk but failed
+// to run (present-but-unusable install).
+export interface DetectedRuntime {
+  runtime_type: string;
+  version?: string;
+  status: 'ok' | 'broken';
+}
+
 export type DaemonWorkspaceMode = 'default' | 'local_path' | 'git';
 export type DaemonWorkspaceSetupRunOn = 'first_attach' | 'config_change';
 
@@ -846,7 +867,7 @@ export interface AgentProfile {
   model_management: string | null; // "platform" | "self" | null
   permissions: string[];
   machine_id: string | null;
-  hosting_mode?: 'hosted' | 'self_hosted';
+  hosting_mode?: 'hosted' | 'self_hosted' | 'platform_runtime';
   runtime_type: string;
   description: string | null;
   thinking_effort: string | null;
@@ -922,6 +943,17 @@ export interface MachineConfigUpdatedData {
   provider_enabled?: boolean;
 }
 
+// Per-agent counterpart of MachineConfigUpdatedData: ONE local agent's
+// explicit llm_source changed, so the daemon respawns just that agent's
+// child. llm_source carries the agent's new EFFECTIVE source (explicit
+// per-agent choice, else the machine default). Mirrors the Go
+// MachineAgentConfigUpdatedData struct.
+export interface MachineAgentConfigUpdatedData {
+  machine_id: string;
+  agent_id: string;
+  llm_source: string;
+}
+
 export interface MachineWorkspaceSetupRequestedData {
   machine_id: string;
   agent_id: string;
@@ -958,6 +990,14 @@ export interface MachineBrowserProfileLifecycleData {
   profile_id: string;
   action: BrowserProfileLifecycleAction;
   start_url?: string;
+  /** Profile's lifecycle_generation after this transition's bump (PR #1650). The
+   *  daemon acts under it and echoes it in its status report so the server can
+   *  reject a stale report. Absent/0 from a pre-generation server. */
+  generation?: number;
+  /** Profile's reset_generation after this transition (bumped only by `reset`). On
+   *  an online reset the daemon records it in its per-profile sidecar so a later
+   *  reconnect doesn't redundantly re-wipe. */
+  reset_generation?: number;
 }
 
 /**
@@ -1078,6 +1118,13 @@ export interface Task {
   canceled_at: string | null;
   archived_at?: string | null;
   deleted_at?: string | null;
+  /**
+   * Per-viewer: whether the requesting user may manage OTHER members' comment
+   * subscriptions for this task (creator / assignee / project lead / org
+   * owner-admin). Populated on single-task GET; undefined elsewhere. Read this to
+   * gate subscriber-management UI — do not re-derive the rule client-side.
+   */
+  can_manage_subscribers?: boolean;
 }
 
 export interface TaskWatcher {
@@ -1158,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 {
@@ -1537,6 +1595,19 @@ export interface Wiki {
   created_by: string;
   created_at: string;
   updated_at: string;
+  /** Protected default wiki — cannot be deleted. */
+  is_default?: boolean | null;
+  /** Set when the wiki is soft-deleted (recoverable). */
+  deleted_at?: string | null;
+  /** User who soft-deleted the wiki. */
+  deleted_by?: string | null;
+  /** Set once purge is claimed — the wiki can no longer be restored. */
+  purge_started_at?: string | null;
+  /** deleted_at + retention window (server-computed) — the recycle-bin countdown
+   *  source. Past this, restore is rejected with 410 WIKI_RETENTION_EXPIRED. */
+  purge_eligible_at?: string | null;
+  /** Server-computed restore availability for recycle-bin rows. */
+  restorable?: boolean | null;
 }
 
 export interface WikiFileChange {
@@ -1568,11 +1639,19 @@ export interface WikiTreeEntry {
   path: string;
   type: 'tree' | 'blob';
   size?: number;
+  /**
+   * Entry sits inside a read-gated private subtree (path restriction). Advisory
+   * display flag — the caller already passed read authorization to receive the
+   * entry; use it to badge private folders, never for access decisions.
+   */
+  restricted?: boolean;
 }
 
 export interface WikiTreeResponse {
   data: WikiTreeEntry[];
   path: string;
+  /** Whether the listed directory itself sits inside a read-gated private subtree. */
+  path_restricted?: boolean;
 }
 
 export interface WikiFileManifestEntry {
@@ -1835,6 +1914,11 @@ export interface CreateWikiPathRestrictionRequest {
   level?: 'read' | 'maintain' | 'admin';
   subjects: string[];
   apply_to_admins?: boolean;
+  // When true, the server returns 409 RESTRICTION_EXISTS if a restriction already
+  // exists at `path` instead of upserting its subjects. Set by the member "create
+  // private space" flow so a stale/concurrent create can't silently overwrite an
+  // existing space's share list; edit-access flows leave it unset (upsert).
+  create_only?: boolean;
 }
 
 export interface WikiAccessStatus {
@@ -1881,6 +1965,24 @@ export interface WikiOperationsResponse {
 // Wiki Blob
 // ============================================================
 
+/**
+ * Copy one wiki file to another path as an independent snapshot (no ongoing
+ * sync). Primary use: "share a private file out" — copy from the caller's
+ * personal namespace (`users/{userId}/…`) into the public wiki so the whole
+ * org can read + edit the copy, leaving the private original untouched.
+ */
+export interface CopyWikiFileRequest {
+  source_path: string;
+  dest_path: string;
+  message?: string;
+}
+
+export interface CopyWikiFileResponse {
+  source_path: string;
+  dest_path: string;
+  commit_sha: string;
+}
+
 export interface WikiBlob {
   path: string;
   ref: string;
@@ -1895,6 +1997,8 @@ export interface WikiBlob {
   content?: string;
   line_count?: number;
   sha256?: string;
+  /** File sits inside a read-gated private subtree — advisory display flag. */
+  restricted?: boolean;
   // Phase 2 additions for the binary response shape:
   mime?: string;
   is_lfs?: boolean;
@@ -2044,6 +2148,16 @@ export interface MembershipChangedData {
   action: 'added' | 'removed' | 'role_changed';
 }
 
+/**
+ * A member was removed from an org — kicked by an admin or self-removal
+ * ("leave org"). Delivered on org:{orgId} (remaining members refresh the
+ * directory) and user:{userId} (the removed user's clients drop the org).
+ */
+export interface OrgMemberRemovedData {
+  org_id: string;
+  user_id: string;
+}
+
 // ---- Task Comment & Activity Types ----
 
 export type TaskActivityAction = 'created' | 'field_changed' | 'commented';
@@ -2085,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;
@@ -2186,6 +2308,14 @@ export interface AgentStepNewData extends AgentStep {}
 export type WikiChangesetCreatedData = WikiChangeset & { org_id: string };
 export type WikiChangesetUpdatedData = WikiChangeset & { org_id: string };
 
+export interface WikiDeletedData {
+  org_id: string;
+  wiki_id: string;
+  slug: string;
+  name: string;
+}
+export type WikiRestoredData = WikiDeletedData;
+
 // Wiki Comment
 
 // Unified Comment (replaces TaskComment and WikiComment)
@@ -2263,6 +2393,134 @@ export interface InboxItem {
   updated_at: string;
 }
 
+// ============================================================
+// External IM Channel Types (platform-mediated Feishu/Slack channel)
+// ============================================================
+
+export type ChannelProvider = 'feishu' | 'slack';
+export type ChannelConnectionStatus = 'pending' | 'active' | 'disabled';
+/**
+ * Inbound transport for a connection. Defaults to the provider's lowest-
+ * onboarding-cost mode server-side (Feishu → socket, Slack → webhook) when
+ * omitted on create; can be overridden per connection.
+ */
+export type ChannelIngressMode = 'webhook' | 'socket';
+export type ChannelMessageStatus = 'received' | 'dispatched' | 'failed';
+
+export interface ChannelConnection {
+  id: string;
+  org_id: string;
+  agent_id: string;
+  provider: ChannelProvider;
+  ingress_mode: ChannelIngressMode;
+  display_name: string;
+  created_by: string;
+  status: ChannelConnectionStatus;
+  external_app_id?: string;
+  external_team_id?: string;
+  archived_at?: string | null;
+  archive_reason?: string | null;
+  /** Returned once at mint time (create / token regeneration). */
+  ingress_url?: string;
+  /** Returned once at mint time (create / token regeneration). */
+  ingress_token?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ChannelCredentialsInput {
+  app_id: string;
+  app_secret: string;
+  verification_token?: string;
+  encrypt_key?: string;
+  team_id?: string;
+}
+
+export interface CreateChannelConnectionInput {
+  agent_id: string;
+  provider: ChannelProvider;
+  display_name: string;
+  /** Override the provider's default inbound transport (optional). */
+  ingress_mode?: ChannelIngressMode;
+  /** Manual provisioning: activates the connection immediately. */
+  credentials?: ChannelCredentialsInput;
+}
+
+export interface UpdateChannelConnectionInput {
+  display_name?: string;
+  status?: 'active' | 'disabled';
+}
+
+export interface ChannelConversation {
+  id: string;
+  org_id: string;
+  connection_id: string;
+  agent_id: string;
+  agent_session_id?: string | null;
+  external_conversation_id: string;
+  external_thread_id: string;
+  conversation_type: string;
+  external_user_id: string;
+  external_user_name: string;
+  last_inbound_at?: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ChannelMessage {
+  id: string;
+  org_id: string;
+  connection_id: string;
+  conversation_id: string;
+  external_message_id: string;
+  text: string;
+  external_user_id: string;
+  external_user_name: string;
+  status: ChannelMessageStatus;
+  received_at: string;
+  created_at: string;
+}
+
+/**
+ * Feishu one-click provisioning session (OAuth device flow). The client
+ * renders `verification_url` as a QR code and lazily polls the status
+ * endpoint every `poll_interval_seconds` — each poll may forward one
+ * provider poll server-side, so respect the interval.
+ */
+export type ChannelProvisioningStatus =
+  | 'pending'
+  | 'polling'
+  | 'done'
+  | 'expired'
+  | 'denied'
+  | 'canceled'
+  | 'failed';
+
+export interface ChannelProvisioningSession {
+  id: string;
+  org_id: string;
+  agent_id: string;
+  provider: ChannelProvider;
+  created_by: string;
+  status: ChannelProvisioningStatus;
+  poll_interval_seconds: number;
+  /** Set when status = 'done': the minted connection. */
+  connection_id?: string;
+  /** Terminal detail: access_denied / expired_token / domain_switched / connection_exists / alias_conflict / internal. */
+  error_code?: string;
+  expires_at: string;
+  created_at: string;
+  updated_at: string;
+  /** QR target — present on live (pending/polling) sessions only. */
+  verification_url?: string;
+  user_code?: string;
+}
+
+export interface InitiateChannelProvisioningInput {
+  agent_id: string;
+  provider: ChannelProvider;
+}
+
 // ============================================================
 // Dispatch Types (agent event delivery)
 // ============================================================
@@ -2275,7 +2533,8 @@ export type DispatchEventType =
   | 'wiki_comment'
   | 'schedule.fire'
   | 'external_trigger'
-  | 'approval_decided';
+  | 'approval_decided'
+  | 'channel_message';
 export type DispatchStatus = 'pending' | 'received' | 'acked';
 export type DispatchDeliveryReason = 'mention' | 'watcher' | 'assignee' | 'creator';
 
@@ -2303,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 {
@@ -2333,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 {
@@ -2398,10 +2749,13 @@ export type WsEventMap = {
   'invitation.revoked': InvitationRevokedEventData;
   'org.join_request.new': OrgJoinRequestNewEventData;
   'org.invite_link.joined': OrgInviteLinkJoinedEventData;
+  'org.member.removed': OrgMemberRemovedData;
   'agent_config.update': AgentConfigUpdateData;
   'presence.update': PresenceUpdateData;
   'wiki.changeset.created': WikiChangesetCreatedData;
   'wiki.changeset.updated': WikiChangesetUpdatedData;
+  'wiki.deleted': WikiDeletedData;
+  'wiki.restored': WikiRestoredData;
   'comment.created': CommentCreatedData;
   'comment.updated': CommentUpdatedData;
   'comment.deleted': CommentDeletedData;
@@ -2412,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;
@@ -2425,6 +2780,7 @@ export type WsEventMap = {
   'machine.agent.attached': MachineAgentAttachedData;
   'machine.agent.detached': MachineAgentDetachedData;
   'machine.config.updated': MachineConfigUpdatedData;
+  'machine.agent_config.updated': MachineAgentConfigUpdatedData;
   'machine.workspace.setup.requested': MachineWorkspaceSetupRequestedData;
   'machine.stop': MachineStopData;
   'machine.filesystem.browse': MachineFilesystemBrowseData;
@@ -2494,7 +2850,14 @@ export interface PlatformConfigResponse {
   version: string;
   schema_version: number;
   min_plugin_version?: string;
+  /** @deprecated V1-compat only — old bridges read this for override-vs-floor. New bridges read `model_is_pin`. */
   mode?: string;
+  /**
+   * Whether the delivered model is an operator PIN (override, beats the runtime's
+   * env/default) vs a catalog FLOOR (loses to env). Optional: an old server omits
+   * it and the bridge falls back to the legacy `model_management`-derived signal.
+   */
+  model_is_pin?: boolean;
   config: Record<string, unknown>;
 }
 
@@ -2843,6 +3206,61 @@ export interface ComputePricing {
 // component name ("cpu" | "memory" | "storage").
 export type ComputePricingResponse = Record<string, ComputePricing>;
 
+/**
+ * Per-runtime capability row from GET /api/v1/runtimes (public, no auth).
+ * Server SSOT: server/pkg/hosting/capabilities.go RuntimeCapability — the
+ * data source for the create/settings interlock (which compute × intelligence
+ * × model combinations are offerable per runtime).
+ */
+export interface RuntimeCapability {
+  runtime: string;
+  /** Where the runtime can run: "hosted" and/or "local". Hermes is cloud-only. */
+  compute_modes: string[];
+  /**
+   * Provider family the runtime's OWN credentials can serve ("anthropic" /
+   * "openai"), or "any" for family-agnostic runtimes. Own-route restriction
+   * only — see cross_family_via_parall.
+   */
+  native_model_family: string;
+  /** On the Parall proxy route any catalog model is allowed regardless of family. */
+  cross_family_via_parall: boolean;
+  /** Whether a pinned model is delivered when the agent runs on its own credentials. */
+  own_route_model_pin: boolean;
+  /** Catalog default the UI pre-selects for this runtime. */
+  recommended_model: string;
+}
+
+/**
+ * Catalog entry from GET /api/v1/models (public, no auth) — the DB-backed
+ * platform model catalog. Server SSOT: handler.PlatformModelDTO
+ * (docs/engineering-design/model-catalog-design.md §6.1). Replaces the
+ * compile-time PLATFORM_MODELS constant as the picker data source.
+ */
+export interface PlatformModelInfo {
+  id: string;
+  name: string;
+  /** Provider family ("anthropic", "openai", "google", ...). */
+  family: string;
+  contextWindow: number;
+  maxTokens: number;
+  effortLevels?: string[];
+  /** Runtime type → runtime-native CLI model name. */
+  runtime_names?: Record<string, string>;
+  /** Set on client-behavior variants (the "(1M)" entries) — see isPlatformModelSelectableForRuntime. */
+  upstream_id?: string;
+  /** Display hints: "recommended" / "new" / "beta". */
+  tags?: string[];
+  sort_order: number;
+  /** True only for a legacy entry appended via include_model (not in the active catalog). */
+  hidden?: boolean;
+}
+
+export interface PlatformModelsResponse {
+  data: PlatformModelInfo[];
+  /** Catalog content hash — changes whenever the catalog changes. */
+  version: string;
+}
+
 export interface MachinePreset {
   key: string;
   cpu_cores: number;
@@ -2914,7 +3332,11 @@ export interface BillingInsufficientEvent {
 // Clip Types
 // ============================================================
 
-export type ClipSourceType = 'registry' | 'custom' | 'builtin';
+// 'channel' is a platform-managed source: it appears on read (Clip.source_type)
+// but the server rejects it on create, so CreateClipRequest uses the narrower
+// UserClipSourceType.
+export type ClipSourceType = 'registry' | 'custom' | 'builtin' | 'channel';
+export type UserClipSourceType = 'registry' | 'custom' | 'builtin';
 export type ClipStatus = 'active' | 'disabled';
 
 export interface Clip {
@@ -2949,7 +3371,7 @@ export interface CreateClipRequest {
   display_name?: string;
   description?: string;
   manifest?: Record<string, unknown>;
-  source_type?: ClipSourceType;
+  source_type?: UserClipSourceType;
   source_ref?: string;
   version?: string;
   machine_id: string;
@@ -3017,6 +3439,15 @@ export type BrowserProfileStatus = 'pending' | 'running' | 'stopped' | 'error' |
  */
 export type BrowserPlacement = 'byoc' | 'hosted';
 
+/** Deployment-wide hosted browser runtime availability (the controller startup
+ *  gate). Drives whether the create UI offers the platform-hosted placement; it
+ *  is org-scoped only for auth — the value itself is the same for every org.
+ *  Fail-closed: the server reports `available: false` if it cannot verify. */
+export interface BrowserRuntimeStatus {
+  available: boolean;
+  reason?: string;
+}
+
 export interface BrowserProfile {
   id: string;
   org_id: string;
@@ -3091,6 +3522,12 @@ export interface MachineBrowserProfile {
   proxy_server?: string | null;
   proxy_username?: string | null;
   proxy_password?: string | null;
+  /** Per-profile fencing tokens (PR #1650): lifecycle_generation bumps on every
+   *  open/stop/reset (daemon reports under it; stale reports rejected);
+   *  reset_generation bumps only on reset (daemon wipes local state on reconnect
+   *  when this is newer than what it last applied). Default 0. */
+  lifecycle_generation: number;
+  reset_generation: number;
 }
 
 export interface BrowserProfileConsent {
@@ -3240,10 +3677,18 @@ export type SearchParams = {
   types?: string;
   chat_id?: string;
   limit?: number;
+  /** Page offset into the per-type candidate pool (default 0). Reachability is capped — past the pool, results are empty with `has_more` false. */
+  offset?: number;
   /** Wiki document-type facet (frontmatter `type`) — a separate axis from `types`. */
   wiki_type?: string;
-  /** RFC3339 or YYYY-MM-DD; narrows messages (created_at) and tasks (updated_at). Not applied to wiki. */
+  /** RFC3339 or YYYY-MM-DD lower bound; narrows messages (created_at) and tasks (updated_at). Not applied to wiki. */
   since?: string;
+  /** Sender filter (Slack `from:`) — user id. Messages only; tasks/wiki carry no sender. */
+  from?: string;
+  /** Result order: `relevance` (default, RRF hybrid) or `recent` (newest-first). Recent applies to messages/tasks; wiki stays relevance (no authored timestamp). */
+  order?: 'relevance' | 'recent';
+  /** Collapse cross-chat message results to one hit per chat (default true). Pass false on the full results page to page every match. No effect when `chat_id` is set. */
+  collapse_by_chat?: boolean;
 };
 
 export interface SearchMessageResult {
@@ -3285,4 +3730,6 @@ export interface SearchResponse {
   messages: SearchMessageResult[];
   tasks: SearchTaskResult[];
   wiki: SearchWikiResult[];
+  /** 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 };
 }