@hyperflow/client

import { hyperflow } from "@hyperflow/client";

await hyperflow.init({
  apiUrl: "https://api.example.com",
  wsUrl: "wss://api.example.com/ws",
});

declare const service: {
  "init"(config: ClientConfig): Promise<void>;
};

declare const service: {
  "authorize"(credentials: AuthorizeInput): Promise<AuthorizeResult>;
};

declare const service: {
  "getCurrentUser"(): Promise<User>;
};

declare const service: {
  "updateMyAccount"(input: UpdateMyAccountInput): Promise<User>;
};

declare const service: {
  "changePassword"(input: ChangePasswordInput): Promise<void>;
};

declare const service: {
  "getWsToken"(): Promise<WebSocketAuthTokenResult>;
};

declare const service: {
  "getCloudLogoutUrl"(returnTo: string): string;
};

declare const service: {
  "logout"(): void;
};

/**
 * Auth wire and entity types.
 *
 * Consumed by {@link AuthService}.
 */
/**
 * Credentials used to authorize a Hyperflow user session.
 */
export type AuthorizeInput = {
  /** User e-mail address. */
  email: string;
  /** Clear-text password for the session. */
  password: string;
  /** Optional flag that asks the backend to keep the session longer. */
  rememberMe?: boolean;
};

/**
 * Response returned after a successful authorization request.
 */
export type AuthorizeResult = {
  /** Access token used for authenticated API requests. */
  accessToken: string;
  /** CSRF token paired with the access token. */
  csrfToken: string;
  /** Authenticated user payload. */
  user: User;
};

/**
 * Represents a pair of authentication tokens used to authorize requests.
 */
export type AuthTokens = {
  /** Bearer access token. */
  accessToken: string;
  /** CSRF token paired with the access token. */
  csrfToken: string;
};

/** Credentials required to change the authenticated user's password. */
export type ChangePasswordInput = {
  currentPassword: string;
  newPassword: string;
  confirmPassword: string;
};

/**
 * Configuration options for the Hyperflow client.
 */
export interface ClientConfig {
  /** Read fresh client capabilities when starting or resuming each act. */
  getActTolerations?: () => readonly ToolToleration[];
  /** Base URL of the Hyperflow REST API. */
  apiUrl: string;
  /** WebSocket endpoint URL. */
  wsUrl: string;
  /** Optional Hyperflow Cloud API base URL for workspace requests. */
  cloudApiUrl?: string;
  /** Identity portal origin used to end a Hyperflow Cloud browser session. */
  authBaseUrl?: string;
  /**
   * Storage backend for authentication tokens.
   * Defaults to `localStorageTokenStorage` (browser `localStorage`).
   * Pass `memoryTokenStorage()` for Node.js or SSR environments.
   */
  tokenStorage?: TokenStorage;
  /** Refreshes expired tokens and returns the replacement pair. */
  refreshTokens?: () => Promise<AuthTokens>;
  /** Called when the session expires and the token refresh fails. */
  onLogout?: () => void;
  /** Client heartbeat interval for WebSocket ping events. */
  wsPingIntervalMs?: number;
  /** Initial reconnect delay after a WebSocket disconnect. */
  wsReconnectBaseDelayMs?: number;
  /** Maximum reconnect delay for WebSocket backoff. */
  wsReconnectMaxDelayMs?: number;
  /** WebSocket transport strategy for multi-tab sharing. */
  wsTransport?: WsTransportMode;
  /** Optional SharedWorker script URL override. */
  sharedWorkerUrl?: string;
}

/**
 * Interface for reading and writing authentication tokens.
 * Implement this to support custom storage backends (e.g. cookies, memory, secure storage).
 */
export interface TokenStorage {
  /** Returns the current tokens, or `null` if none are stored. */
  getTokens(): AuthTokens | null;
  /** Persists the given tokens. */
  setTokens(tokens: AuthTokens): void;
  /** Removes all stored tokens. */
  clearTokens(): void;
}

/** Editable fields of the authenticated user's account. */
export type UpdateMyAccountInput = {
  email?: string | null;
  firstName?: string | null;
  lastName?: string | null;
};

/**
 * Hyperflow user model returned by the auth endpoints.
 */
export type User = {
  /** Numeric user identifier. */
  id: number;
  /** Primary e-mail address. */
  email: string;
  /** Optional first name. */
  firstName?: string;
  /** Optional last name. */
  lastName?: string;
  /** Whether the account is enabled. */
  enabled: boolean;
  /** Creation timestamp returned by the backend. */
  created_at: string;
  /** Last update timestamp returned by the backend. */
  updated_at: string;
};

type WsTransportMode = "auto" | "direct" | "shared-worker" | "broadcast";

declare const service: {
  "getConfig"(): Promise<ConfigResponse>;
};

declare const service: {
  "listByChatClient"(): Promise<ChatClientModelGroup[]>;
};

/**
 * Config wire and entity types.
 *
 * Consumed by {@link ConfigService}.
 */
/** Child node in the composer agent selector tree. */
export type AgentSelectorChildComponent =
  | {
      c: "agent";
      id: string;
    }
  | {
      c: "separator";
    };

/**
 * Authentication mode reported by the server.
 * - `none` — auth disabled
 * - `simple` — local login form
 * - `hyperflowCloud` — proxy-level auth (no local login page)
 */
export type AuthMode = "none" | "simple" | "hyperflowCloud";

type CatalogModel = {
  id: number;
  modelId: string;
  displayName: string;
  provider: string;
  protocol: string;
  contextWindow: number | null;
  maxOutputTokens: number | null;
  inputCostPer1m: number | null;
  cachedInputCostPer1m: number | null;
  outputCostPer1m: number | null;
  tokenizerId: string | null;
  tokenizerMode: string;
  chatTemplateId: string | null;
  tokenizerSource: string;
  tokenizerConfidence: string;
  capabilities: ModelCapabilityFlags;
  modelType: ModelType;
  source: string;
  lastFetchedAt: string;
};

type ChatClientModelGroup = {
  chatClientRef: string;
  catalogProvider: string;
  usageProvider: string;
  models: CatalogModel[];
};

/** Default chat options from `GET /config`. */
export type ChatOptions = {
  /** Agent id used when a session has no explicit active agent. */
  defaultAgentId: string;
};

/** Composer slot component descriptor from `frontendConfig.composer`. */
export type ComposerComponent =
  | {
      c: "agent_selector";
      children?: AgentSelectorChildComponent[] | null;
    }
  | {
      c: "model_selector";
    }
  | {
      c: "context_window_meter";
    }
  | {
      c: "toolhost_selector";
    }
  | {
      c: "tool_policy_selector";
    };

/** Composer layout slots returned in `GET /config`. */
export type ComposerConfig = ComposerConfigInner & {
  inSession?: ComposerConfigInner | null;
};

/** Composer layout slots returned in `GET /config`. */
export type ComposerConfigInner = {
  disclaimer?: ComposerDisclaimerConfig | null;
  slotLeft?: ComposerComponent[] | null;
  slotRight?: ComposerComponent[] | null;
  slotTopLeft?: ComposerComponent[] | null;
  slotTopRight?: ComposerComponent[] | null;
  slotBottomLeft?: ComposerComponent[] | null;
  slotBottomRight?: ComposerComponent[] | null;
  slotBottom?: ComposerComponent[] | null;
};

/** Optional plain-text composer warning settings. */
export type ComposerDisclaimerConfig = {
  /** False hides the warning; absent or null inherits, defaulting to true. */
  enabled?: boolean | null;
  /** Language-tag translations; blank values inherit the corresponding text. */
  text?: Record<string, string> | null;
};

/**
 * Response shape from `GET /config`.
 *
 * Wire field `frontendConfig` is unchanged; maps to UI composer layout.
 */
export type ConfigResponse = {
  authEnabled: boolean;
  authMode?: AuthMode;
  frontendConfig?: FrontendConfig | null;
  chatOptions: ChatOptions;
  sessionOptions?: SessionOptions | null;
};

/** UI configuration subtree of {@link ConfigResponse}. */
export type FrontendConfig = {
  composer?: ComposerConfig | null;
  sessionOptionsComponents?: SessionOptionsComponent[] | null;
};

type ModelCapabilityFlags = {
  image: boolean;
  video: boolean;
  audio: boolean;
  tools: boolean;
  streaming: boolean;
  reasoning: boolean;
  reasoningLevels?: ReasoningLevel[] | null;
};

type ModelType = "llm" | "embedding" | "image" | "audio";

/** Session defaults consumed by the composer from `GET /config`. */
export type SessionOptions = {
  /** Default toolhost used unless the user explicitly selects another host. */
  toolhost?: ToolhostDefaultConfig | null;
};

/** Composer components that can also be exposed as session options. */
export type SessionOptionsComponent = Exclude<
  ComposerComponent,
  {
    c: "context_window_meter";
  }
>;

/** Concrete toolhost id/name or availability-based preference for new sessions. */
export type ToolhostDefaultConfig =
  | string
  | {
      policy: ToolhostDefaultPolicy;
    };

/** Availability-based toolhost preference used for newly-created sessions. */
export type ToolhostDefaultPolicy = "localPrefered" | "cloudPrefered";

declare const service: {
  "listSessions"(params?: ListSessionsParams): Promise<SessionListResponse>;
};

declare const service: {
  "getSession"(id: string): Promise<Session>;
};

declare const service: {
  "getUsage"(sessionId: string): Promise<SessionUsage>;
};

declare const service: {
  "listCustomGroups"(): Promise<SessionCustomGroup[]>;
};

declare const service: {
  "approveTool"(request: ApproveToolRequest): Promise<void>;
};

declare const service: {
  "cancelBackgroundTask"(sessionId: string, taskId: string): Promise<BackgroundTask>;
};

declare const service: {
  "deleteBackgroundTask"(sessionId: string, taskId: string): Promise<void>;
};

declare const service: {
  "subscribeSession"(sessionId: string): void;
};

declare const service: {
  "replaySession"(sessionId: string, afterItemId?: string | null): void;
};

declare const service: {
  "createSession"(input?: CreateSessionInput): Promise<Session>;
};

declare const service: {
  "updateSession"(sessionId: string, input: UpdateSessionInput): Promise<Session>;
};

declare const service: {
  "rewindSession"(sessionId: string, actId: string): Promise<SessionRewindResult>;
};

declare const service: {
  "forkSession"(sessionId: string, actId: string): Promise<SessionForkResult>;
};

declare const service: {
  "deleteSession"(sessionId: string): Promise<void>;
};

declare const service: {
  "createItem"(sessionId: string, item: ClientSessionItem): Promise<void>;
};

declare const service: {
  "listActs"(sessionId: string, params?: ListSessionActsParams): Promise<SessionActsPage>;
};

declare const service: {
  "listBackgroundTasks"(sessionId: string): Promise<BackgroundTask[]>;
};

declare const service: {
  "getBackgroundTask"(sessionId: string, taskId: string): Promise<BackgroundTask>;
};

declare const service: {
  "startAct"(sessionId: string, agentId?: string | null, options?: StartActOptions): void;
};

declare const service: {
  "abortAct"(sessionId: string): void;
};

declare const service: {
  "generateTitle"(sessionId: string): void;
};

declare const service: {
  "createCustomGroup"(name: string): Promise<SessionCustomGroup>;
};

declare const service: {
  "updateCustomGroup"(groupId: string, name: string): Promise<SessionCustomGroup>;
};

declare const service: {
  "deleteCustomGroup"(groupId: string): Promise<void>;
};

declare const service: {
  "unsubscribeSession"(sessionId: string): void;
};

declare const service: {
  "deliverClientToolResult"(sessionId: string, toolCallId: string, result: unknown): void;
};

declare const service: {
  "onSessionEvent"(sessionId: string, handler: (event: ServerEvent) => void): () => void;
};

declare const service: {
  "onAppEvent"(handler: (event: AppEvent) => void): () => void;
};

/**
 * Pending agent OAuth state from `session.agent.auth_required`.
 * Set `completed` when `session.agent.device_authorization.completed` arrives.
 */
export type AgentAuthRequiredRequest = {
  actId: string;
  flows: OAuthFlows;
  completed?: true;
};

/** Named session agent mode applied alongside approval policy. */
export type AgentMode = {
  name: string;
  deny: string[];
  allow: string[];
};

type ApprovalPolicy = "ask" | "always" /* | "auto"*/;

type ApproveToolRequest = {
  agentId: string;
  toolName: string;
  authorizationType: ToolAuthorizationType;
  reference?: string;
  validationSchema?: Record<string, unknown>;
};

/**
 * Session WebSocket protocol types.
 *
 * ## Client events
 * Outbound `session.*` and `session_custom_group.*` frames sent by
 * {@link WsSessionService} via {@link WebSocketClient.request} or `send`.
 * See {@link ClientEvent}.
 *
 * ## Server events
 * Inbound push frames delivered to `onSessionEvent` / `onAppEvent` handlers.
 * See {@link ServerEvent}.
 */
export type Audience = "all" | "agent" | "user" | "none";

/** Background task state delivered by the Session API. */
export type BackgroundTask = {
  id: string;
  sessionId: string;
  userId: number;
  agentId?: string | null;
  actId?: string | null;
  toolCallId?: string | null;
  label?: string | null;
  description?: string | null;
  metadata?: Record<string, unknown> | null;
  status: BackgroundTaskStatus;
  wake: boolean;
  toolhost?: string | null;
  output?: string | null;
  result?: unknown;
  error?: string | null;
  createdAt: string;
  finishedAt?: string | null;
};

/** A long-running agent operation associated with a session. */
export type BackgroundTaskStatus =
  | "running"
  | "completed"
  | "failed"
  | "cancelled"
  | "timed_out";

type ClientEvent =
  | {
      type: "auth";
      eventId?: string;
      token: string;
    }
  | {
      type: "ping";
      eventId?: string;
    }
  | {
      type: "app.subscribe";
      eventId?: string;
    }
  | ({
      type: "session.create";
      eventId?: string;
    } & CreateSessionInput)
  | ({
      type: "session.update";
      eventId?: string;
      sessionId: string;
    } & UpdateSessionInput)
  | {
      type: "session.delete";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.rewind";
      eventId?: string;
      sessionId: string;
      actId: string;
    }
  | {
      type: "session.fork";
      eventId?: string;
      sessionId: string;
      actId: string;
    }
  | {
      type: "session.acts.list";
      eventId?: string;
      sessionId: string;
      first?: number;
      last?: number;
      beforeIndex?: number;
      afterIndex?: number;
      limit?: number;
      includeSessionChanges?: boolean;
    }
  | {
      type: "session.replay";
      eventId?: string;
      sessionId: string;
      afterItemId?: string | null;
    }
  | {
      type: "session.title.generate";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.title.abort_generate";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.item.create";
      eventId?: string;
      sessionId: string;
      item: ClientSessionItem;
    }
  | {
      type: "session.item.delete";
      eventId?: string;
      sessionId: string;
      itemId: string;
    }
  | {
      type: "session.agent.act";
      tolerations?: ToolToleration[];
      eventId?: string;
      sessionId: string;
      agentId?: string | null;
    }
  | {
      type: "session.agent.abort_act";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.subscribe";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.unsubscribe";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.agent.subscribe";
      eventId?: string;
      sessionId: string;
      agentId: string;
    }
  | {
      type: "session.agent.unsubscribe";
      eventId?: string;
      sessionId: string;
      agentId: string;
    }
  | {
      type: "session.user.typing.start";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.user.typing.stop";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.background_tasks.list";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.background_task.get";
      eventId?: string;
      sessionId: string;
      taskId: string;
    }
  | {
      type: "session.tool.result";
      eventId?: string;
      sessionId: string;
      toolCallId: string;
      /** Arbitrary JSON result produced by the client-executed tool. */
      result: unknown;
    }
  | ({
      type: "session_custom_group.create";
      eventId?: string;
    } & SessionCustomGroupInput)
  | ({
      type: "session_custom_group.update";
      eventId?: string;
      groupId: string;
    } & SessionCustomGroupInput)
  | {
      type: "session_custom_group.delete";
      eventId?: string;
      groupId: string;
    };

/** Payload for `session.item.create` (id/actId optional). */
export type ClientSessionItem = {
  id?: string;
  actId?: string;
  type: Exclude<
    SessionItemType,
    "session_change" | "background_task" | "background_task_completed"
  >;
  audience?: Audience;
  metadata?: Record<string, unknown> | null;
  role?: "system" | "user" | "assistant";
  content?: MessageInputContent[];
  reasonText?: string;
  function?: {
    name: string;
    arguments: Record<string, unknown>;
  };
  toolCallId?: string;
  resultType?: "result" | "input_required";
  result?: ToolOutputContent[];
};

type CompactedItemAudience = {
  id: string;
  audience: Audience;
};

type ContextWindowState = {
  systemPromptTokens: number;
  toolDefinitionsTokens: number;
  messagesTokens: number;
  promptOverheadTokens: number;
  promptTotalTokens: number;
  completionTokens: number;
  tokenAccountingMode: string;
  tokenUsageSource: string;
  totalContextWindow: number;
  totalUsed: number;
};

/** Input for `session.create` / REST session creation. */
export type CreateSessionInput = {
  title?: string | null;
  activeAgentId?: string | null;
  agents?: SessionAgentsMap | null;
  customGroupId?: string | null;
  titleGenerationOptions?: TitleGenerationOptions | null;
  backgroundMode?: boolean | null;
  approvalPolicy?: ApprovalPolicy | null;
  toolhost?: string | null;
  agentMode?: AgentMode | null;
};

type DeviceAuthorizationCompletedBody = {
  actId: string;
  sessionId: string;
};

type InProgressItem =
  | {
      kind: "reasoning_activity";
      activity: ReasoningActivity;
    }
  | {
      kind: "reasoning";
      itemId?: string | null;
      reasonText: string;
    }
  | {
      kind: "message";
      itemId?: string | null;
      text: string;
    }
  | {
      kind: "tool_call";
      itemId?: string | null;
      callId: string;
      name: string;
      arguments: string;
    };

type InputRequestOption = {
  label: string;
  value?: string;
  description?: string;
};

type InputRequestQuestion = {
  question: string;
  header?: string;
  multiSelect?: boolean;
  options?: InputRequestOption[];
};

/** Structured multiple-choice/free-text form for `inputRequests`. */
export type InputRequests = {
  questions: InputRequestQuestion[];
};

type ListSessionActsParams = {
  first?: number;
  last?: number;
  beforeIndex?: number;
  afterIndex?: number;
  limit?: number;
  includeSessionChanges?: boolean;
};

type ListSessionsGroupBy = "none" | "status" | "custom";

/** Query parameters for `GET /sessions`. */
export type ListSessionsParams = {
  page?: number;
  perPage?: number;
  title?: string;
  createdAtFrom?: string;
  createdAtTo?: string;
  lastActivityAtFrom?: string;
  lastActivityAtTo?: string;
  sortCreatedAt?: SortDirection;
  sortLastActivityAt?: SortDirection;
  sortId?: SortDirection;
  groupBy?: ListSessionsGroupBy;
};

type MessageContent = MessageTextContent | MessageImageContent | MessageFileContent;

type MessageFileContent = {
  type: "file";
  file: MessageFilePayload;
};

type MessageFileInput =
  | (Omit<MessageFilePayload, "uri" | "bytes"> & {
      uri: string;
      bytes?: never;
      uploadId?: string;
    })
  | (Omit<MessageFilePayload, "uri" | "bytes"> & {
      bytes: number[];
      uri?: never;
      uploadId?: never;
    });

type MessageFilePayload = {
  name?: string;
  /** Wire format field (snake_case per Hyperflow WS API). */
  mime_type?: string;
  uri?: string;
  bytes?: number[];
};

type MessageImageContent = {
  type: "image";
  image: MessageImagePayload;
};

type MessageImagePayload = {
  name?: string;
  /** Wire format field (snake_case per Hyperflow WS API). */
  mime_type?: string;
  uri?: string;
  bytes?: number[];
};

type MessageInputContent =
  | MessageTextContent
  | MessageImageContent
  | {
      type: "file";
      file: MessageFileInput;
    };

type MessageTextContent = {
  type: "text";
  text: string;
};

/**
 * OAuth flow payloads for `session.agent.auth_required` and
 * `session.agent.device_authorization.completed`.
 */
export type OAuthAuthorizationFlow = {
  actId: string;
  sessionId: string;
  authorizationUri: string;
  initiatedFromChatId?: string;
};

type OAuthDeviceFlow = {
  actId: string;
  sessionId: string;
  verificationUri: string;
  userCode: string;
};

/** Tagged union (`flow`: `"device"` | `"authorization"`). */
export type OAuthFlows =
  | ({
      flow: "device";
    } & OAuthDeviceFlow)
  | ({
      flow: "authorization";
    } & OAuthAuthorizationFlow);

/** Pagination metadata on session list responses. */
export type Pagination = {
  page: number;
  perPage: number;
};

type ReasoningActivity = {
  itemId: string;
  status: "started" | "progress" | "completed";
  encrypted?: boolean;
};

/** Named reasoning-effort levels accepted by the Hyperflow backend. */
export type ReasoningLevel =
  | "none"
  | "minimal"
  | "low"
  | "medium"
  | "high"
  | "xhigh"
  | "max"
  | "ultra";

type ResponseDelta =
  | {
      kind: "content";
      text: string;
    }
  | {
      kind: "thinking";
      text: string;
    }
  | {
      kind: "tool_call_start";
      callId: string;
      name: string;
    }
  | {
      kind: "tool_call_arguments";
      callId: string;
      delta: string;
    }
  | {
      kind: "tool_output";
      callId: string;
      delta: ToolOutputContent[];
    };

type ServerEvent =
  | {
      type: "auth.ok";
      eventId?: string;
      userId: number;
    }
  | {
      type: "auth.failed";
      eventId?: string;
      message: string;
    }
  | {
      type: "pong";
      eventId?: string;
    }
  | {
      type: "app.subscribed";
      eventId?: string;
    }
  | {
      type: "session.subscribed";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.unsubscribed";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.agent.subscribed";
      eventId?: string;
      sessionId: string;
      agentId: string;
    }
  | {
      type: "session.agent.unsubscribed";
      eventId?: string;
      sessionId: string;
      agentId: string;
    }
  | {
      type: "session.agent.act.queued";
      eventId?: string;
      sessionId: string;
      agentId: string;
      actId: string;
    }
  | {
      type: "session.item.create.accepted";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.user.typing.ack";
      eventId?: string;
      sessionId: string;
      isTyping: boolean;
    }
  | {
      type: "session.title.abort_generate.ack";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.agent.abort_act.ack";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "error";
      eventId?: string;
      code: string;
      message: string;
    }
  | {
      type: "session.created";
      eventId?: string;
      session: Session;
    }
  | {
      type: "session.updated";
      eventId?: string;
      session: Session;
    }
  | {
      type: "session.rewound";
      eventId?: string;
      sessionId: string;
      removedFromIndex: number;
      pivotUserMessage?: SessionItem;
    }
  | {
      type: "session.forked";
      eventId?: string;
      sessionId: string;
      session: Session;
      pivotUserMessage?: SessionItem;
    }
  | {
      type: "session.agent.options_changed";
      sessionId: string;
      agentId: string;
      changes: SessionAgentOptionChange[];
    }
  | {
      type: "session.deleted";
      eventId?: string;
      sessionId: string;
    }
  | {
      type: "session.status";
      eventId?: string;
      sessionId: string;
      status: string;
    }
  | {
      type: "session.item.created";
      sessionId: string;
      item: SessionItem;
    }
  | {
      type: "session.item.deleted";
      sessionId: string;
      itemId: string;
    }
  | {
      type: "session.acts.listed";
      eventId?: string;
      sessionId: string;
      acts: SessionActWithItems[];
      hasMore: boolean;
    }
  | {
      type: "session.replayed";
      eventId?: string;
      sessionId: string;
      acts: SessionActWithItems[];
    }
  | {
      type: "session.agent.act_state.before_act";
      sessionId: string;
      agentId: string;
      actId: string;
    }
  | {
      type: "session.agent.act_state.generate";
      sessionId: string;
      agentId: string;
      actId: string;
    }
  | {
      type: "session.agent.act_state.after_items";
      sessionId: string;
      agentId: string;
      actId: string;
    }
  | {
      type: "session.agent.act_state.act_completed";
      sessionId: string;
      agentId: string;
      actId: string;
    }
  | {
      type: "session.agent.act_state.act_aborted";
      sessionId: string;
      agentId: string;
      actId: string;
    }
  | {
      type: "session.context_window_state";
      sessionId: string;
      actId: string;
      state: ContextWindowState;
    }
  | {
      type: "session.context_compaction.started";
      sessionId: string;
      actId: string;
      compactionItemId: string;
      info: {
        messageCount: number;
        currentTokens: number;
        contextWindow: number;
      };
    }
  | {
      type: "session.context_compacted";
      sessionId: string;
      actId: string;
      compactionItemId: string;
      updatedItems: CompactedItemAudience[];
      summaryItems: SessionItem[];
    }
  | {
      type: "session.response.reasoning_activity";
      sessionId: string;
      actId: string;
      seq: number;
      activity: ReasoningActivity;
    }
  | {
      type: "session.response.delta";
      sessionId: string;
      actId: string;
      itemId?: string | null;
      delta: ResponseDelta;
      seq?: number;
    }
  | {
      type: "session.response.in_progress";
      eventId?: string;
      sessionId: string;
      actId: string;
      seq: number;
      items: InProgressItem[];
    }
  | {
      type: "session.item.stats";
      sessionId: string;
      actId: string;
      itemId: string;
      stats: Record<string, unknown>;
    }
  | {
      type: "session.response.done";
      sessionId: string;
      actId: string;
      item: SessionItem;
    }
  | {
      type: "session.title.delta";
      eventId?: string;
      sessionId: string;
      delta: string;
    }
  | {
      type: "session.title.done";
      eventId?: string;
      sessionId: string;
      title: string;
    }
  | {
      type: "session.title.failed";
      eventId?: string;
      sessionId: string;
      message: string;
    }
  | {
      type: "session.user.is_typing";
      sessionId: string;
      userId: number;
      isTyping: boolean;
    }
  | {
      type: "session.agent.auth_required";
      sessionId: string;
      actId: string;
      flows: OAuthFlows;
    }
  | {
      type: "session.agent.device_authorization.completed";
      sessionId: string;
      actId: string;
      data: DeviceAuthorizationCompletedBody;
    }
  | {
      type: "session.tool.execution_approval.requested";
      sessionId: string;
      actId: string;
      request: ToolExecutionApprovalRequest;
    }
  | {
      type: "session.tool.input_required";
      sessionId: string;
      actId: string;
      toolCallId: string;
      inputRequests?: unknown;
      requestState?: string;
    }
  | {
      type: "session.tool.client_call";
      executorConnectionId: string;
      sessionId: string;
      actId?: string;
      toolCallId: string;
      name: string;
      arguments?: Record<string, unknown>;
      /** `blocking`: the act waits inline for `session.tool.result`. `notify`: fire-and-forget. */
      mode: "blocking" | "notify";
      /** Only the participant that launched the act executes and delivers. */
      executorUserId?: number;
      timeoutMs?: number;
    }
  | {
      type: "session.tool.result.ack";
      sessionId: string;
      toolCallId: string;
      delivery: string;
    }
  | {
      type: "session.background_tasks.listed";
      eventId?: string;
      sessionId: string;
      tasks: BackgroundTask[];
    }
  | {
      type: "session.background_task.updated";
      eventId?: string;
      sessionId: string;
      task: BackgroundTask;
    }
  | {
      type: "session.background_task.output";
      sessionId: string;
      taskId: string;
      chunk: string;
    }
  | {
      type: "session_custom_group.created";
      eventId?: string;
      group: SessionCustomGroup;
    }
  | {
      type: "session_custom_group.updated";
      eventId?: string;
      group: SessionCustomGroup;
    }
  | {
      type: "session_custom_group.deleted";
      eventId?: string;
      groupId: string;
    };

/**
 * Session entity returned by REST and WebSocket APIs (camelCase wire format).
 */
export type Session = {
  id: string;
  title?: string | null;
  customGroupId?: string | null;
  status: SessionStatus;
  /**
   * When true, the agent keeps running after the client disconnects.
   * Defaults to `true` on the server when omitted at create time.
   * Not exposed in the default Chakra composer UI yet.
   */
  backgroundMode: boolean;
  activeAgentId: string;
  agents: SessionAgentsMap;
  titleGenerationOptions: TitleGenerationOptions;
  approvalPolicy?: ApprovalPolicy;
  /**
   * Remote toolhost name; null/omitted = co-located in-process tools.
   * Patchable via `session.update` / `session.agent.options_changed`.
   */
  toolhost?: string | null;
  /** Runtime-defined mode applied to the active agent. */
  agentMode?: AgentMode | null;
  lastActivityAt?: string | null;
  createdAt: string;
  updatedAt: string;
  isArchived: boolean;
  archivedAt?: string | null;
};