@parall/sdk 1.55.4 → 1.56.0

package/src/types.ts

@@ -4,6 +4,13 @@ import type {
   LabelDeletedData,
   LabelUpdatedData,
 } from './task-label-types.js';
+export type {
+  CompletedUploadPart,
+  FileUrlResponse,
+  PresignedUploadPart,
+  PresignResponse,
+  PresignUploadRequest,
+} from './attachment-types.js';
 
 // ============================================================
 // Entity Types — mirror server data model
@@ -60,12 +67,31 @@ export interface Chat {
   pinned: boolean;
   hidden: boolean;
   my_notification_level?: NotificationLevel;
+  /**
+   * Resolved per-(agent, chat) reply policy for an AGENT caller: override →
+   * room default → mentions_only floor, gated on the runtime capability.
+   * Absent for human callers, DMs, and smart chats — a runtime reading
+   * nothing here falls back to its legacy agent_routing_mode check.
+   */
+  my_agent_reply_policy?: AgentReplyPolicy;
 }
 
 export type ChatMemberRole = 'owner' | 'admin' | 'member';
 
 export type NotificationLevel = 'all' | 'mentions_only' | 'none';
 
+/** Trigger axis of the per-(agent, chat) reply policy. No 'none': @mentions
+ *  are an unsuppressible floor, so it would equal 'mentions_only'. */
+export type AgentReplyTrigger = 'all' | 'mentions_only';
+
+/** Reply-form axis; V1 defines only 'full'. */
+export type AgentReplyForm = 'full';
+
+export interface AgentReplyPolicy {
+  trigger: AgentReplyTrigger;
+  form: AgentReplyForm;
+}
+
 // Push notification subscription
 export interface PushSubscribeRequest {
   platform: 'web' | 'ios' | 'android';
@@ -101,6 +127,14 @@ export interface ChatMember {
   pinned: boolean;
   hidden: boolean;
   joined_at: string;
+  /**
+   * Per-(agent, chat) trigger override on an AGENT member row; absent/null =
+   * follow the room default. Writable by chat owners/admins and org admins
+   * only — never by the agent itself.
+   */
+  agent_reply_trigger?: AgentReplyTrigger | null;
+  /** Reply-form axis; always 'full' in V1. Absent on older servers. */
+  agent_reply_form?: AgentReplyForm;
   /** Org-scoped public title. Omitted by older servers and for former DM peers. */
   title?: string;
   user?: User;
@@ -111,6 +145,11 @@ export interface UpdateChatMemberRequest {
   pinned?: boolean;
   hidden?: boolean;
   notification_level?: NotificationLevel;
+  /** 'all' | 'mentions_only' sets the override; '' clears it (follow the
+   *  room default). Chat-governance authz — agents can never write it. */
+  agent_reply_trigger?: AgentReplyTrigger | '';
+  /** V1 accepts only 'full'. */
+  agent_reply_form?: AgentReplyForm;
 }
 
 export interface TransferChatOwnershipRequest {
@@ -237,6 +276,8 @@ export interface ApprovalCardContent {
   display: {
     title: string;
     description?: string;
+    request_reason?: string;
+    resource_label?: string;
     requester?: { id: string; name: string };
   };
   interaction: {
@@ -248,6 +289,7 @@ export interface ApprovalCardContent {
     status: string;
     decided_by?: string;
     decided_at?: string;
+    decision_reason?: string | null;
     execution_status?: ExecutionStatus | null;
     execution_error?: string | null;
     executed_at?: string | null;
@@ -289,6 +331,7 @@ export interface SystemContent {
   actor_name: string;
   target_id?: string;
   target_name?: string;
+  decision_reason?: string;
 }
 
 export type MessageContent =
@@ -322,10 +365,18 @@ export interface Message {
   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.
+   * cursor, excluding the viewer's own replies (root only). Watcher-scoped:
+   * only threads the viewer watches accrue unread. Populated on top-level
+   * list responses; omitted when zero.
    */
   unread_reply_count?: number;
+  /**
+   * Per-viewer thread watch state (root only): true when the viewer watches
+   * this root's thread. Populated on top-level list responses for roots with
+   * replies; omitted means not watching. Seeds the client's live unread
+   * mirror.
+   */
+  watching?: boolean;
   edited_at: string | null;
   deleted_at: string | null;
   created_at: string;
@@ -381,9 +432,12 @@ export interface Approval {
   resource_uri: string;
   action_payload: Record<string, unknown>;
   title: string;
+  request_reason?: string | null;
+  resource_label?: string | null;
   requester_id: string;
   decided_by: string | null;
   decided_at: string | null;
+  decision_reason?: string | null;
   status: ApprovalStatus;
   expires_at: string | null;
   execution_status?: ExecutionStatus | null;
@@ -412,6 +466,9 @@ export interface Organization {
   avatar_url: string | null;
   is_personal: boolean;
   member_limit: number | null;
+  attachment_max_file_size_bytes?: number | null;
+  attachment_storage_limit_bytes?: number | null;
+  attachment_storage_used_bytes?: number;
   /** Org-level default smart routing strategy: 'llm' | 'agent' | null. */
   smart_routing_strategy: string | null;
   /** Agent ID for strategy='agent'. NULL when strategy is 'llm' or unset. */
@@ -699,12 +756,6 @@ export interface CheckEmailResponse {
   pending_verification?: boolean;
 }
 
-export interface PresignResponse {
-  upload_url: string;
-  attachment_id: string;
-  expires_in: number;
-}
-
 export interface WsTicketResponse {
   ticket: string;
   expires_at: string;
@@ -1536,23 +1587,6 @@ export interface LaunchCredentialResponse {
   agent_id: string;
 }
 
-export interface PresignUploadRequest {
-  file_name: string;
-  file_size: number;
-  mime_type?: string;
-}
-
-export interface FileUrlResponse {
-  url: string;
-  is_proxy_url?: boolean;
-  expires_in: number;
-  width?: number;
-  height?: number;
-  file_name: string;
-  file_size: number;
-  mime_type: string;
-}
-
 export interface AvatarUploadResponse {
   avatar_url: string;
 }
@@ -1705,6 +1739,20 @@ export interface CreateTaskRequest {
   label_ids?: string[];
 }
 
+/**
+ * Moves a task (and its whole subtree) into another project via
+ * POST /tasks/{taskId}/move — the only path that changes the binding; PATCH
+ * keeps refusing project_id changes. Every subtree node is renumbered from the
+ * target project's counter and its old KEY-N identifier stays resolvable as a
+ * permanent alias. parent_id (must belong to the target project) attaches the
+ * moved root under a parent there; same-project calls with a parent degrade to
+ * a reparent, without one they are an idempotent no-op.
+ */
+export interface MoveTaskRequest {
+  project_id: string;
+  parent_id?: string;
+}
+
 export interface UpdateTaskRequest {
   title?: string;
   description?: string;
@@ -1712,9 +1760,10 @@ export interface UpdateTaskRequest {
   priority?: TaskPriority;
   assignee_id?: string | null;
   parent_id?: string | null;
-  // project_id is deliberately absent: a Task's Project is immutable after
-  // creation (server answers 400 PROJECT_IMMUTABLE; resubmitting the current
-  // value is an idempotent no-op).
+  // project_id is deliberately absent: PATCH cannot change a Task's Project
+  // (server answers 400 PROJECT_IMMUTABLE; resubmitting the current value is
+  // an idempotent no-op). Moving between projects is its own explicit
+  // operation — see MoveTaskRequest / moveTask().
   sort_order?: number;
   /**
    * Ordering intent resolved server-side in the update transaction:
@@ -2255,10 +2304,35 @@ export type WikiChangesetStatus =
   | 'superseded'
   | 'conflict';
 
+export type WikiAccessTier = 'public' | 'restricted' | 'private';
+export type WikiMemberRole = 'viewer' | 'editor' | 'manager';
+
+export interface WikiAccessPolicyMember {
+  subject: string; // usr_* or team ID
+  role: WikiMemberRole;
+}
+
+/** GET/PUT shape of the who-can-access projection (membership design §4).
+ *  PUT must echo the revision from the latest GET (409 POLICY_REVISION_STALE
+ *  on mismatch). Container policy bits ride the root ('' path) PUT only. */
+export interface WikiAccessPolicy {
+  path: string;
+  general_access: WikiAccessTier | 'inherit';
+  default_role?: 'editor' | 'viewer';
+  discoverable: boolean;
+  members: WikiAccessPolicyMember[];
+  revision: string;
+  /** Stored rows the projection cannot express — route to the advanced rules surface. */
+  advanced?: boolean;
+  editors_can_invite?: boolean;
+  viewers_can_download?: boolean;
+}
+
 export interface Wiki {
   id: string;
   org_id: string;
-  slug: string;
+  /** Absent on degraded listing entries (discoverable-but-unreadable). */
+  slug?: string;
   name: string;
   repo_owner: string;
   repo_name: string;
@@ -2279,11 +2353,27 @@ export interface Wiki {
   purge_eligible_at?: string | null;
   /** Server-computed restore availability for recycle-bin rows. */
   restorable?: boolean | null;
+  /** Derived from the root path rules (never stored): public | restricted | private. */
+  access_tier?: 'public' | 'restricted' | 'private';
+  /** Caller's explicit membership at the library root: none | viewer | editor | manager. */
+  my_membership?: 'none' | 'viewer' | 'editor' | 'manager';
+  /** True for discoverable-but-unreadable listing entries: only id, name and
+   *  access_tier are populated — enough to request to join, nothing else.
+   *  Degraded entries must not be mounted, synced or treated as content. */
+  degraded?: boolean;
+  /** Caller's library-level star (the sidebar Starred group). Carried on full
+   *  list/get projections only — degraded entries never have it. */
+  starred?: boolean;
 }
 
 export interface WikiFileChange {
   path: string;
-  action: 'create' | 'update' | 'delete';
+  action: 'create' | 'update' | 'delete' | 'rename';
+  /**
+   * Rename source; present only when action is "rename" (path is the rename
+   * target). Additive key — older changesets never carry it.
+   */
+  from_path?: string;
 }
 
 export interface WikiChangeset {
@@ -2316,6 +2406,12 @@ export interface WikiTreeEntry {
    * entry; use it to badge private folders, never for access decisions.
    */
   restricted?: boolean;
+  /**
+   * Committer date (RFC3339) of the newest default-branch commit touching this
+   * entry — the listing's "Last published" value. Present only when the tree
+   * was requested with `last_commit: true` and the lookup succeeded.
+   */
+  last_commit_at?: string;
 }
 
 export interface WikiTreeResponse {
@@ -2493,7 +2589,9 @@ export interface WikiRefsCheckResponse {
 
 export interface WikiDiffFile {
   path: string;
-  action?: string; // "create" | "update" | "delete"
+  action?: string; // "create" | "update" | "delete" | "rename"
+  /** Rename source when action is "rename" (path is the target). */
+  from_path?: string;
   additions: number;
   deletions: number;
 }
@@ -2509,20 +2607,44 @@ export interface CreateWikiRequest {
   default_branch?: string;
 }
 
-export interface WikiFileChangeInput {
+interface WikiFileChangeInputCommon {
   path: string;
-  action: 'create' | 'update' | 'delete';
-  content_base64?: string;
   base_version?: number;
   /**
    * Git blob SHA of the default-branch version this change was authored
    * against. When set on update/delete, the server rejects the changeset
    * with 409 STALE_BASE if the file has since changed on the default branch
-   * (prevents silently overwriting concurrent edits).
+   * (prevents silently overwriting concurrent edits). For rename it guards
+   * the from_path side.
    */
   base_sha?: string;
 }
 
+export interface WikiFileChangeWriteInput extends WikiFileChangeInputCommon {
+  action: 'create' | 'update' | 'delete';
+  content_base64?: string;
+  /** Only valid with action "rename" — the server rejects it elsewhere. */
+  from_path?: never;
+}
+
+/**
+ * Rename is a discriminated variant: `from_path` (the source; `path` is the
+ * target) and `content_base64` are both REQUIRED. The content must be sent —
+ * the server rejects a rename without the content_base64 key
+ * (400 MISSING_FIELDS) because the single-commit move always writes content
+ * and an omitted key would otherwise erase the file; an explicitly empty
+ * string (an empty file) is legal. Requires the server capability
+ * `cap:wiki-rename` — while it is off the server answers 422 RENAME_DISABLED
+ * (older servers answer 400 INVALID_ACTION).
+ */
+export interface WikiFileChangeRenameInput extends WikiFileChangeInputCommon {
+  action: 'rename';
+  from_path: string;
+  content_base64: string;
+}
+
+export type WikiFileChangeInput = WikiFileChangeWriteInput | WikiFileChangeRenameInput;
+
 export interface CreateWikiChangesetRequest {
   title: string;
   message?: string;
@@ -2858,6 +2980,7 @@ export interface CardUpdateData {
   execution_status?: ExecutionStatus | null;
   decided_by?: string;
   decided_at?: string;
+  decision_reason?: string | null;
   executed_at?: string | null;
   execution_error?: string | null;
 }
@@ -2873,7 +2996,7 @@ export interface WatchingData {
 export interface MembershipChangedData {
   chat_id: string;
   user_id: string;
-  action: 'added' | 'removed' | 'role_changed';
+  action: 'added' | 'removed' | 'role_changed' | 'policy_changed';
 }
 
 /**
@@ -5015,6 +5138,12 @@ export interface EdgeBrowserProfile {
   edge_id: string;
   name: string;
   is_default: boolean;
+  /** Stable compare-and-swap revision for Local BYOC Profile operations. */
+  version: number;
+  /** Stable configuration binding used by Alias readiness and execution. */
+  config_revision: number;
+  /** Authoritative persisted Profile operation lifecycle. */
+  lifecycle_state: 'active' | 'pending_create' | 'pending_rename' | 'pending_delete';
   created_at: string;
   updated_at: string;
   /**
@@ -5026,6 +5155,421 @@ export interface EdgeBrowserProfile {
   proxy_configured?: boolean;
 }
 
+export type EdgeProfileOperationAction = 'create' | 'rename' | 'delete';
+export type EdgeProfileOperationStatus =
+  | 'confirmation_required'
+  | 'pending'
+  | 'retryable'
+  | 'rejected'
+  | 'outcome_unknown'
+  | 'succeeded';
+export type EdgeProfileOperationOutcome = 'applied' | 'retryable' | 'rejected';
+
+export type EdgeProfileOperationErrorCode =
+  | 'JWT_REQUIRED'
+  | 'HUMAN_REQUIRED'
+  | 'EDGE_NOT_FOUND'
+  | 'EDGE_OFFLINE'
+  | 'EDGE_STATUS_UNAVAILABLE'
+  | 'PROFILE_NOT_FOUND'
+  | 'PROFILE_VERSION_CONFLICT'
+  | 'PROFILE_OPERATION_IN_PROGRESS'
+  | 'PROFILE_OPERATION_NOT_FOUND'
+  | 'PROFILE_OPERATION_CONFLICT'
+  | 'PROFILE_DELETE_IMPACT_CHANGED'
+  | 'IDEMPOTENCY_CONFLICT'
+  | 'INVALID_IDEMPOTENCY_KEY'
+  | 'INVALID_INPUT';
+
+export type EdgeProfileOperationRequest =
+  | { action: 'create'; name: string }
+  | { action: 'rename'; profile_id: string; expected_version: number; name: string }
+  | { action: 'delete'; profile_id: string; expected_version: number };
+
+export interface EdgeProfileOperationConfirmRequest {
+  impact_hash: string;
+  confirmation_token: string;
+}
+
+export interface EdgeProfileDeleteImpact {
+  profile_id: string;
+  profile_version: number;
+  aliases: Array<{ alias_id: string; name: string }>;
+  /** Classified legacy rows block confirmation; they are never silently deleted. */
+  legacy_connections: Array<{ connection_id: string; classification: string }>;
+  grants_count: number;
+  accepted_or_running_executions: number;
+  impact_hash: string;
+  confirmation_token: string;
+}
+
+export interface EdgeProfileOperationReceipt {
+  operation_id: string;
+  edge_id: string;
+  profile_id: string;
+  action: EdgeProfileOperationAction;
+  status: EdgeProfileOperationStatus;
+  expected_version?: number;
+  target_version: number;
+  attempt: number;
+  name_before?: string;
+  name_after?: string;
+  impact?: EdgeProfileDeleteImpact;
+  /** Present only while a Delete is awaiting the explicit strong confirmation. */
+  confirmation_token?: string;
+  /** Exact Edge outcome only; Server-private lifecycle evidence is never exposed here. */
+  edge_outcome?: EdgeProfileOperationOutcome;
+  error?: { code: string; message?: string };
+  created_at: string;
+  updated_at: string;
+  completed_at?: string;
+}
+
+export interface BrowserAliasCreateRequest {
+  name: string;
+  clip_id: string;
+  edge_id: string;
+  profile_id: string;
+  idempotency_key: string;
+}
+
+export interface BrowserAliasRenameRequest {
+  name: string;
+  expected_version: number;
+  idempotency_key: string;
+}
+
+export interface BrowserAliasDeleteRequest {
+  expected_version: number;
+  idempotency_key: string;
+}
+
+export type BrowserAliasErrorCode =
+  | 'JWT_REQUIRED'
+  | 'HUMAN_REQUIRED'
+  | 'INVALID_REQUEST'
+  | 'INVALID_ALIAS_NAME'
+  | 'CLIP_NOT_AVAILABLE'
+  | 'PROFILE_NOT_FOUND'
+  | 'ALIAS_NOT_FOUND'
+  | 'ALIAS_NOT_READY'
+  | 'ALIAS_NAME_TAKEN'
+  | 'ALIAS_STALE'
+  | 'PROFILE_OPERATION_IN_PROGRESS'
+  | 'IDEMPOTENCY_CONFLICT'
+  | 'EDGE_OFFLINE'
+  | 'EDGE_STATUS_UNAVAILABLE';
+
+export interface BrowserAliasVersion {
+  id: string;
+  version_seq: number;
+  source_kind: 'publisher_working_copy' | 'approved_public_snapshot';
+  source_clip_version_id?: string;
+  source_working_revision?: string;
+  version_label?: string;
+  artifact_digest?: string;
+  preparation_status: 'pending' | 'preparing' | 'ready' | 'failed';
+  preparation_result?: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+}
+
+export type BrowserAliasReadinessStatus =
+  | 'checking'
+  | 'ready'
+  | 'needs_action'
+  | 'unavailable'
+  | 'error';
+
+export const BROWSER_ALIAS_READINESS_REASON_CODES = [
+  'edge_offline',
+  'profile_not_found',
+  'profile_damaged',
+  'artifact_invalid',
+  'runtime_incompatible',
+  'needs_login',
+  'target_service_unavailable',
+  'readiness_check_running',
+  'readiness_check_timeout',
+  'readiness_contract_error',
+] as const;
+
+export type BrowserAliasReadinessReasonCode = (typeof BROWSER_ALIAS_READINESS_REASON_CODES)[number];
+
+export interface BrowserAliasReadinessReason {
+  code: BrowserAliasReadinessReasonCode;
+  status: BrowserAliasReadinessStatus;
+  hint: string;
+  observed_at: string;
+  retry_after_ms?: number;
+}
+
+export interface BrowserAliasReadiness {
+  alias_id: string;
+  status: BrowserAliasReadinessStatus;
+  blocking_reasons: BrowserAliasReadinessReason[];
+  primary_reason?: BrowserAliasReadinessReasonCode;
+  hint?: string;
+  observed_at: string;
+  source: 'server' | 'edge';
+  retry_after_ms?: number;
+  alias_revision: number;
+  active_alias_version_id?: string;
+  profile_revision: number;
+  profile_config_revision: number;
+  generation: number;
+  updated_at: string;
+}
+
+export interface BrowserAliasReadinessCheckRequest {
+  idempotency_key: string;
+}
+
+export type BrowserAliasReadinessCheckStatus = 'pending' | 'dispatched' | 'succeeded' | 'rejected';
+
+export interface BrowserAliasReadinessCheckReceipt {
+  check_id: string;
+  alias_id: string;
+  status: BrowserAliasReadinessCheckStatus;
+  error_code?: 'REPORT_STALE';
+  generation: number;
+  attempt: number;
+  readiness?: BrowserAliasReadiness;
+  created_at: string;
+  updated_at: string;
+  dispatched_at?: string;
+  completed_at?: string;
+}
+
+export interface BrowserAlias {
+  id: string;
+  name: string;
+  version: number;
+  lifecycle: 'preparing' | 'active' | 'update_preparing' | 'update_failed' | 'deleting';
+  edge: { id: string; name: string; status: 'online' | 'offline'; placement: 'byoc' | 'hosted' };
+  profile: {
+    id: string;
+    name: string;
+    version: number;
+    config_revision: number;
+    lifecycle_state: string;
+  };
+  clip: { id: string; name: string; version?: string };
+  desired_version?: BrowserAliasVersion;
+  active_version?: BrowserAliasVersion;
+  active_artifact_digest?: string;
+  preparation_result?: Record<string, unknown>;
+  update_result?: Record<string, unknown>;
+  readiness?: BrowserAliasReadiness;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface BrowserAliasDeleteProof {
+  alias_deleted: true;
+  grants_deleted: number;
+  name_released: true;
+}
+
+export interface BrowserAliasCommandContractSnapshot {
+  command_name: string;
+  input_schema: Record<string, unknown>;
+  output_schema: Record<string, unknown> | null;
+  side_effect_level: string;
+  data_scopes: string[];
+  allowed_domains: string[];
+  required_capabilities: string[];
+}
+
+export interface BrowserAliasGrantContractEvidence {
+  contract_hash: string;
+  contract_snapshot: BrowserAliasCommandContractSnapshot;
+}
+
+export interface BrowserAliasGrantCommand {
+  command_name: string;
+  status: 'missing' | 'active' | 'review_required';
+  authorized?: BrowserAliasGrantContractEvidence;
+  current: BrowserAliasGrantContractEvidence;
+  delta?: { changed_fields: string[] };
+}
+
+export interface BrowserAliasGrantSet {
+  key_id: string;
+  alias: { id: string; name: string; clip: BrowserAlias['clip'] };
+  /** Zero means this Key+Alias set has never been written. */
+  version: number;
+  commands: BrowserAliasGrantCommand[];
+  updated_at?: string;
+}
+
+export interface BrowserAliasGrantReplaceRequest {
+  expected_version: number;
+  idempotency_key: string;
+  commands: Array<{
+    command_name: string;
+    authorized_contract_hash: string;
+    authorized_contract_snapshot: BrowserAliasCommandContractSnapshot;
+  }>;
+}
+
+export interface ManagedBrowserAliasSummary {
+  id: string;
+  name: string;
+  clip: BrowserAlias['clip'];
+  readiness?: BrowserAliasReadiness;
+  commands: string[];
+  needs_owner_review: string[];
+}
+
+export interface ManagedBrowserAliasCommand {
+  name: string;
+  status: 'active';
+  description: string;
+  input_schema: Record<string, unknown>;
+  output_schema: Record<string, unknown> | null;
+  side_effect_level: string;
+  data_scopes: string[];
+  allowed_domains: string[];
+  required_capabilities: string[];
+}
+
+export interface ManagedBrowserAliasReviewRequiredCommand {
+  name: string;
+  status: 'review_required';
+  hint: string;
+}
+
+export interface ManagedBrowserAliasInfo {
+  id: string;
+  name: string;
+  clip: BrowserAlias['clip'];
+  readiness?: BrowserAliasReadiness;
+  commands: ManagedBrowserAliasCommand[];
+  needs_owner_review: ManagedBrowserAliasReviewRequiredCommand[];
+}
+
+export type BrowserAliasExecutionStatus =
+  | 'accepted'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'outcome_unknown';
+
+export interface BrowserAliasExecutionRequest {
+  request_id: string;
+  alias: string;
+  command: string;
+  args: Record<string, unknown>;
+}
+
+export interface BrowserAliasExecutionError {
+  code: string;
+  message: string;
+  hint?: string;
+}
+
+/** Redacted managed-key/Owner recovery DTO. It never contains target IDs,
+ * hashes, dispatch claims or Edge-ledger evidence. */
+export interface BrowserAliasExecutionReceipt {
+  request_id: string;
+  alias: string;
+  command: string;
+  status: BrowserAliasExecutionStatus;
+  dispatched: true;
+  command_timeout_ms: number;
+  execution_deadline: string;
+  result?: Record<string, unknown>;
+  error?: BrowserAliasExecutionError;
+  accepted_at: string;
+  running_at?: string;
+  terminal_at?: string;
+  updated_at: string;
+}
+
+export type BrowserUseAction =
+  | 'read'
+  | 'tabs'
+  | 'wait'
+  | 'snapshot'
+  | 'get'
+  | 'screenshot'
+  | 'open'
+  | 'navigate'
+  | 'viewport'
+  | 'click'
+  | 'fill'
+  | 'type'
+  | 'press'
+  | 'scroll'
+  | 'close'
+  | 'recover'
+  | 'eval';
+
+export interface BrowserUseTarget {
+  tab_id?: string;
+  browser_generation?: number;
+  document_generation?: number;
+  snapshot_id?: string;
+  ref?: string;
+}
+
+export interface BrowserUseOperationRequest {
+  contract_version: 'browser-use-operation-v1';
+  request_id: string;
+  profile_id: string;
+  action: BrowserUseAction;
+  target?: BrowserUseTarget;
+  params: Record<string, unknown>;
+  /** Canonical RFC3339 UTC instant, no more than two minutes in the future. */
+  deadline: string;
+}
+
+export type BrowserUseOperationPhase =
+  | 'accepted'
+  | 'started'
+  | 'succeeded'
+  | 'failed'
+  | 'outcome_unknown';
+
+export interface BrowserUseOperationError {
+  code: string;
+  message?: string;
+  hint?: string;
+}
+
+/** Durable Browser Use proof. `data` is encrypted/transient: it is present
+ * only while result_available is true and disappears after result_expires_at;
+ * the terminal receipt and result_digest remain durable. */
+export interface BrowserUseOperationReceipt {
+  contract_version: 'browser-use-operation-v1';
+  operation_id: string;
+  request_id: string;
+  profile_id: string;
+  profile_version: number;
+  profile_config_revision: number;
+  action: BrowserUseAction;
+  required_grant: 'browser.read' | 'browser.interact' | 'browser.advanced';
+  phase: BrowserUseOperationPhase;
+  dispatched?: boolean;
+  receipt_id?: string;
+  receipt_digest?: string;
+  occurred_at?: string;
+  tab_id?: string;
+  browser_generation?: number;
+  duration_ms?: number;
+  result_digest?: string;
+  result_available: boolean;
+  result_expires_at?: string;
+  data?: unknown;
+  error?: BrowserUseOperationError;
+  deadline: string;
+  accepted_at: string;
+  started_at?: string;
+  terminal_at?: string;
+  updated_at: string;
+}
+
 /**
  * Sanitized per-profile egress proxy status (hosted Cloud Profiles) — the GET
  * response and the PUT/DELETE result. NEVER carries the password; `password_set`