@parall/sdk 1.36.1 → 1.37.0

package/src/types.ts

@@ -774,12 +774,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 +860,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 +936,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 +983,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 +1111,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 {
@@ -1537,6 +1577,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 +1621,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 +1896,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 +1947,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 +1979,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 +2130,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';
@@ -2186,6 +2282,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 +2367,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 +2507,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';
 
@@ -2398,10 +2631,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;
@@ -2425,6 +2661,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 +2731,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 +3087,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 +3213,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 +3252,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 +3320,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 +3403,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 +3558,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 +3611,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 };
 }